✨ dblCheck

Platforms
Transport
Integrations
Avg. Cost per Agent Session

📖 Table of Contents

• 📜 dblCheck
  • 🔭 Overview
  • 🍀 Here's a Quick Demo
  • ⭐ What's New in v1.2
  • ⚒️ Core Tech Stack
  • 📋 Validation Scope
  • 🛠️ Installation & Usage
  • 🦾 Operating Modes
  • 🔄 Test Network Topology
  • ⬆️ Planned Upgrades
  • ♻️ Repository Lifecycle
  • 📄 Disclaimer
  • 📜 License
  • 📧 Collaborations

🔭 Overview

AI-assisted network intent validation framework for multi-vendor environments.

Continuously checks live network state against design intent and invokes a Claude agent to diagnose, explain, and document failures and inconsistencies between expected vs. actual state.

🔑 Therefore, the key is building and maintaining an up-to-date network intent schema - and dblCheck does the rest.

▫️ Key characteristics:

• Intent-driven validation - Define expected state in NetBox config contexts,
• AI root-cause diagnosis - Claude agent investigates failures using 8 read-only MCP tools
• Read-only - Agent queries and investigates devices, never configures
• Real-time dashboard - Live validation results and streamed AI diagnosis
• Daemon mode - Scheduled validation runs, always-on monitoring
• HashiCorp Vault - All secrets (device creds, NetBox token, Jira key etc.) stored in Vault
• NetBox - Network inventory and expected state loaded automatically
• Jira - Network state drift and deviations logged to Jira
• 582 tests - 21 suites (19 unit + 2 integration)

▫️ Supported models:

• Haiku 4.5
• Sonnet 4.6
• Opus 4.6 (default, best reasoning)

▫️ Operational Guardrails:

• See guardrails.md

▫️ Agent Prompt:

• See agent_prompt.md

🍀 Here's a Quick Demo

• Demo video coming soon...

⭐ What's New in v1.2

• See CHANGELOG.md

⚒️ Core Tech Stack

Tool
Claude Agent	✓
MCP (FastMCP)	✓
Python	✓
Scrapli	✓
HashiCorp Vault	✓
NetBox	✓
Jira	✓

📋 Validation Scope

Protocol	What's Checked
OSPF	Neighbor state (FULL), area config, process config
EIGRP	Neighbor state, interfaces, topology
BGP	Peer state (Established), prefix counts
Interfaces	Up/down state, expected operational status

🛠️ Installation & Usage

▫️ Prerequisites:

• Python 3.11+
• HashiCorp Vault
• NetBox
• Jira (optional)

▫️ Step 1 - Install:

git clone https://github.com/pdudotdev/dblCheck /opt/dblcheck
cd /opt/dblcheck
python3 -m venv dbl
dbl/bin/pip install -r requirements.txt

▫️ Step 2 - Vault:

Start Vault (dev mode, lab use):

vault server -dev -dev-root-token-id=<your-root-token>
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=<your-root-token>

Or initialize and unseal an existing Vault:

vault operator init -key-shares=1 -key-threshold=1   # first-time setup
vault operator unseal                                  # after every restart

🔑 Save the unseal key output from vault operator init somewhere safe - you'll need it every time Vault restarts or seals. Without it, a sealed Vault cannot be recovered.

⚠️ dblCheck requires Vault to be running and unsealed before any run. If Vault is unavailable, credential lookups fall back to env vars (see .env.example).

Store secrets:

vault kv put secret/dblcheck/router username=<user> password=<pass>
vault kv put secret/dblcheck/netbox token=<token>
vault kv put secret/dblcheck/jira token=<token>
vault kv put secret/dblcheck/dashboard token=<token>
# vault kv put secret/dblcheck/anthropic api_key=<key>

▫️ Step 3 - Configure .env:

• See example

cp .env.example .env

▫️ Step 4 - Claude auth:

Option A - Anthropic account:

claude login

Option B - API key via Vault.

▫️ Step 5 - Register the MCP server:

claude mcp add dblcheck -s user -- /home/<user>/dbl/bin/python server/MCPServer.py

🦾 Operating Modes

Interactive Mode

• Run:

dbl/bin/python cli/dblcheck.py                          # full validation
dbl/bin/python cli/dblcheck.py --no-diagnose            # skip AI diagnosis

Daemon Mode

dblCheck runs as a systemd daemon that validates the network on a schedule and serves a live dashboard.

▫️ Install the service:

sudo deploy/install.sh

Detects your install path and user automatically - no manual editing required.

▫️ Manage with: systemctl start | stop | restart | status dblcheck

▫️ Dashboard:

http://localhost:5556

Shows live validation results and streams AI diagnosis output when failures are found. Port is configurable via DASHBOARD_PORT in .env.

⚠️ NOTE: The daemon validates every 300 seconds by default. Change with INTERVAL=<seconds> in .env.

🔄 Test Network Topology

▫️ Network diagram:

▫️ Lab environment:

• 16 devices defined in TOPOLOGY.yml
• 5 × Cisco IOL nodes (IOS)
• 3 × Cisco c8000v nodes (IOS-XE)
• 4 × Arista cEOS nodes
• 2 × MikroTik CHR nodes
• 1 × Juniper JunOS node
• 1 x Aruba AOS-CX node
• OSPF multi-area, EIGRP, BGP
• Device credentials stored in Vault
• Network inventory and state in NetBox

⬆️ Planned Upgrades

• New protocols supported

♻️ Repository Lifecycle

New features are being added periodically (protocols, integrations, optimizations).

Stay up-to-date:

• Watch and Star this repository

📄 Disclaimer

You are responsible for defining your own network intent (NetBox config contexts), building your test environment, and meeting the necessary conditions (Python 3.11+, Claude CLI, HashiCorp Vault, etc.).

📜 License

Licensed under the Business Source License 1.1. Source code is available for research, educational, and non-commercial use. Commercial use, SaaS deployment, enterprise integration, or paid services require a commercial license.

📧 Collaborations

Interested in collaborating?

• Email:
  • Reach out at hello@ainoc.dev
• LinkedIn:
  • Let's discuss via LinkedIn