SaaS API Documentation
This documentation provides details on how to use the API endpoints and examples of requests and responses.
Requires
Internet access to the your SaaS server on HTTPS port 443
Access key provided by Atomicorp support
Authentication
All requests to this API must include the Authorization header with a Bearer token. The access key can be provided by contacting support@atomicorp.com
Authorization: Bearer <access_token>
Actions
List Agents
Retrieve a list of all agents registered to this system, regardless of connection status.
Fields:
id: The agent ID
name: The agent name
ip: The agent IP address
register_ip: The IP address the agent may come from, any indicates any IP address
internal_key: The internal key used to authenticate the agent
os_name: The operating system name
os_version: The operating system version
os_major: The operating system major version
os_minor: The operating system minor version
os_codename: The operating system codename
os_build: The operating system build
os_platform: The operating system platform
os_uname: The operating system uname
os_arch: The operating system architecture
version: The agent version
config_sum: The agent configuration checksum
merged_sum: The agent merged configuration checksum
manager_host: The manager host
node_name: The node name
date_add: The date the agent was added
last_keepalive: The last keepalive time
group: The agent group
sync_status: The agent sync status
connection_status: The agent connection status
disconnection_time: The agent disconnection time
URL: https://<HOSTNAME>/api/v1/?action=list_agents
Method: GET
Response: List of agents in JSON format.
Example Response:
[ { "id": 0, "name": "awp-hub-rocky8", "ip": "127.0.0.1", "register_ip": "127.0.0.1", "internal_key": null, "os_name": "Rocky Linux", "os_version": "8.9", "os_major": "8", "os_minor": "9", "os_codename": "Green Obsidian", "os_build": null, "os_platform": "rocky", "os_uname": "Linux |awp-hub-rocky8 |4.18.0-513.9.1.el8_9.x86_64 |#1 SMP Wed Nov 29 18:55:19 UTC 2023 |x86_64", "os_arch": "x86_64", "version": "OSSEC v4.7.0", "config_sum": null, "merged_sum": null, "manager_host": "awp-hub-rocky8", "node_name": "primary", "date_add": 1699992097, "last_keepalive": 253402300799, "group": null, "sync_status": "synced"last_partial_scan, "connection_status": "active", "disconnection_time": 0 }, { "id": 4, "name": "rhel8-qa", "ip": null, "register_ip": "any", "internal_key": "aaaaaaaaaaaabbbbbbbbbbbcccccccccccccdddddddddddddddddd", "os_name": null,last_partial_scan "os_version": null, "os_major": null, "os_minor": null, "os_codename": null, "os_build": null, "os_platform": null, "os_uname": null, "os_arch": null, "version": null, "config_sum": null, "merged_sum": null, "manager_host": null, "node_name": "unknown", "date_add": 1659362090, "last_keepalive": null, "group": "default", "sync_status": "synced", "connection_status": "never_connected", "disconnection_time": 0 }, ]
Example Request:
curl -H "Authorization: Bearer <ACCESS_KEY>" -k "https://<HOSTNAME>/api/v1/?action=list_agents"
Get Agent Information
Retrieve information about a specific agent.
URL: https://<HOSTNAME>/api/v1/?action=get_agent&agentId=<AGENT_ID>
Method: GET
Parameters:
agentId (integer): The ID of the agent to retrieve information for.
Response: Agent information in JSON format.
Example Response:
{ "id": 5, "name": "amzn2-64.winona.atomicorp.com", "ip": null, "register_ip": "any", "internal_key": "aaaaaaaaaaaabbbbbbbbbbbcccccccccccccdddddddddddddddddd", "os_name": null, "os_version": null, "os_major": null, "os_minor": null, "os_codename": null, "os_build": null, "os_platform": null, "os_uname": null, "os_arch": null, "version": null, "config_sum": null, "merged_sum": null, "manager_host": null, "node_name": "unknown", "date_add": 1659465551, "last_keepalive": null, "group": "default", "sync_status": "synced", "connection_status": "never_connected", "disconnection_time": 0 }
Example Request:
curl -H "Authorization: Bearer <ACCESS_KEY>" -k "https://<HOSTNAME>/api/v1/?action=get_agent&agentId=<AGENT_ID>"
Vulnerability Data
Retrieve vulnerability data for agents.
Get Vulnerability Data
Retrieve vulnerability data for all agents or a specific agent based on provided filters, such as agent ID, agent name, group name, and detection time.
Fields:
id: The agent ID
name: The agent name
group: The group name
vulnerability_data: Vulnerability data
name: The package name
version: The package version
architecture: The package architecture
cve: The CVE ID
detection_time: The detection time on the agent for the issue in epoch time
severity: The severity of the issue (Low, Medium, High, Critical). This is calculated based on the OVAL data, if available, otherwise it will use the NVD data
cvss2_score: CVSS v2 score (NVD)
cvss3_score: CVSS v3 score (NVD)
reference: internal reference field (used for deduplication)
type: The type of the issue (PACKAGE, FILE, COMMAND, etc.)
status: The status of the issue (VALID: vulnerability detected, OBSOLETE: vulnerability resolved by an update, or package removed)
external_references: External references (OVAL, NVD, etc.)
condition: The conditions to detect the issue (Example: Package less or equal than 1.0.6)
title: The title of the issue
published: The published date of the issue (NVD, OVAL, etc.)
updated: Last time the issue was updated by the publisher (NVD, OVAL, etc.)
last_delta_scan: The last delta scan time, if available
last_full_scan: The last full scan time
URL: https://<HOSTNAME>/api/v1/?action=get_vulns
Method: GET
Parameters:
agentId (integer, optional): The ID of the agent to retrieve vulnerability data for.
agentName (string, optional): The name of the agent to retrieve vulnerability data for.
groupName (string, optional): The group name of agents to retrieve vulnerability data for.
detection_time (integer, optional): Epoch time to filter vulnerabilities detected after this time.
Response: Vulnerability data in JSON format.
Example Response:
{
"166": {
"id": 166,
"name": "rhel9-simulation", "group": "test2",
"vulnerability_data": [ {
"name": "libesmtp",
"version": "1.0.6-24.el9",
"architecture": "x86_64",
"cve": "CVE-2019-19977",
"detection_time": "1708960322",
"severity": "Medium",
"cvss2_score": 7.5,
"cvss3_score": 9.8,
"reference": "e03ce0a05779a22befc676c5788acebff7af9827",
"type": "PACKAGE",
"status": "VALID",
"external_references": "[\"https://github.com/Kirin-say/Vulnerabilities/blob/master/Stack_Overflow_in_libesmtp.md\",\"https://web.archive.org/web/20190528215510/http://brianstafford.info/libesmtp/\",\"https://github.com/jbouse-debian/libesmtp/blob/ca5bd0800ef1da234315da4c59716568eb5e6402/ntlm/ntlmstruct.c#L228-L242\",\"https://nvd.nist.gov/vuln/detail/CVE-2019-19977\",\"https://access.redhat.com/security/cve/CVE-2019-19977\"]",
"condition": "Package less or equal than 1.0.6",
"title": "CVE-2019-19977 affects libesmtp",
"published": "2019-12-26",
"updated": "2020-01-03"
},
{
"name": "libsndfile",
"version": "1.0.31-7.el9",
"architecture": "x86_64",
"cve": "CVE-2022-33065",
"detection_time": "1708960322",
"severity": "Medium",
"cvss2_score": 0,
"cvss3_score": 7.8,
"reference": "f91b8b34d1b824d0ee7dc783f502295906860267",
"type": "PACKAGE",
"status": "VALID",
"external_references": "[\"https://github.com/libsndfile/libsndfile/issues/833\",\"https://github.com/libsndfile/libsndfile/issues/789\",\"https://nvd.nist.gov/vuln/detail/CVE-2022-33065\",\"https://access.redhat.com/security/cve/CVE-2022-33065\"]",
"condition": "Package unfixed",
"title": "CVE-2022-33065 affects libsndfile",
"published": "2023-07-18",
"updated": "2023-08-02"
}
],
"last_delta_scan": "2024-03-13 14:05:10",
"last_full_scan": "2024-03-13 13:34:12"
}
}
Example Request (Get Vulnerability Data for Agent ID 168):
curl -H "Authorization: Bearer <ACCESS_KEY>" "https://<HOSTNAME>/api/v1/?action=get_vulns&agentId=168"
Example Request (Get Vulnerability Data for Agent Name rhel9-simulation):
curl -H "Authorization: Bearer <ACCESS_KEY>" "https://<HOSTNAME>/api/v1/?action=get_vulns&agentName=rhel9-simulation"
Example Request (Get Vulnerability Data for Group Name test2):
curl -H "Authorization: Bearer <ACCESS_KEY>" "https://<HOSTNAME>/api/v1/?action=get_vulns&groupName=test2"
Example Request (Get Vulnerability Data for Group Name test2 where detection_time is greater than 1708960322):
curl -H "Authorization: Bearer <ACCESS_KEY>" "https://<HOSTNAME>/api/v1/?action=get_vulns&groupName=test2&detection_time=1708960322"