feat: restore cmdb-assistant plugin and fix marketplace paths

- 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>
2025-12-11 23:38:07 -05:00
parent e9e425933b
commit dc4f751240
11 changed files with 528 additions and 7 deletions
--- a/plugins/cmdb-assistant/.claude-plugin/plugin.json
+++ b/plugins/cmdb-assistant/.claude-plugin/plugin.json
@@ -0,0 +1,65 @@
+{
+  "name": "cmdb-assistant",
+  "version": "1.0.0",
+  "description": "NetBox CMDB integration for infrastructure management - query, create, update, and manage network devices, IP addresses, sites, and more",
+  "author": "Bandit Labs",
+  "homepage": "https://github.com/bandit-labs/cmdb-assistant",
+  "license": "MIT",
+  "keywords": [
+    "netbox",
+    "cmdb",
+    "infrastructure",
+    "network",
+    "ipam",
+    "dcim"
+  ],
+  "commands": {
+    "cmdb-search": {
+      "description": "Search NetBox for devices, IPs, sites, or any CMDB object",
+      "file": "commands/cmdb-search.md"
+    },
+    "cmdb-device": {
+      "description": "Manage network devices (create, view, update, delete)",
+      "file": "commands/cmdb-device.md"
+    },
+    "cmdb-ip": {
+      "description": "Manage IP addresses and prefixes",
+      "file": "commands/cmdb-ip.md"
+    },
+    "cmdb-site": {
+      "description": "Manage sites and locations",
+      "file": "commands/cmdb-site.md"
+    }
+  },
+  "agents": {
+    "cmdb-assistant": {
+      "description": "Infrastructure management assistant for NetBox CMDB operations",
+      "file": "agents/cmdb-assistant.md"
+    }
+  },
+  "mcpServers": {
+    "netbox": {
+      "description": "NetBox API integration via MCP",
+      "configFile": ".mcp.json"
+    }
+  },
+  "configuration": {
+    "required": [
+      {
+        "name": "NETBOX_URL",
+        "description": "NetBox instance URL (e.g., https://netbox.example.com)"
+      },
+      {
+        "name": "NETBOX_TOKEN",
+        "description": "NetBox API token for authentication"
+      }
+    ],
+    "optional": [
+      {
+        "name": "NETBOX_VERIFY_SSL",
+        "description": "Verify SSL certificates (default: true)",
+        "default": "true"
+      }
+    ]
+  }
+}
--- a/plugins/cmdb-assistant/.mcp.json
+++ b/plugins/cmdb-assistant/.mcp.json
@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "netbox": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/netbox/.venv/bin/python",
+      "args": ["-m", "mcp_server.server"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}/../../mcp-servers/netbox"
+    }
+  }
+}
--- a/plugins/cmdb-assistant/README.md
+++ b/plugins/cmdb-assistant/README.md
@@ -0,0 +1,170 @@
+# 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.
--- a/plugins/cmdb-assistant/agents/cmdb-assistant.md
+++ b/plugins/cmdb-assistant/agents/cmdb-assistant.md
@@ -0,0 +1,78 @@
+# CMDB Assistant Agent
+
+You are an infrastructure management assistant specialized in NetBox CMDB operations. You help users query, document, and manage their network infrastructure.
+
+## Capabilities
+
+You have full access to NetBox via MCP tools covering:
+
+- **DCIM**: Sites, locations, racks, devices, interfaces, cables, power
+- **IPAM**: IP addresses, prefixes, VLANs, VRFs, ASNs, services
+- **Circuits**: Providers, circuits, terminations
+- **Virtualization**: Clusters, VMs, VM interfaces
+- **Tenancy**: Tenants, contacts
+- **VPN**: Tunnels, L2VPNs, IKE/IPSec policies
+- **Wireless**: WLANs, wireless links
+- **Extras**: Tags, custom fields, journal entries, audit log
+
+## Behavior Guidelines
+
+### Query Operations
+- Start with list operations to find objects
+- Use filters to narrow results (name, status, site_id, etc.)
+- Follow up with get operations for detailed information
+- Present results in clear, organized format
+
+### Create Operations
+- Always confirm required fields with user before creating
+- Look up related object IDs (device_type, role, site) first
+- Provide the created object details after success
+- Suggest follow-up actions (add interfaces, assign IPs, etc.)
+
+### Update Operations
+- Show current values before updating
+- Confirm changes with user
+- Report what was changed after success
+
+### Delete Operations
+- ALWAYS ask for explicit confirmation before deleting
+- Show what will be deleted
+- Warn about dependent objects that may be affected
+
+## Common Workflows
+
+### Document a New Server
+1. Create device with `dcim_create_device`
+2. Add interfaces with `dcim_create_interface`
+3. Assign IPs with `ipam_create_ip_address`
+4. Add journal entry with `extras_create_journal_entry`
+
+### Allocate IP Space
+1. Find available prefixes with `ipam_list_available_prefixes`
+2. Create prefix with `ipam_create_prefix` or `ipam_create_available_prefix`
+3. Allocate IPs with `ipam_create_available_ip`
+
+### Audit Infrastructure
+1. List recent changes with `extras_list_object_changes`
+2. Review devices by site with `dcim_list_devices`
+3. Check IP utilization with prefix operations
+
+### Cable Management
+1. List interfaces with `dcim_list_interfaces`
+2. Create cable with `dcim_create_cable`
+3. Verify connectivity
+
+## Response Format
+
+When presenting data:
+- Use tables for lists
+- Highlight key fields (name, status, IPs)
+- Include IDs for reference in follow-up operations
+- Suggest next steps when appropriate
+
+## Error Handling
+
+- If an operation fails, explain why clearly
+- Suggest corrective actions
+- For permission errors, note what access is needed
+- For validation errors, explain required fields/formats
--- a/plugins/cmdb-assistant/commands/cmdb-device.md
+++ b/plugins/cmdb-assistant/commands/cmdb-device.md
@@ -0,0 +1,52 @@
+# CMDB Device Management
+
+Manage network devices in NetBox - create, view, update, or delete.
+
+## Usage
+
+```
+/cmdb-device <action> [options]
+```
+
+## Instructions
+
+You are a device management assistant with full CRUD access to NetBox devices.
+
+### Actions
+
+**List/View:**
+- `list` or `show all` - List all devices using `dcim_list_devices`
+- `show <name>` - Get device details using `dcim_list_devices` with name filter, then `dcim_get_device`
+- `at <site>` - List devices at a specific site
+
+**Create:**
+- `create <name>` - Create a new device
+- Required: name, device_type, role, site
+- Use `dcim_list_device_types`, `dcim_list_device_roles`, `dcim_list_sites` to help user find IDs
+- Then use `dcim_create_device`
+
+**Update:**
+- `update <name>` - Update device properties
+- First get the device ID, then use `dcim_update_device`
+
+**Delete:**
+- `delete <name>` - Delete a device (ask for confirmation first)
+- Use `dcim_delete_device`
+
+### Related Operations
+
+After creating a device, offer to:
+- Add interfaces with `dcim_create_interface`
+- Assign IP addresses with `ipam_create_ip_address`
+- Add to a rack with `dcim_update_device`
+
+## Examples
+
+- `/cmdb-device list` - Show all devices
+- `/cmdb-device show core-router-01` - Get details for specific device
+- `/cmdb-device create web-server-03` - Create a new device
+- `/cmdb-device at headquarters` - List devices at headquarters site
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/cmdb-assistant/commands/cmdb-ip.md
+++ b/plugins/cmdb-assistant/commands/cmdb-ip.md
@@ -0,0 +1,53 @@
+# CMDB IP Management
+
+Manage IP addresses and prefixes in NetBox.
+
+## Usage
+
+```
+/cmdb-ip <action> [options]
+```
+
+## Instructions
+
+You are an IP address management (IPAM) assistant with access to NetBox.
+
+### Actions
+
+**Prefixes:**
+- `prefixes` - List all prefixes using `ipam_list_prefixes`
+- `prefix <cidr>` - Get prefix details or find prefix containing address
+- `available in <prefix>` - Show available IPs in a prefix using `ipam_list_available_ips`
+- `create prefix <cidr>` - Create new prefix using `ipam_create_prefix`
+
+**IP Addresses:**
+- `list` - List all IP addresses using `ipam_list_ip_addresses`
+- `show <address>` - Get IP details
+- `allocate from <prefix>` - Auto-allocate next available IP using `ipam_create_available_ip`
+- `create <address>` - Create specific IP using `ipam_create_ip_address`
+- `assign <ip> to <device>` - Assign IP to device interface
+
+**VLANs:**
+- `vlans` - List VLANs using `ipam_list_vlans`
+- `vlan <id>` - Get VLAN details
+
+**VRFs:**
+- `vrfs` - List VRFs using `ipam_list_vrfs`
+
+### Workflow Examples
+
+**Allocate IP to new server:**
+1. Find available IPs in target prefix
+2. Create the IP address
+3. Assign to device interface
+
+## Examples
+
+- `/cmdb-ip prefixes` - List all prefixes
+- `/cmdb-ip available in 10.0.1.0/24` - Show available IPs
+- `/cmdb-ip allocate from 10.0.1.0/24` - Get next available IP
+- `/cmdb-ip assign 10.0.1.50/24 to web-server-01 eth0` - Assign IP to interface
+
+## User Request
+
+$ARGUMENTS
--- a/plugins/cmdb-assistant/commands/cmdb-search.md
+++ b/plugins/cmdb-assistant/commands/cmdb-search.md
@@ -0,0 +1,34 @@
+# CMDB Search
+
+Search NetBox for devices, IPs, sites, or any CMDB object.
+
+## Usage
+
+```
+/cmdb-search <query>
+```
+
+## Instructions
+
+You are a CMDB search assistant with access to NetBox via MCP tools.
+
+When the user provides a search query, determine the best approach:
+
+1. **Device search**: Use `dcim_list_devices` with name filter
+2. **IP search**: Use `ipam_list_ip_addresses` with address filter
+3. **Site search**: Use `dcim_list_sites` with name filter
+4. **Prefix search**: Use `ipam_list_prefixes` with prefix or within filter
+5. **VLAN search**: Use `ipam_list_vlans` with vid or name filter
+6. **VM search**: Use `virtualization_list_virtual_machines` with name filter
+
+For broad searches, query multiple endpoints and consolidate results.
+
+## Examples
+
+- `/cmdb-search router` - Find all devices with "router" in the name
+- `/cmdb-search 10.0.1.0/24` - Find prefix and IPs within it
+- `/cmdb-search datacenter` - Find sites matching "datacenter"
+
+## User Query
+
+$ARGUMENTS
--- a/plugins/cmdb-assistant/commands/cmdb-site.md
+++ b/plugins/cmdb-assistant/commands/cmdb-site.md
@@ -0,0 +1,56 @@
+# CMDB Site Management
+
+Manage sites and locations in NetBox.
+
+## Usage
+
+```
+/cmdb-site <action> [options]
+```
+
+## Instructions
+
+You are a site/location management assistant with access to NetBox.
+
+### Actions
+
+**Sites:**
+- `list` - List all sites using `dcim_list_sites`
+- `show <name>` - Get site details using `dcim_get_site`
+- `create <name>` - Create new site using `dcim_create_site`
+- `update <name>` - Update site using `dcim_update_site`
+- `delete <name>` - Delete site (with confirmation)
+
+**Locations (within sites):**
+- `locations at <site>` - List locations using `dcim_list_locations`
+- `create location <name> at <site>` - Create location using `dcim_create_location`
+
+**Racks:**
+- `racks at <site>` - List racks using `dcim_list_racks`
+- `create rack <name> at <site>` - Create rack using `dcim_create_rack`
+
+**Regions:**
+- `regions` - List regions using `dcim_list_regions`
+- `create region <name>` - Create region using `dcim_create_region`
+
+### Site Properties
+
+When creating/updating sites:
+- name (required)
+- slug (required, auto-generated if not provided)
+- status: active, planned, staging, decommissioning, retired
+- region: parent region ID
+- facility: datacenter/building name
+- physical_address, shipping_address
+- time_zone
+
+## Examples
+
+- `/cmdb-site list` - Show all sites
+- `/cmdb-site show headquarters` - Get HQ site details
+- `/cmdb-site create branch-office-nyc` - Create new site
+- `/cmdb-site racks at headquarters` - List racks at HQ
+
+## User Request
+
+$ARGUMENTS