netbox-ndx

NetBox Data Exchange（NDX）

NDX（NetBox Data Exchange）は、インフラストラクチャのコンポーネントメタデータを厳選し、継続的に更新するカタログです。数百のメーカーにわたる数万種類のデバイスタイプを網羅しています。検索可能な参照データセットを提供し、メーカーの PDF や EOL に関する告知を何時間もかけて調べる手間を省きます。

オープンなカタログに、商用の拡充データと製品内機能を組み合わせています。 デバイス／モジュール／ラックタイプの定義カタログは、誰でも利用できます。コミュニティユーザーを含め、誰でも公開カタログを閲覧し、YAML 形式のタイプ定義を手動でダウンロードできます（コミュニティ Device Type Library と同じ形式です）。商用なのは、（a）拡充データ（ライフサイクル／熱特性／運用／プラットフォーム／可観測性のメタデータ）と、（b）NetBox Cloud／NetBox Enterprise 内蔵の NDX 機能（製品内から拡充データを閲覧、インポート、同期、関連付けする機能）です。NDX を説明する際は、この境界を明確にしてください。

NDX は機能であり、プラグインではありません。 製品内の機能は「NDX 機能」と呼んでください。プラグインによる実装は内部的な詳細です。提供される機能と、API を通じた利用方法に焦点を当ててください。

NDX に関する知識は古くなっている可能性があります。 カタログの対象範囲、拡充フィールド、プランごとの動作は継続的に変化します。データは AI の支援を受けてキュレーションされており、出典情報と信頼度が付与されています。事前学習済みの知識よりも検索結果を優先し、値を提示する際は必ず出典情報も明示してください。

NDX が提供するもの — 2 つのデータレイヤー

レイヤー	内容	アクセス	NetBox での格納先
デバイスタイプ定義	デバイス／モジュール／ラックタイプの物理的な構成情報：インターフェース、電源ポート、コンソールポート、ベイ、ラックユニット、重量。コミュニティ Device Type Library（DTL）と同じ形式で、出典を明記したうえで全内容を収録し、さらに NetBox Labs がキュレーションした数千件の定義を含みます。	オープン — コミュニティユーザーを含む誰もがカタログを閲覧し、YAML を手動でダウンロードできます	コンポーネントテンプレートを含む、標準的な NetBox の DeviceType／ModuleType／RackType オブジェクト
拡充データ	DTL にはない新しいメタデータ：ライフサイクル日、熱特性、環境上の制限、運用時の電力／騒音、プラットフォーム／NOS、可観測性プロトコルのメタデータ（SNMP／gNMI／NETCONF／Redfish／Modbus など）。各値には出典情報と信頼度スコアが付与されています。商用の付加価値です。	商用 — 有料プランで製品内の NDX 機能を通じて値を提供	インポートした各タイプに関連付けられる拡充レコード

NDX ではないもの

• 監視／テレメトリーではありません。 リアルタイムの状態は含まれません。
• CMDB／インスタンスデータではありません。 NDX が記述するのはデバイスのタイプ（「Cisco Nexus 93180YC-FX3」など）であり、実際に稼働している特定の機器ではありません。
• 自動設定ではありません。 可観測性メタデータは、何をどのように監視するか（OID、パス）を示しますが、ツールを設定するものではありません。
• 完全性は保証されません。 対象範囲にはばらつきがあり、多くのフィールドは null です。出典情報と信頼度によって、その状況を把握できます。

情報の取得元

情報源	URL／方法	用途
NDX 機能のドキュメント	https://netboxlabs.com/docs/ndx/	機能のリファレンス、インポート／同期、プラン
NDX 公開カタログ	https://netboxlabs.com/ndx	カタログの閲覧／検索、YAML のダウンロード（拡充データの値にはアクセス制限あり）
NetBox DCIM モデル	https://netboxlabs.com/docs/netbox/models/dcim/	DeviceType／ModuleType／RackType の構造
コミュニティ DTL	https://github.com/netbox-community/devicetype-library	NDX に含まれるオープンソースの DTL（Apache-2.0）
NetBox MCP／Platform MCP	設定されている場合 — /api/plugins/ndx/ エンドポイントを一覧表示／検査	実際のエンドポイントと拡充フィールドの確認

まず、機能が利用可能か確認します

curl -s -H "Authorization: Bearer $NETBOX_TOKEN" \
  "$NETBOX_URL/api/plugins/ndx/import-records/?limit=1" | python -m json.tool

