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**:

  .. code-block:: json

    [
        {
            "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:

  .. code-block:: console

    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**:

  .. code-block:: json

    {
        "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**:

  .. code-block:: console

    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**:

.. code-block:: json

  	{
  	  "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):

.. code-block:: console

    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): 

.. code-block:: console

    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):

.. code-block:: console

    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):

.. code-block:: console

    curl -H "Authorization: Bearer <ACCESS_KEY>" "https://<HOSTNAME>/api/v1/?action=get_vulns&groupName=test2&detection_time=1708960322"

