Result Notifications
Orbital Result Notification Structures
Note: Orbital can asynchronously send results to a Remote Data Store (RDS) configured through the UI or via API.
The first option is the Cisco Threat Response Private Intelligence store, which is described here and can be viewed here.
The remaining options all share a similar format described in this document. With both a compact and expanded table-oriented result format that can be sent to any personal RDS, Orbital also supports sending results to Amazon S3™, Azure™, and Splunk™. In all cases successfully creating an RDS requires making sure the destination exists, can be authenticated to with the credentials provided, and successfully written to. Each time an RDS is created or selected in a new scheduled query Orbital sends a ping to the RDS, which is a small packet that must be successfully delivered for the request to succeed. When using an Amazon S3 RDS the ping is stored as a file named orbital-rds-ping.json and is overwritten with each request. This ping file can be safely discarded. The format of a ping is defined in the sections below.
Note: All times are UTC, in RFC3339 format.
Ping Headers
{
"X-Orbital-Event": ["ping"],
"X-Orbital-Eventid": ["e7fc42a9-97d5-5ea5-f1d9-dd6dae62f150"], // Example internal Request ID, useful for support.
"Accept-Encoding": ["gzip"],
"User-Agent": ["Go-http-client/1.1"],
"Content-Type": ["application/json"]
}
Default Ping Body
{
"ping": {
"id": "3JWq5ZWB8jFEnry0NoA3Lg", // Example ID of new RDS object, or blank for a live postback request.
"created": "2019-09-26T15:46:38.717497401Z", // Time the RDS was created.
"creator": "7ef6da70-eeef-4a18-83ea-2e94dd6f9ba2", // Example user ID that created the RDS.
"disabled": false, // Current "disabled" state for the RDS.
"organization": "d76c035d-e896-438c-8d75-158be85fc958", // Example organization ID of the user.
"updated": "2019-09-26T15:46:38.717497401Z", // Time the RDS was last updated.
"lastcalled": "0001-01-01T00:00:00Z", // Time the RDS was last called.
"laststatus": "", // Status of the last RDS call, "success" or "failure."
"errormessage": "", // Error message of the last RDS call, or blank.
"config": {
"label": "MyHost RDS", // User defined label for the RDS.
"url": "http://myhost.com/rds" // RDS URL.
}
}
}
Splunk Ping Body
{
"event": {<default ping body>},
"source": "orbital",
"sourcetype": "_json"
}
RDS Payloads
Once the RDS is created, new scheduled jobs can be associated with an RDS so that results get sent to the RDS via an HTTP POST. The default result wrapper is described as well as the Splunk specific wrapper. Additionally, the result itself can use the compact or expanded formats, both described below.
Results Headers
{
"X-Orbital-Event": ["job-results"]
"X-Orbital-Eventid": ["QiI8Tmnv2XTJak3myq5duw"], // Value is the ID of the Orbital live query or scheduled query for result set.
"Accept-Encoding": ["gzip"],
"User-Agent": ["Go-http-client/1.1"],
"Content-Length": [1540],
"Content-Type": ["application/json"]
}
Default Results Body
{
"job-results": [
<job-result 1>,
<job-result 2>,
<job-result N>
]
}
Splunk Results Body
{
"event": {<job result with selected format>},
"source": "orbital",
"sourcetype": "_json"
}
The “job-result” Object
{
"version": 3, // Result notice protocol version.
"format": "compact", // Result format identifier.
"query": { // Information about the query that spawned the results.
"id": "0IXVxgIqx-KvHUGL9kHRug", // Orbital ID from the live query or scheduled query that spawned the results.
"context": { // Map of key-value pairs provided to the query, if any.
"key": "val"
}
"osquery": [ // List of osquery sql stanzas and metadata.
{
"types": [ // Observable type hint for each result column.
"crontab_event",
"crontab_minute",
"crontab_hour",
"crontab_day_of_month",
"crontab_month",
"crontab_day_of_week",
"command_line",
"file_path"
],
"sql": "SELECT event, minute, hour, day_of_month, month, day_of_week, command, path \nFROM crontab;\n", // SQL statement
"label": "crontab_monitoring", // Custom unique identifier for this stanza of SQL.
"name": "Crontab Events" // Custom human readable name for this stanza of SQL.
}
]
},
"results": [ // List of Orbital formatted results, either compact or expanded.
<formatted result 1>,
<formatted result 2>,
<formatted result N>
]
}
The formatted-result payload comes in two varieties, compact and expanded. They differ in their presentation of result rows and columns.
Compact Formatted Result
This is an example compact formatted result for the Orbital Catalog query Crontab Events.
{
"nodeinfo":{
"id":"aCaqXcztcZ4DDhPjsIGJkA", // Orbital ID associated with the endpoint.
"ampuuid":"19504e9e-88a6-4ba7-a079-c24c6eb597d8", // Secure Endpoint GUID associated with the endpoint.
"os":"windows" // OS of the endpoint.
},
"id": "Rv-BriP-XAMev3LN8DNoug", // Orbital ID of this result.
"creator": "7ef6da70-eeef-4a18-83ea-2e94dd6f9ba2", // User ID associated with this result.
"organization": "d76c035d-e896-438c-8d75-158be85fc958", // Organization ID associated with the query that created the result.
"endpoint_organization": "d76c035d-e896-438c-8d75-158be85fc958",// Organization ID associated with the endpoint that created the result.
"endpoint_type": "amp", // Endpoint type for the endpoint that created this result.
"reported": "2020-09-15T21:03:38.067793669Z", // Time the result was reported from the endpoint.
"error": "", // Error reported from the endpoint, or empty.
"node": "aCaqXcztcZ4DDhPjsIGJkA", // Orbital ID associated with the endpoint.
"query": "0IXVxgIqx-KvHUGL9kHRug", // Orbital ID from the query that spawned this result.
"osQuery": [ // List of osquery result objects, one per input SQL stanza.
{
"types": [ // Observable types for each result column, if any.
"",
"",
"",
"",
"",
"",
"",
"file_path"
],
"columns": [ // Column names for results.
"event",
"minute",
"hour",
"day_of_month",
"month",
"day_of_week",
"command",
"path"
],
"values": [ // Serialized data from all columns and rows for this SQL stanza.
"",
"17",
"*",
"*",
"*",
"*",
"root cd / && run-parts --report /etc/cron.hourly",
"/etc/crontab",
"",
"25",
"6",
"*",
"*",
"*",
"root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )",
"/etc/crontab",
"",
"47",
"6",
"*",
"*",
"7",
"root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )",
"/etc/crontab",
"",
"52",
"6",
"1",
"*",
"*",
"root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )",
"/etc/crontab"
],
"error": "", // Error for this SQL stanza, if any.
"secs": 0.0008076209924183786, // Time in seconds to run this SQL stanza on the endpoint.
"label": "crontab_monitoring", // Custom input label associated with this SQL stanza.
"name": "Crontab Events" // Custom input name associated with this SQL stanza.
}
],
"resultsCompressed": false, // Always false.
"context": { // Map of key-value pairs provided to the query, if any.
"key": "val"
}
"hostinfo": { // Host information for the endpoint. Note fieldname difference from expanded
"osinfo": {
"os": "windows",
"osname": "",
"release": "5.0.0-23-generic",
"version": "#24~18.04.1-Ubuntu SMP Mon Jul 29 16:12:28 UTC 2019",
"arch": "amd64"
},
"hostname": "myP52",
"fqdn": {
"127.0.1.1": "myP52"
},
"interfaces": {
"br-3cb44620fa12": {
"name": "br-3cb44620fa12",
"mac": "02:42:34:92:b5:93",
"ipv4": "172.18.0.1/16",
"active": false
},
"wlp0s20f3": {
"name": "wlp0s20f3",
"mac": "d4:3b:04:0c:36:c1",
"ipv4": "10.99.154.69/28",
"ipv6": "fe80::f24f:9302:5686:fa04/64",
"active": false
}
},
"external": {
"name": "",
"mac": "",
"ipv4": "127.0.0.1",
"active": true
},
"updated": "2020-09-15T19:08:29.362008182Z",
"version": ""
},
"rowcount": 4, // Number of rows from all SQL stanzas combined.
"seconds": 0.0014323319774121046 // Number of seconds to process all SQL stanzas combined.
"source_uri": "https://orbital.amp.cisco.com/jobs/job-id/results" // Service link for result.
}
Expanded Formatted Result
This is an example expanded formatted result for the Orbital Catalog query Crontab Events.
{
"id": "cukgSCMixtO8G2KPmUKKJA", // Orbital ID of this result.
"creator": "7ef6da70-eeef-4a18-83ea-2e94dd6f9ba2", // User ID associated with this result.
"organization": "d76c035d-e896-438c-8d75-158be85fc958", // Organization ID associated with the query that created the result.
"endpoint_organization": "d76c035d-e896-438c-8d75-158be85fc958",// Organization ID associated with the endpoint that created the result.
"endpoint_type": "amp", // Endpoint type for the endpoint that created this result.
"reported": "2020-09-15T20:49:26.896692372Z", // Time the result was reported from the endpoint.
"error": "", // Error reported from the endpoint, or empty.
"nodeinfo":{
"id":"aCaqXcztcZ4DDhPjsIGJkA", // Orbital ID associated with the endpoint.
"ampuuid":"19504e9e-88a6-4ba7-a079-c24c6eb597d8", // Secure Endpoint GUID associated with the endpoint.
"os":"windows" // OS of the endpoint.
},
"query": "0IXVxgIqx-KvHUGL9kHRug", // Orbital ID from the query that spawned this result.
"osQuery": [ // List of osquery result objects, one per input SQL stanza.
{
"types":[ // Observable types for each result column, if any.
"",
"",
"",
"",
"",
"",
"",
"file_path"
],
"columns":[ // Column names for results.
"event",
"minute",
"hour",
"day_of_month",
"month",
"day_of_week",
"command",
"path"
],
"table":[
{
"meta_name":"Crontab Events" // Custom input name associated with this SQL stanza.
"meta_label":"crontab_monitoring", // Custom input label associated with this SQL stanza.
"event":"", // Row data in key-value format, in column order.
"minute":"17",
"hour":"*",
"day_of_month":"*",
"month":"*",
"day_of_week":"*",
"command":"root cd / \u0026\u0026 run-parts --report /etc/cron.hourly",
"path":"/etc/crontab"
},
{
"meta_name":"Crontab Events"
"meta_label":"crontab_monitoring",
"event":"",
"minute":"25",
"hour":"6",
"day_of_month":"*",
"month":"*",
"day_of_week":"*",
"command":"root test -x /usr/sbin/anacron || ( cd / \u0026\u0026 run-parts --report /etc/cron.daily )",
"path":"/etc/crontab"
},
{
"meta_name":"Crontab Events"
"meta_label":"crontab_monitoring",
"event":"",
"minute":"47",
"hour":"6",
"day_of_month":"*",
"month":"*",
"day_of_week":"7",
"command":"root test -x /usr/sbin/anacron || ( cd / \u0026\u0026 run-parts --report /etc/cron.weekly )",
"path":"/etc/crontab"
},
{
"meta_name":"Crontab Events"
"meta_label":"crontab_monitoring",
"event":"",
"minute":"52",
"hour":"6",
"day_of_month":"1",
"month":"*",
"day_of_week":"*",
"command":"root test -x /usr/sbin/anacron || ( cd / \u0026\u0026 run-parts --report /etc/cron.monthly )",
"path":"/etc/crontab"
}
],
"error": "", // Error for this SQL stanza, if any.
"secs": 0.0008076209924183786, // Time in seconds to run this SQL stanza on the endpoint.
"label": "crontab_monitoring", // Custom input label associated with this SQL stanza.
"name": "Crontab Events" // Custom input name associated with this SQL stanza.
}
],
"context": { // Map of key-value pairs provided to the query, if any.
"key": "val"
}
"info":{ // Host information for the endpoint. Note fieldname difference from compact
"osinfo":{
"os":"windows",
"osname":"",
"release":"5.0.0-23-generic",
"version":"#24~18.04.1-Ubuntu SMP Mon Jul 29 16:12:28 UTC 2019",
"arch":"amd64"
},
"hostname":"myP52",
"fqdn":{
"127.0.1.1":"myP52"
},
"interfaces":{
"br-3cb44620fa12":{
"name":"br-3cb44620fa12",
"mac":"02:42:52:92:b5:93",
"ipv4":"172.18.0.1/16",
"active":false
},
"wlp0s20f3":{
"name":"wlp0s20f3",
"mac":"d4:3b:04:0c:82:c1",
"ipv4":"10.99.154.69/28",
"ipv6":"fe80::f24f:9302:5686:fa04/64",
"active":false
}
},
"external":{
"name":"",
"mac":"",
"ipv4":"127.0.0.1",
"active":true
},
"updated":"2020-09-15T19:08:29.362008182Z",
"version":""
},
"rowcount": 4, // Number of rows from all SQL stanzas combined.
"seconds": 0.0014323319774121046 // Number of seconds to process all SQL stanzas combined.
"source_uri": "https://orbital.amp.cisco.com/jobs/job-id/results" // Service link for result.
}
Note: Orbital will not remove documented RDS result fields, but reserves the right to add fields to the output as they become necessary.
Note: The compact field job-results.results.hostinfo is named job-results.results.info in the expanded format.