netbox-discovery

NetBox Discovery（Orb Agent）

你对 Orb Agent 的了解可能已经过时。 Discovery 后端、配置选项和支持的平台会随版本发布而变化。请优先检索，而非依赖预训练知识。

检索来源

来源	URL / 方法	用途
Discovery 文档	https://netboxlabs.com/docs/discovery/	产品概览、入门指南
Orb Agent 文档	https://netboxlabs.com/docs/orb-agent/	配置、后端、密钥
配置示例	https://netboxlabs.com/docs/orb-agent/config_samples/	agent.yaml 文件示例
Orb Agent 仓库	https://github.com/netboxlabs/orb-agent	源码、docs/（权威键名）、变更日志
NetBox MCP 服务	如已配置——在 NetBox 中验证已发现的对象	Discovery 后验证

简介

Orb Agent 是基于 Docker 的网络发现 Agent，可自动发现基础设施，并通过 Diode 将其摄取到 NetBox。它提供五种 Discovery 后端——network（NMAP）、device（NAPALM）、SNMP、gNMI 和 custom worker——以及用于导出 OTLP 指标且不会向 NetBox 摄取任何内容的可观测性后端（snmp_telemetry、gnmi_telemetry、pktvisor、OpenTelemetry Infinity）。所有后端均通过单个 YAML 文件配置。

数据流： Orb Agent → gRPC → Diode Server → Diode NetBox Plugin → NetBox

前提条件： NetBox 4.5+（涵盖 4.5–4.7）、已部署 Diode 服务、已在 NetBox 中安装 diode-netbox-plugin。本指南适用于 orb-agent v2.16.x（镜像标签 netboxlabs/orb-agent:2.16.0）。

Agent 中捆绑的 Diode SDK 决定了 Discovery 可以发出哪些 NetBox 模型。NetBox 4.6 模型（CableBundle、RackGroup、VirtualMachineType）和 4.7 字段/模型（cooling、ModuleBayType、channelized interfaces、Service.port_mappings）仅在安装了相应版本且使用匹配 Diode 插件的 NetBox 上可用——参见 netbox-diode。

有关 Diode SDK 用法和自定义摄取模式，请参见 netbox-diode。

快速参考

最简 agent.yaml

orb:
  config_manager:
    active: local
  backends:
    common:
      diode:
        target: grpc://diode-server:8080/diode  # Cloud/Enterprise: https://your-instance.netboxcloud.com/diode
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: my-agent
    network_discovery:    # Enable desired backends
    device_discovery:
    snmp_discovery:
  policies:
    # Backend-specific policies go here

Docker 运行

docker run --net=host \
  -v ${PWD}:/opt/orb/ \
  -e DIODE_CLIENT_ID -e DIODE_CLIENT_SECRET \
  netboxlabs/orb-agent:2.16.0 run -c /opt/orb/agent.yaml

在生产环境中固定镜像标签（2.16.0）；latest 始终指向最新版本。

Dry Run（测试，不向 Diode 发送数据）

backends:
  common:
    diode:
      dry_run: true             # client_id / client_secret not required in dry run
      dry_run_output_dir: /opt/orb

配置结构

agent.yaml 在 orb: 下包含四个顶层部分（另有可选的 labels）：

部分	用途
config_manager	策略的加载方式——active: 用于选择 sources: 下的来源（local、git 或 fleet）
secrets_manager	可选的外部密钥存储——active: 用于选择 sources: 下的提供方
backends	要启用的后端，以及通用 Diode/OTLP 设置和每个后端的生命周期（start_mode）
policies	每个后端的 Discovery 策略定义（仅适用于 config_manager.active: local）

任何 orb.* 键也可通过环境变量 ORB_<PATH> 覆盖，路径片段之间使用 __ 分隔（例如 ORB_SECRETS_MANAGER__ACTIVE=vault）——这便于在部署时注入密钥管理器的选择。完整的 YAML 架构和覆盖规则请参见 references/agent-config-format.md。

配置管理器

config_manager 和 secrets_manager 使用相同的结构：active: 键用于指定来源，sources: 映射用于定义来源配置。

• local — 在同一个 YAML 文件中定义策略。配置最简单。
• git — 按 schedule: 轮询 Git 仓库以获取策略。在 sources.git 下配置，包含 url:、branch:、auth:（一个字符串：basic、ssh 或 github_app）、username:/password:（basic）或 private_key:（ssh），或 github_app: 配置块（client_id、installation_id、private_key），以及 skip_tls:。仓库根目录需要有一个 selector.yaml，用于将 Agent 匹配到策略文件。

