Skip to content

Commit 7266d67

Browse files
leoparenteleoparente
authored
chore: update backends docs (#74)
1 parent 203f000 commit 7266d67

File tree

4 files changed

+92
-15
lines changed

4 files changed

+92
-15
lines changed

‎agent/docker/Dockerfile

+3-2
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,9 @@ FROM python:3.12-slim-bullseye
2929

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

3536
RUN mkdir -p /opt/orb
3637

‎docs/backends/device_discovery.md

+60-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,20 @@
11
# Device Discovery
22
The device discovery backend leverages [NAPALM](https://napalm.readthedocs.io/en/latest/index.html) to connect to network devices and collect network information.
33

4+
## Diode Entities
5+
The device discovery backend uses [Diode Python SDK](https://github.com/netboxlabs/diode-sdk-python) to ingest the following entities:
6+
7+
* [Device](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#device)
8+
* [Interface](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#interface)
9+
* [Device Type](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#device-type)
10+
* [Platform](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#platform)
11+
* [Manufacturer](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#manufacturer)
12+
* [Site](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#site)
13+
* [Role](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#role)
14+
* [IP Address](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#ip-address)
15+
* [Prefix](https://github.com/netboxlabs/diode-sdk-python/blob/develop/docs/entities.md#prefix)
16+
17+
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.
418

519
## Configuration
620
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.
@@ -34,9 +48,33 @@ Config defines data for the whole scope and is optional overall.
3448
#### Defaults
3549
Current supported defaults:
3650

37-
| Key | Description |
38-
|:-----:|:-------------:|
39-
| site | NetBox Site Name |
51+
| Key | Type | Description |
52+
|:-----:|:----:|:-------------:|
53+
| site | str | NetBox Site Name |
54+
| role | str | Device role (e.g., switch) |
55+
| description | str | General description |
56+
| comments | str | General comments |
57+
| tags | list | List of tags |
58+
59+
##### Nested Defaults
60+
61+
| Key | Type | Description |
62+
|-------------|------|---------------------------------|
63+
| device | map | Device-specific defaults |
64+
| ├─ description | str | Device description |
65+
| ├─ comments | str | Device comments |
66+
| ├─ tags | list | Device tags |
67+
| interface | map | Interface-specific defaults |
68+
| ├─ description | str | Interface description |
69+
| ├─ tags | list | Interface tags |
70+
| ipaddress | map | IP address-specific defaults |
71+
| ├─ description | str | IP address description |
72+
| ├─ comments | str | IP address comments |
73+
| ├─ tags | list | IP address tags |
74+
| prefix | map | Prefix-specific defaults |
75+
| ├─ description | str | Prefix description |
76+
| ├─ comments | str | Prefix comments |
77+
| ├─ tags | list | Prefix tags |
4078

4179
### Scope
4280
The scope defines a list of devices that can be accessed and pulled data.
@@ -63,6 +101,25 @@ orb:
63101
schedule: "* * * * *"
64102
defaults:
65103
site: New York NY
104+
role: switch
105+
description: for all
106+
comments: comment all
107+
tags: [tag1, tag2]
108+
device:
109+
description: device description
110+
comments: this device
111+
tags: [tag3, tag4]
112+
interface:
113+
description: interface description
114+
tags: [tag5]
115+
ipaddress:
116+
description: my ip
117+
comments: my comment
118+
tags: [tag6]
119+
prefix:
120+
description:
121+
comments:
122+
tags: [tag7]
66123
scope:
67124
- driver: ios
68125
hostname: 192.168.0.5

‎docs/backends/network_discovery.md

+25-7
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Network Discovery
22
The network discovery backend leverages [NMAP](https://nmap.org/) to scan networks and discover IP information.
33

4+
## Diode Entities
5+
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.
46

57
## Configuration
68
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.
@@ -37,20 +39,26 @@ Config defines data for the whole scope and is optional overall.
3739
#### Defaults
3840
Current supported defaults:
3941

40-
| Key | Description |
41-
|:-----:|:-------------:|
42-
| comments | NetBox Comments information to be added to discovered IP |
43-
| description | NetBox Description data to be added to discovered IP |
42+
| Key | Type | Description |
43+
|:-----:|:----:|:-------------:|
44+
| comments | str | NetBox Comments information to be added to discovered IP |
45+
| description | str | NetBox Description data to be added to discovered IP |
46+
| tags | list | NetBox Tags to be added to discovered IP |
4447

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

4851
| Parameter | Type | Required | Description |
4952
|:---------:|:----:|:--------:|:-----------:|
5053
| 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. |
51-
52-
53-
54+
| fast_mode | bool | no | Fast mode - Scan fewer ports than the default scan (-F). |
55+
| timing | int | no | Set timing template, higher is faster (-T<0-5>). |
56+
| ports | list | no | Only scan specified ports (-p). Sample: [22,161,162,443,500-600,8080]. |
57+
| exclude_ports | list | no | Exclude the specified ports from scanning. Sample: [23, 9000-12000]. |
58+
| ping_scan | bool | no | Ping Scan (-sn) - disable port scan. If `scan_types` is defined, `ping_scan` will be ignored. |
59+
| top_ports | int | no | Scan <number> most common ports (--top-ports). |
60+
| max_retries | int | no | Caps number of port scan probe retransmissions (--max-retries). |
61+
| 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. |
5462

5563
### Sample
5664
A sample policy including all parameters supported by the network discovery backend.
@@ -66,11 +74,21 @@ orb:
6674
defaults:
6775
comments: none
6876
description: IP discovered by network discovery
77+
tags: [net-discovery, orb-agent]
6978
scope:
7079
targets:
7180
- 192.168.7.32
7281
- 192.168.7.30-40 # IP range
7382
- 192.168.7.0/24 # IP subnet
7483
- google.com # dns lookup
84+
fast_mode: True
85+
max_retries: 0
7586

7687
```
88+
### ⚠️ Warning
89+
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>`:
90+
91+
- `-sS` → SYN scan (stealth scan, requires root privileges)
92+
- `-p1-1000` → Scans the top 1000 most common ports
93+
- `--open` → Only shows open ports
94+
- `-T3` → Uses the default timing template (T3 is the standard speed)

‎docs/backends/worker.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
# Worker
22
The worker backend allows to run custom implementation as part of Orb Agent.
33

4+
## Diode Entities
5+
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.
6+
47
## Configuration
58
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.
69

7-
810
```yaml
911
orb:
1012
backends:
@@ -32,8 +34,7 @@ Config defines data for the whole scope and is optional overall.
3234

3335

3436
### Scope
35-
The scope can be defined
36-
37+
The scope can be defined as either a `list` or a `map`, allowing the user to parse it according to their preference.
3738

3839
### Sample
3940
A sample policy including all parameters supported by the device discovery backend.

0 commit comments

Comments
 (0)