Simon Knight

Device Interaction Framework

Active Rust

Contents

Concept

A Rust library and CLI for network device interaction and automated testing. Provides the essential PyATS capabilities — testbed management, CLI output parsing, and state verification — without the complexity. Connects to devices (real, simulated, or mocked), executes commands, parses structured output, and verifies correctness with the type safety of compiled Rust.

Code Samples

connectivity-check.yaml

# Example Verification Suite
# Demonstrates common network state checks.

name: "Connectivity Audit"
tests:
  # Check if the uplink interface is up on the spine
  - device: "spine-1"
    check: "interface_up"
    interface: "GigabitEthernet0/1"
    within: "30s"

  # Check for a critical route
  - device: "spine-1"
    check: "route_exists"
    destination: "10.0.0.0/8"

  # Verify connectivity to an external target
  - device: "spine-1"
    check: "ping"
    target: "8.8.8.8"
    threshold: 0.0

lab-testbed.yaml

# Example Testbed for Device Interaction Framework
# This testbed demonstrates a mix of Mock and real SSH devices.

testbed:
  name: example-lab
  credentials:
    default:
      username: admin
      password: admin_password

devices:
  # A core spine router using Mock backend for development
  spine-1:
    type: router
    os: cisco_ios
    role: spine
    tags: [core, datacenter-1]
    connections:
      mock:
        protocol: mock
        ip: 127.0.0.1

  # A leaf switch using SSH for production
  leaf-1:
    type: switch
    os: cisco_ios
    role: leaf
    tags: [access, rack-1]
    connections:
      ssh:
        protocol: ssh
        ip: 10.1.1.10
        port: 22

  # Another leaf switch
  leaf-2:
    type: switch
    os: cisco_ios
    role: leaf
    tags: [access, rack-2]
    connections:
      ssh:
        protocol: ssh
        ip: 10.1.1.11
        port: 22

Usage

# Connect to a device interactively
di-cli connect spine-1 --testbed lab.yaml

# Execute a command
di-cli exec spine-1 "show ip route" --testbed lab.yaml

# Run a verification suite
di-cli verify connectivity-check.yaml --testbed lab.yaml

Architecture

flowchart TD DB[DeviceBackend trait] DB --> MOCK["Mock
Fast parser development"] DB --> SIM["Simulator
Dynamic protocol testing"] DB --> SSH["Real SSH
Production validation"] style MOCK fill:#e8f5e9 style SIM fill:#fff3e0 style SSH fill:#fce4ec

Three-tier testing strategy: mock fixtures for fast parser development, Network Simulator integration for dynamic testing, real SSH for production validation. All three use the same DeviceBackend trait, so parsers and verification logic work identically across tiers.

~7,000 lines of Rust across 5 crates. 131 tests passing.

Quick Facts

   
Status Active
Stack Rust

What This Is

A fast, simple, and ergonomic Rust library and CLI for network device interaction and automated testing. Provides the essential PyATS capabilities—testbed management, CLI parsing, and state verification—without the complexity, as a focused component in a broader network automation toolkit.

Core Value

Enable rapid, type-safe validation of network device state through streamlined device interaction: connect to devices (real, simulated, or mocked), execute commands, parse structured output, and verify correctness—all with the performance and safety guarantees of Rust.

Current Milestone: v1.1 Complete Testing Stack

Goal: Complete the original vision by adding code-first verification framework and user-facing CLI tool, enabling end-to-end device testing workflow.

Target features:

Requirements

# Validated

Core Connectivity (v1.0):

Parser Framework (v1.0):

Backend Implementations (v1.0):

Testing & Examples (v1.0):

# Active

Verification Framework:

CLI Tool:

Testing & Examples:

# Out of Scope

Context

Current State (v1.0 shipped 2026-02-22):

Known Technical Debt (from v1.0 audit):

Ecosystem Integration: This tool is one component in a broader network automation toolkit. Related projects:

Development Workflow:

  1. Develop parsers using mock fixtures (real vendor outputs) ✓
  2. Test against netsim daemon (dynamic simulation) — partial (backend exists, integration tests pending)
  3. Validate against real devices (production hardware) — ready (SSH backend complete)

Inspiration: PyATS/Genie provides excellent network automation capabilities but is heavyweight and Python-based. This tool extracts the essential testing loop (define topology → connect → parse → verify) with:

Constraints

Key Decisions

Decision Rationale Outcome
Three-tier testing strategy (mock → netsim → real) Enables fast parser development (mock fixtures), dynamic testing (netsim), and production validation (real hardware) without blocking on device availability ✓ Good — MockBackend enables testing without hardware, SSH backend ready for real devices
Trait-based backend abstraction (DeviceBackend trait) Allows pluggable connection mechanisms (SSH, mock, netsim native) while maintaining type safety and enabling compile-time optimization ✓ Good — 3 backend implementations (Mock, SSH, Netsim), zero overhead trait dispatch
Start with core commands (route, interfaces, ping, traceroute) Proves the full stack (connect → parse → verify) works before expanding to 15+ commands; faster path to validation against netsim ✓ Good — All 4 parsers working with real IOS fixtures, full stack validated
Code-first verification API (not YAML tests) Rust API provides type safety, IDE support, and composability; YAML adds parsing complexity and loses compile-time checks — Pending — Verification framework is Phase 5
Cisco as reference implementation Most mature netsim support; well-documented CLI; establishes parser patterns before expanding to multi-vendor ✓ Good — Cisco IOS parser patterns established, extensible to other vendors
Use russh over thrussh russh is actively maintained fork with better async support and security updates ✓ Good — SSH backend works reliably, prompt-delimited execution successful
Parser registry with trait objects Enables dynamic parser lookup by command name while maintaining type safety through downcasting ✓ Good — Registry integration tests pass, type-safe API validated
nom for parsing with nom_locate Provides composable parser combinators with line/column error reporting ✓ Good — Reusable primitives (ip, interface, protocol), actionable error messages
ConnectionPool per-device caching Reuse SSH sessions to avoid reconnection overhead ✓ Good — Pool unit tests prove session reuse, single-flight execution prevents race conditions

Last updated: 2026-02-22 after v1.1 milestone start