Sign in

v1

latestOpenAPI 3.1.0Elastic 2.02026-07-179371211.2 KB
Grid

Node Check-in

Used by Security Onion agent nodes to check-in with their current metrics and request any pending jobs assigned to it. It is not recommended to make calls to this API endpoint, as this is intended to be used exclusively by official Security Onion nodes only.

post/connect/node

Request body

addressstring

The IP address of this node

captureLossPctnumber

The current percentage capture loss experienced by the network, if applicable to this node

connectionStatusstring

The connectivity status between this node and the manager node: unknown, ok, fault

consumptionEpsinteger

The events per second (EPS) consumed by this node

cpuUsedPctnumber

The current CPU usage of the node, across all cores

descriptionstring

The node's optional description

diskTotalNsmGBnumber

Total size, in gigabytes, of the NSM data disk/partition

diskTotalRootGBnumber

Total size, in gigabytes, of the root operating system disk/partition

diskUsedElasticGBnumber

The disk space used, in gigabytes, on the backend data store system (Elasticsearch)

diskUsedInfluxDbGBnumber

The disk space used, in gigabytes, on the metrics data store system (InfluxDB)

diskUsedNsmPctnumber

Percentage usage of the NSM data disk/partition

diskUsedRootPctnumber

Percentage usage of the root system disk/partition

epochTimestring

The node's data epoch; this is the date and time of the oldest known PCAP data available to the node

eventstoreStatusstring

The event storage status; this refers to the backend status, such as Elasticsearch: unknown, ok, fault

failedEventsinteger

The count of failed events (currently not in use)"

fpsEnabledinteger

Indicates whether federal information processing standards are enabled on this node

gmdEnabledinteger

Indicates whether guaranteed message delivery is enabled on this node

gridIdstring

Grid ID, used for subgrids

highstateAgeSecondsinteger

How long ago, in seconds, the last highstate completed on this node

idstring

The node ID

imageBackstring

The Security Onion appliance back image, if available

imageFrontstring

The Security Onion appliance front image, if available

ioWaitPctnumber

The IO wait percentage for this node

lksEnabledinteger

Indicates whether disk encryption is enabled on this node

load15mnumber

The node's 15-minute load metric

load1mnumber

The node's 1-minute load metric

load5mnumber

The node's 5-minute load metric

memoryTotalGBnumber

Total size, in gigabytes, of the system memory, or RAM

memoryUsedPctnumber

Percentage usage of the system memory, or RAM

metricsEnabledboolean

Indicates whether the metric subsytem is available

mgmtMacstring

The MAC address assigned to this node's management NIC

modelstring

The Seurity Onion appliance model, or N/A if this is not an official Security Onion appliance

nonCriticalNodeboolean

Indicates whether this node is a non-critical node of the overall grid. An examples of a non-critical nodes is a desktop node

onlineTimestring

The date and time when this node first came online; best estimate based on the node's apparent file system age

osNeedsRestartinteger

Indicates whether the node needs to be restarted to apply kernel updates: 0 = no restart needed, 1 = needs restarted

osUptimeSecondsinteger

The number of seconds that the operating system has been "up" since its last reboot

pcapDaysnumber

The number of days of PCAP storage available to this node

processJsonstring

The status of each individual process on the node, in JSON format

processStatusstring

The overall status of the node's Security Onion processes: unknown, ok, fault

productionEpsinteger

The events per second (EPS) produced by this node (not currently populated)

raidStatusstring

The raid status, if applicable: unknown, ok, fault

redisQueueSizeinteger

The backlog of events waiting to be processed

rolestring

The node's assigned role; assigned during node setup

statusstring

The current state of the node: unknown, ok, fault, pending, restart

stenoLossPctnumber

The current percentage packet loss experienced by Stenographer, if applicable to this node

suriLossPctnumber

The current percentage packet loss experienced by Suricata, if applicable to this node

suriRulesFailedinteger

The number of Suricata rules that failed to load, if applicable to this node

suriRulesLoadedinteger

The number of Suricata rules currently loaded, if applicable to this node

suriRulesReloadTimestring

The timestamp of the last Suricata rule reload, if applicable to this node

suriRulesStatusstring

The status of Suricata rule loading: ok, unknown

swapTotalGBnumber

Total size, in gigabytes, of the system swap memory

swapUsedPctnumber

Percentage usage of the system swap memory

trafficManInMbsnumber

The inbound traffic rate, in megabytes per second, to this node's management network interface

trafficManOutMbsnumber

The outbound traffic rate, in megabytes per second, from this node's management network interface

trafficMonInDropsMbsnumber

The inbound traffic packet drop rate, in megabytes per second, to this node's monitor network interface

