Docs on Omniac Business

Authentication

Thu, 05 Jan 2017 00:00:00 +0000

Our API supports two types of authentication. API keys are easy und straight forward to use, but also less secure since they can be affected by a man-in-the-middle-attack. The more secure approach is to use OAuth with client credential flow. This way we are able to provide you an identity or also to use your identity-provider.

API Key

To use an API Key we need to enable this feature within your tenant. The provided key must be sent with each request using X-API-KEY Header.

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

This section outlines the steps to get started with omniac Business, including how to start the monitoring of a user, how to query a users alerts and how to query a users data.

alert

Thu, 05 Jan 2017 00:00:00 +0000

Alerts are notifications generated by omniac Business when breach incidents for certain attributes are detected. These alerts are crucial for maintaining the security and privacy of users’ data. Each alert contains details about the breach incident, including the type of attribute affected, the source, the time it happened, a criticality classification, short standard description of the incident and a recommendation. Depending on what details are required, the alert payload can be individualized.

attribute

Thu, 05 Jan 2017 00:00:00 +0000

Attributes are used to store and monitor various personal data of a user. They are stored in a masked, hashed and encrypted way to ensure privacy and security. There are up to 39 attributes available - a detailed list can be found below. Mainitaining attributes is done through the PUT /attributes endpoint. This replaces all attributes with the provided ones so make sure to include existing attributes as well. Old Attributes can be accessed through the GET /profile endpoint.

Basic Data Structure

Thu, 05 Jan 2017 00:00:00 +0000

This section contains a brief introduction into the data. Every tenant will have multiple profiles, within a profile there will be a list of attributes and alerts.

- * tenant
  |- settings
  |
  |- profiles
     |- profile
     |  |- alerts
     |  |- attributes
     |
     |- profile
     |  |- alerts
     |  |- attributes

Datastructure

Thu, 05 Jan 2017 00:00:00 +0000

Example Golang

Thu, 05 Jan 2017 00:00:00 +0000

Introduction and project setup

Go (Golang) is a statically typed, compiled programming language developed by Google, known for its simplicity, efficiency, and excellent concurrency support, making it ideal for building scalable web services, APIs, and microservices. To manage project dependencies in Go, you use Go modules. You can initialize a new Go module in your project directory by running the terminal command go mod init <module-name>, where <module-name> is typically your repository URL (e.g., github.com/username/project). This creates a go.mod file that tracks your dependencies. When you import packages and run go mod tidy, Go automatically downloads and manages the required dependencies. Go’s module system ensures reproducible builds and proper version management. You can build your project with go build and run it directly with go run main.go. This approach keeps your projects organized and ensures consistent dependency management across different environments.

Example Python

Thu, 05 Jan 2017 00:00:00 +0000

Introduction and project setup

Python is a versatile, high-level programming language praised for its readability and extensive libraries, making it ideal for web development, data analysis, and automation. To manage project-specific dependencies and avoid conflicts, it’s best practice to use a virtual environment. You can create one in your project directory by running the terminal command python -m venv .venv, where .venv is the name of your environment folder. Once created, you must activate it. On Windows, use .venv\Scripts\activate, and on macOS or Linux, use source .venv/bin/activate. After activation, your command prompt will change to show the environment’s name, and any packages you install with pip will be isolated to that specific project. When you’re finished, simply type deactivate to return to your global Python context. This process keeps your projects tidy and reproducible.

profile

Thu, 05 Jan 2017 00:00:00 +0000

A profile holds all the information for one specific user within your tenant. This profile combines a set of attributes that have been saved for a user and the triggered alerts in case breach incidents were detected.

Creating a profile is as simple as issuing a POST request against the profiles endpoint (/v1/profiles). The same endpoint also accepts requests with a profileID (/v1/profiles/{profileID}) with the following methods:

GET for retrieving a profile,
DELETE for removing a profile and
PUT for storing new attributes.

Please consult the openapi spec for in depth request and repsonse documentation.

tenant

Thu, 05 Jan 2017 00:00:00 +0000

Tenants represent individual customers or organizations that use the omniac Business service. Each tenant has its own set of users, data, and configurations, allowing for tailored security monitoring and management. Cross tenant access of data is not allowed, ensuring that each tenant’s information remains private and secure.

Configuration

Initially a tenant will be provided to you by omniac Business. You or a representative of omniac Business can then configure the tenant to your needs. The configuration includes:

Example Java

Thu, 05 Jan 2017 00:00:00 +0000

Introduction and project setup

Java is a robust, object-oriented programming language known for its platform independence and strong type system, making it ideal for enterprise applications, web services, and large-scale systems. To manage project dependencies and build processes effectively, it’s best practice to use a build tool like Maven or Gradle. For this guide, we’ll use Maven. You can create a new Maven project by running mvn archetype:generate -DgroupId=com.example.omniac -DartifactId=omniac-client -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false in your terminal. This creates a standard project structure with a pom.xml file for dependency management. Navigate to your project directory with cd omniac-client. The Maven structure keeps your source code in src/main/java and tests in src/test/java, providing a clean and organized development environment that’s easily understood by IDEs and other developers.

Examples

Thu, 05 Jan 2017 00:00:00 +0000

Within this section you will find some example implementations. We provide examples for the usage of our api and also how to implement the data handling like hashing and encryption.

OpenAPI Generator

Thu, 05 Jan 2017 00:00:00 +0000

OpenAPI Generator

We recommend using the official OpenAPI Generator to generate the client code. The generator can be found at OpenAPI Generator. It offers various options for generating client libraries in different programming languages. It generates code based on the OpenAPI specification such as functions to invoke the endpoints and types for the request and response bodies.

Client Generation Steps

Download the OpenAPI Specification: Obtain the OpenAPI specification file for omniac Business. This file is YAML format and describes the API endpoints, request parameters, and response structures.
Install OpenAPI Generator: If you haven’t already, install the OpenAPI Generator CLI tool. Consult the OpenAPI Generator documentation for installation instructions.
Generate the Client: Use the OpenAPI Generator CLI to generate the client code. The command typically looks like this:
```
openapi-generator-cli generate -i path/to/openapi.yaml -g <language> -o path/to/output/directory
```
Replace <language> with the desired programming language (e.g., python, java, javascript, etc.) and specify the path to the OpenAPI specification file and the output directory where the generated client code will be saved.

Receive Push Alerts

Thu, 05 Jan 2017 00:00:00 +0000

To get notified even faster, we provide a push api for new alerts. As soon as incidents are found for certain attributes, we will publish the alert into your system. This is done over a HTTP-call. The delivery will marked as done on our side as soon as your api returns a 2xx http status code.

To use this feature, you need to contact us, so we can enable the feature for your tenant.

Encryption in the client

Thu, 05 Jan 2017 00:00:00 +0000

In addition to the option of sending the data to be monitored in plain text to omniac Business, we also offer the option of receiving the data already normalized, encrypted, and hashed. The latter is also the method we recommend, as it ensures that your users’ personal attributes never leave your company context in plain text. The processing steps required for this must be identical to those we perform before using the data to search our data leak database. This procedure is briefly explained below.