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 で検出されたオブジェクトを確認	検出後の検証

はじめに

Orb Agent は Docker ベースのネットワーク検出エージェントです。インフラストラクチャを自動的に検出し、Diode 経由で NetBox に取り込みます。5 つの検出バックエンド（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）です。

エージェントにバンドルされた Diode SDK によって、Discovery が出力できる NetBox モデルが決まります。NetBox 4.6 のモデル（CableBundle、RackGroup、VirtualMachineType）と 4.7 のフィールド／モデル（冷却、ModuleBayType、チャネル化インターフェイス、Service.port_mappings）が利用できるのは、対応するバージョンの NetBox インストールと一致する Diode プラグインを使用している場合のみです。詳しくは 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 は最新リリースを追跡します。

ドライラン（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: 配下に 4 つのトップレベルセクション（および任意の labels）があります。

セクション	目的
config_manager	ポリシーの読み込み方法 — active: で sources: 配下のソース（local、git、fleet）を選択します
secrets_manager	任意の外部シークレットストア — active: で sources: 配下のプロバイダーを選択します
backends	有効にするバックエンド、および共通の Diode／OTLP 設定とバックエンドごとのライフサイクル（start_mode）
policies	バックエンドごとの検出ポリシー定義（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 が必要です。

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

エージェントは、トップレベルの orb.labels に対してセレクターを照合します（backends.common.agent_labels はテレメトリ専用のラベルです）。selector.yaml の形式と GitHub App 認証については、references/deployment-patterns.md を参照してください。

シークレットマネージャー

同じ active: + sources: の構成です。orb-agent v2.16 では、5 つのプロバイダーが提供されています。

プロバイダー（active:）	参照構文
vault（HashiCorp KV v2）	${vault://<mount>//<path>/<key>}（修飾形式。複数セグメントのマウントにも対応）、${vault://<path>/<key>}（sources.vault.mount が必要）、または旧形式の ${vault://<mount>/<path>/<key>} — トークン、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 が必要です。rootless Podman では、次の設定を使用する必要があります。

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

デバイス検出（NAPALM）

NAPALM（標準ドライバー7種類＋カスタムドライバー41種類、計48種類をバンドル）経由でデバイスに接続し、デバイス、インターフェース、IP、プレフィックス、VLAN、VRF、モジュール、プラットフォーム、メーカー、実行中の設定など、詳細なインベントリーを検出します。

スコープ： hostname（サブネット／範囲に対応。ポリシーあたり最大65,536アドレス）、username、password、driver（省略可能。標準ドライバーから自動検出）、optional_args、override_defaults、netbox_id。

主な機能：

• 動作の切り替えは defaults ではなく config.options に設定します：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 のリンクアグリゲーション Ethernet メンバー情報から 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"）。配置されるのはスタックマスターのみです
• インターフェースのパターンマッチング（match/type を含む interface_patterns、interface_exclude_patterns）
• ProxyJump を使った ssh_config_file 経由のジャンプホスト／SSH サポート
• INSTALL_DRIVERS_PATH 環境変数によるカスタム NAPALM ドライバー
• 認証情報の再利用に使える YAML アンカー
• スイッチスタック／Virtual Chassis — 1 つの VirtualChassis エンティティとメンバーごとに 1 つの Device エンティティを作成し、インターフェース／IP を所有メンバーに割り当てます。メンバー名には stack_member_name_template を使用します（デフォルトは {name}-{id}）。StackWise Virtual に対応しています (v2.12)
• 既存のデバイスを PK で照合するための、ターゲットごとのスコープオプション netbox_id

SNMP ディスカバリー

SNMP ポーリングを通じて、デバイス、インターフェース、IP、MAC、VLAN、プレフィックス、VRF、モジュール、スイッチスタックを検出します。

スコープ： targets（各要素は、host（IP、サブネット、または範囲）と、任意の port、authentication、override_defaults、netbox_id を含むマップ）と、フォールバックとしてのポリシーレベルの authentication。

認証： protocol_version: SNMPv1|SNMPv2c|SNMPv3（キーは version ではなく protocol_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。IEEE8023-LAG-MIB から Interface.lag を設定し、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 の変更を、発生から数秒以内に取り込みます。

スコープ： 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)）を含む targets。認証情報を使用する 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 がオンデマンドとして宣言されるため、ディスカバリー専用のエージェントは追加の処理を実行しません。フリートから開始されたリセットでも、同じスーパーバイザーを通じてバックエンドが再起動されます。

ポリシー

ポリシーはバックエンドごとに定義し、名前付きポリシーを複数同時に実行できます（名前はそのまま転送され、/ を含めることはできません）。

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}

1 回限りの実行にするには、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 の raw socket スキャンには --net=host が必要です（代替方法：-u root）。--stop-timeout 60 を指定すると、実行中のポリシー処理を完了できます。--log-driver local を指定すると、ログの増加を抑えられます。再起動ポリシーを再起動後にも適用するため、起動時にランタイムを有効にしてください（systemctl enable --now docker）。

Podman

• 特権モード： sudo podman run --privileged --net=host ...
• ルートレス： sudo は不要ですが、TCP コネクトスキャンのみに制限されます。ユーザーに対して 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 ベースのマルチエージェント管理

フリートのデプロイでは、エージェントのラベルとポリシーファイルを対応付ける selector.yaml を含む中央リポジトリとともに、Git 設定マネージャーを使用してください。エージェントは 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 です。認識されないキーはエージェントログに警告として記録されます（v2.15）。ポリシーを変更した後はログを確認してください。
• 名前変更時の注意点： 既存のデプロイで device_name_source を fqdn に変更したり、interface_name_source や vlan_interface_name_prefix を変更したりすると、既存のオブジェクトの名前を先に変更しない限り、新しい NetBox オブジェクトが作成されます（Diode は名前で照合します）。
• VLAN にはサイトとグループが必要です。 グループを指定せずに送信された VLAN は VID のみで照合され、グループスコープの VLAN が重複します。defaults.site を設定せずに vlan.group を指定すると、グループのスコープはプレースホルダーサイト undefined になります。両方を設定してください。照合できない 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。
• エージェント：CyberArk の url では CCP エンドポイント全体を指定できます。照合可能なスコープがない状態で VLAN が送信されると、一度だけ警告します。リッスンアドレスを別のプロセスが使用している場合、バックエンドの起動を拒否します。マッピングキーの隣にある YAML マージキーは、設定エラーとして扱われます。
• テレメトリバックエンド（Observability、NetBox への取り込みなし）：ポリシーごとに 1 つの OTLP インストルメンテーションスコープを使用し、policy_name を保持します。

orb-agent v2.15.0 (2026-09-16)

• バックエンドスーパーバイザーで 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 を追加。フリートテレメトリブリッジで 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（device）、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 管理フリートのパターン

スキル間の参考資料

• netbox-diode — プログラムによるデータ取り込みのための Diode SDK（Discovery は内部で Diode を使用）
• netbox-assurance — 検出されたデータと意図された状態を比較する Assurance エンジン