diff --git a/.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json b/.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json index f347c5e..7dfc3a2 100644 --- a/.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json +++ b/.claude-plugins/projman-marketplace/.claude-plugin/marketplace.json @@ -9,19 +9,19 @@ "name": "projman", "version": "0.1.0", "description": "Sprint planning and project management with Gitea and Wiki.js integration", - "source": "./../../projman" + "source": "./../../../plugins/projman" }, { "name": "project-hygiene", "version": "0.1.0", "description": "Post-task cleanup hook that removes temp files, warns about unexpected root files, and manages orphans", - "source": "./../../project-hygiene" + "source": "./../../../plugins/project-hygiene" }, { "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", - "source": "./../../cmdb-assistant" + "source": "./../../../plugins/cmdb-assistant" } ] } diff --git a/CLAUDE.md b/CLAUDE.md index 109ea27..686e580 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,7 +39,7 @@ Only these directories may exist at the repository root: | `docs/` | Documentation | | `hooks/` | Shared hooks (if any) | | `mcp-servers/` | Shared MCP servers | -| `plugins/` | All plugins (projman, projman-pmo, project-hygiene) | +| `plugins/` | All plugins (projman, projman-pmo, project-hygiene, cmdb-assistant) | | `scripts/` | Setup and maintenance scripts | ### File Creation Rules diff --git a/README.md b/README.md index bf3fbae..acb3320 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ AI-guided sprint planning with Gitea and Wiki.js integration. Transforms a prove **Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync` -### cmdb-assistant *(Planned)* +### [cmdb-assistant](./plugins/cmdb-assistant/README.md) **NetBox CMDB Integration** Full CRUD operations for network infrastructure management directly from Claude Code. @@ -156,9 +156,13 @@ support-claude-mktplace/ │ │ ├── .claude-plugin/ │ │ ├── commands/ │ │ └── agents/ -│ └── project-hygiene/ # Cleanup automation plugin +│ ├── project-hygiene/ # Cleanup automation plugin +│ │ ├── .claude-plugin/ +│ │ └── hooks/ +│ └── cmdb-assistant/ # NetBox CMDB integration │ ├── .claude-plugin/ -│ └── hooks/ +│ ├── commands/ +│ └── agents/ ├── mcp-servers/ # Shared MCP servers │ ├── gitea/ │ ├── wikijs/ diff --git a/plugins/cmdb-assistant/.claude-plugin/plugin.json b/plugins/cmdb-assistant/.claude-plugin/plugin.json new file mode 100644 index 0000000..865f796 --- /dev/null +++ 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" + } + ] + } +} diff --git a/plugins/cmdb-assistant/.mcp.json b/plugins/cmdb-assistant/.mcp.json new file mode 100644 index 0000000..f9209c4 --- /dev/null +++ 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" + } + } +} diff --git a/plugins/cmdb-assistant/README.md b/plugins/cmdb-assistant/README.md new file mode 100644 index 0000000..40dc7d8 --- /dev/null +++ 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 ` | Search for devices, IPs, sites, or any CMDB object | +| `/cmdb-device ` | Manage network devices (list, create, update, delete) | +| `/cmdb-ip ` | Manage IP addresses and prefixes | +| `/cmdb-site ` | 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. diff --git a/plugins/cmdb-assistant/agents/cmdb-assistant.md b/plugins/cmdb-assistant/agents/cmdb-assistant.md new file mode 100644 index 0000000..b216e15 --- /dev/null +++ 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 diff --git a/plugins/cmdb-assistant/commands/cmdb-device.md b/plugins/cmdb-assistant/commands/cmdb-device.md new file mode 100644 index 0000000..13e6a2d --- /dev/null +++ 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 [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 ` - Get device details using `dcim_list_devices` with name filter, then `dcim_get_device` +- `at ` - List devices at a specific site + +**Create:** +- `create ` - 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 ` - Update device properties +- First get the device ID, then use `dcim_update_device` + +**Delete:** +- `delete ` - 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 diff --git a/plugins/cmdb-assistant/commands/cmdb-ip.md b/plugins/cmdb-assistant/commands/cmdb-ip.md new file mode 100644 index 0000000..fc01a1e --- /dev/null +++ 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 [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 ` - Get prefix details or find prefix containing address +- `available in ` - Show available IPs in a prefix using `ipam_list_available_ips` +- `create prefix ` - Create new prefix using `ipam_create_prefix` + +**IP Addresses:** +- `list` - List all IP addresses using `ipam_list_ip_addresses` +- `show
` - Get IP details +- `allocate from ` - Auto-allocate next available IP using `ipam_create_available_ip` +- `create
` - Create specific IP using `ipam_create_ip_address` +- `assign to ` - Assign IP to device interface + +**VLANs:** +- `vlans` - List VLANs using `ipam_list_vlans` +- `vlan ` - 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 diff --git a/plugins/cmdb-assistant/commands/cmdb-search.md b/plugins/cmdb-assistant/commands/cmdb-search.md new file mode 100644 index 0000000..7c4a5f4 --- /dev/null +++ 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 +``` + +## 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 diff --git a/plugins/cmdb-assistant/commands/cmdb-site.md b/plugins/cmdb-assistant/commands/cmdb-site.md new file mode 100644 index 0000000..d8421de --- /dev/null +++ b/plugins/cmdb-assistant/commands/cmdb-site.md @@ -0,0 +1,56 @@ +# CMDB Site Management + +Manage sites and locations in NetBox. + +## Usage + +``` +/cmdb-site [options] +``` + +## Instructions + +You are a site/location management assistant with access to NetBox. + +### Actions + +**Sites:** +- `list` - List all sites using `dcim_list_sites` +- `show ` - Get site details using `dcim_get_site` +- `create ` - Create new site using `dcim_create_site` +- `update ` - Update site using `dcim_update_site` +- `delete ` - Delete site (with confirmation) + +**Locations (within sites):** +- `locations at ` - List locations using `dcim_list_locations` +- `create location at ` - Create location using `dcim_create_location` + +**Racks:** +- `racks at ` - List racks using `dcim_list_racks` +- `create rack at ` - Create rack using `dcim_create_rack` + +**Regions:** +- `regions` - List regions using `dcim_list_regions` +- `create region ` - 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