trafficMonInMbsnumber

The inbound traffic rate, in megabytes per second, to this node's monitor network interface

updateTimestring

The date and time when this node was most recently updated"

uptimeSecondsinteger

The number of seconds since this node first came online and joined the grid

versionstring

The version of Security Onion installed on this node

zeekLossPctnumber

The current percentage packet loss experienced by Zeek, if applicable to this node

Example request

{
  "address": "4.3.2.1",
  "captureLossPct": 24.0605,
  "connectionStatus": "fault",
  "consumptionEps": 110,
  "cpuUsedPct": 5.0035165275079265,
  "description": "East coast sensor",
  "diskTotalNsmGB": 772.7962808320001,
  "diskTotalRootGB": 314.41920000000005,
  "diskUsedElasticGB": 386.948,
  "diskUsedInfluxDbGB": 1.922272,
  "diskUsedNsmPct": 84.28509193998036,
  "diskUsedRootPct": 20.944604461814038,
  "epochTime": "2024-12-01T03:24:01Z",
  "eventstoreStatus": "ok",
  "gridId": "so1",
  "highstateAgeSeconds": 220,
  "id": "sensor-001",
  "imageBack": "5000v2_back_thumb.jpg",
  "imageFront": "5000v2_front_thumb.jpg",
  "ioWaitPct": 0.21099,
  "lksEnabled": 1,
  "load15m": 1.09,
  "load1m": 0.43,
  "load5m": 0.96,
  "memoryTotalGB": 33.176731648,
  "memoryUsedPct": 60.66793353109983,
  "metricsEnabled": true,
  "mgmtMac": "AA:BB:CC:11:22:33",
  "model": "SOS5000-DE02",
  "onlineTime": "2024-01-26T21:17:25Z",
  "osNeedsRestart": 1,
  "osUptimeSeconds": 1384801,
  "pcapDays": 1.8762268518518517,
  "processJson": "{\"status_code\":0, \"containers\":[{\"Name\":\"so-dockerregistry\", \"Status\":\"running\",\"Details\":\"Up 2 weeks\"}, ... ]}",
  "processStatus": "ok",
  "raidStatus": "unknown",
  "role": "so-standalone",
  "status": "ok",
  "suriLossPct": 1.1345,
  "suriRulesLoaded": 45879,
  "suriRulesReloadTime": "2025-12-04T01:04:07.994734+0000",
  "suriRulesStatus": "ok",
  "swapTotalGB": 8.589930496000001,
  "swapUsedPct": 63.27341235800379,
  "trafficManInMbs": 0.031592,
  "trafficManOutMbs": 0.030966666666666667,
  "trafficMonInMbs": 1.6864359999999998,
  "updateTime": "2024-12-03T15:42:21.723166638Z",
  "uptimeSeconds": 26936696,
  "version": "2.4.110"
}

Response

The array of assigned, pending jobs that this node is responsible for processing, if any

completeTimestring

The date and time when the job was completed

createTimestring

The date and time when the job was created

failCountinteger

The number of times the job was processed but failed

failTimestring

The date and time when the job last failed and was marked incomplete

failurestring

The failure reason

fileExtensionstring

The file extension for any attached job result/output data

idinteger

The unique Job ID

kindstring

The kind of job that this object represents; blank values represent pcap jobs

nodeIdstring

The unique node ID that is responsible for completing this job

ownerstring

Owner field [not actively used by the API]

sensorIdstring

Legacy sensor ID field

sizeinteger

The size of the job stream output, if a stream output was attached

statusinteger

The current state of the job. 0 = pending, 1 = complete, 2 = incomplete, 3 = deleted

userIdstring

The unique user ID that created this job

Example response

[
  {
    "completeTime": "2024-10-07T12:15:09.12424556Z",
    "createTime": "2024-10-07T06:45:49.52456415Z",
    "failTime": "0001-01-01T00:00:00Z",
    "fileExtension": "bin",
    "filter": {
      "beginTime": "2024-12-03T00:25:09.899Z",
      "dstIp": "1.2.3.4",
      "dstPort": 80,
      "endTime": "2024-12-03T00:29:09.899Z",
      "importId": "bd77c8bc7498c795cc6608c5d45bd51b",
      "protocol": "tcp",
      "srcIp": "44.2.12.63",
      "srcPort": 55312
    },
    "id": 1004,
    "kind": "analyze",
    "nodeId": "sensor-001",
    "results": [
      {
        "id": "malwarebazaar",
        "summary": "no result"
      }
    ],
    "size": 3781,
    "status": 1,
    "userId": "39314a6b-0b79-4210-1233-4e3fbcd7bfec"
  }
]