菜单
Configure and operate Orb Agent for automated network discovery into NetBox. Use when writing agent.yaml configs, setting up network/device/SNMP/worker discovery backends, deploying Orb Agent containers, managing policies and secrets, or troubleshooting discovery pipelines.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/netboxlabs/skills --skill netbox-discovery命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | netbox-discovery |
| description | Configure and operate Orb Agent for automated network discovery into NetBox. Use when writing agent.yaml configs, setting up network/device/SNMP/worker discovery backends, deploying Orb Agent containers, managing policies and secrets, or troubleshooting discovery pipelines. |
| license | Apache-2.0 |
Your knowledge of Orb Agent may be outdated. Discovery backends, configuration options, and supported platforms change between releases. Prefer retrieval over pre-trained knowledge.
| Source | URL / Method | Use for |
|---|---|---|
| Discovery docs | https://netboxlabs.com/docs/discovery/ | Product overview, getting started |
| Orb Agent docs | https://netboxlabs.com/docs/orb-agent/ | Configuration, backends, secrets |
| Config examples | https://netboxlabs.com/docs/orb-agent/config_samples/ | Sample agent.yaml files |
| Orb Agent repo | https://github.com/netboxlabs/orb-agent | Source, Dockerfile, changelog |
| NetBox MCP server | If configured — verify discovered objects in NetBox | Post-discovery validation |
Orb Agent is a Docker-based network discovery agent that automatically discovers infrastructure and ingests it into NetBox via Diode. It supports four discovery backends — network (NMAP), device (NAPALM), SNMP, and custom worker — each configurable through a single YAML file.
Data flow: Orb Agent → gRPC → Diode Server → Diode NetBox Plugin → NetBox
Prerequisites: NetBox 4.5+ (covers 4.5.x–4.6.x), Diode server deployed, diode-netbox-plugin installed in NetBox. This skill targets orb-agent v2.9.x.
Ingesting the NetBox 4.6 models (CableBundle, RackGroup, VirtualMachineType) — e.g. from switch-stack discovery — requires a NetBox 4.6 install with a matching Diode plugin/SDK.
For Diode SDK usage and custom ingestion patterns, see netbox-diode.
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 run --net=host \
-v ${PWD}:/opt/orb/ \
-e DIODE_CLIENT_ID -e DIODE_CLIENT_SECRET \
netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml
backends:
common:
diode:
dry_run: true
dry_run_output_dir: /opt/orb
The agent.yaml has four top-level sections under orb::
| Section | Purpose |
|---|---|
config_manager | How policies are loaded — active: selects a source under sources: (local, git, or fleet) |
secrets_manager | Optional external secret store — active: selects a provider under sources: |
backends | Which discovery engines to enable, plus common Diode settings |
policies | Per-backend discovery policy definitions |
See references/agent-config-format.md for the complete YAML schema.
Both config_manager and secrets_manager use the same shape: an active: key naming the source, and a sources: map of source configs.
sources.git with url:, branch:, auth: (a string: basic or ssh), username:/password: (basic) or private_key: (ssh), and skip_tls:. The repo needs a root selector.yaml that matches agents to policy files.config_manager:
active: git
sources:
git:
url: "https://github.com/org/policies.git" # NOT "repo:"
branch: main
auth: basic # string, NOT auth.type
username: orb
password: ${GIT_TOKEN}
skip_tls: false
The agent matches selectors against its top-level orb.labels (not backends.common.agent_labels, which are telemetry labels only). See references/deployment-patterns.md for the selector.yaml format.
Same active: + sources: shape. orb-agent v2.9 ships four providers:
Provider (active:) | Reference syntax |
|---|---|
vault (HashiCorp) | ${vault://engine/path/to/secret/key} — token, AppRole, UserPass, Kubernetes, LDAP auth; multi-segment mount paths supported |
doppler | ${doppler://<secret_name>} or qualified ${doppler://<project>/<config>/<secret_name>} |
cyberark (CCP, beta) | ${cyberark://<Safe>/<Object>} or ${cyberark://<AppID>//<Safe>/<Object>/<Field>} |
delinea (Secret Server, beta) | ${delinea://id/<id>/<field>} or ${delinea://path/<path>/<field>} |
Optional schedule polls for secret rotations (auto-updates policies). Plain environment variables also work: ${VAR_NAME}.
Scans IP ranges/subnets with NMAP and ingests discovered IP addresses.
Scope: IPs, IP ranges, subnets, domain names.
Key policy options: schedule, fast_mode, timing (T0-T5), ports, top_ports, scan_types (syn/connect), os_detection, ping_scan, dns_servers.
⚠️ Root required by default. The default scan uses SYN scan (-sS) which requires CAP_NET_RAW. For rootless Podman, you must use:
config:
scan_types: [connect]
skip_host: true
# Do NOT enable fast_mode
Connects to devices via NAPALM and discovers detailed inventory — devices, interfaces, IPs, prefixes, VLANs, platforms, manufacturers.
Scope: hostname (supports subnets/ranges), username, password, driver (optional — auto-detected), optional_args.
Key features:
ssh_config_file with ProxyJumpINSTALL_DRIVERS_PATH env varcapture_running_config, capture_startup_config)VirtualChassis entity plus one Device per member and routes interfaces/IPs to the owning member (Cisco IOS, Juniper, Aruba CX, HP Comware, Brocade FastIron, Huawei VRP)netbox_id per-target scope option for matching an existing device by PKDiscovers devices and interfaces via SNMP polling.
Scope: Hosts (IPs, subnets, ranges) with per-target or policy-level authentication.
Auth: SNMPv1/v2c (community string), SNMPv3 (username, security_level, auth/priv protocols and passphrases).
Key options: schedule, timeout, snmp_timeout, retries, lookup_extensions_dir.
Runs custom Python packages that use the Diode Python SDK to ingest any entity type.
Config: package (required — Python package name), schedule.
Scope: Freeform (list or map — defined by the package).
Custom packages: Use INSTALL_WORKERS_PATH env var + workers.txt.
See references/backend-details.md for full parameter reference and entity mappings.
Policies are defined per-backend and can run multiple named policies simultaneously:
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}
Omit schedule for run-once execution. Schedule format is standard cron.
docker run --net=host \
-v ${PWD}:/opt/orb/ \
-e DIODE_CLIENT_ID -e DIODE_CLIENT_SECRET \
netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml
--net=host is needed for NMAP raw socket scans. Alternative: -u root.
sudo podman run --privileged --net=host ...| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores |
| Memory | 1.5 GB | 2 GB |
| Disk | 1 GB | 2 GB |
Docker 20.10+ / Podman 4.0+. Linux x86_64/arm64 fully supported; macOS/Windows limited (no host networking).
For fleet deployments, use Git config manager with a central repo containing selector.yaml that matches agent labels to policy files. Agents poll on a cron schedule for config changes.
See references/deployment-patterns.md for detailed deployment examples.
--net=host support — network discovery is limited.scan_types: [connect] + skip_host: true + no fast_mode.timeout (minutes) and appropriate timing level.driver explicitly.