An API bucket pulls a list of values (IP addresses, domains, hashes and so on) from an HTTP endpoint at regular intervals and keeps it ready for use in alert rules. The list is filled by the logsign-bucket-worker service.
Log in to Logsign USO and then switch to Settings.
Settings > Alerts & Incidents > Buckets
Click + Bucket at the top right.
Definition
Type the bucket name in the Description field. Only letters, digits, spaces and the characters _ . - / are accepted.
Set Type to API. The API fields described below appear in the Data section only after this selection.
Under Group, select one of Behaviour, Intelligence, Asset or Other. Severity, Context, Tags and Roles are optional.
Use Authentication:
If the API does not require authentication, leave this box unchecked and continue with Method. If it does, check Use Authentication and fill in the authentication fields first.
Under Auth Headers, click Add Key-Value and enter the header exactly as the API expects it in the request. For example:
Key: Authorization
Value: Bearer {Token}
Auth Method currently offers a single option, Basic Auth. Logsign sends the headers you enter as they are and does not encode anything for you. For Basic authentication, encode username:password with base64 yourself and enter it as Key: Authorization, Value: Basic {base64 value}. For token based APIs, use the Bearer example above. Which form to use depends entirely on your API capability.
When you edit a saved bucket, header values are not shown again. Leave a value blank to keep the stored one.
Method:
Choose GET or POST according to your endpoint capability. When you select POST, a Body field appears where you can enter the request body (for example {"key": "value"}).
Content Type:
This value is sent as the Content-Type header of the request. Your options are application/json or text/plain. With application/json, a POST body is sent as JSON.
URL:
Enter the full URL of the API endpoint the list will be pulled from. In this example, a machine on the local network is used.
Params:
In this example the params field is empty. If your API endpoint expects query parameters, add them here with Add Key-Value, one key and value per row.
Response Format:
Select the format the API returns. The options are json and text, and each one shows its own field below.
Text Delimiter (if you select text):
Specifies the character that separates the values in the response. You can also use \n (new line) or \t (tab).
In our example, the API output looks like the line below, so the delimiter is a comma (,).
192.168.1.1,192.168.1.2,192.168.1.3,192.168.1.4,192.168.1.5,192.168.1.6,192.168.1.7,192.168.1.8,192.168.1.9,192.168.1.10
Json Response Key (if you select json):
Specifies the path, in dot notation, of the field whose values will be written to the bucket.
In our example, the "web_name" field is the one we want in the bucket. Because it sits inside the "blacklist_websites" array, the full path is required.
[
{
"blacklist_websites": [
{ "web_name": "1.1.1.1", "reason": "Malicious" },
{ "web_name": "1.1.1.2", "reason": "Malicious" },
{ "web_name": "1.1.1.3", "reason": "Malicious" }
]
}
]
The Json Response Key to use for this structure is blacklist_websites.web_name. Arrays are walked automatically. You can also use * for every element or a number such as 0 for a single element (for example blacklist_websites.0.web_name).
Match Type:
Select Static Key (default) for exact value matching, or IP - Network if the list contains IP addresses or networks.
Enable Pagination:
If the API returns the list in pages, check Enable Pagination and fill in the fields that appear:
- Pagination Style: Page-based (page + size), Page only (single param), Offset-based (offset + limit) or Range (from + to).
- First Param Name and Second Param Name: the parameter names your API uses. They are filled in with defaults for the selected style (for example page and size) and must be different from each other.
- Start Value (default 1), Page Size (default 100), Max Pages (default 1000) and Delay Between Pages (ms) (default 0).
Collection stops at the first empty page, at a page with fewer items than Page Size, or when Max Pages is reached.
Exclusion List:
Values you add here with Add are never written to the bucket, even if the API returns them.
Purge Period:
Sets, in seconds, how long a value stays in the bucket after the last fetch that returned it (default 3600). Values that the API no longer returns are removed once this period has passed.
After making these edits, save and wait for logsign-bucket-worker to fill the bucket.