ページ分割されたレスポンスが返る場合、製品内の NDX 機能を利用できます。404 は、このインスタンスで機能が有効になっていないことを示します（公開カタログでは引き続き閲覧でき、YAML としてダウンロードできますが、この NetBox には組み込まれていません）。製品内機能は NetBox Cloud（すべてのプラン）と NetBox Enterprise に付属します。無料プランではカタログ、インポート、エンリッチメントの利用可能フラグを確認でき、有料プランではエンリッチメントの値をすべて確認できます（以下の「プラン」を参照）。

---

対象範囲

このスキルでは、NetBox REST API（/api/plugins/ndx/）を介した NDX データの利用（NetBox トークンを持つエージェントがアクセスできるインターフェース）と、エンリッチメントのデータモデルについて説明します。以下は対象外です。

• 独自のデータモデルの設計 → netbox-data-modeling を使用
• インベントリの一括移行 → netbox-migration を使用
• コア REST のパターン／認証 → netbox-api-integration を使用

基本方針：NDX は読み取り／利用が中心です。 権威あるカタログは NetBox Labs が一元管理し、インスタンスはそこからデータを取得します。エージェントはエンリッチメントデータとライフサイクルデータを検索して利用します。インポートは二次的な操作です。エンリッチメントの値を作成することはできません。

REST API のインターフェース

ベースプレフィックスは /api/plugins/ndx/ です。標準の NetBox トークン認証と DRF のページネーション（count／next／previous／results、?limit=／?offset=）を使用します。

エンドポイント	メソッド	目的
import-records/	GET (, PATCH)	主な検索テーブル。インポートした各タイプを NetBox オブジェクトにマッピングし、エンリッチメントをインラインで保持します
import-records/{id}/	GET, PATCH	1 件のインポートレコード
enrichments/	GET (, PATCH)	エンリッチメントレコードを直接取得します（has_* フラグでフィルタリング）
enrichments/{id}/	GET, PATCH	1 件のエンリッチメントレコード
import/	POST	カタログのエントリーを 1 件以上 NetBox にインポートします
sync/	POST	更新確認のバックグラウンド処理をキューに登録します（update_available フラグを設定しますが、更新は適用しません）

import-records と enrichments は読み取り用エンドポイントとして扱ってください。レコードはインポート処理によって設定され、手動で作成するものではありません。

GET import-records/ — エントリーポイント

各レコードは、NDX カタログの識別情報をローカルの NetBox タイプにリンクし、エンリッチメント全体をネストして含みます。

• ndx_id — 固定 ID。vendor_slug/slug 形式（例：cisco/nexus-93180yc-fx3）
• ndx_manufacturer、ndx_model、ndx_vendor_slug
• ndx_source — community、netbox_labs、または both
• ndx_version — 最終同期時のデータバージョン
• first_imported、last_synced、update_available（ブール値）
• enrichment — エンリッチメントオブジェクト全体を含むネストされた読み取り専用データ（または null）

フィルター：ndx_vendor_slug、ndx_source、update_available。検索：製造元／モデル／ndx_id を対象に ?q= を指定します。

GET /api/plugins/ndx/import-records/?q=Nexus 93180YC-FX3
GET /api/plugins/ndx/import-records/?ndx_vendor_slug=cisco&update_available=true

GET enrichments/ — データの有無で検索

すべてのカテゴリーフィールド、6 つの has_* フラグ、extensions_data、ネストされた provenance_entries を含むエンリッチメントレコードを返します。利用可能フラグでフィルタリングします。

GET /api/plugins/ndx/enrichments/?has_lifecycle=true

エンリッチメントオブジェクトには製造元／モデルが含まれません。人が読める識別情報を取得するには、import-records/ 経由で参照してください。

POST import/ と POST sync/

POST /api/plugins/ndx/import/  {"ndx_ids": ["arista/dcs-7050sx3-48yc8", "cisco/nexus-93180yc-fx3"]}

