netbox-validation

NetBox Validation

NetBox Validation 使用三个引擎持续依据声明式策略验证基础设施数据：意图（NetBox 数据）、配置分析（渲染后的配置）和图分析（基础设施依赖关系）。它会生成每台设备的结果、汇总发现项和合规评分。

你对 NetBox Validation 的了解可能已经过时。 名称、API 字段、策略包内容和引擎功能会随版本更新而变化。请优先检索，而不要依赖预训练知识。

当前插件： 1.14.3（2026-10-06）。1.14.0 开始支持 NetBox 4.7；插件声明支持 NetBox 4.4–4.7.x，文档要求 NetBox 4.5+（NetBox Cloud）。在 NetBox 4.7 上运行时，版本需为 ≥ 1.14.0。参见版本说明。

检索来源

来源	URL / 方法	用途
Validation 文档	https://netboxlabs.com/docs/validation/	完整参考、引擎、检查目录、策略包
Validation REST API	https://netboxlabs.com/docs/validation/api-reference/	端点详情
NetBox Platform MCP	如已配置 — 5 个验证工具	运行验证、查询合规性、管理策略
NetBox MCP 服务	如已配置 — 只读访问	验证设备、策略和评分

首先：验证连接

确认已安装 Validation 插件，且你的令牌有权访问：

curl -s -H "Authorization: Bearer $NETBOX_TOKEN" \
  "$NETBOX_URL/api/plugins/validation/policies/" | python -m json.tool

你应该会看到分页的策略列表（也可能是空结果）。如果收到 404，说明未安装 Validation 插件。如果收到 403，说明你的令牌缺少验证权限。

---

核心概念

对象层级结构

Policy (scope + rules + triggers)
  -> Run (execution of a policy against devices)
    -> Results (per-device, per-check pass/fail/warning/error/skip)
      -> Findings (aggregated failures, actionable items)
        -> Compliance Scores (per-device, per-policy, 0-100%)

策略

Validation 策略定义要检查的内容和范围。范围筛选条件包括：站点、区域、站点组、设备角色、平台和标签。策略包含规则，并控制引擎开关、触发器和 cron 计划。

规则

每条规则指定：

字段	说明
engine	intent、config 或 graph
category	检查分组 — addressing、redundancy、standards、completeness、security_intent、topology、reachability、power、infrastructure、routing、security、baseline、overlay
check_name	要运行的具体检查（例如 no_duplicate_ips）
severity	critical、high、medium、low 或 info
parameters	检查专用配置（阈值、模式、预期值）

规则可以选择用自己的 roles 和 platforms 筛选条件（ID 列表）覆盖策略范围。

三个引擎

引擎	检查数	评估内容	数据源	主要优势
意图	44	NetBox 数据关系	NetBox ORM	快速，无外部依赖
配置	35	渲染后的设备配置	配置分析引擎（来自 NetBox Config Templates）	结构分析、可达性
图	16	基础设施依赖关系图	NetBox ORM	影响范围、故障域

三个引擎可以在同一策略中共存。Premium 层级客户可使用配置引擎和图引擎。配置引擎会分析从 NetBox Config Templates 渲染的配置；启用该引擎前，请先为设备分配模板（通过设备、平台或角色）。

运行状态

状态	含义
pending	已创建，等待执行
running	正在执行检查
passed	所有检查均已通过
failed	一个或多个检查失败
error	执行期间发生引擎错误

从插件 1.12.0 起，每次运行都会关联到其 NetBox 后台作业，并受作业超时限制；对于孤立运行（工作进程在运行中丢失），系统会进行清理，而不会让它们一直处于 running 状态。

每次运行都会公开 job_id（核心后台作业）。插件设置 job_timeout（默认值为 3600s）和 run_retention_days（默认值为 180；<= 0 表示禁用）用于管理此行为：每小时执行一次的清理作业会删除超出保留期限的已完成运行，但不会删除正在执行的运行，并且始终保留每个策略的最近一次运行。

结果状态

每个设备、每项检查的结果状态为：pass、fail、skip、warning 或 error。结果包含 expected、actual、message、remediation 和 extra（引擎专属详情）。

发现项生命周期

open -> acknowledged -> resolved
                    \-> suppressed

状态	使用时机
open	新发现项，需要审核
acknowledged	已审核，已计划修复
resolved	已修复，并通过运行确认
suppressed	有意例外，已接受风险

