AlienVault® APIs

AT&T Cybersecurity publishes Application Programming Interfaces (APIs) for USM Anywhere™ (version 2.0) and USM Central™ (version 1.1). These Representational State Transfer (REST) APIs provide a programmatic interface that enables you to access your USM Anywhere or USM Central data directly from your own applications and extensions. The AlienVault 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.

Edition: Access to the AlienVault API is limited to Standard and Premium accounts.

See https://www.alienvault.com/pricing for more information about the feature and data support provided by each of the USM Anywhere editions.

Authentication

The AlienVault APIs use Open Authorization (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 AlienVault APIs.

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

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"
}

Note: The OAuth access token expires after 15 minutes. When or before it expires, you must use the oauth/token endpoint to re-authenticate and get a new token.

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

Authorization: Bearer <access_token>

Requests and Responses

All connections should use the HTTPS protocol on port 443 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 or USM Central subdomain. When exceeding the threshold, a 429 response is returned until you are back under the rate limit.

Most endpoints in the AlienVault 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 colleciton:

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

Important: The AlienVault APIs can only access alarm and event data stored in the local system; raw logs in cold storage are not accessible by the API calls.

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}

Important: The AlienVault APIs can only access alarm and event data stored in the local system; raw logs in cold storage are not accessible by the API calls.

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": [],
 	"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 AlienVault API specific cause differs from the following standard.

Standard HTTP status codes and descriptions
Status Code Generalized Description
200 Request completed successfully.
201 Create request completed successfully.
400 Request error. See response body for details.
401 Authentication failure, invalid access credentials.
403 Insufficient permission.
404 Requested endpoint does not exist.
409 Invalid operation for this endpoint. See response body for details.
429 Rate limit for this operation has been reached.
500 Unspecified internal server error. See response body for details.