[其他] NetBox自动化资产发现实战：使用orb-agent与Diode插件导入IP地址

本文详细介绍了如何使用orb-agent进行网络扫描，收集IP信息，并通过Diode将数据自动化导入NetBox。这两个工具都是NetBox官方推出的自动化发现产品，能够帮助运维团队高效管理网络资产。以下是整体架构示意图：

+------------------+
|    orb-agent     |
|------------------|
| 网络扫描/资产发现 |
+------------------+
          |
          | grpc 通过NMAP/SNMP等扫描结果（IP、主机、服务）
          v
+------------------+
|      Diode       |
|------------------|
| 数据清洗/转换    |
| 安全传输/推送    |
+------------------+
          |
          | grpc 通过Diode插件标准化后的资产数据
          v
+------------------+
|     NetBox       |
|------------------|
| IPAM / DCIM 管理 |
| 资产持续更新     |
+------------------+

相关文档

• Diode GitHub仓库：https://github.com/netboxlabs/diode
• Diode快速入门指南：https://github.com/netboxlabs/diode/blob/develop/GET_STARTED.md

Diode安装

环境要求

• NetBox 版本大于 4.2.3
• Docker 版本大于 27.0.3

Docker 国内安装

建议安装最新版本，并使用Docker Compose V2进行部署。国内用户可参考南京大学镜像站获取安装帮助：https://mirror.nju.edu.cn/mirrorz-help/docker-ce/?mirror=NJU

Docker Hub国内加速配置

执行以下命令配置镜像加速器：

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

环境介绍

• 操作系统：Rocky Linux 9.7
• NetBox版本：4.4.8（源码部署）
• NetBox访问地址：http://192.168.31.173

Docker安装Diode Server

1. 创建工作目录并下载安装脚本：

   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

2. 运行脚本并启动服务：

   ./quickstart.sh http://192.168.31.173
   docker compose up -d

   注意：Diode Server会占用宿主机的8080端口。

获取netbox-to-diode用户密钥

执行以下命令获取密钥，用于后续Diode插件配置：

echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)

NetBox接入Diode Server

1. 进入NetBox安装目录并激活Python虚拟环境：

   cd /opt/netbox
   source venv/bin/activate
   pip install netboxlabs-diode-netbox-plugin

2. 编辑配置文件configuration/configuration.py，启用插件并配置参数：

   
   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`需填写上一步获取的密钥。

3. 执行数据库迁移并重启服务：
```bash
cd /opt/netbox/netbox
./manage.py migrate netbox_diode_plugin
sudo systemctl restart netbox netbox-rq

orb Agent部署

1. 创建工作目录：

   mkdir /opt/orb
   cd /opt/orb

2. 创建配置文件agent.yaml，定义网络扫描任务：

   
   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

  
  注意：将`target`中的IP地址替换为实际Diode Server的IP。

配置结构解析

• config_manager：配置源为本地文件，便于测试。
• backends：定义数据上报后端，通过gRPC将扫描结果推送到Diode。
• policies：定义每分钟执行一次的网络发现任务，扫描指定子网和域名，并打上标签。

3. 创建Docker Compose文件docker-compose.yml：

   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)

4. 启动orb Agent服务：

   docker compose up -d
   docker compose logs

成果展示

部署完成后，NetBox中将自动更新扫描到的IP地址等资产信息，实现网络资产的持续同步与管理。