合规分数

score = passed / (passed + failed + error) x 100

跳过的检查不计入。分数按（设备、策略、运行）计算，并随时间跟踪。

---

快速参考 — 常见工作流

创建并执行运行

创建运行并不会执行它。此过程分为两步：

# Step 1: Create the run — policy, trigger AND status are required (400 without "status")
RUN=$(curl -s -X POST "$NETBOX_URL/api/plugins/validation/runs/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policy": 1, "trigger": "manual", "status": "pending"}')

RUN_ID=$(echo $RUN | python -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Step 2: Execute it (synchronous — returns when complete)
curl -X POST "$NETBOX_URL/api/plugins/validation/runs/$RUN_ID/execute/" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

执行端点为同步操作——它会返回已完成的运行（状态、计数、分数）。无需轮询。只有 pending（或 error）状态的运行才能执行；重新执行已完成的运行会返回 400。

安装策略包

# List available packs (a bare JSON array)
curl "$NETBOX_URL/api/plugins/validation/policy-packs/" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Install a pack (creates policy + all rules)
curl -X POST "$NETBOX_URL/api/plugins/validation/policy-packs/addressing-ipam/install/" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

查询合规分数

# Fleet-wide latest scores
curl "$NETBOX_URL/api/plugins/validation/compliance/" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Scores for a specific device, newest first
curl "$NETBOX_URL/api/plugins/validation/compliance/?device_id=10&ordering=-measured_at" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Scores for a specific policy
curl "$NETBOX_URL/api/plugins/validation/compliance/?policy_id=1" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

筛选发现项

# Open critical findings from the latest run of each policy
curl "$NETBOX_URL/api/plugins/validation/findings/?latest=true&status=open&severity=critical" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Acknowledge a finding
curl -X PATCH "$NETBOX_URL/api/plugins/validation/findings/42/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "acknowledged"}'

针对分支运行

curl -X POST "$NETBOX_URL/api/plugins/validation/runs/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policy": 1, "trigger": "manual", "status": "pending", "branch_id": 5}'

验证引擎会从 main 读取规则，并在分支上下文中执行检查，以查看分支叠加数据。

定向运行（缩小范围）

# Target specific site(s)
curl -X POST "$NETBOX_URL/api/plugins/validation/runs/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"policy": 1, "trigger": "api", "status": "pending", "target_sites": [9]}'

# Validate a single device across all matching policies
curl -X POST "$NETBOX_URL/api/plugins/validation/runs/validate-device/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device": 101}'

YAML 导入/导出

# Export a single policy
curl -X POST "$NETBOX_URL/api/plugins/validation/policies/1/export/" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Import a policy from YAML
curl -X POST "$NETBOX_URL/api/plugins/validation/policies/import/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d @my-policy.yaml

---

策略管理

策略范围

策略通过以下字段的任意组合来限定设备范围：

范围字段	API 字段	效果
站点	sites	仅包含位于这些站点的设备
区域	regions	仅包含位于这些区域中站点的设备
站点组	site_groups	仅包含位于这些组中站点的设备
设备角色	roles	仅包含具有这些角色的设备
平台	platforms	仅包含运行在这些平台上的设备
标签	device_tags	仅包含具有这些标签的设备

每个字段都是 NetBox 对象 ID 列表。范围字段按 AND 组合。范围为空表示所有活动设备。未知字段会被静默忽略：带有 scope_sites 的请求体会创建一个不限定范围的策略，且不会报错，因此写入后请从响应中读取 sites / roles。

curl -X POST "$NETBOX_URL/api/plugins/validation/policies/" -H "Authorization: Bearer $NETBOX_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Leaf Baseline", "sites": [1, 2], "roles": [3], "device_tags": [7]}'

选择字段（规则中的 engine、category、severity；运行中的 trigger、status；结果中的 status、severity；发现项中的 severity、category、status）读取时会返回 {"value", "label"} 对象；写入时则使用裸字符串。策略的 latest_run 摘要中的 status / trigger 为裸字符串。应比较 x["status"]["value"]，而不是 x["status"]。

引擎开关

策略字段	默认值	效果
enable_config_engine	false	为此策略启用配置分析检查
enable_graph_engine	false	为此策略启用图韧性检查
trigger_on_cr_submit	true	提交变更请求时运行
trigger_on_branch_merge	false	合并分支时运行

