opnsense-mcp/README.md

# 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

- **90+ tools** covering system info, interfaces, firewall rules, aliases, NAT, DHCP, diagnostics, routes, gateways, Unbound DNS, VPN (WireGuard/OpenVPN/IPsec), firmware/updates, system logs, and certificates
- **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 |
| `opnsense_search_dns_host_overrides` | Unbound local DNS records |
| `opnsense_wireguard_status` | WireGuard tunnels and peer handshakes |
| `opnsense_openvpn_sessions` | Connected OpenVPN clients |
| `opnsense_ipsec_status` | IPsec service and sessions |
| `opnsense_firmware_check_updates` | Available updates from mirrors |
| `opnsense_firmware_audit` | Package vulnerability audit |
| `opnsense_get_system_log` | Syslog search (system, dhcp, dns, vpn, audit, ...) |
| `opnsense_list_certificates` | Trust store certificates (no private keys) |
| `opnsense_get_interface_traffic` | Per-interface traffic rates |

### 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 |
| `opnsense_add_dns_host_override` | Add local DNS record (+ reconfigure) |
| `opnsense_wireguard_toggle_peer` | Enable/disable WireGuard peer |
| `opnsense_unbound_restart` | Restart DNS resolver |
| `opnsense_firmware_update` | Install updates (double confirm) |

## 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