leo-claude-mktplace/plugins/cmdb-assistant/README.md

CMDB Assistant

A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.

What's New in v1.1.0

• Data Quality Validation: Hooks for SessionStart and PreToolUse that check data quality and warn about missing fields
• Best Practices Skill: Reference documentation for NetBox patterns (naming conventions, dependency order, role management)
• /cmdb-audit: Analyze data quality across VMs, devices, naming conventions, and roles
• /cmdb-register: Register the current machine into NetBox with all running applications (Docker containers, systemd services)
• /cmdb-sync: Synchronize existing machine state with NetBox (detect drift, update with confirmation)

Features

• Full CRUD Operations: Create, read, update, and delete across all NetBox modules
• Smart Search: Find devices, IPs, sites, and more with natural language queries
• IP Management: Allocate IPs, manage prefixes, track VLANs
• Infrastructure Documentation: Document servers, network devices, and connections
• Audit Trail: Review changes and maintain infrastructure history
• Data Quality Validation: Proactive checks for missing site, tenant, platform assignments
• Machine Registration: Auto-discover and register servers with running applications
• Drift Detection: Sync machine state and detect changes over time

Installation

Prerequisites

1. A running NetBox instance (v4.x recommended)
2. NetBox API token with appropriate permissions
3. The NetBox MCP server configured (see below)

Configure NetBox Credentials

Create the configuration file:

mkdir -p ~/.config/claude
cat > ~/.config/claude/netbox.env << 'EOF'
NETBOX_API_URL=https://your-netbox-instance/api
NETBOX_API_TOKEN=your-api-token-here
NETBOX_VERIFY_SSL=true
NETBOX_TIMEOUT=30
EOF

Install the Plugin

Add to your Claude Code plugins or marketplace configuration.

Commands

Command	Description
/initial-setup	Interactive setup wizard for NetBox MCP server
/cmdb-search <query>	Search for devices, IPs, sites, or any CMDB object
/cmdb-device <action>	Manage network devices (list, create, update, delete)
/cmdb-ip <action>	Manage IP addresses and prefixes
/cmdb-site <action>	Manage sites and locations
/cmdb-audit [scope]	Data quality analysis (all, vms, devices, naming, roles)
/cmdb-register	Register current machine into NetBox with running apps
/cmdb-sync	Sync machine state with NetBox (detect drift, update)

Agent

The cmdb-assistant agent provides conversational infrastructure management:

@cmdb-assistant Show me all devices at the headquarters site
@cmdb-assistant Allocate the next available IP from 10.0.1.0/24 for the new web server
@cmdb-assistant What changes were made to the network today?

Usage Examples

Search for Infrastructure

/cmdb-search router
/cmdb-search 10.0.1.0/24
/cmdb-search datacenter

Device Management

/cmdb-device list
/cmdb-device show core-router-01
/cmdb-device create web-server-03
/cmdb-device at headquarters

IP Address Management

/cmdb-ip prefixes
/cmdb-ip available in 10.0.1.0/24
/cmdb-ip allocate from 10.0.1.0/24

Site Management

/cmdb-site list
/cmdb-site show headquarters
/cmdb-site racks at datacenter-east

NetBox Coverage

This plugin provides access to the full NetBox API:

• DCIM: Sites, Locations, Racks, Devices, Interfaces, Cables, Power
• IPAM: IP Addresses, Prefixes, VLANs, VRFs, ASNs, Services
• Circuits: Providers, Circuits, Terminations
• Virtualization: Clusters, Virtual Machines, VM Interfaces
• Tenancy: Tenants, Contacts
• VPN: Tunnels, L2VPNs, IKE/IPSec Policies
• Wireless: WLANs, Wireless Links
• Extras: Tags, Custom Fields, Journal Entries, Audit Log

Hooks

Event	Purpose
SessionStart	Test NetBox connectivity, report data quality issues
PreToolUse	Validate VM/device parameters before create/update

Hooks are non-blocking - they emit warnings but never prevent operations.

Architecture

cmdb-assistant/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── .mcp.json                 # MCP server configuration
├── commands/
│   ├── initial-setup.md     # Setup wizard
│   ├── cmdb-search.md       # Search command
│   ├── cmdb-device.md       # Device management
│   ├── cmdb-ip.md           # IP management
│   ├── cmdb-site.md         # Site management
│   ├── cmdb-audit.md        # Data quality audit (NEW)
│   ├── cmdb-register.md     # Machine registration (NEW)
│   └── cmdb-sync.md         # Machine sync (NEW)
├── hooks/
│   ├── hooks.json           # Hook configuration
│   ├── startup-check.sh     # SessionStart validation
│   └── validate-input.sh    # PreToolUse validation
├── skills/
│   └── netbox-patterns/
│       └── SKILL.md         # NetBox best practices reference
├── agents/
│   └── cmdb-assistant.md    # Main assistant agent
└── README.md

The plugin uses the shared NetBox MCP server at mcp-servers/netbox/.

Configuration

Required Environment Variables

Variable	Description
NETBOX_API_URL	Full URL to NetBox API (e.g., https://netbox.example.com/api)
NETBOX_API_TOKEN	API authentication token

Optional Environment Variables

Variable	Default	Description
NETBOX_VERIFY_SSL	true	Verify SSL certificates
NETBOX_TIMEOUT	30	Request timeout in seconds

Getting a NetBox API Token

1. Log into your NetBox instance
2. Navigate to your profile (top-right menu)
3. Go to "API Tokens"
4. Click "Add a token"
5. Set appropriate permissions (read-only or read-write)
6. Copy the generated token

Troubleshooting

Connection Issues

• Verify NETBOX_API_URL is correct and accessible
• Check firewall rules allow access to NetBox
• For self-signed certificates, set NETBOX_VERIFY_SSL=false

Authentication Errors

• Ensure API token is valid and not expired
• Check token has required permissions for the operation

Timeout Errors

• Increase NETBOX_TIMEOUT for slow connections
• Check network latency to NetBox instance

License

MIT License - Part of the Leo Claude Marketplace.