Initial import from Proxmox host
This commit is contained in:
Hermes CT107
150
README.md
Normal file
150
README.md
Normal file
@@ -0,0 +1,150 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user