意图检查始终会运行。配置检查和图检查要求在策略上启用相应引擎，并且该引擎在部署级别可用。

策略包

预置策略包支持一键安装：

• 14 个入门包（113 条规则）——涵盖寻址、布线、数据质量、命名、冗余、安全意图、叶脊基线、配置分析、变更前配置、BGP 属性、电源／网络／全面弹性
• 9 个合规框架（177 条规则；Premium）——CLOS Fabric、TIA-942、NIS2/DORA、NIST 800-53、NERC CIP、PCI-DSS、MANRS、ISO 27001、HIPAA Security Rule（2026）

默认列出入门包；只有当插件设置 enabled_policy_packs 包含 "compliance"（默认值为 ["starter"]）时，才会显示（并可安装）框架包——安装已禁用的类别会返回 403。GET /policy-packs/ 返回纯 JSON 数组（没有 count/results）；每个条目包含 slug、name、description、category（starter | compliance）、policy_count、rule_count、engines、installed、installed_policy_ids。已安装的包会创建常规策略和规则。安装后，可自定义范围、参数、触发器和计划。请参阅 references/policy-packs.md。

删除规则和策略

从插件 1.13.0 起，DELETE /rules/{id}/ 和 DELETE /policies/{id}/ 会保留历史运行结果。结果会保留 rule_name 和 check_name 快照，运行记录和合规评分会保留 policy_name；删除后，rule / policy 外键字段会变为 null，因此应读取 *_name 字段，而不要假定外键已设置。即使存在运行记录，也不再拒绝卸载策略包——包中的策略会被移除，其运行历史则会以快照中的策略名称保留。删除运行记录（DELETE /runs/{id}/）是唯一会造成数据破坏的操作：它会级联删除该运行记录的结果、发现项和合规评分。

克隆和导入

# Clone a policy (copies all rules and scoping)
curl -X POST "$NETBOX_URL/api/plugins/validation/policies/1/clone/" \
  -H "Authorization: Bearer $NETBOX_TOKEN"

# Import from YAML
curl -X POST "$NETBOX_URL/api/plugins/validation/policies/import/" \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d @my-policy.yaml

---

验证触发器

触发器	方式	说明
手动	通过 API 创建并执行，或在 UI 中点击“立即运行”	分两步：先创建（trigger: "manual"、status: "pending"），再执行
分支合并	trigger_on_branch_merge: true	NetBox Branching 分支合并到 main 时运行；可捕获合并数据中的回归问题
变更请求提交	trigger_on_cr_submit: true（默认开启）	NetBox Changes 变更请求提交时运行；以 CR 的分支为目标，确保合并前的安全性
定时	在 schedule 中使用 cron——0 2 * * *（每天 02:00）、0 */6 * * *（每 6 小时）、0 0 * * 0（每周）	以 main 为目标（无分支上下文）；最短间隔为 5 分钟

运行记录的 trigger 值：manual、api、schedule、branch、merge、cr。

运行范围

所有运行记录都支持可选的目标范围缩小：

字段	类型	效果
target_sites	站点 ID 列表	仅包含这些站点上的设备
target_devices	设备 ID 列表	仅包含这些特定设备
target_tags	标签 ID 列表	仅包含带有这些标签的设备

目标字段与策略范围按 AND 逻辑组合。它们只能缩小范围，不能扩大范围。（公开 API 参考文档中，target_tags 使用标签 slug；与其他目标字段一样，该端点实际接收 NetBox Tag ID。）

---

合规与发现项

评分维度

可按设备（跨策略）、策略（跨设备）、站点／角色（?site_id=、?role_id=）和时间查询合规评分（通过合规仪表板和 /compliance/trend/ 查看 7d/30d/90d 趋势）。

发现项聚合

发现项会将相关故障归纳为可执行事项。例如，如果 no_duplicate_ips 对 5 台设备检查失败，一个发现项会将这 5 台设备归为一组。图引擎的发现项按故障点分组（每条电源馈线或每个共享故障域对应一个发现项）。每个发现项都包含 affected_devices、is_new、recurrence_count、first_seen、policy_id/policy_name 和 has_blast_radius。

严重性升级

图引擎发现会根据影响范围自动升级严重性：

未受保护的设备	升级
1--2	不变
3--5	medium -> high
6--10	high -> critical
10+	始终为 critical

