Connect API

Note

This is an enterprise-level feature of Security Onion. Contact Security Onion Solutions, LLC via our website at https://securityonion.com/pro for more information about purchasing a Security Onion Pro license to enable this feature.

The Security Onion Connect API allows other servers to integrate with Security Onion, and access the same functionality that the Security Onion Console user-interface provides. Access to the Connect API is permitted through API Clients, which can be created by SOC administrators via the SOC UI -> Administration -> API Clients screen.

The Connect API currently provides functionality exposed by the Security Onion Console server. It does not provide full access to third-party applications included with the Security Onion platform. Specifically, while you can read events from Elasticsearch, you cannot manipulate Kibana settings via the Security Onion Connect API, unless those settings are already exposed via the SOC Configuration system.

Enabling Connect API

By default, newly setup grids will not be configured for API client access. To enable API client access, the following steps must be taken:

  1. A license key must be applied to the grid. The license key must include the API feature.

  2. The Hydra feature must be enabled via the hydra > enabled setting in the Configuration screen.

  3. Synchronize the grid to apply the license key and configuration changes. This can be done via the Configuration screen options dropdown.

API Client Credentials

In order to communicate with the Connect API, an API Client must be created. Navigate to the Administration menu using a superuser account. Under the Administration menu click the API Clients menu option. Create a new API client using a short name that reflects the intended usage of this client. Use the Notes field to provide more information, if desired. Upon saving the new client a generated secret will be issued. This client ID and secret pair is needed to authenticate to the Connect API. Protect these credentials using industry best practices.

Authorization / RBAC

API clients are permitted access to various components within Security Onion using the same RBAC system for users. However, rather than assign roles to API clients, the more granular permissions are assigned. For example, while a user might be assigned the analyst role, an API client would be assigned the events/read, events/write, cases/read, etc. This ensures that remote systems will only have access to the minimum necessary permissions required for the integration.

Currently OAuth 2.0 scopes are not utilized, since these permissions are assigned outside of the OAuth 2.0 flow.

OAuth 2.0 Authentication Flow

API clients must use The OAuth 2.0 client credentials flow to authenticate to the Security Onion manager node.

Exchange Client Credentials for an Access Token

Obtain an access token by submitting a POST request to https://BASE_URL/oauth2/token, and providing the client ID and client secret via the Basic authentication scheme. The body of the request must contain grant_type=client_credentials.

Example:

curl --cacert ca.crt -X POST -u socl_my_new_client:hwKHspsX2bMuoIs7kGwN https://BASE_URL/oauth2/token -d grant_type=client_credentials

Where you will replace:

  • ca.crt with your manager’s certificate authority. If a custom certificate has been applied to your grid after setup completed, you can access it via the Configuration screen (requires superuser role) from the nginx > ssl > SSL/TLS Cert File [adv] config setting, or if using the default generated certificate authority, retrieve the /etc/pki/ca.crt certificate file via SSH from the manager node.

  • socl_my_new_client with your client ID (generated by SOC during API client creation)

  • hwKHspsX2bMuoIs7kGwN with your API client’s generated secret

  • BASE_URL with your manager’s IP or hostname, depending on which option you selected during Security Onion setup

The response will resemble the following:

{"access_token":"ory_at_xI1_2FVvoWR60GHAXZXAcDW7V3qEi2mIB8RKnpqN0fk.Hy5LaHPqh9sfWVEtDXDhs8Gj-9YZ85FJHp6pyD0eeNw","expires_in":3599,"scope":"","token_type":"bearer"}

The access token will expire in 2 hours, by default, after which a new access token must be requested using this same credential exchange method again.

Authorize API Requests with an Access Token

Now that the access token has been retrieved, the API requests can be submitted. These requests will utilize the access token via the HTTP Authorization header, using the Bearer scheme.

Example:

curl --cacert ca.crt -X GET --oauth2-bearer ory_at_U74544Scqho5KGOci-qemWsOjxOU8TALqddAnrfxAGg.7GlO4SYPUAllO23LVqs9e_FXl0tAdRlUk3AH9IplWRU https://BASE_URL/connect/info

Where the provided bearer token above must be replaced with the access token extracted from the client credential exchange response.

Manager of Managers

To interact with subgrid data, while still communicating with the primary Manager of Managers (MoM) node, include an additional query string parameter on the API URL. The parameter key is gridId and the value should be set to the desired subgrid ID.

API Reference

Warning

New releases of Security Onion may contain additional fields in API responses. Consequently, it is important that the API output be properly parsed by official libraries that can handle these scenarios. Using custom parsing of API outputs may lead to upgrade-related malfunctions.

An interactive API view is available: Interactive API