netsert

Declarative network state testing via gNMI

What is it?

netsert validates network device state using gNMI. Define what your network should look like in YAML — interfaces up, BGP sessions established, hostnames correct — and netsert validates that against live devices.

Think of it as unit tests for your network.

Why netsert?

Traditional approach

Engineer pushes config change
Maybe runs show commands manually
Hope nothing broke
Find out at 3am when monitoring alerts

With netsert

Engineer pushes config change
CI runs netsert run assertions.yaml
If anything breaks → exit code 1 → pipeline blocked
Fix before merge

Installation

Using Go

go install github.com/ndtobs/netsert/cmd/netsert@latest

From source

git clone https://github.com/ndtobs/netsert.git
cd netsert
go build -o netsert ./cmd/netsert

Quick start

Create an assertion file:

# assertions.yaml
assertions:
  - target: router1:6030
    path: interfaces[Ethernet1]/state/oper-status
    expect: UP

  - target: "@leaves"
    path: bgp[default]/neighbors[10.0.0.1]/state/session-state
    expect: ESTABLISHED

Run it:

$ netsert run -f assertions.yaml -u admin -p admin --insecure

✓ router1: interfaces[Ethernet1]/state/oper-status = UP
✓ leaf1: bgp[default]/neighbors[10.0.0.1]/state/session-state = ESTABLISHED
✓ leaf2: bgp[default]/neighbors[10.0.0.1]/state/session-state = ESTABLISHED

3/3 passed

Features

Declarative — Define expected state in YAML, not scripts
gNMI native — Structured data via gRPC, not CLI scraping
Short path syntax — Write readable paths, not verbose OpenConfig
Inventory groups — Target devices with @group syntax
Generators — Bootstrap assertions from live device state
Concurrent execution — 10 workers × 5 parallel by default
CI/CD ready — Exit codes and JSON output
Vendor neutral — Works with Arista, Nokia, Juniper, Cisco

Why gNMI?

gNMI	CLI/SSH
Structured data (protobuf)	Unstructured text (regex parsing)
Fast (gRPC)	Slow (SSH overhead)
Vendor-neutral paths	Vendor-specific commands
Real-time state	Cached CLI output

Writing assertions → GitHub