lmiranda
dc4f751240
- Restored cmdb-assistant plugin from commit ba599e3
- Moved to plugins/cmdb-assistant/ following new structure
- Updated .mcp.json path to ../../mcp-servers/netbox
- Fixed marketplace.json paths for all plugins (now in plugins/)
- Updated README.md with cmdb-assistant link and structure
- Updated CLAUDE.md governance to include cmdb-assistant
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
171 lines
4.5 KiB
Markdown
171 lines
4.5 KiB
Markdown
# CMDB Assistant
|
|
|
|
A Claude Code plugin for NetBox CMDB integration - query, create, update, and manage your network infrastructure directly from Claude Code.
|
|
|
|
## 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
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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 |
|
|
|---------|-------------|
|
|
| `/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 |
|
|
|
|
## 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
|
|
|
|
## Architecture
|
|
|
|
```
|
|
cmdb-assistant/
|
|
├── .claude-plugin/
|
|
│ └── plugin.json # Plugin manifest
|
|
├── .mcp.json # MCP server configuration
|
|
├── commands/
|
|
│ ├── cmdb-search.md # Search command
|
|
│ ├── cmdb-device.md # Device management
|
|
│ ├── cmdb-ip.md # IP management
|
|
│ └── cmdb-site.md # Site management
|
|
├── 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 Bandit Labs plugin collection.
|