ID が 5 件以下の場合、インポートは同期的に実行され、ID ごとの {success, message, created, updated} が返ります。ID が 5 件を超える場合、バックグラウンドジョブがキューに登録されます（202）。インポート後、タイプはコンポーネントテンプレートを持つ通常の NetBox DeviceType／ModuleType／RackType となり、（有料プランでは）エンリッチメントも付与されます。インポートには、オブジェクトを直接作成する場合と同じ add 権限が必要です（dcim.add_devicetype／add_moduletype／add_racktype）。(plugin 0.8.1+) デバイスタイプのインポートでは、DTL の inventory-items リストから InventoryItemTemplate も作成され（デバイスタイプのみ）、DTL の port-mappings リストにある位置情報を使ってフロントポートをリアポートにリンクします。

POST /api/plugins/ndx/sync/   {}     # 202; flags update_available, does not apply changes

エンリッチメントデータ

この機能の中核です。各デバイス／モジュール／ラックタイプには、エンリッチメントレコードを1つ設定できます。フィールドの完全な一覧はreferences/enrichment-fields.mdを参照してください。特定の属性を読むときに読み込んでください。

カテゴリ（それぞれにhas_*の利用可否フラグがあります）：ライフサイクル、熱、環境、運用、プラットフォーム、snmp。一部の重要度の高いフィールドはトップレベルの列に昇格しています。詳細なプロトコルデータは、プロトコル（platform、snmp、redfish、gnmi、netconf、ipmi、bacnet、modbus、cellular）をキーとするextensions_data JSON blobに格納されています。

// shape of an enrichment (abbreviated)
{
  "eos_date": "2027-04", "eol_announced": "2024-10-31", "last_support_date": "2030-04-30",
  "tdp_watts": 715, "max_power_draw_watts": 1100, "max_operating_temp_c": 40.0,
  "nos": "NX-OS", "snmp_sys_object_id": "1.3.6.1.4.1.9.12.3.1.3.1234",
  "has_lifecycle": true, "has_thermal": true, "has_snmp": true,
  "extensions_data": {"snmp": {"versions": ["v2c","v3"], "mibs": [...]},
                       "gnmi": {"default_port": 6030, "encoding": ["json_ietf"]}},
  "provenance_entries": [
    {"field": "lifecycle.eos_date", "source": "https://...", "provenance_type": "vendor_eol_bulletin",
     "confidence": "high", "retrieved": "2026-01-15"}
  ]
}

エンリッチメントを正しく利用するためのルール

1. まずhas_*フラグを確認してください。 値が空でもフラグがTrueの場合、データはカタログに存在しますが、利用中のプランによって制限されています（無料プランと有料プランの違い）。「欠落」ではなく「有料プランで利用可能」と報告してください。
2. すべての値がnullでないか確認してください。 カバー範囲は限定的です。対象カテゴリのフラグがtrueでも、多くのフィールドはnullです。
3. ライフサイクルの日付は文字列で、形式はYYYY-MMまたはYYYY-MM-DDです。慎重に解析してください。
4. 出典と信頼度は必ず提示してください。 nullでない値にはそれぞれprovenance_entries[]エントリがあり、source URL、provenance_type、high～unverifiedのconfidenceが記録されています。low／unverifiedは慎重に扱ってください。
5. 詳細なプロトコルデータはトップレベルの列ではなく、extensions_data**にあります。**昇格しているのはsysObjectID、OIDプレフィックス、NOSのみです。

NDXのライフサイクルとコアのend_of_life（NetBox 4.7以降）

NetBox 4.7では、DeviceTypeおよびModuleTypeに任意のend_of_life日付が1つ追加されました（「メーカーがこのデバイスタイプをサポートしなくなる日付」）。また、cooling_method（air／liquid／hybrid／immersion）も追加されました。この2つのレイヤーは互いを補完するものであり、重複ではありません。

	コアのend_of_life (4.7)	NDXライフサイクルエンリッチメント
形式	出典のないYYYY-MM-DD形式の日付1つ	6つの日付（ga_date、eol_announced、eos_date、eosw_date、eosec_date、last_support_date）、形式はYYYY-MMまたはYYYY-MM-DD
出典情報	なし — ユーザーが管理	出典URLと信頼度を含むprovenance_entries[]
適用範囲	コアのフィルター、テーブル、エクスポート、あらゆるプラグイン、NetBox 4.7以降のすべてのバージョン	Cloud／Enterpriseの/api/plugins/ndx/、有料プランで利用可能な値

