NetBox 自动化导入资产 - IP地址

简介

本文章主要讲解使用orb-agent 扫描网络收集IP信息，通过Diode 摄取到NetBox。

这两个工具都是NetBox官方的自动化发现产品，下面是示意图。

+------------------+
|    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国内加速

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

环境介绍

  • 系统使用Rocky Linux 9.7
  • 使用源码部署的NetBox 4.4.8
  • NetBox访问地址为 http://192.168.31.173

NetBox部署教程：https://songxwn.com/netbox4-CN/

Docker安装Diode Server

mkdir /opt/diode
# 创建 Diode 服务的工作目录，用于存放配置和 compose 文件

cd /opt/diode
# 进入工作目录，后续文件都会下载到这里

curl -sSfLo quickstart.sh https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh
# 从官方仓库下载 Diode 的 quickstart 脚本，用于自动生成 docker-compose.yaml 等文件
# -sSfL 参数确保失败时退出，并跟随重定向

chmod +x quickstart.sh
# 给 quickstart.sh 添加可执行权限

./quickstart.sh http://192.168.31.173
# 运行 quickstart 脚本，指定你的 NetBox访问 URL
# 脚本会自动生成 docker-compose.yaml、配置文件和默认目录结构

docker compose up -d
# 启动 Diode 服务（PostgreSQL、Redis、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

cd /opt/netbox
# 进入 NetBox 的安装目录（通常包含 venv、configuration、netbox 源码等）

source venv/bin/activate
# 激活 NetBox 的 Python 虚拟环境，确保插件安装到 NetBox 的 venv 中

pip install netboxlabs-diode-netbox-plugin
# 在 NetBox 的虚拟环境中安装 Diode NetBox 插件，用于与 Diode/Orb 集成


]

开启插件，并配置接入Diode参数

编辑configuration/configuration.py文件

PLUGINS = [
    "netbox_diode_plugin",

PLUGINS_CONFIG = {
    "netbox_diode_plugin": {
        # Diode gRPC target for communication with Diode server
        "diode_target_override": "grpc://<diode-server:port>/diode",
        # NetBox username associated with changes applied via plugin
        "diode_username": "netbox-to-diode",
        # netbox-to-diode client secret from earlier step
        "netbox_to_diode_client_secret": "NT3yLOQamJpx545nSacRf4IN8VrJ2zmWHkyrD2SkbAc="
    },
}
  • 注意：netbox_to_diode_client_secret 填写密钥为上面获取到的。

使能插件生效

cd /opt/netbox/netbox
# 进入 NetBox 的 Django 项目目录（包含 manage.py），插件迁移必须在这里执行

./manage.py migrate netbox_diode_plugin
# 执行 Diode 插件的数据库迁移，创建插件所需的表结构

sudo systemctl restart netbox netbox-rq
# 重启 NetBox 主服务和后台任务队列，使插件加载并生效

orb Agent 部署

mkdir /opt/orb
# 创建 Orb Agent 的工作目录，用于存放配置文件、agent.yaml、compose 文件等

cd /opt/orb
# 进入 Orb Agent 的工作目录，后续所有操作都会在这里进行

创建/opt/orb/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 # IP subnet
            - google.com # dns lookup
          fast_mode: True
          max_retries: 0

注意：grpc://192.168.31.173:8080/diode ，把IP替换为你的服务器IP即可。

🧩 ORB 配置结构总览

这段 YAML 主要定义了三个部分：

  1. config_manager：ORB 自身的配置管理方式
  2. backends：ORB 如何把数据上报到后端（如 diode）
  3. policies：定义具体的任务（这里是 network discovery）

你可以把它类比成：

  • config_manager = ORB 的“配置源”
  • backends = ORB 的“输出插件”
  • policies = ORB 的“任务调度器 + 任务定义”

✅ 1. config_manager

config_manager:
  active: local

意思是：

  • ORB 的配置来源是 本地文件（local）
  • 而不是从远端配置中心（如 diode server）动态拉取

这意味着你修改本地 YAML 就能立即生效，适合开发/测试环境。

✅ 2. backends（数据上报后端）

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 的网络发现任务。

policies:
  network_discovery:
    discovery_1:

✅ 3.1 config（任务执行参数）

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（扫描范围）

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 的执行流程理解：

每分钟：
  └─ 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文件

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) 获取

部署启动

docker compose up -d

docker compose logs

成果

技术交流群

发送邮件到 ➡️ me@songxwn.com

或者关注WX公众号：网工格物

微信扫码

博客（最先更新）

https://songxwn.com/

posted @ 2025-12-15 10:57  网工格物  阅读(98)  评论(0)    收藏  举报