Introduction

Each of the URLs described in this document is accessed on port 3000 and has a prefix of /hx/api/v3.

The Trellix Endpoint Security (HX) API attempts, as much as possible, to conform to the HTTP/1.1 protocol RFC 2616, especially in regards to:

Section 9—Method Definitions
Section 10—Status Code Definitions
Section 14—Header Field Definitions

Endpoint Security (HX) API also uses the following:

RFC 5789—PATCH Method for HTTP
RFC 2518 Section 8.9—WEBDAV MOVE Method for HTTP

This section covers the following topics:

Content type

All request and response content should be in JSON using the application/json media format. If you include an Accept header in the request, the request must include */*, application/*, or application/json. Otherwise, the server responds with a 406 Unacceptable response.

If you include a Content-Type header in a request, the request must be application/json. Any other type will result in a 415 Unsupported Media Type response.

For PUT, POST, and PATCH requests, the request body is a JSON object representing the changes being made to a resource. Unknown fields in the request result in an error code of 422 (Unprocessable Request).

All responses are formatted as JSON and contain, at a minimum, a “message” field:

{ message: 'OK' }

Other fields that might be returned are details, data, and meta:

{ message: 'OK', details: [], data: {}, meta: {} }

If the response contains a list of entities, the array of entities is found in the data object:

{ message: 'OK', details: [], data: { total: 0, entries: [] }, meta: {} }

SSL certificate

All communication with the API is done through an SSL connection. You must have a valid SSL certificate on your Endpoint Security (HX) server.

Concurrency

Sometimes automated processes are used to manipulate records that might also be modified by other users. The Endpoint Security (HX) API uses the HTTP/1.1 standard ETag and If-Match headers to allow client processes to account for concurrent updates to existing records. All records that support concurrency checking are returned from the server containing a _revision property. In addition, when individual records are retrieved from the server, the server response includes the ETag header. The ETag for an individual record is the same as that recordʼs _revision field. All ETags served by the Endpoint Security (HX) API are strong ETags according to RFC 2616 Section 13.3.3; however, Endpoint Security (HX) ETags do not track statistical or summary fields.

Individual records

Individual records that support concurrency checking are returned with both the _revision property and the ETag header set. Subsequent requests that manipulate that record can include the If-Match header. If the If-Match header is included, the server confirms that the current _revision property matches before performing the update. If the If-Match value does not match the current _revision, a concurrency error has occurred, and the server returns an HTTP 412 status code with an error message.

If the If-Match header is missing or the If-Match value is set to “*”, concurrency errors are ignored.

If the update is successful, a new ETag header is returned in the response.

Syntax

Response header:

ETag: "<record _revision>"

Response body:

{
   message: 'OK',
   data: {
	. . .
	_revision: '<record _revision>'
   }
}

Request header:

If-Match: *|"<record _revision>"

Examples

#get a record
curl -i https://localhost:3000/hx/api/v3/examples/1 > output.txt
         
#parse the ETag header
eTag="$(grep "^ *ETag *:" output.txt)"
eTag="${eTag#*: }"
         
#update the record.  This will return a 412 status if ETag is no longer #valid.
curl -X PUT https://localhost:3000/hx/api/v3/examples/1 -H "If-Match: ${eTag}" -d '{"sample":"data"}'

Lists

Certain resources in the API return a list of data instead of an individual record. No ETag header is returned in the server response for these URLs; however, the _revision property is included in the JSON for each record included in the list. This _revision can be used as the ETag for a subsequent update to that record.

Syntax

Response body:

{
   "message": "OK",
   "details": [],
   "data": {
	total: <INT>,   // total number of records ignoring limit or offset
       query: {},      // any search or filter parameters that were applied.  example: query: { search: 'a', enabled: true }
       sort: {},       // sort order that was applied to these results. example: sort: { fieldA: 1, fieldB: -1 }
       offset: <INT>,  // zero based record offset for pagination applied to 
			// these results
       limit: <INT>,   // number of records per pagination applied to these 
			// results.
       . . .
       "entries": [
           . . .
           { . . . "_revision": "<revision>" }
       ] 
   }
}

Examples

# For this example, the output of /examples returns records with an _id,  
# value, and _revision

# Note: this example uses jq to parse json (jq -http://stedolan.github.io/jq)
# Other json parsers may be substituted (such as python, node, jsawk, and so 
# on).

# Get a list of data
curl https://localhost:3000/hx/api/v3/examples?offset=0&limit=10 > output.txt
cat output.txt

#{ 
#    "message":"OK",
#    "details":[],
#    "data":{
#        "total":2,
#        "query":{},
#        "sort":{"value":1},
#        "offset":0,
#        "limit": 10,
#        "entries":[
#            {"_id":1,"value":"A","_revision":"20131211222718729465100019"},
#            {"_id":2,"value":"B","_revision":"20131212003007234741100037"}
#        ]
#    }
#}

# Parse, sort, and extract the data, then update it using 
# the If-Match header.
while read id; do
	read revision
	read value
	curl -X PUT https://localhost:3000/hx/api/v3/examples/${id} \
		-H "If-Match: ${revision}" \
		-d "{\"value\":\"${value}2\"}"
done < <(jq < output.txt -c -r '.data.entries[] | ._id, ._revision, .value')

If-None-Match

For resources that support concurrency checking, use the If-None-Match header to determine if a record has changed. If the If-None-Match header is provided and the recordʼs _revision matches the value provided, the server returns a 304 NOT MODIFIED (for GET and HEAD methods) or a 412 PRECONDITION NOT MET (for all other methods) response. An asterisk (*) matches all _revisions. Using an asterisk on PUT requests prevents you from inadvertently modifying existing resources instead of creating a new resource.

Syntax

Request header:

If-None-Match: *|"<record _revision>"

Examples

#get a record
curl -i https://localhost:3000/hx/api/v3/examples/1 > output.txt
   
#parse the ETag header
eTag="$(grep "^ *ETag *:" output.txt)"
eTag="${eTag#*: }"
   
#update the record.  This will return a 304 status if ETag is still valid; #otherwise, it returns the record.
curl https://localhost:3000/hx/api/v3/examples/1 -H "If-None-Match: ${eTag}"

JSON document structure

Note

JSON requires slashes to be escaped. For example, if a file or directory path contains “\”, you must use “\\“ instead. In addition to escaping JSON slashes, if you are using a regular expression, you have to double escape again. Then to search for .xls files in the \Temp\ subdirectory, you would submit the following:

*\\\\Temp\\\\.xls

You must use standard regex expressions, including regex escaping techniques. (Specifying '\\\\' matches a single '\\' and specifying '\\' matches ' '.) The following example matches all files in any subdirectory:

*

The following example matches all the *.xls files in any subdirectory:

*\\.xls

The following example matches *.xls files in a subdirectory named Temp (note that backslashes must be escaped):

*\\\\Temp\\\\.*\\.xls

Reference fields

Use reference fields when referring to a specific document from another document within the Endpoint Security (HX) API. Generally, the _id and the URL of the document are included. You can include additional fields when appropriate.

uri_name

Some records, such as indicators and indicator categories, have a uniquely identifying field called uri_name. The uri_name determines how that resource is represented in a URL, which indicates the resource’s location. Use uri_name to store an external identifier. This field allows API clients to directly access the resource using its own identifiers, instead of discovering or storing the Endpoint Security (HX) serverʼs internal identifier. In most cases, the uri_name is accompanied by a display_name that allows you to override what is displayed in the Endpoint Security (HX) Web UI for that record. If the display_name is omitted, the uri_name is displayed in the Endpoint Security (HX) Web UI.

Any string value is legal in the uri_name field. The uri_name field is a case-sensitive field.

Moving resources

The uri_name field indicates a recordʼs location in the API. The proper way to change a recordʼs location is to issue a request using the MOVE method. The MOVE method requires a Destination HTTP header that contains the new location of the resource. The destination must be the partial URL of the new location.

The Endpoint Security (HX) API does not support the Overwrite header. The MOVE request fails if the destination resource already exists.

The API does not support the Depth header. The Depth is always infinite.

Examples

#set up two categories and two indicators.
curl -X PUT https://localhost:3000/hx/api/v3/indicator_categories/category_a -d '{}'
curl -X PUT https://localhost:3000/hx/api/v3/indicator_categories/category_b -d '{}'
curl -X PUT https://localhost:3000/hx/api/v3/indicators/category_a/indicator_a -d '{}'
curl -X PUT https://localhost:3000/hx/api/v3/indicators/category_a/indicator_b -d '{}'
         
#example: rename an indicator
curl -X MOVE https://localhost:3000/hx/api/v3/indicators/category_a/indicator_a -H "Destination: /category_a/indicator_c"
         
#example: move an indicator to a different category
curl -X MOVE https://localhost:3000/hx/api/v3/indicators/category_a/indicator_c -H "Destination: /category_b/indicator_c"
         
#example: rename a category
curl -X MOVE https://localhost:3000/hx/api/v3/indicator_categories/category_a -H "Destination: /category_c"
         
#example: move and rename an indicator.
curl -X MOVE https://localhost:3000/hx/api/v3/indicators/category_c/indicator_b -H "Destination: /category_b/indicator_d"
         
#category_c (originally category a) is now empty.  We can delete it.
curl -X DELETE https://localhost:3000/hx/api/v3/indicator_categories/category_c
         
#category_b now contains indicator_c and indicator_d (originally indicator_a and indicator_b)
curl https://localhost:3000/hx/api/v3/indicators/category_b

Ports

The requests in this document include the port number, for example:

GET https://<IP_address>:<port_number>/hx/api/v3/hosts

Use port 3000 on physical appliances and virtual servers. You do not need to specify a port number on cloud servers or Endpoint Security (HX) servers in a Helix environment.

HTTP methods

The Endpoint Security (HX) API supports several HTTP methods. In general, HTTP/1.1 protocol RFC 2616 specifications are followed. Not all methods are available on all routes.

GET

The GET method retrieves a resource or list of resources. Conditional GET requests using If-Match and If-None-Match are supported for resources with ETags. The GET method supports sorting and filtering lists of results.

Sorting results

To sort a list of results by a specified field, use the following format:

sort=<field>[+<asc|desc>]

For example:

```
sort=_id
```
```
sort=_id+asc
```
```
sort=_id+desc
```

You can use the following to sort results in ascending order:

```
1
```
```
a
```
```
asc
```
```
ascending
```

You can use the following to sort results in descending order:

```
-1
```
```
d
```
```
desc
```
```
descending
```

You can sort by multiple fields. For example:

sort=_id&sort=timestamp+desc

This example sorts the results first by _id in ascending order. Then the results are sorted by timestamp in descending order.

The fields that can be used for sorting are described in the “Query Parameters” section for each endpoint that supports sorting.

Filtering results

To narrow the list of results to a specified field value, use the following format:

<filter_field>=<filter_value>

where filter_field is a field to use as a filter and filter_value is the value for that field.

The available filters are described in the “Query Parameters” section for each endpoint that supports filters.

POST

The POST method creates a new resource and assigns it a new identifier. Alternatively, it executes an action (such as a transition of state).

PUT

The PUT method creates or overwrites a resource with a known identifier. If-Match and If-None-Match are supported for resources with ETags.

Use If-Match: * to force overwrite-only mode.
Use If-None-Match: * to force create-only mode.
Use If-Match: <ETag> to enforce concurrency protection. See Concurrency for more details.

If the resource already exists and all preconditions pass (such as If-Match and If-None-Match), a PUT request overwrites the resource and sets any unspecified editable fields back to their default values. Reference, Immutable, and Read-only fields retain (or recalculate) their values.

Because PUT overwrites all editable fields of a resource, PATCH is generally the preferred method of updating an existing resource.

PATCH

The PATCH method updates only the specified fields for a resource. This method is different from PUT, which overwrites and resets all editable fields. If-Match and If-None-Match are supported for resources with ETags.

MOVE

For resources containing the uri_name field, MOVE changes the uri_name of the specified resource (thus changing the URL used to reference that resource). MOVE can also move a child resource to a new parent. See Reference fields for more information about the uri_name field. If-Match and If-None-Match are supported for resources with ETags.

DELETE

The DELETE method deletes the resource. If-Match and If-None-Match are supported for resources with ETags.

Legal tokens and types

The following table lists legal tokens and the corresponding data types.

Note

These event tokens and types might not be supported by all Endpoint Security Agent (HX)s.

Event tokens	Types
addressNotificationEvent/address	text
addressNotificationEvent/timestamp	text
fileWriteEvent/fullPath	text
fileWriteEvent/devicePath	text
fileWriteEvent/drive	text
fileWriteEvent/eventReason	text
fileWriteEvent/filePath	text
fileWriteEvent/fileName	text
fileWriteEvent/fileExtension	text
fileWriteEvent/size	integer, range
fileWriteEvent/md5	md5
fileWriteEvent/pid	integer, range
fileWriteEvent/process	text
fileWriteEvent/processPath	text
fileWriteEvent/parentProcessPath	text
fileWriteEvent/parentPid	integer, range
fileWriteEvent/openTime	text
fileWriteEvent/openDuration	text
fileWriteEvent/writes	integer, range
fileWriteEvent/numBytesSeenWritten	integer, range
fileWriteEvent/lowestFileOffsetSeen	integer, range
fileWriteEvent/dataAtLowestOffset	text
fileWriteEvent/textAtLowestOffset	text
fileWriteEvent/closed	text
fileWriteEvent/timestamp	text
fileWriteEvent/username	text
regKeyEvent/pid	integer, range
regKeyEvent/path	text
regKeyEvent/process	text
regKeyEvent/processPath	text
regKeyEvent/hive	text
regKeyEvent/keyPath	text
regKeyEvent/originalPath	text
regKeyEvent/eventType	integer
regKeyEvent/valueName	text
regKeyEvent/valueType	text
regKeyEvent/value	text
regKeyEvent/text	text
regKeyEvent/timestamp	text
regKeyEvent/username	text
ipv4NetworkEvent/remoteIP	text
ipv4NetworkEvent/remotePort	integer, range
ipv4NetworkEvent/localIP	text
ipv4NetworkEvent/localPort	integer, range
ipv4NetworkEvent/protocol	text
ipv4NetworkEvent/pid	integer, range
ipv4NetworkEvent/process	text
ipv4NetworkEvent/processPath	text
ipv4NetworkEvent/timestamp	text
ipv4NetworkEvent/username	text
imageLoadEvent/fullPath	text
imageLoadEvent/devicePath	text
imageLoadEvent/drive	text
imageLoadEvent/filePath	text
imageLoadEvent/fileName	text
imageLoadEvent/fileExtension	text
imageLoadEvent/pid	integer, range
imageLoadEvent/process	text
imageLoadEvent/processPath	text
imageLoadEvent/parentPid	integer, range
imageLoadEvent/timestamp	text
imageLoadEvent/username	text
dnsLookupEvent/hostname	text
dnsLookupEvent/pid	integer, range
dnsLookupEvent/timestamp	text
dnsLookupEvent/process	text
dnsLookupEvent/processPath	text
dnsLookupEvent/username	text
processEvent/eventType	text
processEvent/pid	integer, range
processEvent/processPath	text
processEvent/process	text
processEvent/parentPid	integer, range
processEvent/parentProcessPath	text
processEvent/parentProcess	text
processEvent/timestamp	text
processEvent/username	text
processEvent/startTime	text
processEvent/processCmdLine	text
processEvent/md5	md5
urlMonitorEvent/hostname	text
urlMonitorEvent/requestUrl	text
urlMonitorEvent/urlMethod	text
urlMonitorEvent/userAgent	text
urlMonitorEvent/httpHeader	text
urlMonitorEvent/remoteIpAddress	text
urlMonitorEvent/remotePort	integer, range
urlMonitorEvent/localPort	integer, range
urlMonitorEvent/pid	integer, range
urlMonitorEvent/process	text
urlMonitorEvent/processPath	text
urlMonitorEvent/username	text
urlMonitorEvent/timeStamp	text

API error codes

While using the Endpoint Security (HX) API, you might encounter various error codes.

Error	Description
1000	This error is unknown.
1001	The object could not be created.
1002	The object could not be read. Check if the object exists and that you belong to the correct authorization group, have the correct active license, and have the correct role.
1003	The object could not be updated.
1004	The object could not be deleted. Check if the object exists.
1005	The object was not found. Check if the object exists.
1006	There is a conflict. The object might already exist, the correct access permission is needed, a dependency check failed, or the field values in a POST, PUT, or PATCH request are contradictory.
1007	The request body is missing required information.
1008	The prerequisite has not been met.
1009	There was a conflict because the record being saved has been changed by another user since the previous GET request.
1010	There was a conflict when trying to delete an object. Check if the object exists.
1011	There was a conflict because the object is read only.
1012	No matching ETag was found when the If-Match HTTP request header was used.
1013	There was a conflict because matches were found when the If-None-Match HTTP request header was used.
1014	There was a conflict because the area contains an object.
1015	There was a conflict in the state of an object.
1016	Too many results were returned.
1017	The concurrency limit was reached.
1018	There was a mismatch of object types.
1019	A dependency was not found.
1100	The login name already exists.
1101	The user does not have the correct privileges to perform the operation.
1102	The action is forbidden.
1103	The token is not supported.
1104	The incorrect authorization scheme was used with the HTTP authorization request header.
1105	Authentication failed.
1106	Updates cannot be made because the user account is locked.
1107	A user account was successfully locked.
1150	The requested operation requires a specific license.
1151	The feature was disabled.
1200	The start date occurs after the end date.
1201	The date range and interval are too large.
1300	The connection has timed out because it was idle for too long.
1301	An unexpected condition was encountered.
1302	The document type specified in the Accepts HTTP request header is not supported.
1303	The document type specified in the Content-Type HTTP request header is not supported.
1304	The request body could not be parsed.
1305	The header is incorrectly formatted.
1306	The ETag was incorrectly formatted.
1307	The ETag is ambiguous.
1308	The HTTP method used is not supported.
1309	The request body is too large.
2000	A request validation routine failed for unknown reasons.
2001	A required field was missing from the request.
2002	The minimum length of a string field was not met.
2003	The maximum length of a string field was exceeded.
2004	The format of a string field was incorrect.
2005	The required dependencies of a specific field included in the request are missing.
2006	The two values provided must be the same.
2007	The wrong type was specified.
2008	The data type of a provided field was incorrect. For example, the date type of a field was an object instead of a string.
2009	The minimum number of items for a JSON array was not met.
2010	The field requires one of a predefined, case-sensitive list of values.
2011	Two conflicting fields were provided. Remove one of the fields.
2012	The range was empty.
2013	The number exceeded the maximum.
2014	The number did not reach the minimum.
2015	Additional or unknown properties are not allowed.
2016	A PATCH request included no fields that could be modified.
2017	The property is read only.
2018	The property cannot be changed.
2019	The format was incorrect.
2020	The range was incorrect.
2021	The Content-Type was not set to application/json, but the request body might be JSON.
2022	No body was included in the request.
2023	The minimum value was greater than the maximum value.
2024	The field requires one of a predefined, case-insensitive list of values.
3000	Generic host set error.
3001	A bad host set dependency exists.
3002	A circular host set dependency exists.
3501	The attempt to retrieve host set query counts timed out.
3502	There was an error resolving host set membership.
4000	The operation was successful.
5001	The prerequisite was not executed before containment.
5002	The containment state of the agent has successfully been changed.
5003	The containment driver is too large.
5004	There was an unexpected problem with the containment.
5005	The containment driver URI is invalid.
5100	Restricted threat category
5101	Unresolved threat category
5102	The condition was skipped.
5400	The acquisition types are missing.
5401	The XML was invalid.
5402	The audit was not supported.
5403	The audit parameter was not supported.
5404	The value type was not supported.
5405	The value was not supported.
5406	The audit already exists.
5407	The audit parameter already exists.
5408	The setting is not supported.
5409	The command is invalid.
5410	The type of the audit parameter is not supported.
5411	The browser was added to the current audit.
5412	The browser was added to previous audits.
5413	The filter is not supported.
5414	The audit is not supported for this platform.
5415	The audit parameter is not supported for this platform.
5416	The audit was remapped for this platform.
6001	The manifest is incorrect.
6002	The provided agent .cms package could not be verified.
6003	The agent version is incorrect.
6004	The agent version was not found.
6005	The installer package was not created.
6006	No file was uploaded.
6007	The package was malformed.
6008	The object was not uploaded.
6009	The upload type was invalid.
7000	The query results were unexpected.
7001	There was an unexpected database issue.
7100	The URL was changed.
7101	The sort was ignored.
7102	The sort field was unknown.
7103	The sort field is not supported.
7104	The Destination HTTP request header was not provided.
7105	The destination is illegal.
7106	The destination already exists.
7108	The destination was not correctly formatted.
7109	An empty body was expected.
7110	The endpoint is deprecated.
7111	The action is not supported.
8001	The intel type is already being processed.
8002	The intel version is incompatible.
8003	The intel is partially supported.
9001	The system resource could not be reloaded.
11000	The acquisition feature has been disabled by the administrator.
12000	There was an unknown error while trying to delete a set of alerts.
13000	There is an error in the SF status configuration settings.
13001	The SF status configuration settings were not found.
13002	The SF tasker node settings were not found.
13003	The SF tasker node server connection was refused.
13004	The SF tasker node server agents were not found.
13005	There was a error with the SF tasker node server.
14000	The disk has no more space for acquisitions.
14001	The disk threshold has been reached.
15000	A triage update is required.