Sensor Activity Feed User Guide
Technical Details
By default, your Sensor Activity Feed includes activity from all sensors in your Workspace from the past 24 hours and returns a JSON-encoded response.
API URL
https://api.greynoise.io/v1/workspaces/:workspace_id_goes_here:/sensor/activity
You can find your WORKSPACE_ID in the Sensor install command under the Sensors section in the Visualizer. The WORKSPACE_ID is a string of hexadecimal characters with a format of
88888888-aaaa-bbbb-cccc-121212121212
Example URL
https://api.greynoise.io/v1/workspaces/88888888-aaaa-bbbb-cccc-121212121212/sensors/activity
Authorization
Accessing the Sensor Activity Feed requires passing your API key in the header field or via an integration configuration. Your API key is under your Account page in the Viz.
HTTP header field
key: GN API KEY
API Parameters
Parameter Name | Parameter Type | Required | Description |
---|---|---|---|
format | string | No | The file format for the feed response. Valid options are json (default) or csv. |
start_time | datetime | No | Returns IP sessions starting after the indicated time in UTC using the ISO 8601 format (e.g. 2024-04-15T03:10:00Z). The default start time is set to the previous 24 hours from the time of the query. |
stop_time | datetime | No | Returns IP sessions starting before the indicated time in UTC using the ISO 8601 format (e.g., 2024-04-15T03:10:00Z). The default stop time is set to the time of the query. |
source_ip | string | No | Filter the returned IP sessions to a specific source IP address (e.g., 66.249.64.11). This is useful when investigating activity from one IP and to allow viewing only the related sessions. It is recommended to define start_time if you are searching for IP activity prior to the last 24 hours. |
persona_id | string | No | Filter the returned IP sessions to a specific sensor persona. The persona ID is a hexadecimal string, similar to 7cb37b3a-44d4-4276-85d9-b3ac2c7614f6, and can be found in the feed response. Future feed versions will simplify this filter by using the persona name. |
size | int | No | The number of results returned. The default size value is the field maximum of 10,000 sessions. |
scroll | string | No | Scroll token that is used to request the next page of sessions. The number of sessions in a page is determined by the size parameter (default 10,000). The scroll token can be retrieved from the x-scroll-id field in the HTTP response header. |
Feed Data Schema
Parameter Name | Parameter Type | Description |
---|---|---|
session_id | string | The unique session ID. In future product updates, you will be able to use the session ID to request PCAPs. |
start_time | datetime | The time this session with the source IP started in UTE using the ISO 8601 format (e.g. 2024-04-15T03:10:00Z). |
stop_time | datetime | The time this session with the source IP stopped in UTE using the ISO 8601 format (e.g. 2024-04-15T03:10:00Z). |
sensor_id | string | The unique ID of the sensor that captured this IP session. |
persona_id | string | The unique ID of the persona running on the sensor that captured this IP session. |
destination_ip | string | The IP address of the sensor that captured this session. |
destination_port | integer | The port on the sensor that captured this session. |
protocols | string list | The protocols that were identified in this session (e.g. [“tcp”, “http”]). |
source_ip | string | The IP address originating the activity that hit your sensor. |
source_port | integer | The port originating the activity that hit your sensor. |
packets | integer | The total number of network packets sent and received in this session. |
bytes | integer | The total number of bytes sent and received in this session. |
http_uri | string | The HTTP domain/path requested from your sensor by the source IP. |
API Sample Response - Single Session
{
"session_id": "240128--xcUTczYns9JCrQu9x--5J2q",
"start_time": "2024-01-28T18:16:49Z",
"stop_time": "2024-01-28T18:16:52Z",
"sensor_id": "ee629d6b-a033-43cb-8667-8b4ee7eff3a0",
"persona_id": "7cb37b3a-44d4-4276-85d9-b3ac2c7614f6",
"destination_ip": "172.31.36.96",
"destination_port": "80",
"protocols": [
"tcp",
"http"
],
"source_ip": "176.97.210.231",
"source_port": "52424",
"packets": "7",
"bytes": "2234",
"http_uri": "mydomain.com/admin.html"
}
Integrations
GreyNoise Python CLI and SDK
The latest version of the GreyNoise Python SDK and command line interface supports the Sensor Activity Feed.
Sample with JSON Output
import json
from greynoise import GreyNoise
session = GreyNoise(
api_key='<key_goes_here>',
integration_name="sdk-sensor-activity-feed-sample")
response = session.sensor_activity("<workspace_id_goes_here>")
# print feed to console
print(response)
# write feed output to file in current directory
filename = "output.json"
output = json.dumps(response, indent=4, sort_keys=True)
with open(filename, 'w') as f:
print(output, file=f)
import requests
workspace_id = "<workspace_id_goes_here>"
activity_url = "https://api.greynoise.io/v1/workspaces/" + workspace_id + "/sensors/activity"
headers = {"key": "<api_key>", "Accept": "application/json",
"User-Agent": "python-sensor-activity-feed-sample"}
params = {
}
activity_response = requests.get(activity_url, headers=headers, params=params)
if activity_response.status_code == 200:
# print feed to console
print(activity_response.json())
# write feed output to file in current directory
filename = "output.json"
with open(filename, 'w') as f:
print(activity_response.json(), file=f)
else:
print(activity_response.raise_for_status())
Sample with CSV Output
from greynoise import GreyNoise
session = GreyNoise(
api_key='<key_goes_here>',
integration_name="sdk-sensor-activity-feed-sample")
response = session.sensor_activity("<workspace_id_goes_here>", file_format="csv")
# print feed to console
print(response)
# write feed output to file in current directory
filename = "output.csv"
with open(filename, 'w') as f:
print(response, file=f)
import requests
workspace_id = "<workspace_id_goes_here>"
activity_url = "https://api.greynoise.io/v1/workspaces/" + workspace_id + "/sensors/activity"
headers = {"key": "<api_key>", "Accept": "application/json",
"User-Agent": "python-sensor-activity-feed-sample"}
params = {
"format": "csv"
}
activity_response = requests.get(activity_url, headers=headers, params=params)
if activity_response.status_code == 200:
# print feed to console
print(activity_response.text)
# write feed output to file in current directory
filename = "output.csv"
with open(filename, 'w') as f:
print(activity_response.text, file=f)
else:
print(activity_response.raise_for_status())
Manual integration
Any platform that supports a JSON or CSV feed with authentication via an API key can ingest the Sensor Activity Feed.
More official integrations will be available soon!
FAQ
Who can access my feed?
Only users in your organization’s workspace can access your sensor activity feed. The feed is populated from the sensors in your organization’s workspace.
Updated about 1 month ago