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.