151 lines
4.9 KiB
Markdown
151 lines
4.9 KiB
Markdown
# OPNsense MCP
|
||
|
||
Model Context Protocol server for [OPNsense](https://opnsense.org/) firewall management. Designed for use with [Hermes Agent](https://github.com/NousResearch/hermes-agent) and any MCP-compatible client.
|
||
|
||
## Features
|
||
|
||
- **60+ tools** covering system info, interfaces, firewall rules, aliases, NAT, DHCP, diagnostics, routes, and gateways
|
||
- **Safety guardrails**: write operations disabled by default, dry-run mode, WAN rule blocking, required description prefix
|
||
- **Savepoint workflow**: create savepoint → apply → cancel rollback (matches OPNsense official API pattern)
|
||
- **Audit logging**: all mutations logged to JSONL
|
||
|
||
## Quick Start
|
||
|
||
### 1. Create an OPNsense API key
|
||
|
||
In OPNsense: **System → Access → Users** → edit user → add API key. Download the key/secret pair.
|
||
|
||
Grant only the privileges needed. For read-only use, limit to read privileges. For writes, include firewall, aliases, routes, etc.
|
||
|
||
### 2. Install
|
||
|
||
```bash
|
||
pip install -e /path/to/opnsense-mcp
|
||
```
|
||
|
||
Or with the Hermes venv:
|
||
|
||
```bash
|
||
/usr/local/lib/hermes-agent/venv/bin/pip install -e /root/opnsense-mcp
|
||
```
|
||
|
||
### 3. Configure environment
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# Edit .env with your API key, secret, and firewall URL
|
||
```
|
||
|
||
| Variable | Default | Description |
|
||
|----------|---------|-------------|
|
||
| `OPNSENSE_URL` | `https://10.77.30.1:40443` | Firewall base URL |
|
||
| `OPNSENSE_API_KEY` | — | API key (required) |
|
||
| `OPNSENSE_API_SECRET` | — | API secret (required) |
|
||
| `OPNSENSE_VERIFY_SSL` | `false` | Verify TLS certificate |
|
||
| `OPNSENSE_ALLOW_WRITES` | `false` | Enable mutating operations |
|
||
| `OPNSENSE_DRY_RUN` | `false` | Log writes without executing |
|
||
| `OPNSENSE_REQUIRE_DESCRIPTION_PREFIX` | `mcp:` | Prefix for new firewall rules |
|
||
| `OPNSENSE_BLOCK_WAN_INBOUND_ANY` | `true` | Block WAN allow-all rules |
|
||
|
||
### 4. Register with Hermes
|
||
|
||
```bash
|
||
hermes mcp add opnsense \
|
||
--command /usr/local/lib/hermes-agent/venv/bin/opnsense-mcp \
|
||
--env OPNSENSE_URL=https://10.77.30.1:40443 \
|
||
--env OPNSENSE_API_KEY=your_key \
|
||
--env OPNSENSE_API_SECRET=your_secret \
|
||
--env OPNSENSE_VERIFY_SSL=false \
|
||
--env OPNSENSE_ALLOW_WRITES=false
|
||
```
|
||
|
||
Or add to `~/.hermes/config.yaml`:
|
||
|
||
```yaml
|
||
mcp_servers:
|
||
opnsense:
|
||
command: "/usr/local/lib/hermes-agent/venv/bin/opnsense-mcp"
|
||
env:
|
||
OPNSENSE_URL: "https://10.77.30.1:40443"
|
||
OPNSENSE_API_KEY: "your_key"
|
||
OPNSENSE_API_SECRET: "your_secret"
|
||
OPNSENSE_VERIFY_SSL: "false"
|
||
OPNSENSE_ALLOW_WRITES: "false"
|
||
timeout: 120
|
||
```
|
||
|
||
Restart the Hermes gateway after adding.
|
||
|
||
### 5. Test
|
||
|
||
```bash
|
||
hermes mcp test opnsense
|
||
```
|
||
|
||
Or ask Hermes: *"Use opnsense_test_connection to verify firewall access"*
|
||
|
||
## Tool Categories
|
||
|
||
### Read-only (always available with valid API key)
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `opnsense_test_connection` | Verify API auth and connectivity |
|
||
| `opnsense_get_system_info` | Version, uptime, health |
|
||
| `opnsense_list_interfaces` | Interface status and IPs |
|
||
| `opnsense_search_firewall_rules` | Search filter rules |
|
||
| `opnsense_search_aliases` | Search aliases |
|
||
| `opnsense_search_dhcp_leases` | DHCP lease table |
|
||
| `opnsense_get_arp_table` | ARP / IP→MAC |
|
||
| `opnsense_get_gateway_status` | WAN gateway health |
|
||
| `opnsense_get_firewall_log` | Recent blocked/ passed traffic |
|
||
| `opnsense_get_pf_states` | Active connection states |
|
||
| `opnsense_search_port_forwards` | Port forward rules |
|
||
|
||
### Write operations (require `OPNSENSE_ALLOW_WRITES=true`)
|
||
|
||
| Tool | Description |
|
||
|------|-------------|
|
||
| `opnsense_add_firewall_rule` | Add filter rule (prefix required) |
|
||
| `opnsense_toggle_firewall_rule` | Enable/disable rule |
|
||
| `opnsense_create_firewall_savepoint` | Snapshot before changes |
|
||
| `opnsense_apply_firewall` | Apply pending changes |
|
||
| `opnsense_cancel_firewall_rollback` | Confirm changes (cancel 60s rollback) |
|
||
| `opnsense_safe_apply_firewall_rule_change` | Savepoint + toggle + apply workflow |
|
||
| `opnsense_alias_add_entry` | Add IP to alias |
|
||
| `opnsense_add_d_nat_rule` | Add port forward |
|
||
|
||
## Safe Change Workflow
|
||
|
||
```text
|
||
1. opnsense_create_firewall_savepoint → returns revision
|
||
2. opnsense_toggle_firewall_rule(uuid) → make change
|
||
3. opnsense_apply_firewall(revision) → apply with 60s auto-rollback
|
||
4. Verify connectivity
|
||
5. opnsense_cancel_firewall_rollback(revision) → keep change
|
||
```
|
||
|
||
Or use `opnsense_safe_apply_firewall_rule_change` which combines steps 1–3.
|
||
|
||
## Standalone Usage
|
||
|
||
Run directly as an MCP stdio server:
|
||
|
||
```bash
|
||
OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... opnsense-mcp
|
||
```
|
||
|
||
Compatible with Cursor, Claude Desktop, and other MCP clients.
|
||
|
||
## Security Notes
|
||
|
||
- Never commit API keys. Use environment variables or Hermes secrets.
|
||
- Start with read-only (`ALLOW_WRITES=false`) until you trust the agent workflows.
|
||
- Use a dedicated OPNsense user with minimal privileges.
|
||
- Review audit log at `OPNSENSE_AUDIT_LOG_PATH`.
|
||
- Enable Hermes `approvals: mode: manual` for production use.
|
||
|
||
## License
|
||
|
||
MIT
|