MCP OPNsense Diagnostics

Read-only diagnostic MCP server for OPNsense firewall. Safe mode is ON by default. AI cannot disable safe mode under any circumstances — only the user controls this.

Architecture

src/
├── index.ts              # Orchestration only: init -> preflight -> register -> connect
├── config.ts             # 12-Factor config from env vars + CLI flag
├── client.ts             # I/O adapter: OPNsense API via node:http/node:https
├── safe-mode.ts          # Policy gate — user-only control, AI can only re-enable
├── policy.ts             # Centralized policy enforcement (safe mode + SSRF reduction)
├── helpers.ts            # Shared MCP response formatting + error handling
├── rate-limiter.ts       # Sliding-window request throttling
├── types/opnsense.ts     # TypeScript interfaces
└── tools/
    ├── system.ts
    ├── interfaces.ts
    ├── firewall.ts
    ├── vpn.ts
    ├── dns-dhcp.ts
    ├── routing.ts
    ├── diagnostics.ts
    └── safe-mode-tool.ts

Local Development

If you only want to use the published MCP server, you do not need a local install. Use the npx configs below.

npm install
npm run build

Configuration

| Variable / Flag | Required | Default | Description | |---|---|---|---| | OPNSENSE_HOST | Yes | - | OPNsense URL, should be https://... | | OPNSENSE_API_KEY | Yes | - | API key from System > User Management | | OPNSENSE_API_SECRET | Yes | - | API secret | | OPNSENSE_SKIP_TLS_VERIFY | No | false | Disable cert verification for self-signed certs | | OPNSENSE_SAFE_MODE | No | true | User-controlled safe mode. Set to false to allow active diagnostics | | OPNSENSE_TIMEOUT | No | 30000 | API request timeout in milliseconds | | --allow-active | No | - | CLI flag — shortcut to disable safe mode without changing env vars |

How to Toggle Safe Mode

วิธีที่ 1: CLI flag --allow-active (แนะนำ — ง่ายที่สุด)

เพิ่ม --allow-active ใน args ของ Claude Desktop config เมื่อต้องการให้ AI ใช้ active diagnostics ได้:

// ✅ Active mode — AI สามารถ ping / traceroute / DNS lookup ได้
{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "mcp-opnsense-diagnostics", "--allow-active"],
      "env": {
        "OPNSENSE_HOST": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your_key",
        "OPNSENSE_API_SECRET": "your_secret"
      }
    }
  }
}

เอา --allow-active ออกแล้ว restart ก็กลับเป็น safe mode อัตโนมัติ

วิธีที่ 2: Environment variable

// Safe mode OFF ผ่าน env var
"env": {
  "OPNSENSE_SAFE_MODE": "false",
  ...
}

วิธีที่ 3: Dual profile (สลับโปรไฟล์ไม่ต้องแก้ config)

ตั้ง 2 server ใน Claude Desktop config แล้วเลือกใช้ตัวที่ต้องการ:

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "mcp-opnsense-diagnostics"],
      "env": {
        "OPNSENSE_HOST": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your_key",
        "OPNSENSE_API_SECRET": "your_secret"
      }
    },
    "opnsense-active": {
      "command": "npx",
      "args": ["-y", "mcp-opnsense-diagnostics", "--allow-active"],
      "env": {
        "OPNSENSE_HOST": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your_key",
        "OPNSENSE_API_SECRET": "your_secret"
      }
    }
  }
}

• ใช้ opnsense → safe mode เปิด (ตรวจสอบ/รายงานเท่านั้น)
• ใช้ opnsense-active → safe mode ปิด (AI สามารถ ping/traceroute/DNS ได้)

Security Features

| Feature | Description | |---|---| | Safe mode | ON by default; blocks active diagnostics | | User-only control | AI cannot disable safe mode. Only the user can via --allow-active flag or OPNSENSE_SAFE_MODE=false env var before server start | | AI re-lock | AI can re-enable safe mode (escalate to stricter) but never disable it | | Per-request TLS | Uses node:https request options; no global NODE_TLS_REJECT_UNAUTHORIZED mutation | | Rate limiting | Max 10 API requests per 60 seconds | | Path validation | Endpoints must start with /api/ and cannot contain .. | | Error sanitization | HTML stripped, whitespace normalized, truncated to 200 chars | | SSRF reduction | Blocks localhost, private IP ranges, bracketed IPv6, encoded numeric hosts | | Audit logging | Safe mode state changes logged to stderr with timestamps | | Preflight check | API connectivity verified before accepting MCP connections |

Operating Model

• Default mode is inspect/report only. AI diagnoses issues, explains likely causes, and suggests remediation steps for the user to carry out.
• AI cannot disable safe mode. There is no tool action, token, or command that allows it.
• If the user wants AI to run active diagnostics, use one of the three methods above (CLI flag, env var, or dual profile).
• AI can re-enable safe mode via opn_safe_mode action=enable to return to strict read-only mode.
• Once re-enabled by AI, safe mode stays on until the user restarts with active mode again.

Available Tools

• System: opn_system_health, opn_system_services, opn_firmware_status, opn_firmware_info
• Interfaces: opn_interface_config, opn_interface_stats, opn_arp_table, opn_ndp_table, opn_vip_status, opn_memory_stats
• Firewall: opn_firewall_log, opn_firewall_states, opn_firewall_stats, opn_firewall_rules
• VPN: opn_vpn_openvpn_sessions, opn_vpn_wireguard_status, opn_vpn_ipsec_phase1, opn_vpn_ipsec_phase2, opn_vpn_ipsec_connections
• DNS/DHCP: opn_dns_unbound_stats, opn_dns_unbound_cache, opn_dhcp_v4_leases, opn_dhcp_v6_leases
• Routing: opn_routing_table, opn_gateway_status
• Active diagnostics: opn_diag_ping, opn_diag_traceroute, opn_diag_dns_lookup, opn_connection_check
• Safe mode: opn_safe_mode (status, enable)

opnsense