发现项分流

1. 按严重性筛选发现项（优先处理 critical）；仅查看当前发现项时使用 ?latest=true
2. 查看详情：受影响的设备、expected 与 actual、remediation
3. 对于图发现，检查影响范围卡片
4. 确认你计划修复的发现项
5. 在 NetBox 中修复根本问题
6. 重新运行验证以确认
7. 将发现项标记为已解决

---

集成模式

变更前验证流水线

1. Create Branch          (netbox-branching)
2. Make changes           (normal NetBox API with X-NetBox-Branch header)
3. Submit Change Request  (netbox-changes) -> validation auto-runs
4. Review validation results
5. Approve CR, merge branch
6. Post-merge validation auto-runs (optional)

将 trigger_on_cr_submit: true 设为启用合并前安全检查。将 trigger_on_branch_merge: true 设为启用合并后验证。

分支上下文

针对分支运行验证时，在运行中传入 branch_id。引擎会从 main 读取规则，并在分支上下文中执行检查（查看拟议的新增、修改和删除）。

配置分析会从 main 和分支渲染配置，以进行差异分析（可达性丢失、BGP 会话中断、路由回归）。

通过 MCP 进行 Agent 集成

NetBox Labs Platform MCP Server 提供 5 个验证工具：

工具	用途
run_validation	为策略创建并执行一次运行，可选指定分支或设备
get_compliance_analytics	合规评分、趋势、按维度划分的评分
get_findings_analytics	按严重性、状态、类别和策略筛选发现项
import_validation_policy	从 YAML 导入策略
clone_validation_policy	克隆包含所有规则和范围设置的策略

倾向于直接访问 API 的 Agent 可以使用带有 bearer token 身份验证的 REST 端点。

Agent 工作流模式

Agent creates branch -> makes changes -> runs validation
  Pass -> creates change request for human review
  Fail -> reads findings, self-corrects, re-validates

验证提供自动化安全网，确保 Agent 遵循与人工工程师相同的策略框架。

---

反模式

错误做法	失败原因	正确做法
创建运行并假定它会执行	创建运行会将状态设为 pending	创建后向 /runs/{id}/execute/ 发送 POST 请求
创建运行时省略 trigger 或 status	两者都是必填项 — 400 {"status": ["This field is required."]}（公开 API 参考文档省略了 status；但该端点仍要求提供）	请求体始终为 {"policy": <id>, "trigger": "manual", "status": "pending"}（trigger 可以是 "api" 或 "schedule"）
使用 scope_sites / scope_roles / scope_tags 限定策略范围	未知字段会被静默丢弃 — 创建的策略没有范围限制（包含所有设备）	使用 sites、regions、site_groups、roles、platforms、device_tags（ID 列表），并从响应中读取 sites/roles
将选项字段与裸字符串比较	status、trigger、engine、category、severity 读取时会返回 {"value", "label"}	比较 ["value"]；写入时使用裸字符串
使用分支整数 ID 进行分支验证	创建运行时，branch_id 需要的是分支的整数 ID，但 X-NetBox-Branch 标头使用的是 schema_id	在不同上下文中使用相应的标识符
安装配置包/图谱包却未启用引擎	配置/图谱规则会产生 skip 结果	在策略上设置 enable_config_engine / enable_graph_engine
仅启用了入门包时安装合规性包	POST .../install/ 会返回 403	将 "compliance" 添加到插件设置 enabled_policy_packs 中
将 skip 视为失败	跳过的结果不计入评分，也不会创建发现项	查看结果 message — 没有 Config Template、没有电源端口、引擎不可用
期望目标范围扩大策略范围	目标字段与策略范围会进行 AND 组合	目标只能缩小范围 — 策略范围之外的设备会被排除
执行后轮询运行是否完成	执行是同步的 — 完成后才会返回	直接读取响应；无需轮询
运行图谱检查并指定设备目标以期节省资源	图谱引擎无论如何都会加载站点内的所有设备	对图谱密集型策略使用按站点限定范围的运行

---

API 端点摘要