NDXはコアのend_of_lifeを自動入力します（NDXプラグイン0.7.0以降、2026-09-19、NetBox 4.7以降）。 インポート時および再インポート時に、NDXはエンリッチメントの**last_support_date**（「メーカーがサポートしなくなる日付」に意味的に合致する値）をDeviceType／ModuleType.end_of_lifeに書き込みます。eos_date（販売終了）やeol_announcedから書き込むことはありません。エージェントが把握しておくべきルールは次のとおりです。

• プラグイン設定populate_core_end_of_lifeで制御されます（デフォルトはオン）。オフの場合、ライフサイクルデータはエンリッチメントレコードのみに残ります。
• 厳密なYYYY-MM-DD形式の値のみが書き込まれます。部分的なYYYY-MM形式のlast_support_dateはスキップされます（ログに記録され、フィールドは変更されません）。推測した日付は、日付がないより悪いものとして扱われます。
• ローカルでの編集が優先されます。コアフィールドに書き込まれるのは、値が空か、NDXが最後に書き込んだ値と一致する場合のみです。ユーザーが変更した日付は、再インポートしても変更されません。
• cooling_methodは入力されません。NDXの熱カテゴリのcooling_type（air／liquid／mixed／passive）は、エンリッチメントレコードに残ります。

そのため、NDXプラグインが最新の状態で4.7以降を使用している場合、コアのend_of_lifeはNDXによって管理されるものとして扱い、手動で上書きしないでください。設定がオフの場合、タイプがプラグイン0.7.0より前にインポートされて再同期されていない場合、またはNDXの日付が部分的で、ユーザーが補完した日付を許容する場合に限り、自分で設定してください。

NDXが最後に書き込んだ値と異なる手動設定のend_of_lifeは、再インポート時にも保持されます。NDXのcooling_typeをコアのcooling_methodにコピーする場合は、mixedをhybridに変換し、passiveは設定しないでください（コアに相当する値がありません）。この処理はNDXでは自動的に行われません。

一般的なワークフロー

一連の手順については、references/consume-workflows.md を参照してください。特に重要なものは次のとおりです。

• 既知のタイプのエンリッチメントを参照する： GET import-records/?q=<model> → ネストされた enrichment を読み取る（2 回目の呼び出しは不要）→ eos_date、max_power_draw_watts、extensions_data.gnmi.default_port などを読み取ります。
• EOL/EOS 対応状況レポート： GET /api/dcim/devices/ から導入済みのデバイスを取得し、それらの device_type ID を収集して、各 ID を対応する NDX インポートレコードと照合します。eos_date／last_support_date を過ぎている、または近づいているタイプにフラグを付け、データの出所を示して報告します。(4.7) コアの DeviceType.end_of_life も読み取り、両者を照合してください（上記を参照）。
• オブザーバビリティ設定を作成する： snmp_sys_object_id、extensions_data.snmp.mibs[]、または extensions_data.gnmi／.netconf／.redfish を読み取り、何をポーリングするかを決めます（NDX が示すのは何を／どのようにポーリングするかであり、設定そのものではありません）。
• カタログのエントリをインポートする： ndx_id（複数可）を指定して POST import/ を実行します。

アクセス階層（概念レベル）

• 誰でも利用可能： デバイス／モジュール／ラックのタイプ定義です。公開カタログを参照し、YAML を手動でダウンロードできます。NetBox Cloud／Enterprise は不要です。コミュニティ DTL と同じ形式です。
• 無料（すべての NetBox Cloud プラン＋NetBox Enterprise）：製品内の NDX 機能です。デバイスタイプの完全なカタログに加え、インポートとエンリッチメントの利用可能フラグ（has_*）を利用できますが、エンリッチメントの値にはアクセス制限があります。
• 有料： エンリッチメントの値をすべて利用できます。

したがって、ライフサイクル関連フィールドが空の has_lifecycle: true は、データが存在しないことではなく、アクセス階層による制限を示しています。

避けるべきパターン

