- October 26, 2021: Added shortcuts to sections.
- May 11, 2021: To allow for faster identification of infected machines, destination IP addresses of Compromised System findings for your organization are now unmasked.
- February 15, 2017: Published.
https://alerts.api.bitsighttech.com/stream
The Bitsight Infection Alerts API provides a live stream of infection data through a portion of the Cyberfeed API from AnubisNetworks, a Bitsight company. This allows developers to integrate real-time infection data into existing systems or build new applications around the infection data.
Access to the Infections Alerts data requires an API token [infection_alerts_API_token]. This is separate from your Bitsight API token and will be provided to you by our support staff.
Getting Infection Events
Bitsight Infection Alert data is sent from the server in JSON format.
The easiest and most common way to start downloading the data through the API is to use curl on the command line. This will download streaming data each time the server has a new event. Add the “-s” option (silent) to hide download statistics while receiving data.
curl "https://alerts.api.bitsighttech.com/stream?key=infection_alerts_API_token"
Add the “-N” option to skip buffering: “In normal work situations, curl will use a standard buffered output stream that will have the effect that it will output the data in chunks, not necessarily exactly when the data arrives. Using this option will disable that buffering.”
curl -sN "https://alerts.api.bitsighttech.com/stream?key=infection_alerts_API_token"
See the curl online manual for more usage flags related to curl.
Testing
Set the maxbytes parameter to 1 (maxbytes=1). Append the parameter to the end of your request, like so:
curl "https://alerts.api.bitsighttech.com/stream?key=infection_alerts_API_token&maxbytes=1"
This will exit as soon as a single event (over 1 byte) is returned.
Stream Limiting
If you want to receive a certain amount of data, up to a certain quantity or after a time, use one of the following options:
-
maxbytes=xx - Set a byte limit (integer) so that once you receive x number of bytes, the connection will close. The API may send slightly more than you request if it means sending a complete event rather than half an event.
-
maxtime=xx - Set a time limit (integer) in milliseconds and then close the connection after that amount of time has passed. As with maxbytes, the API may send slightly more data just before it closes the connection.
The following example sends a request which closes the connection after 3 seconds:
curl "https://alerts.api.bitsighttech.com/stream?key=abcdefg12345678&maxtime=3000"
Event Data
Server Response & Headers
The Stream Platform replies right away with a response like:
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Content-Type: text/json;charset=utf-8
Set-Cookie: s=(<cookie value>)
Date: Mon, 21 Mar 2016 13:31:03 GMT
Connection: close
{"a":"foo","b":123}\r\n{"a":"foo","b":123}\r\n(...)
The Stream Platform will reply with 200 OK and all headers as soon as the request is accepted, but the first body chunk may occur only later when the first event becomes available.
Tip: To help make the terminal output more human-readable, pipe your request to jq (part of most Linux distribution package repositories; Mac/Windows users visit ./jq), like so:
curl "https://alerts.api.bitsighttech.com/stream?key=infection_alerts_API_token" | jq .
Example Response
{
"env": {
"request_method": "POST",
"remote_port": "61966",
"server_name": "<a-sinkhole-server-name>",
"server_port": "80",
"remote_addr": "xxx.xxx.xxx.xxx",
"server_addr": "xxx.xxx.xxx.xxx"
},
"_ts": 1234567890,
"trojanfamily": "Rerdom",
"_geo_env_remote_addr": {
"country_name": "United States"
}
}
Response Attributes
| Field Name | Value |
|---|---|
| trojanfamily | Identifies the name of the malware which caused the event. |
| env.remote_address | The event originated at this IP address. |
| env.server_addr | The malware sent communications to this IP address. |
| env.server_name | A Bitsight sinkhole server, which is able to detect incoming malware. |
Applying Filters
You can filter events by certain fields and information in those fields by adding filters to your request. The name of the filter is the target field. You may filter by any field returned in the JSON objects from the server and add what values you like. You may add multiple filters to your query.
Filters are written as “f._fieldname”. For instance if you want to find onlymalware events caused by Genieo infections, you would use the following:
curl "https://alerts.bitsighttech.com:8080/stream?key=abcdefg12345678&f._trojanfamily=Genieo"
Connector
The Generic CEF integration guide (connector) is available to help convert the JSON stream from the API into the formats and data structures required to integrate into your existing SIEM and data processing solutions. It’s a CEF/LEEF connector that’s configured to produce CEF for generic integrations and supports the HP format.
If you need connectors for your systems, notify Bitsight Support of your requirements.