端点	方法	用途
/policies/	GET, POST	列出和创建策略
/policies/{id}/	GET, PUT, PATCH, DELETE	管理策略
/policies/{id}/clone/	POST	克隆策略及其所有规则和范围
/policies/{id}/export/	POST	导出为 YAML
/policies/import/	POST	从 YAML 导入
/policies/export-all/	POST	导出所有策略
/policies/{id}/run-for-site/	POST	针对指定站点运行 — {"sites": [...]}；创建并执行
/policies/{id}/run-for-devices/	POST	针对指定设备运行 — {"devices": [...]}；创建并执行
/rules/	GET, POST	列出和创建规则（按 policy_id、engine、category、severity、is_active 筛选）
/rules/{id}/	GET, PUT, PATCH, DELETE	管理规则
/runs/	GET, POST	列出和创建运行记录（按 policy_id、status、trigger、branch_id、has_branch、created_after/before 筛选）
/runs/{id}/	GET, DELETE	运行状态和摘要；DELETE 会删除运行记录及其关联的结果、发现项和评分
/runs/{id}/execute/	POST	执行待处理的运行
/runs/validate-device/	POST	对设备运行所有匹配的策略
/results/	GET	结果（按 run_id、device_id、rule_id、status、severity、engine 筛选）
/findings/	GET, POST	发现项（按 run_id、severity、status、category、policy_id、device_id、site_id、role_id、branch_id、is_new、latest、q 筛选）
/findings/{id}/	GET, PUT, PATCH	更新发现项状态
/findings/summary/	GET	按状态、严重性和类别统计发现项数量（遵循筛选条件）
/findings/bulk-update-status/	POST	{"ids": [...], "status": "..."} — 批量更改状态
/findings/matrix/	GET	未关闭发现项的类别 × 严重性统计（?site_id=、?role_id=）
/compliance/	GET	合规评分（按 device_id、policy_id、run_id、site_id、role_id 筛选）
/compliance/summary/	GET	全体设备评分、设备数量和发现项数量
/compliance/trend/?days=N	GET	随时间变化的每日合规评分
/compliance/breakdown/?group_by=site|role|policy	GET	按维度分组的评分（已删除策略的历史记录仍使用快照中的名称）
/compliance/distribution/	GET	设备合规评分直方图
/compliance/worst-performers/?limit=N	GET	评分最低的设备
/policy-packs/	GET	资源包数组（slug、category、rule_count、engines、installed、installed_policy_ids）
/policy-packs/{slug}/	GET	资源包详情以及 policies[] 和 rules[]
/policy-packs/{slug}/install/	POST	安装资源包（若其类别未启用，则返回 403）
/policy-packs/{slug}/uninstall/	POST	卸载资源包

所有端点均位于 /api/plugins/validation/ 下。

---

版本说明

插件 1.14.x（2026-09 – 2026-10）

• 1.14.0：支持 NetBox 4.7（声明支持 4.4–4.7.x）。
• 1.14.1：仅更新 plugin-catalog 元数据。
• 1.14.2：规则 category 新增 routing、security、baseline 和 overlay（随附资源包会与 addressing、redundancy、standards、completeness、security_intent、topology、reachability、power、infrastructure 一起使用）。
• 1.14.3（2026-10-06）：无用户可见的变更。

NetBox 4.7 (2026-09-02)

• 需要插件 1.14.0+。检查在服务器端评估 NetBox 数据，因此检查名称和参数保持不变。
• 变化的是 Agent 用于修复发现问题的核心 REST API：选择类自定义字段读取时为 {"value", "label"}（写入原始值——在 custom_field_populated / asset_documentation_complete 检查失败后尤其相关）；设备读取时默认包含 config_context（4.7.3+ 可通过 ?omit=config_context 将其省略；?exclude=config_context 会被忽略——请使用 ?fields=）；服务使用 port_mappings（["tcp/443"]），而不再使用 protocol + ports。批量修复失败时会按 index 返回每个对象的错误。参见 netbox-api-integration。
• 在 4.7 上运行分支上下文需要 netbox-branching 1.2.x（NetBox 4.4–4.6 需要 1.1.x）——参见 netbox-branching。

插件 1.12–1.13 (2026-08)

• 1.12.0：强化运行生命周期（作业超时、孤立运行回收器、运行↔作业关联）。1.13.0：删除规则和策略时不会丢失运行历史。

---

参考资料

参考资料	加载时机
references/api-patterns.md	需要策略/运行/结果生命周期的完整 API 示例时
references/check-reference.md	需要全部 95 项检查的名称、参数或引擎详情时
references/policy-packs.md	需要策略包目录、slug、安装/自定义指导或框架详情时