1. NDX を「プラグイン」と呼ぶ、またはインストール／PLUGINS_CONFIG の仕組みを説明する。これは機能です。
2. オープンソースと商用の境界を誤って説明する。 タイプ定義（YAML）は誰でも利用でき、手動でダウンロードできます。一方、エンリッチメントの値と製品内の NDX 機能（Cloud／Enterprise）は商用です。カタログ全体を商用と呼んだり、エンリッチメントの値が無料であると示唆したりしないでください。
3. 上流のカタログ API を呼び出す。 エージェントが呼び出すのは、自身の NetBox 上の /api/plugins/ndx/... のみです。外部の NDX カタログ／CDN エンドポイントを対象とするコードを生成しないでください。
4. has_* フラグを「データあり」と解釈する。 true でも値が空の場合、データは存在しますがアクセス階層によって制限されています。そのように報告してください。
5. 完全性を前提とする。 null を確認してください。カバレッジはベンダーや製品の年代によって異なります。
6. 出所／信頼度を無視する。 常に source と confidence を提示してください。データは AI の支援を受けて精選されています。
7. ライフサイクルの日付を完全な日付として扱う。 YYYY-MM 形式の場合があります。
8. エンリッチメントオブジェクトでメーカー／モデルを探す。 これらはインポートレコードにあるため、import-records/ を経由してください。
9. 詳細なプロトコルデータをカラムとして探す。 プロトコルをキーとする extensions_data 内にあります。
10. sync/ がデータを更新すると期待する。 同期で行われるのは更新のフラグ付けのみです。適用するには再インポートが必要です。
11. NDX をインスタンス／監視データとして扱う。 NDX はデバイスタイプの参照メタデータのみを扱います。
12. ベンダー PID をキーにした 2 つ目のデバイスタイプを作成する。 NDX はマーケティング名を model に、PID を part_number に保存します。PID を model として作成されたタイプ（修正前の Discovery／Diode が作成していたもの）は重複であり、NDX のエンリッチメントが紐付かなくなります。タイプを作成する前に part_number で照合してください。

バージョンに関する注記

NDX plugin 0.8.x（2026-10）

現在のプラグインは 0.8.3（2026-10-15）です。NetBox 4.5.0 以降を宣言しています（マニフェストでは 4.5～4.7）。populate_core_end_of_life のデフォルトは変更されていません。

• 0.8.0 — NDX の出所情報に関する変更が、GET /api/core/object-changes/ で {id, field, source, provenance_type, confidence, retrieved, note} として表示されるようになりました。0.8.0 より前は、出所情報の変更を含む変更履歴ページはすべて 500 を返していました。
• 0.8.1 — デバイスタイプのインポートでは、DTL の inventory-items リストから InventoryItemTemplates を作成します（デバイスタイプのみ。モジュールタイプには在庫アイテムテンプレートがありません）。前面ポートと背面ポートのマッピングは、front_port_position を含む DTL の port-mappings リストから読み込まれるため、NetBox 4.5 以降では複数の位置を持つ前面ポートも正しくマッピングされます。
• 0.8.2 / 0.8.3 — プラグインのマニフェストとドキュメントのみの変更です。カタログの Type フィルターには、Device / Module / Rack Types が記載され、インポートでは種類ごとに対応する add 権限が必須となります。

NetBox 4.7（2026-09-02）

• DeviceType／ModuleType にコアの end_of_life（日付）と cooling_method、Rack／RackType に cooling_capability／cooling_capacity、さらに完全な冷却モデル（ソース、供給口、吸気口、排気口）が追加されました。NDX エンリッチメントでは、出所情報付きの複数日付によるライフサイクルおよび熱記録を引き続き保持します。NDX plugin 0.7.0 以降は、インポート時に last_support_date からコアの end_of_life を書き込みます（populate_core_end_of_life を設定。デフォルトで有効。厳密な日付のみ。ローカル編集は保持されます）。cooling_method は書き込みません。NDX plugin 0.7.1 以降は NetBox 4.5～4.7 との互換性を宣言しています（現行は 0.8.3）。
• 4.7 では、リクエストで config_context を除外しない限り、GET /api/dcim/devices/ は config_context を読み込みます（?exclude=config_context はすべての 4.7.x で無視されます。4.7.3 以降では ?fields=／?omit= によって再び DB 処理を省略できます）。公開状況レポートの取得では、?fields=id,name,device_type を指定してください。
• 選択肢のカスタムフィールドは {"value", "label"} として読み込まれます。これは、4.5～4.6 のインスタンスで NDX 由来の値をカスタムフィールドに保存し、それらを比較する場合にのみ関係します。

参考資料

• references/enrichment-fields.md — カテゴリごとのすべてのエンリッチメントフィールド、extensions_data プロトコルブロック、出所情報の構造を説明しています。特定の属性を確認する際に読み込んでください。
• references/consume-workflows.md — 検索、EOL の公開状況、可観測性、インポートに関する完全な API シーケンスを説明しています。