简介
本文章主要讲解使用orb-agent 扫描网络收集IP信息，通过Diode 摄取到NetBox。
这两个工具都是NetBox官方的自动化发现产品，下面是示意图。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| +------------------+
| orb-agent |
|------------------|
| 网络扫描/资产发现 |
+------------------+
|
| grpc 通过NMAP/SNMP等扫描结果（IP、主机、服务）
v
+------------------+
| Diode |
|------------------|
| 数据清洗/转换 |
| 安全传输/推送 |
+------------------+
|
| grpc 通过Diode插件标准化后的资产数据
v
+------------------+
| NetBox |
|------------------|
| IPAM / DCIM 管理 |
| 资产持续更新 |
+------------------+
|
相关文档
https://github.com/netboxlabs/diode
https://github.com/netboxlabs/diode/blob/develop/GET_STARTED.md
Diode安装
环境要求
NetBox 版本大于 4.2.3
Docker 版本大于 27.0.3
Docker 国内安装
PS：安装最新版，使用compose V2部署。
https://mirror.nju.edu.cn/mirrorz-help/docker-ce/?mirror=NJU
Docker Hub国内加速
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker-0.unsee.tech",
"https://docker-cf.registry.cyou",
"https://docker.1panel.live"
]
}
EOF
systemctl enable docker
systemctl daemon-reload && sudo systemctl restart docker
systemctl enable docker
|
环境介绍
NetBox部署教程：https://songxwn.com/netbox4-CN/
Docker安装Diode Server
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| mkdir /opt/diode
cd /opt/diode
curl -sSfLo quickstart.sh https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh
chmod +x quickstart.sh
./quickstart.sh http://192.168.31.173
docker compose up -d
|
查看netbox-to-diode用户的密钥 - 用于diode插件
1
2
3
4
|
echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)
|
Netbox 接入Diode Server
1
2
3
4
5
6
7
8
9
10
11
12
| cd /opt/netbox
source venv/bin/activate
pip install netboxlabs-diode-netbox-plugin
]
|
开启插件，并配置接入Diode参数
编辑configuration/configuration.py文件
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
PLUGINS = [
"netbox_diode_plugin",
PLUGINS_CONFIG = {
"netbox_diode_plugin": {
"diode_target_override": "grpc://<diode-server:port>/diode",
"diode_username": "netbox-to-diode",
"netbox_to_diode_client_secret": "NT3yLOQamJpx545nSacRf4IN8VrJ2zmWHkyrD2SkbAc="
},
}
|
- 注意：netbox_to_diode_client_secret 填写密钥为上面获取到的。
使能插件生效
1
2
3
4
5
6
7
8
9
10
|
cd /opt/netbox/netbox
./manage.py migrate netbox_diode_plugin
sudo systemctl restart netbox netbox-rq
|
orb Agent 部署
1
2
3
4
5
6
7
8
9
|
mkdir /opt/orb
cd /opt/orb
|
创建/opt/orb/agent.yaml - 网络扫描导入
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
| orb:
config_manager:
active: local
backends:
common:
diode:
target: grpc://192.168.31.173:8080/diode
client_id: ${DIODE_CLIENT_ID}
client_secret: ${DIODE_CLIENT_SECRET}
agent_name: agent01
network_discovery:
policies:
network_discovery:
discovery_1:
config:
schedule: "* * * * *"
timeout: 5
defaults:
description: IP discovered by network discovery
tags: [net-discovery, orb-agent]
scope:
targets:
- 192.168.31.0/24
- google.com
fast_mode: True
max_retries: 0
|
注意：grpc://192.168.31.173:8080/diode ，把IP替换为你的服务器IP即可。
🧩 ORB 配置结构总览
这段 YAML 主要定义了三个部分：
config_manager：ORB 自身的配置管理方式
backends：ORB 如何把数据上报到后端（如 diode）
policies：定义具体的任务（这里是 network discovery）
你可以把它类比成：
✅ 1. config_manager
1
2
| config_manager:
active: local
|
意思是：
这意味着你修改本地 YAML 就能立即生效，适合开发/测试环境。
✅ 2. backends（数据上报后端）
1
2
3
4
5
6
7
8
| backends:
common:
diode:
target: grpc://192.168.31.173:8080/diode
client_id: ${DIODE_CLIENT_ID}
client_secret: ${DIODE_CLIENT_SECRET}
agent_name: agent01
network_discovery:
|
🔍 解释：
common.diode
这是一个通用 backend，所有 policy 都可以复用它。
字段说明：
| 字段 |
作用 |
target |
diode server 的 gRPC 地址 |
client_id / client_secret |
用于认证（通常来自环境变量） |
agent_name |
ORB agent 的标识，便于后端区分来源 |
你可以把它理解为：
ORB 发现到的 IP、DNS 结果等，会通过 gRPC 推送到 diode。
network_discovery:
这里留空，表示 network_discovery policy 默认使用 common backend。
✅ 3. policies（任务定义）
这里定义了一个名为 discovery_1 的网络发现任务。
1
2
3
| policies:
network_discovery:
discovery_1:
|
✅ 3.1 config（任务执行参数）
1
2
3
4
5
6
| config:
schedule: "* * * * *"
timeout: 5
defaults:
description: IP discovered by network discovery
tags: [net-discovery, orb-agent]
|
🔍 字段解释：
| 字段 |
作用 |
schedule: "* * * * *" |
每分钟执行一次（cron 表达式） |
timeout: 5 |
每个探测任务最多执行 5 秒 |
defaults.description |
发现的资产默认描述 |
defaults.tags |
给发现的资产自动打标签 |
你可以把它理解为：
每分钟跑一次扫描，扫描结果会带上默认标签和描述，便于后端分类。
✅ 3.2 scope（扫描范围）
1
2
3
4
5
6
| scope:
targets:
- 192.168.31.0/24
- google.com
fast_mode: True
max_retries: 0
|
🔍 字段解释：
✅ targets
扫描目标列表，支持：
CIDR（如 192.168.31.0/24）
域名（如 google.com）
ORB 会自动：
对子网进行 ping/port 探测
对域名进行 DNS 解析
✅ fast_mode: True
快速扫描模式：
不做深度端口探测
不做反向 DNS
更适合大规模快速发现
✅ max_retries: 0
失败不重试，适合快速巡检。
✅ 整体流程（用你的视角总结）
ORB 的执行流程理解：
1
2
3
4
5
6
| 每分钟：
└─ network_discovery policy 启动
├─ 扫描 192.168.31.0/24
├─ DNS 解析 google.com
├─ 发现结果打上默认标签
└─ 通过 diode backend 上报到 192.168.31.173:8080
|
Docker compose 部署orb Agent
创建/opt/orb/docker-compose.yml文件
1
2
3
4
5
6
7
8
9
10
11
| services:
orb-agent:
image: netboxlabs/orb-agent:latest
container_name: orb-agent
environment:
DIODE_CLIENT_ID: "diode-ingest"
DIODE_CLIENT_SECRET: "NT3yLOQamJpx545nSacRf4IN8VrJ2zmWHkyrD2SkbAc="
volumes:
- /opt/orb:/opt/orb
command: ["run", "-c", "/opt/orb/agent.yaml"]
restart: unless-stopped
|
- DIODE_CLIENT_SECRET密钥通过命令
echo $(jq -r '.[] | select(.client_id == "diode-ingest") | .client_secret' /opt/diode/oauth2/client/client-credentials.json) 获取
部署启动
1
2
3
4
| docker compose up -d
docker compose logs
|
成果
技术交流群
发送邮件到 ➡️ [email protected]
或者关注WX公众号：网工格物
博客（最先更新）
https://songxwn.com/
