lmiranda
9698e8724d
Sprint 4 - Plugin Commands implementation adding 18 new user-facing commands across 8 plugins as part of V5.2.0 Plugin Enhancements. **projman:** - #241: /sprint-diagram - Mermaid visualization of sprint issues **pr-review:** - #242: Confidence threshold config (PR_REVIEW_CONFIDENCE_THRESHOLD) - #243: /pr-diff - Formatted diff with inline review comments **data-platform:** - #244: /data-quality - DataFrame quality checks (nulls, duplicates, outliers) - #245: /lineage-viz - dbt lineage as Mermaid diagrams - #246: /dbt-test - Formatted dbt test runner **viz-platform:** - #247: /chart-export - Export charts to PNG/SVG/PDF via kaleido - #248: /accessibility-check - Color blind validation (WCAG contrast) - #249: /breakpoints - Responsive layout configuration **contract-validator:** - #250: /dependency-graph - Plugin dependency visualization **doc-guardian:** - #251: /changelog-gen - Generate changelog from conventional commits - #252: /doc-coverage - Documentation coverage metrics - #253: /stale-docs - Flag outdated documentation **claude-config-maintainer:** - #254: /config-diff - Track CLAUDE.md changes over time - #255: /config-lint - 31 lint rules for CLAUDE.md best practices **cmdb-assistant:** - #256: /cmdb-topology - Infrastructure topology diagrams - #257: /change-audit - NetBox audit trail queries - #258: /ip-conflicts - Detect IP conflicts and overlaps Closes #241, #242, #243, #244, #245, #246, #247, #248, #249, #250, #251, #252, #253, #254, #255, #256, #257, #258 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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.2.0
/cmdb-topology: Generate Mermaid diagrams showing infrastructure topology (rack view, network view, site overview)/change-audit: Query and analyze NetBox audit log for change tracking and compliance/ip-conflicts: Detect IP address conflicts and overlapping prefixes
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
- A running NetBox instance (v4.x recommended)
- NetBox API token with appropriate permissions
- 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) |
/cmdb-topology <view> |
Generate Mermaid diagrams (rack, network, site, full) |
/change-audit [filters] |
Query NetBox audit log for change tracking |
/ip-conflicts [scope] |
Detect IP conflicts and overlapping prefixes |
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
│ ├── cmdb-register.md # Machine registration
│ ├── cmdb-sync.md # Machine sync
│ ├── cmdb-topology.md # Topology visualization (NEW)
│ ├── change-audit.md # Change audit log (NEW)
│ └── ip-conflicts.md # IP conflict detection (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
- Log into your NetBox instance
- Navigate to your profile (top-right menu)
- Go to "API Tokens"
- Click "Add a token"
- Set appropriate permissions (read-only or read-write)
- Copy the generated token
Troubleshooting
Connection Issues
- Verify
NETBOX_API_URLis 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_TIMEOUTfor slow connections - Check network latency to NetBox instance
License
MIT License - Part of the Leo Claude Marketplace.