{
  "schema": "netdryrun.capabilities/v1",
  "url": "https://netdryrun.com/capabilities.json",
  "name": "Netdryrun",
  "version": "0.4.1",
  "summary": "Netdryrun dry-runs a network change in a real containerlab lab before it reaches production, and returns a verdict with evidence. verify_change (0.4, FRR): declare what you intend to change; anything else that changes in the routing state fails the run.",
  "use_cases": [
    {
      "id": "dry_run",
      "when": "Before proposing or applying a routing or policy change, when the lab has checks (netdryrun.yml) that state what must hold.",
      "does": "Deploys the containerlab lab with the change, waits for convergence, runs every check, destroys the lab. A pass covers only what the checks look at.",
      "mcp": {
        "tool": "dry_run",
        "arguments": {
          "path": "/path/to/lab"
        }
      },
      "cli": "netdryrun run /path/to/lab --json report.json",
      "github_action": {
        "uses": "netdryrun/Netdryrun@v0.4.1",
        "with": {
          "path": "lab"
        }
      }
    },
    {
      "id": "verify_change",
      "since": "0.4",
      "platforms": [
        "frr"
      ],
      "when": "When no checks exist and a ticket states what the change is meant to do: declare that intent, and anything else that changes in the routing state fails.",
      "does": "Boots the lab with the before configs and with the after configs, snapshots sessions, routes of every protocol, every BGP path and every advertisement, and fails on any difference the intent doesn't declare. An approval needs each side booted twice with identical snapshots.",
      "mcp": {
        "tool": "verify_change",
        "arguments": {
          "topology": "/path/to/lab/topology.clab.yml",
          "before": "main",
          "after": "/path/to/lab-after",
          "intent": "intent:\n  - prefix: 10.101.0.0/24\n    appears_on: [edge1, up1, peer1]\n"
        }
      },
      "cli": "netdryrun verify topology.clab.yml --before main --after HEAD --intent netdryrun-intent.yml --json report.json",
      "github_action": {
        "uses": "netdryrun/Netdryrun@v0.4.1",
        "with": {
          "mode": "verify",
          "topology": "lab/topology.clab.yml",
          "intent-file": "netdryrun-intent.yml"
        }
      }
    },
    {
      "id": "record_baseline",
      "when": "No checks and no stated intent: capture today's behavior as checks, then run them against the change.",
      "does": "Reads sessions and routes from a lab and returns checks as YAML; writes nothing.",
      "mcp": {
        "tool": "record_baseline",
        "arguments": {
          "topology": "/path/to/lab/topology.clab.yml"
        }
      },
      "cli": "netdryrun record /path/to/lab/topology.clab.yml --deploy"
    },
    {
      "id": "validate",
      "when": "Before a run: check a netdryrun.yml and its topology without starting a lab.",
      "mcp": {
        "tool": "validate",
        "arguments": {
          "path": "/path/to/lab"
        }
      },
      "cli": "netdryrun validate /path/to/lab"
    }
  ],
  "prerequisites": [
    "Linux, or Windows with WSL2; not macOS",
    "Docker and containerlab, with root-equivalent rights (labs run privileged containers)",
    "Python 3.10 to 3.14 (pipx install netdryrun, or uvx netdryrun mcp)",
    "Not inside a sandbox without Docker-in-Docker; there, open a pull request and let the GitHub Action run it",
    "Images: FRR and SR Linux are public; SONiC needs docker-sonic-vs; Arista EOS needs your own cEOS image",
    "A lab of the network (a containerlab topology and its configs); Netdryrun never connects to real devices"
  ],
  "limits": [
    "A pass of dry_run covers only what the checks look at; behavior no check covers is not tested.",
    "verify_change covers the observed control-plane state of the lab (BGP sessions, routes of every protocol, every BGP path, advertised and received routes), nothing else: no data plane beyond ping checks.",
    "verify_change is FRR only in 0.4; the topology must be identical on both sides.",
    "verify_change: an intent explains what it declares, leaks included; the intent must come from the ticket or the operator, never from the diff.",
    "verify_change: received routes are compared before inbound policy without their communities (FRR doesn't list them there); a default-originate advertisement is compared by presence, not by its attributes.",
    "verify_change: IPv4 and IPv6 unicast only; sessions carrying other address families, and unnumbered BGP neighbors, are refused (exit 2).",
    "Settle and hold stretch to the longest BGP advertisement interval a driver reads, except on Arista EOS, where a configured out-delay is not read yet: raise --settle and --hold above it there (planned for 0.4.1).",
    "A route that crosses several peers with long advertisement intervals can take one interval per hop, and update-delay is not read: raise --settle for those.",
    "A lab whose state never settles gives INCONCLUSIVE (exit 3): this says nothing about the change; retry at most once, then escalate.",
    "afi: evpn is refused on Arista EOS and Nokia SR Linux.",
    "verify_change does not observe nodes passed as unobserved (hosts), IGP adjacency state (OSPF and IS-IS routes are compared, their adjacencies are not), or the data plane beyond a standing guard's ping checks: an undeclared change there does not fail.",
    "record covers every active VRF on FRR and SONiC; on Nokia SR Linux and Arista EOS it records the default VRF only, with a warning.",
    "SR Linux: graceful restart: a path the router marks stale (a restarting peer's route, kept until it re-sends it or the stale timer ends) stops the read with a 'not settled' error, so a check samples again until the mark clears and never passes or fails on a route about to go. The mark is read from the NOS's own field (`stale-route`); a live graceful restart has not been captured on this NOS to confirm the field turns true during one. Mitigation: leave graceful restart off in the lab.",
    "SR Linux: A path SR Linux marks invalid (`invalid-reason`) for anything but `rejected-route` (rejected by import policy, which doesn't count as received) is an error until the driver reads that reason, and so is a path marked invalid (`valid-route: false`) with no reason given: a check on that prefix fails with the reason named, never passes.",
    "SONiC: graceful restart: SONiC's routing is FRR, and its driver reads FRR's `stale` flag as the FRR driver does: a `route` or `bgp_route` check never passes on a stale path (a restarting peer's route, kept until it re-sends it or the stale timer ends). A live graceful restart has not been captured on docker-sonic-vs to confirm the flag. Mitigation: leave graceful restart off in the lab.",
    "Arista EOS: graceful restart: a path the router marks stale (a restarting peer's route, kept until it re-sends it or the stale timer ends) stops the read with a 'not settled' error, so a check samples again until the mark clears and never passes or fails on a route about to go. The mark is read from the NOS's own field (`routeType.stale`); a live graceful restart has not been captured on this NOS to confirm the field turns true during one. Mitigation: leave graceful restart off in the lab.",
    "Arista EOS: `med: 0` is refused before the lab boots (exit 2): cEOS 4.36.3M prints MED 0 for a path received with no MED (live capture, 0.4 interop test), and no field of `show ip bgp <prefix> | json` tells the two apart. A non-zero MED is checked as usual; a path whose MED reads 0 reports it as \"not set\".",
    "Juniper (beta): graceful restart: the driver doesn't read the stale mark yet, so a `route` or `bgp_route` check can pass on a restarting peer's route that is about to go (found by the 0.4.1 acceptance run; the junos-frr example negotiates graceful restart with FRR). Mitigation: leave graceful restart off in the lab, or give the checks a `timeout` above the stale timer.",
    "Juniper (beta): Hidden routes count as received, except routes Junos hid because the import policy rejected them (`hidden-reason` \"Rejected by import policy\"): those can never be used, and FRR and Arista EOS don't keep them at all.",
    "Juniper (beta): `bgp_route` reads routes received over BGP only. Junos doesn't list its own static, direct or aggregate routes as BGP routes, even when an export policy advertises them.",
    "Juniper (beta): `bgp_prefixes` counts received routes minus those import policy rejected, reading the hidden routes' reasons when Junos hides any. A hidden route whose reason is neither \"Rejected by import policy\" nor \"Protocol nexthop is not on the interface\" leaves the count a range from accepted to received, and a bound is judged only when the whole range agrees (otherwise the check fails, never passes).",
    "Juniper (beta): Link and node faults on a cJunosEvolved node and `inject_routes` from it are refused before deploying.",
    "Juniper (beta): Every deploy installs Junos in the VM: about 4 minutes to a CLI on a quiet 20-thread host, up to 19 minutes with a CPU-heavy job beside it. Set `CPTX_NUM_IF` (see the example) and a check `timeout` that covers the boot.",
    "Juniper (beta): startup config: Netdryrun doesn't verify that the startup config loaded on Junos yet (the report says `not verified on junos`). Mitigation: add a positive check for what each changed line creates. Fix scheduled: 0.4.1.",
    "Juniper (beta): graceful restart: a route Junos marks stale (`Stale` or `LongLivedStale` in its state) stops the read with a 'not settled' error, so a check samples again until the mark clears and never passes or fails on a route about to go. The token is Junos's documented spelling; a live restart hasn't shown it yet (the example's FRR is a graceful-restart helper, not a restarter, so j1 drops a dead peer's routes at once). Mitigation: leave graceful restart off in the lab.",
    "Juniper (beta): `netdryrun record` reads the whole table in Junos's terse form, which doesn't show `NotInstall`, so it can record a static with `no-install` as an active route. The recorded check then fails on it (a route check reads the extensive answer, where `NotInstall` makes the route inactive), never passes.",
    "Cisco NX-OS (beta): Each NX-OS node is a VM inside its container: NX-API answered 5 to 7 minutes after deploy in our runs, and the node needs KVM, 4 vCPUs and about 9 GiB of memory (8 GB for the VM). Give checks a `timeout` of at least 900 s.",
    "Cisco NX-OS (beta): Failure scenarios (`link_down`, `node_isolated`) on an NX-OS node are refused: the container's interfaces only carry frames to the VM. Take the link down on the other side of the link.",
    "Cisco NX-OS (beta): `med: 0` is refused before deploying: NX-OS prints MED 0 for a path received with no MED, so the two can't be told apart. Check a non-zero MED, or that route on another platform.",
    "Cisco NX-OS (beta): graceful restart: a path the router marks stale (a restarting peer's route, kept until it re-sends it or the stale timer ends) stops the read with a 'not settled' error, so a check samples again until the mark clears and never passes or fails on a route about to go. The mark is read from the NOS's own field (`pathstaled`); a live graceful restart has not been captured on this NOS to confirm the field turns true during one. Mitigation: leave graceful restart off in the lab.",
    "Cisco NX-OS (beta): startup config: a line the NOS rejects at boot isn't detected yet, so the lab can run without it. Mitigation: add a positive check for what each changed line creates. Fix scheduled: 0.4.",
    "MikroTik RouterOS (beta): Each RouterOS node is a VM inside its container: the REST API answers about a minute after deploy, and the startup config is imported after that (an import stops at its first error), so give checks a `timeout` of at least 600 s. One CHR node per lab until MikroTik confirms more are allowed.",
    "MikroTik RouterOS (beta): IPv6 sessions and routes, ping inside a VRF, and failure scenarios (`link_down`, `node_isolated`) are refused with a clear message, not answered.",
    "MikroTik RouterOS (beta): `bgp_prefixes` counts prefixes the router received AND policy accepted (derived from the routing route table): the session's own `prefix-count` includes rejected prefixes and is not used.",
    "MikroTik RouterOS (beta): A path without a LOCAL_PREF attribute reports local_pref as unknown, never as the default: a `local_pref` check on it fails.",
    "MikroTik RouterOS (beta): graceful restart, add-path, multipath and max-prefix behaviour are not captured yet: a route row with a key the parser does not know stops the read with an error."
  ],
  "platforms": [
    {
      "driver": "frr",
      "name": "FRR"
    },
    {
      "driver": "srlinux",
      "name": "Nokia SR Linux"
    },
    {
      "driver": "sonic",
      "name": "SONiC (docker-sonic-vs)"
    },
    {
      "driver": "eos",
      "name": "Arista EOS (cEOS, bring your own image)"
    },
    {
      "driver": "junos",
      "name": "Juniper cJunosEvolved (beta, bring your own image)"
    },
    {
      "driver": "nxos",
      "name": "Cisco NX-OS (Nexus 9000v, beta, bring your own image)"
    },
    {
      "driver": "routeros",
      "name": "MikroTik RouterOS 7 (CHR, beta, bring your own image)"
    }
  ],
  "mcp": {
    "install": [
      "uvx netdryrun mcp",
      "claude mcp add netdryrun -- netdryrun mcp"
    ],
    "transport": "stdio",
    "tools": [
      "dry_run",
      "verify_change",
      "start_run",
      "get_result",
      "run_checks",
      "record_baseline",
      "validate",
      "check_types"
    ],
    "registry_name": "io.github.netdryrun/netdryrun"
  },
  "check_types": [
    "bgp_session",
    "bgp_prefixes",
    "route",
    "bgp_route",
    "ping"
  ],
  "verdicts": {
    "run": [
      "CHECKS PASSED (only what the checks cover)",
      "DO NOT APPLY THIS CHANGE",
      "INCONCLUSIVE: the lab did not reach a testable state; this says nothing about your change. Do not apply it until a run passes."
    ],
    "verify": [
      "INTENT MATCHED",
      "NO BEHAVIOR CHANGE",
      "UNDECLARED CHANGES: DO NOT APPLY",
      "INCONCLUSIVE",
      "INCONCLUSIVE: UNHEALTHY BASELINE",
      "ERROR: NO VERDICT"
    ],
    "decide_on": "status, never the verdict text"
  },
  "exit_codes": {
    "run": {
      "0": "passed",
      "1": "failed",
      "2": "error (no verdict)",
      "3": "inconclusive"
    },
    "verify": {
      "0": "matched or no_change",
      "1": "failed (undeclared changes, a declaration that didn't happen, or a failed standing guard)",
      "2": "error (no verdict)",
      "3": "inconclusive or unhealthy_baseline"
    }
  },
  "never": [
    "connects to real devices",
    "sends telemetry or uploads anything by default (the GitHub Action's reserved cloud input is off)",
    "writes or weakens checks or intents for you"
  ],
  "docs": {
    "ai_agents": "https://netdryrun.com/ai-agents/",
    "verify": "https://netdryrun.com/reference/verify/",
    "cli": "https://netdryrun.com/reference/cli/",
    "config": "https://netdryrun.com/reference/config/",
    "github_action": "https://netdryrun.com/github-action/",
    "mcp_result_schema": "https://netdryrun.com/schemas/mcp-result-v1.json",
    "verify_report_schema": "https://netdryrun.com/schemas/verify-v1.json",
    "agents_md": "https://github.com/netdryrun/Netdryrun/blob/main/AGENTS.md",
    "llms_txt": "https://netdryrun.com/llms.txt"
  }
}
