Warning: You are viewing an older version of this documentation. Most recent is here: 40.0.1

REST API¶

The REST API provides a way to interact with Stamus Central Server (SCS) and registered Probes programmatically through HTTP requests using JSON format.

Generate an Access Token¶

To access the REST-API, a user first need to generate a unique token associated to its account. The API accesses are made on the behalf of a given user.

To do that, login to SCS and go under your account settings from the header’s menu.

From the left side panel, under User Settings, select Edit Token.

If you already generated a token for this account, it will be presented in the Token field, otherwise this field will be empty.

In both cases, to generate a new token, simply click the Regeneate button at the bottom of the page and you should see the Token field updated with a hash value such as 3064d9deadbeef36436daba5531e105123ec0fee

Accessing the REST-API¶

To access the REST-API, one can choose to access it programmatically using the command cURL for example, or browse the REST-API endpoints through the Web Interface.

An access to the REST-API using command line will look like the following:

curl -X GET -k https://<SCS_ADDRESS>/rest/<ENDPOINT>/<OPTIONAL_PARAMETERS> -H 'Authorization: Token <TOKEN>' -H 'Content-Type: application/json'

To access the REST-API:

The HTTP header Content-Type: application/json must be provided
The Access Token must be sent using the HTTP header Authorization: Token <TOKEN>
The body of the request must contain JSON parameters encoded in UTF8 (if the request supports parameters)

To access the Web Interface of the REST-API, simply open your browser to https://<SCS_ADDRESS>/rest/

API usage¶

HTTP Methods¶

The REST-API allows accessing different kind of objects such as user accounts, rulesets, sources, threats and so on. Each object has its own endpoint and the following table summarize the different kind of accesses that can be made.

In this table, pk represent the Primary Key (unique identifier) of a given object.

URL	HTTP Method	JSON Parameters	Description
`/rest/<object>/`	GET		List all objects of type <object>
`/rest/<object>/`	POST	Dictionary of key/value of field	Create an object of type <object>
`/rest/<object>/`	OPTIONS		Description of the fields of the object
`/rest/<object>/<pk>/`	GET		Returns all the fields of the object
`/rest/<object>/<pk>/`	OPTIONS		Description of the fields of the object
`/rest/<object>/<pk>/`	PUT	Dictionary of key/value of field	Update the fields specified in parameters
`/rest/<object>/<pk>/`	PATCH	Dictionary of key/value of field	Like PUT, but skips checking for the presence of `required` fields
`/rest/<object>/<pk>/`	DELETE		Deletes the object
`/rest/<object>/<action>/`	GET/POST	Dictionary describing the action (on POST request)	Performs an <action> related to <object>
`/rest/<object>/<pk>/<action>/`	GET/POST	Dictionary describing the action (on POST request)	Performs an <action> on the object

Hint

Most queries accept an optional dictionary with a comment key to be stored in the actions history.

List Parameters¶

When using the GET method to retrieve a list of objects, the following parameters may come handy to navigate the data retrieved. Those parameters are also available through the Web Interface from the Filters dropdown.

Type	Parameter	Description
Pagination	`page=<page_no>`	Specify the page number to retrieve. Each call returns at most 30 results
Ordering	`ordering=<field>`	Results can be sorted ascendingly by specifying the field name, or descendingly by preceeding the field name with `-`. Multiple terms can be combined such as `ordering=name,-pk`
Searching	`search=<word>`	List of comma-separated or space-separated keywords. Results returned contain all keywords specified, matched case insensitively.
Filtering	`<field>=<value>`	Filtering allows to filter by field on exact matches (for character strings, the whole text has to match, case sensitive). Multiple filters can be combined.

Accessing Host ID¶

Stamus’ unique capability Host ID is also accessible through the REST-API and when used, one gets the very same information as shown in Stamus Central Server.

The following endpoint, /rest/appliances/host_id/<IP_ADDRESS>, will retrieve all Host ID information available for the specified IP address.

Examples¶

cURL¶

curl -X GET -k https://<SCS_ADDRESS>/rest/appliances/host_id/<IP_ADDRESS> -H 'Authorization: Token <TOKEN>' -H 'Content-Type: application/json'

For example, if your SCS IP address is 10.11.0.12 and you want to get more information on 10.0.0.101, the query will look like the following:

curl -X GET -k https://10.11.0.12/rest/appliances/host_id/10.0.0.101 -H 'Authorization: Token 3064d9deadbeef36436daba5531e105123ec0fee' -H 'Content-Type: application/json'

Python¶

import requests
headers = {'Authorization': 'Token <TOKEN>', 'Content-Type': 'application/json'}
res = requests.get('https://<SCS_ADDRESS>/rest/appliances/host_id/<HOST_IP>', params={}, verify=False, headers=headers)
print(res.text)

Direct Link¶

You could also use a direct web url to open up HostID web GUI page for an IP:

https://<SCS_ADDRESS>/rules/hunt?session=temporary&page=HOSTS_LIST&ip=<IP_ADDRESS>

For example, if your SCS IP address is 10.11.0.12 and you want to get more information on 10.0.0.101, the link should look like the following:

https://10.11.0.12/rules/hunt?session=temporary&page=HOSTS_LIST&ip=10.0.0.101

Objects relations¶

SCS and probes¶

A few addresses describe probes, with slight differences that can be useful depending on the use case:

/rest/appliances/stamus_appliance/ contains all Stamus probes with parameters writable.
/rest/appliances/stamus_appliance_template/ contains all Stamus probe templates with parameters writable.
/rest/appliances/suricata_appliance/ contains all Suricata probes with parameters writable.
/rest/appliances/appliances/ lists all Stamus probes and Suricata probes read-only (it mainly contains fields common to Stamus and Suricata probes, plus a type field which can be either Stamus or Suricata).
/rest/appliances/stamus_device/ contains all Stamus probes and SCS read-only (SCS always has a pk of 1). stamus_appliance objects contain a stamusdevice_id field that corresponds to the primary key of the stamus_device object.

Primary keys of stamus_appliance, suricata_appliance and appliance objects are shared. That is, the pk of an appliance object can be combined to the type field to find the address of the corresponding full object.

Network interfaces¶

Network interfaces objects are tied to Stamus probes and probes templates. Interfaces are added by setting the interfaces field of stamus_appliance and stamus_appliance_template. This field can be set with a list of interfaces defined by a dictionary {"name": "eth0", "active": true/false}. When reading the interfaces field, the interfaces dictionaries will contain the pk of the interface object available at /rest/appliances/network_interface/. Interfaces can be deleted by a DELETE to the network_interface object, or by changing the interfaces fields of the probe or template.

Protocols¶

Protocols work the same way as interfaces using the protocols fields of a probe or a template.

Templates¶

Stamus probes (and templates) can inherit a template by setting the parent_tmpl field of a stamus_appliance to the value of the pk of the stamus_appliance_template. Subsequent modifications to the template are then applied automatically to its children objects. To override a field of an object that inherits from a template, it is necessary to list it in the overriden_fields field of this object.

Inheritance works the same way for protocols and interfaces.

REST API¶

Generate an Access Token¶

Accessing the REST-API¶

API usage¶

HTTP Methods¶

List Parameters¶

Accessing Host ID¶

Examples¶

cURL¶

Python¶

Direct Link¶

Objects relations¶

SCS and probes¶

Network interfaces¶

Protocols¶

Templates¶

User actions¶