NetBox Event Collector

NetBox event collector integration for Cortex XSIAM.

Analytics & SIEM · NetBox

Details

IDNetBox Event Collector
ProviderNetBoxLabs
CategoryAnalytics & SIEM
From Version6.8.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesXSIAM

README

This is the NetBox event collector integration for Cortex XSIAM.
This integration was integrated and tested with version 3.0 and above of NetBox API.

Configure NetBox Event Collector in Cortex

Parameter Required
Server URL (e.g., https://www.example.com) True
API Key True
First fetch time False
The maximum number of alerts per fetch False
Trust any certificate (not secure) False
Use system proxy settings False

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

netbox-get-events

Gets events from NetBox.

Base Command

netbox-get-events

Input

Argument Name Description Required
should_push_events If true, the command will create events, otherwise it will only display them. Possible values are: true, false. Default is false. Required
limit Maximum number of results to return. Optional

Context Output

There is no context output for this command.

Command Example

!netbox-get-events should_push_events=true limit=1

Human Readable Output

journal-entries Events

assigned_object assigned_object_id assigned_object_type comments created created_by custom_fields display id kind last_updated tags url
id: 4
url: https://www.example.com/api/dcim/devices/4/
display: test3
name: test3		 4 dcim.device   2022-12-04T14:33:52.067484Z 1   2022-12-04 14:33 (Info) 6 value: info
label: Info		 2022-12-07T08:19:57.807055Z   https://www.example.com/api/extras/journal-entries/6/

object-changes Events

action changed_object changed_object_id changed_object_type display id postchange_data prechange_data request_id time url user user_name
value: update
label: Updated		 id: 6
url: https://www.example.com/api/extras/journal-entries/6/
display: 2022-12-04 14:33 (Info)
created: 2022-12-04T14:33:52.067484Z		 6 extras.journalentry extras | journal entry 2022-12-04 14:33 (Info) updated by netbox 10 kind: info
tags:
created: 2022-12-04T14:33:52.067Z
comments:
created_by: 1
last_updated: 2022-12-07T08:19:57.807Z
custom_fields: {}
assigned_object_id: 4
assigned_object_type: 25		 kind:
tags:
created: 2022-12-04T14:33:52.067Z
comments:
created_by: 1
last_updated: 2022-12-04T14:33:52.067Z
custom_fields: {}
assigned_object_id: 4
assigned_object_type: 25		 12345678-abcd-1234-abcd-1234567890ab 2022-12-07T08:19:57.810348Z https://www.example.com/api/extras/object-changes/10/ id: 1
url: https://www.example.com/api/users/users/1/
display: netbox
username: netbox		 netbox

Configuration parameters

  • url — Server URL (e.g., https://www.example.com) (required)
  • credentials — (required)
  • first_fetch — First fetch time
  • max_fetch — The maximum number of alerts per fetch
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings

Commands (1)

  • netbox-get-events

    Gets events from NetBox.

Source

NetBoxEventCollector.py NetBoxEventCollector_test.py NetBoxEventCollector.yml NetBoxEventCollector_description.md
Download History Raw 
import json

from NetBoxEventCollector import LOG_TYPES

BASE_URL = "https://www.example.com/api/extras"


# helper function to load json file
def util_load_json(path):
    with open(path, encoding="utf-8") as f:
        return json.loads(f.read())


def test_add_time_key_to_events():
    """
    Given:
        - list of events
    When:
        - Calling add_time_key_to_events
    Then:
        - Ensure the _time key is added to the events
    """
    from NetBoxEventCollector import add_time_key_to_events

    events = util_load_json("test_data/netbox-get-events.json")
    events = add_time_key_to_events(events)

    assert events[0]["_time"] == "2022-12-04T14:33:52.067484Z"
    assert events[4]["_time"] == "2022-12-07T08:19:57.810348Z"


def test_get_events_command(requests_mock):
    """
    Given:
        - NetBox client and limit of events to fetch
    When:
        - Calling get_events_command
    Then:
        - Ensure the events are returned as expected and the pagination is working as expected
    """
    from NetBoxEventCollector import Client, get_events_command

    for log_type in LOG_TYPES:
        requests_mock.get(
            f"{BASE_URL}/{log_type}?limit=4&ordering=&id__gte=0", json=util_load_json(f"test_data/get_events_{log_type}-01.json")
        )
        requests_mock.get(
            f"{BASE_URL}/{log_type}/?id__gte=0&limit=2&offset=2&ordering=",
            json=util_load_json(f"test_data/get_events_{log_type}-02.json"),
        )

    client = Client(base_url=BASE_URL, verify=False)
    events, _ = get_events_command(client, limit=4)

    mock_events = util_load_json("test_data/netbox-get-events.json")

    assert events == mock_events


def test_fetch_events_command(requests_mock):
    """
    Given:
        - NetBox client and max_fetch, last_run and first_fetch_time
    When:
        - Calling fetch_events_command
    Then:
        - Ensure the events are returned as expected and the next_run is as expected
    """
    from NetBoxEventCollector import Client, fetch_events_command

    # mock the first fetch id
    requests_mock.get(
        f"{BASE_URL}/journal-entries?ordering=id&limit=1&created_after=2022-01-01T00:00:00Z", json={"results": [{"id": 5}]}
    )
    requests_mock.get(
        f"{BASE_URL}/object-changes?ordering=id&limit=1&time_after=2022-01-01T00:00:00Z", json={"results": [{"id": 9}]}
    )

    # mock the events
    requests_mock.get(
        f"{BASE_URL}/journal-entries?limit=2&ordering=id&id__gte=5",
        json=util_load_json("test_data/fetch_events_journal-entries.json"),
    )
    requests_mock.get(
        f"{BASE_URL}/object-changes?limit=2&ordering=id&id__gte=9",
        json=util_load_json("test_data/fetch_events_object-changes.json"),
    )

    client = Client(base_url=BASE_URL, verify=False)
    next_run, events = fetch_events_command(client, max_fetch=2, last_run={}, first_fetch_time="2022-01-01T00:00:00Z")

    mock_events = util_load_json("test_data/netbox-fetch-events.json")

    assert events == mock_events
    assert next_run == {"journal-entries": 7, "object-changes": 11}