config_manager:
  active: git
  sources:
    git:
      url: "https://github.com/org/policies.git"   # NOT "repo:"
      branch: main
      schedule: "*/5 * * * *"
      auth: basic                                   # string, NOT auth.type
      username: orb
      password: ${GIT_TOKEN}
      skip_tls: false

Agent 会根据其顶层 orb.labels 匹配选择器（而非仅用于遥测的 backends.common.agent_labels）。有关 selector.yaml 格式和 GitHub App 身份验证，请参阅 references/deployment-patterns.md。

密钥管理器

使用相同的 active: + sources: 结构。orb-agent v2.16 提供五种提供程序：

提供程序（active:）	引用语法
vault（HashiCorp KV v2）	${vault://<mount>//<path>/<key>}（限定格式，支持多段 mount）、${vault://<path>/<key>}（需要 sources.vault.mount），或旧格式 ${vault://<mount>/<path>/<key>} — 支持 Token、AppRole、UserPass、Kubernetes、LDAP 身份验证
doppler	${doppler://<secret_name>} 或限定格式 ${doppler://<project>/<config>/<secret_name>}
cyberark（CCP，测试版）	${cyberark://<Safe>/<Object>} 或 ${cyberark://<AppID>//<Safe>/<Object>/<Field>} — sources.cyberark.url 可以是 CCP 基础 URL；如果 CCP 在非默认 IIS 应用名称下运行，则可以是完整的 …/api/Accounts 端点 (v2.16)
delinea（Secret Server，测试版）	${delinea://id/<id>/<field>} 或 ${delinea://path/<path>/<field>}
dsv（Delinea DevOps Secrets Vault，v2.14+）	${dsv://<secret-path>/<field-key>}

可选的 schedule 会轮询密钥轮换（自动更新策略）。普通环境变量也可使用：${VAR_NAME} — 但仅适用于各后端会解析的字段（所有 device_discovery 范围/默认值字符串；仅 SNMP 凭据字段；不包括 network_discovery 范围）。

发现后端

网络发现（NMAP）

使用 NMAP 扫描 IP 范围/子网，并导入发现的 IP 地址（通过反向查找获得 dns_name，通过 defaults 设置 VRF/租户/角色）。defaults.tenant 和 defaults.vrf 可以是裸名称或映射；vrf 映射可以包含自己的 tenant（{name, tenant: {name, group}}），这样 Diode 就会匹配归属于租户的 VRF，而不是创建一个没有租户的重复项 — defaults.tenant 仅适用于 IP (v2.16)。

范围： IP、IP 范围、子网、域名。

关键策略选项： config.schedule、config.timeout（分钟，默认值为 5）；范围选项 fast_mode、timing（T0-T5）、ports（列表）、top_ports、scan_types（syn/connect/udp/...）、os_detection、ping_scan、skip_host、dns_servers、icmp_echo/icmp_timestamp/icmp_netmask。

⚠️ 默认需要 root 权限。 默认扫描使用 SYN 扫描（-sS），需要 CAP_NET_RAW。对于无 root 权限的 Podman，必须使用：

scope:
  scan_types: [connect]
  skip_host: true
  # Do NOT enable fast_mode

设备发现（NAPALM）

通过 NAPALM 连接设备（捆绑了 48 个驱动：7 个标准驱动 + 41 个自定义驱动），并发现详细清单，包括设备、接口、IP、前缀、VLAN、VRF、模块、平台、制造商和运行配置。

范围：hostname（支持子网/范围，每个策略最多 65536 个地址）、username、password、driver（可选——在标准驱动中自动检测）、optional_args、override_defaults、netbox_id。

主要功能：

• 行为开关位于 config.options 下（不在 defaults 下）：discovery_drivers（启用自定义驱动的自动检测）、device_name_source: hostname|fqdn （v2.15）、emit_device_name: false（停止提议重命名主机名——需要 netbox_id 或 asset_tag）、discover_modules: off|linecards|full、discover_vrfs、capture_running_config/capture_startup_config（以及 sanitize_config）、create_unknown_vlans、emit_host_prefixes、emit_prefix_vlan（svi-name 还会使用设备为 L3 接口报告的 VLAN ID，前提是驱动支持此功能——Junos、MikroTik、FastIron （v2.16））、emit_lag_membership（默认为 true；根据 Junos 聚合以太网成员关系设置 Interface.lag——不会创建任何对象，必须发现 ae 聚合接口并将其类型设为 lag）（v2.16）
• 嵌套默认值层级（站点、角色、机架、租户、逐实体覆盖）；vlan.group 接受名称，或按 scope_site/scope_site_group/scope_region/scope_location 限定范围的映射 （v2.15）；已配置的 vrf 映射（defaults.vrf、ipaddress.vrf、prefix.vrf、vrf_ipv4/vrf_ipv6）可以指定自己的 tenant——地址/前缀的租户不会设置 VRF 的租户 （v2.16）
• 机架位置 （v2.16）：rack（策略的 defaults 或每个目标的 override_defaults）会将设备放置在其站点/位置中同名的机架上；position（从 1 开始的 U 位，步长为 0.5）和 face（front|rear）仅可在单地址目标的 override_defaults 中使用，且必须同时设置，并且需要指定机架。数字机架名称需加引号（rack: "01"）。仅放置堆叠主设备
• 接口模式匹配（interface_patterns，包含 match/type；interface_exclude_patterns）
• 通过带有 ProxyJump 的 ssh_config_file 支持跳板机/SSH
• 通过 INSTALL_DRIVERS_PATH 环境变量使用自定义 NAPALM 驱动
• 使用 YAML 锚点复用凭据
• 交换机堆叠 / Virtual Chassis——一个 VirtualChassis 实体和每个成员一个 Device；接口/IP 会路由到所属成员；成员名称来自 stack_member_name_template（默认 {name}-{id}）；支持 StackWise Virtual （v2.12）
• netbox_id 逐目标范围选项，用于通过 PK 匹配现有设备

SNMP 发现

通过 SNMP 轮询发现设备、接口、IP、MAC、VLAN、前缀、VRF、模块和交换机堆叠。

范围： targets（每项都是一个映射，包含 host——IP、子网或范围——以及可选的 port、authentication、override_defaults、netbox_id），并以策略级别的 authentication 作为回退。

身份验证： protocol_version: SNMPv1|SNMPv2c|SNMPv3（键名为 protocol_version，而非 version）；v1/v2c 使用 community；v3 使用 username、security_level、auth_protocol/auth_passphrase（MD5、SHA、SHA224–SHA512）、priv_protocol/priv_passphrase（DES、AES、AES192/256、AES192C/256C）、context_name（v2.13）。

关键选项： schedule、timeout（秒）、snmp_timeout、snmp_probe_timeout、retries、lookup_extensions_dir；config.options：discover_modules、discover_vrfs、discover_asset_tags、emit_prefixes、emit_device_name、interface_name_source: auto|ifname|ifdescr、create_unknown_vlans、emit_lag_membership（默认为 true；Interface.lag 来自 IEEE8023-LAG-MIB，Junos 逻辑单元会合并到物理端口）（v2.16）、vlan_interface_name_prefix（重命名交换机以裸 VLAN ID 命名的接口，例如 5 → Vlan5；更改此项会重命名接口）（v2.16）。默认值：rack（字面值，绝不是 OID），以及每个目标的 position/face 和 vrf.tenant，与设备发现相同 （v2.16）。后端级别的 ingest_buffer_size 用于限制排队中的 Diode 数据摄取量。

v1/v2c 子网扫描会向范围内的每个地址发送团体字符串。在不受信任的网段上进行范围扫描时，请使用 SNMPv3。

gNMI 发现 （v2.12+）

事件驱动：长期运行的 gNMI 订阅（依次回退：ON_CHANGE → SAMPLE → GET）会在设备、接口、模块、IP 和 VRF 发生变化后的数秒内摄取这些变更。

范围： targets，包含 host（单个端点，或在订阅前进行扫描的 CIDR/范围 （v2.15））、port（默认值为 9339）、username/password、tls（ca/cert/key、skip_verify、insecure）、profile、mode、netbox_id、override_defaults（position/face 只能出现在此处 （v2.16））。带凭据的 CIDR/范围目标要求使用经过验证的 TLS。

关键选项： mode（auto|on_change|sample|get）、debounce_ms、sample_interval_ms、get_interval_ms、rescan_interval_ms、options.capture_config、options.emit_lag_membership（默认启用；仅将成员端口链接到同一周期中发现且类型为 lag 的 LAG 聚合接口）（v2.16）；默认值与设备发现相同（包括作用域限定的 vlan.group、rack，以及作为名称或 {name, group, …} 映射的 ip_address/prefix/vlan/vrf 租户——vrf.tenant 会应用于每个发现的 VRF）（v2.16）。

Worker（自定义 Python）

运行使用 Diode Python SDK 摄取任意实体类型的自定义 Python 包。

配置： package（必填——Python 包名称）、schedule。 范围： 自由格式（列表或映射，由软件包定义）。 自定义软件包： 使用 INSTALL_WORKERS_PATH 环境变量和 workers.txt。

完整参数参考和实体映射请参阅 references/backend-details.md。

后端生命周期 （v2.15）

由一个监督器管理后端进程。每个后端键都接受 start_mode: eager|on_demand（按需后端会在启动时配置，但在收到首个策略时才启动；启动失败后每 5 分钟重试一次）和 start_timeout（秒，1–300）。默认情况下，镜像将 snmp_telemetry 和 gnmi_telemetry 声明为按需后端，因此仅用于发现的 Agent 不会运行任何额外内容。由 Fleet 发起的重置会通过同一监督器重启后端。

策略

策略按后端定义，并可同时运行多个命名策略（名称会原样转发，且不得包含 /）：

policies:
  network_discovery:
    scan_office:
      config:
        schedule: "0 */6 * * *"
        defaults:
          tags: [discovered, office]
      scope:
        targets:
          - 10.0.0.0/24
          - 10.0.1.0/24
  device_discovery:
    switches:
      config:
        schedule: "0 2 * * *"
        defaults:
          site: main-dc
          role: switch
      scope:
        - hostname: 10.0.0.1
          username: admin
          password: ${vault://kv//network/switch_pass}

省略 schedule 即可执行一次。计划格式为标准 cron。

部署

Docker（推荐）

docker run -d --name orb-agent --restart unless-stopped \
  --stop-timeout 60 --log-driver local \
  --net=host \
  -v ${PWD}:/opt/orb/ \
  --env-file ${PWD}/.env \
  netboxlabs/orb-agent:2.16.0 run -c /opt/orb/agent.yaml

NMAP 原始套接字扫描需要 --net=host（替代方案：-u root）。--stop-timeout 60 可让正在执行的策略运行完成；--log-driver local 可限制日志增长。请在启动时启用运行时（systemctl enable --now docker），以便重启策略在系统重启后生效。

Podman

• 特权模式： sudo podman run --privileged --net=host ...
• 无根模式： 无需 sudo，但仅限 TCP connect 扫描；为用户启用 podman-restart.service，并运行 loginctl enable-linger。

系统要求

资源	最低配置	推荐配置
CPU	2 核	4 核
内存	1.5 GB	2 GB
磁盘	1 GB	2 GB

Docker 20.10+（推荐 24.0+）/ Podman 4.0+（推荐 5.0+）。完整支持 Linux x86_64/arm64；macOS/Windows 支持有限（不支持主机网络）。

基于 Git 的多 Agent 管理

对于大规模部署，请使用 Git 配置管理器，并在中央仓库中放置 selector.yaml，将 Agent 标签与策略文件进行匹配。Agent 按 cron 计划轮询配置变更。GitHub App 身份验证（auth: github_app）会提供短时有效、限定仓库范围的凭据，而非 PAT。

详细部署示例请参阅 references/deployment-patterns.md。

常见问题

• 默认网络发现 = SYN 扫描，且需要 root 权限。 请务必先进行试运行。
• macOS/Windows： 不支持 --net=host，网络发现能力有限。
• 无根 Podman： 必须使用 scan_types: [connect] + skip_host: true，且不使用 fast_mode。
• 先进行试运行。 在正式接入 Diode 前验证 JSON 输出。
• 大型子网： NMAP 扫描可能较慢，请使用 timeout（分钟）和适当的 timing 级别。
• NAPALM 驱动自动检测仅会尝试 7 个标准驱动；请在 options.discovery_drivers 中列出打包的自定义驱动，或明确设置 driver。
• 键名很重要： interface_patterns 条目使用 match/type；SNMP 身份验证使用 protocol_version；网络 ICMP 标志为扁平键 icmp_echo/icmp_timestamp/icmp_netmask；设备发现的 IP 默认键为 ipaddress，SNMP/gNMI 使用 ip_address。对于无法识别的键，Agent 日志会发出警告 (v2.15)——更改策略后请检查日志。
• 重命名注意事项： 在现有部署中将 device_name_source 切换为 fqdn，或更改 interface_name_source、vlan_interface_name_prefix，会创建新的 NetBox 对象，除非先重命名现有对象（Diode 按名称匹配）。
• VLAN 需要站点和组。 不带组发送的 VLAN 仅按 VID 匹配，并会与按组限定的 VLAN 重复；没有 defaults.site 的 vlan.group 会将组限定到占位站点 undefined。两者都要设置——Agent 首次发送无法匹配的 VLAN 时会记录警告 (v2.16)。
• 机架位置具有粘性。 每次运行都会重新应用 position/face（在 NetBox 中移动的设备会移回原位）；如果某个 U 已被另一台设备占用，Diode 会更新 该设备；NetBox 拒绝的位置会导致该周期的设备记录处理失败——请查看 Diode 接入日志。

版本说明

orb-agent v2.16.0（2026-10-12）

• 随附的后端：device-discovery 1.34.0、snmp-discovery 1.38.0、network-discovery 1.20.0、gnmi-discovery 1.2.0、snmp-telemetry 1.1.0、gnmi-telemetry 1.1.0。
• device/snmp/gnmi-discovery 支持机架放置：在 defaults 或目标的 override_defaults 中设置 rack；position + face 仅适用于单地址目标。
• 已配置的 VRF 映射会指定自身的 tenant（device/snmp/network-discovery；gnmi 的 vrf.tenant 适用于发现的 VRF）。network-discovery 的 defaults.tenant 以及 gnmi 的地址/前缀/VLAN tenant 支持 {name, group, description, comments, tags} 映射。
• Interface.lag：device-discovery 从 Junos AE 成员关系获取，snmp-discovery 从 IEEE8023-LAG-MIB 获取，gnmi-discovery 从 OpenConfig aggregate-id 获取；全部由 emit_lag_membership 控制（默认开启）。
• emit_prefix_vlan: svi-name 也会解析设备报告的 VLAN ID（Junos L3 VLAN 接口、MikroTik、FastIron；任何厂商的 SNMP 纯数字 SVI）；snmp 的 vlan_interface_name_prefix。
• Agent：CyberArk url 支持完整的 CCP 端点；发送的 VLAN 没有可匹配的范围时只发出一次警告；如果其他进程占用了后端的监听地址，则拒绝启动；映射键旁的 YAML 合并键现在会导致配置错误。
• 遥测后端（Observability，不接收 NetBox 数据）：每个策略对应一个 OTLP instrumentation scope，并携带 policy_name。

orb-agent v2.15.0（2026-09-16）

• 后端 supervisor 支持 start_mode: on_demand / start_timeout；镜像中随附 snmp-telemetry v1.0.0 和 gnmi-telemetry v1.0.0（Observability — 不接收 NetBox 数据）。
• Git 配置管理器：auth: github_app。心跳携带 last_restart_ts；在 fleet telemetry bridge 上提供 OTLP/HTTP。
• device-discovery：device_name_source、作用域限定的 vlan.group、基于 SVI 的前缀↔VLAN 关联、记录未识别的 IOS 模块、每策略目标展开预算。gnmi-discovery：CIDR/范围目标、作用域限定的 vlan.group。snmp-discovery：Huawei VLAN MIB、Juniper VRF MIB、stack_member_name_template。
• v2.14：dsv 密钥管理器。v2.13：emit_device_name（设备）、SNMPv3 context_name。v2.12：gnmi_discovery 后端、ORB_* 环境变量覆盖、StackWise Virtual 堆栈、emit_host_prefixes、emit_device_name（SNMP）。

参考资料

• references/agent-config-format.md — agent.yaml 的完整 YAML 架构
• references/backend-details.md — 各后端的完整参数参考和实体映射
• references/deployment-patterns.md — Docker、Podman、Vault、Git 管理的 fleet 模式

跨技能参考

• netbox-diode — 用于以编程方式接收数据的 Diode SDK（Discovery 内部使用 Diode）
• netbox-assurance — 将发现的数据与预期状态进行比较的 Assurance 引擎