USM Anywhere APIs

LevelBlue publishes APIs for USM Anywhere™ version 2.0. These Representational State Transfer (REST) APIs provide a programmatic interface that enables you to access your USM Anywhere data directly from your own applications and extensions. The APIs are organized around basic REST principles, with easy-to-understand, resource-oriented URLs, and use HTTP response codes to indicate API errors. All API responses return JavaScript Object Notation (JSON), including those with errors.

Authentication

The USM Anywhere APIs use OAuth 2.0 for endpoint protection, which provides token-based authentication and authorization on the Internet. The diagram below illustrates the authorization flow between the user and the USM Anywhere APIs.

Before you can retrieve a token, you must create a Client ID and secret code in USM Anywhere for your user account.

To get your Client ID and secret code

1. Click the icon and then select Profile Settings.
2. On the Profile page, select the API Clients tab.
3. Click New Client.

4. Enter an alphanumeric name for the client and then click Create Client.

   The system generates the Client ID and secret code. Save this information. You will need it to create a username and password in a later step.

   Important: This code is only available when it is first generated, so be sure to keep it secure and copy it when it is displayed. If you want to generate a new code, use the Reset Secret link.

Then, you need to use the oauth/token endpoint to request a token used for authentication by the other API endpoints. For example:

curl -X POST "https://<your-subdomain>.alienvault.cloud/api/{version}/oauth/token?grant_type=client_credentials" \
     -d @request_body \
     --user <username>:<password>

The POST command has a single www-form-urlencoded parameter, grant_type, and currently the only supported value is client_credentials. Use the Client ID for username and the secret code for password.

The response to this POST command contains the OAuth token that must be used to make subsequent requests to the other API endpoints.

{
	"access_token": "xxx.yyy.zzz",
	"token_type": "bearer",
	"expires_in": 899,
	"scope": "trust read write",
	"jti": "3b4cc123-2164-44cb-ae34-9c76d7c429ab"
}

Next, you must use the token in the header on subsequent requests to the other endpoints. For example:

Authorization: Bearer <access_token>

This token can be used to request data from any other USM Anywhere subdomains you have permission to access.

Requests and Responses

All connections should use the HTTPS protocol using the public Domain Name System (DNS) name for your subdomain. For example:

GET https://<your-subdomain>.alienvault.cloud/api/2.0/alarms

GET https://<your-subdomain>.alienvault.cloud/api/2.0/alarms/{alarmId}

A given client is limited to 100 GET and 50 POST requests per second for a USM Anywhere subdomain. When exceeding the threshold, a 429 response is returned until you are back under the rate limit.

Most endpoints in the USM Anywhere APIs support standard REST paradigms. You can either retrieve a collection or a member of a collection.

Get a Collection

Enter this request to get a collection:

GET https://<your-subdomain>.alienvault.cloud/api/2.0/alarms

You will receive this response for the request:

{
  "_links": {
    "first": {
      "href": "https://<your-subdomain>.alienvault.cloud/api/2.0/alarms?page=0&size=20&sort=timestamp_occured,desc",
      "templated": false
    },
    "self": {
      "href": "https://<your-subdomain>.alienvault.cloud/api/2.0/alarms",
      "templated": false
    },
    "next": {
      "href": "https://<your-subdomain>.alienvault.cloud/api/2.0/alarms?page=1&size=20&sort=timestamp_occured,desc",
      "templated": false
    },
    "last": {
      "href": "https://<your-subdomain>.alienvault.cloud/api/2.0/alarms?page=175&size=20&sort=timestamp_occured,desc",
      "templated": false
    }
  },
  "_embedded": {
    "alarms": [
        ... content omitted for clarity ...
    ]
  },
  "page": {
    "size": 20,
    "totalElements": 3506,
    "totalPages": 176,
    "number": 0
  }
}

Collection responses are JSON objects with a structure that allows pagination using Hypermedia as the Engine of Application State (HATEOAS)-style links. See USM Anywhere API References for the complete example.

Get a Member of a Collection

Enter this request to get a member of a collection:

GET https://<your-subdomain>.alienvault.cloud/api/2.0/alarms/{alarmId}

You will receive this response for the request:

{
	"uuid": "971918fd-a569-548a-5a80-1ffcda2a8365",
 	"has_alarm": false,
 	"needs_enrichment": true,
 	"priority": 20,
 	"suppressed": false,
 	"destinations": [],
 	"sources": [],
	"timestamp_occured": "1517932134000",
 	"events": [
		... content omitted for clarity ...
				],
 	"_links": {
		"self": {
			"href": "https://<your-subdomain>.alienvault.cloud/api/2.0/alarms/971918fd-a569-548a-5a80-1ffcda2a8365",
			"templated": false
			}
 		   }
}

Single-item responses are JSON objects that represent the resource state. See USM Anywhere API References for the complete example.

HTTP Status Codes

Responses can include one of the HTTP status codes listed in the table below, in addition to content data. Status codes are not part of endpoint descriptions because the implementation follows the HTTP standard for reporting status. However, the API reference documentation notes status codes with special significance for the endpoint, or where the USM Anywhere API specific cause differs from the following standard.