Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update backends docs #74

Merged
merged 3 commits into from
Mar 13, 2025
Merged

chore: update backends docs #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1c3135d
chore: update backends docs
leoparente Mar 13, 2025
dcf61cc
prepare docker image
leoparente Mar 13, 2025
466324d
improve docs
leoparente Mar 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions agent/docker/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ FROM python:3.12-slim-bullseye

RUN \
apt update && \
apt install --yes --force-yes --no-install-recommends nmap openssh-client && \
rm -rf /var/lib/apt
apt install --yes --no-install-recommends nmap libcap2-bin openssh-client && \
rm -rf /var/lib/apt && \
setcap cap_net_raw,cap_net_admin=eip $(which nmap)

RUN mkdir -p /opt/orb

Expand Down
63 changes: 60 additions & 3 deletions docs/backends/device_discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,20 @@
# Device Discovery
The device discovery backend leverages [NAPALM](https://napalm.readthedocs.io/en/latest/index.html) to connect to network devices and collect network information.

## Diode Entities
The device discovery backend uses [Diode Python SDK](https://github.com/netboxlabs/diode-sdk-python) to ingest the following entities:

* [Device](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#device)
* [Interface](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#interface)
* [Device Type](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#device-type)
* [Platform](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#platform)
* [Manufacturer](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#manufacturer)
* [Site](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#site)
* [Role](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#role)
* [IP Address](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#ip-address)
* [Prefix](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#prefix)

Interfaces are attached to the device and ip addresses will be attached to the interfaces. Prefixes are added to the same interface site that it belongs to.

## Configuration
The `device_discovery` backend does not require any special configuration, though overriding `host` and `port` values can be specified. The backend will use the `diode` settings specified in the `common` subsection to forward discovery results.
Expand Down Expand Up @@ -34,9 +48,33 @@ Config defines data for the whole scope and is optional overall.
#### Defaults
Current supported defaults:

| Key | Description |
|:-----:|:-------------:|
| site | NetBox Site Name |
| Key | Type | Description |
|:-----:|:----:|:-------------:|
| site | str | NetBox Site Name |
| role | str | Device role (e.g., switch) |
| description | str | General description |
| comments | str | General comments |
| tags | list | List of tags |

##### Nested Defaults

| Key | Type | Description |
|-------------|------|---------------------------------|
| device | map | Device-specific defaults |
| ├─ description | str | Device description |
| ├─ comments | str | Device comments |
| ├─ tags | list | Device tags |
| interface | map | Interface-specific defaults |
| ├─ description | str | Interface description |
| ├─ tags | list | Interface tags |
| ipaddress | map | IP address-specific defaults |
| ├─ description | str | IP address description |
| ├─ comments | str | IP address comments |
| ├─ tags | list | IP address tags |
| prefix | map | Prefix-specific defaults |
| ├─ description | str | Prefix description |
| ├─ comments | str | Prefix comments |
| ├─ tags | list | Prefix tags |

### Scope
The scope defines a list of devices that can be accessed and pulled data.
Expand All @@ -63,6 +101,25 @@ orb:
schedule: "* * * * *"
defaults:
site: New York NY
role: switch
description: for all
comments: comment all
tags: [tag1, tag2]
device:
description: device description
comments: this device
tags: [tag3, tag4]
interface:
description: interface description
tags: [tag5]
ipaddress:
description: my ip
comments: my comment
tags: [tag6]
prefix:
description:
comments:
tags: [tag7]
scope:
- driver: ios
hostname: 192.168.0.5
Expand Down
32 changes: 25 additions & 7 deletions docs/backends/network_discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Network Discovery
The network discovery backend leverages [NMAP](https://nmap.org/) to scan networks and discover IP information.

## Diode Entities
The network discovery backend uses [Diode Go SDK](https://github.com/netboxlabs/diode-sdk-go) to ingest discover IP Address entities with Global VRF and allows defining Description, Comments and Tags for them.

## Configuration
The `network_discovery` backend does not require any special configuration, though overriding `host` and `port` values can be specified. The backend will use the `diode` settings specified in the `common` subsection to forward discovery results.
Expand Down Expand Up @@ -37,20 +39,26 @@ Config defines data for the whole scope and is optional overall.
#### Defaults
Current supported defaults:

| Key | Description |
|:-----:|:-------------:|
| comments | NetBox Comments information to be added to discovered IP |
| description | NetBox Description data to be added to discovered IP |
| Key | Type | Description |
|:-----:|:----:|:-------------:|
| comments | str | NetBox Comments information to be added to discovered IP |
| description | str | NetBox Description data to be added to discovered IP |
| tags | list | NetBox Tags to be added to discovered IP |

### Scope
The scope defines a list of targets to be scanned.

| Parameter | Type | Required | Description |
|:---------:|:----:|:--------:|:-----------:|
| targets | list | yes | The targets that NMAP will scan. These can be specified as IP addresses (192.168.1.1), IP ranges (192.168.1.10-20), IP subnets with mask (192.168.1.0/24) or resolvable domain names. |



| fast_mode | bool | no | Fast mode - Scan fewer ports than the default scan (-F). |
| timing | int | no | Set timing template, higher is faster (-T<0-5>). |
| ports | list | no | Only scan specified ports (-p). Sample: [22,161,162,443,500-600,8080]. |
| exclude_ports | list | no | Exclude the specified ports from scanning. Sample: [23, 9000-12000]. |
| ping_scan | bool | no | Ping Scan (-sn) - disable port scan. If `scan_types` is defined, `ping_scan` will be ignored. |
| top_ports | int | no | Scan <number> most common ports (--top-ports). |
| max_retries | int | no | Caps number of port scan probe retransmissions (--max-retries). |
| scan_types | list | no | Scan technique to be used by NMAP. Supports [udp,connect,syn,ack,window,null,fin,xmas,maimon,sctp_init,sctp_cookie_echo,ip_protocol]. If more than one TCP scan type (`connect,syn,ack,window,null,fin,xmas,maimon`) is defined, only the fist one will be applied. |

### Sample
A sample policy including all parameters supported by the network discovery backend.
Expand All @@ -66,11 +74,21 @@ orb:
defaults:
comments: none
description: IP discovered by network discovery
tags: [net-discovery, orb-agent]
scope:
targets:
- 192.168.7.32
- 192.168.7.30-40 # IP range
- 192.168.7.0/24 # IP subnet
- google.com # dns lookup
fast_mode: True
max_retries: 0

```
### ⚠️ Warning
Be **AWARE** that executing a policy with only targets defined is equivalent to running `nmap <targets>`, which in turn is the same as executing `nmap -sS -p1-1000 --open -T3 <target>`:

- `-sS` → SYN scan (stealth scan, requires root privileges)
- `-p1-1000` → Scans the top 1000 most common ports
- `--open` → Only shows open ports
- `-T3` → Uses the default timing template (T3 is the standard speed)
7 changes: 4 additions & 3 deletions docs/backends/worker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
# Worker
The worker backend allows to run custom implementation as part of Orb Agent.

## Diode Entities
The worker backend can ingest any [supported entity](https://github.com/netboxlabs/diode-sdk-python?tab=readme-ov-file#supported-entities-object-types) of Diode Python SDK.

## Configuration
The `worker` backend does not require any special configuration, though overriding `host` and `port` values can be specified. The backend will use the `diode` settings specified in the `common` subsection to forward discovery results.


```yaml
orb:
backends:
Expand Down Expand Up @@ -32,8 +34,7 @@ Config defines data for the whole scope and is optional overall.


### Scope
The scope can be defined

The scope can be defined as either a `list` or a `map`, allowing the user to parse it according to their preference.

### Sample
A sample policy including all parameters supported by the device discovery backend.
Expand Down