# pfsense-mcp

[![CI](https://github.com/ArktechNWA/pfsense-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ArktechNWA/pfsense-mcp/actions/workflows/ci.yml)

A bidirectional AI agent for pfSense. Two components, one package: an MCP server for Claude Code control, and an emergency brain that activates when your network needs help.

**Status:** Planning
**Author:** Claude (claude@arktechnwa.com) + Meldrey
**License:** MIT
**Organization:** [ArktechNWA](https://github.com/ArktechNWA)

---

## Why?

Your AI assistant can help configure firewalls, but it's blind to your network's health. It can't see if your WAN is down, can't check DHCP leases, can't restart a stuck interface.

Worse: when your network breaks, you lose access to your AI assistant entirely.

pfclaude solves both problems:
1. **Normal mode**: Claude Code controls pfSense via MCP — full visibility, full capability
2. **Emergency mode**: When Claude Code is unreachable, pfSense's onboard brain activates — diagnostics, notifications, autonomous recovery

---

## Philosophy

1. **Maximum capability** — Expose everything pfSense can do
2. **User controls exposure** — Checkbox permissions, not hardcoded limits
3. **Maximum availability** — Multiple transport channels, graceful fallbacks
4. **Lightweight emergency brain** — Minimal resource usage, adaptive monitoring
5. **Bidirectional communication** — Email commands work even when network is broken

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code (workstation)                                       │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pfsense-mcp                                                 │ │
│ │  - Full pfSense API passthrough                             │ │
│ │  - All operations: firewall, NAT, DHCP, VPN, logs, etc.     │ │
│ │  - Authenticated over HTTPS                                 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
           ↕ HTTPS + API Key (primary)
           ↕ SSH (fallback)
┌─────────────────────────────────────────────────────────────────┐
│ pfSense Router                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pfClaude Package                                            │ │
│ │                                                             │ │
│ │  NORMAL MODE          │  EMERGENCY MODE                     │ │
│ │  ─────────────        │  ──────────────                     │ │
│ │  API Server           │  Watchdog Daemon                    │ │
│ │  ↕ MCP talks here     │  ↳ Health monitors                  │ │
│ │                       │  ↳ Trigger detection                │ │
│ │  Full pfSense ops     │  ↳ Decision engine                  │ │
│ │  Auth'd requests      │  ↳ Autonomous actions               │ │
│ │                       │  ↳ Notification dispatch            │ │
│ │                       │                                     │ │
│ │  ───────────────────────────────────────────────────────── │ │
│ │  SHARED INFRASTRUCTURE                                      │ │
│ │  • Permission matrix (checkboxes)                           │ │
│ │  • SMTP client (outbound alerts)                            │ │
│ │  • Email parser (inbound commands)                          │ │
│ │  • Cloud beacon (optional status sync)                      │ │
│ │  • Local knowledge base (patterns, history)                 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

---

## Authentication

### API Authentication

Simple, proven security:

```json
{
  "auth": {
    "api_key": "randomly-generated-64-char-key",
    "require_https": true,
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.5"],
    "rate_limit": 100,
    "lockout_threshold": 5,
    "lockout_duration": 900
  }
}
```

- API key transmitted in header: `X-PfClaude-Key: <key>`
- HTTPS required (uses pfSense's existing certificate)
- Optional IP whitelist (only accept from known Claude IPs)
- Rate limiting: 100 requests/min default
- Failed auth lockout: 5 failures → 15 min ban

### Email Authentication

For inbound email commands:

```
Subject: [PFCLAUDE:1234] status
```

- Sender must be in whitelist
- PIN must match configured value
- Timestamp validation (reject if >5min old)
- Rate limit: 10 commands/hour

---

## Trigger Conditions

**Tiered detection with configurable thresholds:**

### Tier 1: Monitoring (always on, ultra-light)

| Check | Description | Default |
|-------|-------------|---------|
| Interface link state | Is the physical link up? | ✓ |
| Heartbeat reception | Has Claude Code checked in? | ✓ |
| Gateway reachability | Can we ping default gateway? | ✓ |
| WAN connectivity | Can we reach external IPs? | ✓ |

### Tier 2: Concern (triggers increased monitoring)

| Check | Description | Default |
|-------|-------------|---------|
| Packet loss > 10% | Network degraded | ✓ |
| Latency spike > 3x | Something's congested | ✓ |
| DNS resolution failing | Name lookups broken | ✓ |
| DHCP not responding | Clients can't get IPs | ✓ |
| Unusual traffic volume | 5x normal (attack? loop?) | ✓ |

### Tier 3: Emergency (activates autonomous response)

| Check | Description | Default |
|-------|-------------|---------|
| LAN interface down | Physical link lost | ✓ |
| N consecutive heartbeat misses | Default: 3 | ✓ |
| Gateway unreachable for N seconds | Default: 60 | ✓ |
| WAN up but LAN unreachable | Asymmetric failure | ✓ |
| All monitored hosts unreachable | Total LAN failure | ✓ |

---

## Health Check Design

**Lightweight, adaptive, CPU-aware:**

```
┌─────────────────────────────────────────────────────────────────┐
│ ADAPTIVE FREQUENCY                                              │
│                                                                 │
│ State: HEALTHY     → Check every 60s                            │
│ State: CONCERNED   → Check every 15s                            │
│ State: DEGRADED    → Check every 5s                             │
│ State: EMERGENCY   → Check every 2s (active response mode)      │
│                                                                 │
│ CPU AWARENESS                                                   │
│ • If system load > 80%, halve check frequency                   │
│ • If memory < 10% free, disable non-critical checks             │
│ • Never consume > 2% CPU for monitoring                         │
│                                                                 │
│ HYSTERESIS                                                      │
│ • Each check returns: OK (0), WARN (1), FAIL (2)                │
│ • Aggregate score determines state transition                   │
│ • Need 3 consecutive same-state readings to transition          │
└─────────────────────────────────────────────────────────────────┘
```

---

## Autonomous Actions

**User configures what pfClaude can do WITHOUT asking:**

### Always Safe (default: enabled)

| Action | Description |
|--------|-------------|
| Log events locally | Always on |
| Send email notification | Alert user |
| Update cloud beacon status | External visibility |
| Capture diagnostic snapshot | Preserve state |

### Diagnostic (default: enabled)

| Action | Description |
|--------|-------------|
| Run connectivity tests | ping, traceroute |
| Capture interface statistics | Counters, errors |
| Gather recent log entries | Context for diagnosis |
| Check service status | What's running/stopped |
| Query ARP/NDP tables | Who's on the network |

### Restorative (default: disabled)

| Action | Description |
|--------|-------------|
| Restart specific interface | Often fixes link issues |
| Flush connection state table | Clears stuck connections |
| Restart DHCP service | Fixes lease issues |
| Restart DNS resolver | Fixes resolution issues |
| Clear ARP cache | Fixes stale entries |
| Restart specific service | Configurable list |

### Failover (default: disabled)

| Action | Description |
|--------|-------------|
| Switch to backup WAN gateway | Major network change |
| Enable/disable interface | Significant impact |
| Apply emergency ruleset | Pre-configured safe rules |
| Trigger CARP failover | HA environments |

### Defensive (default: disabled)

| Action | Description |
|--------|-------------|
| Block IPs exceeding threshold | Anti-DoS |
| Enable emergency rate limiting | Protect resources |
| Activate lockdown ruleset | Maximum security |
| Disable non-essential services | Reduce attack surface |

---

## Local Intelligence

### Pattern Memory

```json
{
  "pattern_memory": {
    "enabled": true,
    "database": "/var/db/pfclaude/patterns.db",
    "max_size_mb": 10,
    "retention_days": 90
  }
}
```

- Stores: "Last time X happened, Y was the cause"
- Learns: "Interface restart fixed this 3/4 times"
- Tracks: Normal baselines (traffic, latency, errors)
- SQLite DB, <10MB footprint

### Haiku Batch Analysis (optional)

```json
{
  "haiku_analysis": {
    "enabled": true,
    "schedule": "0 3 * * *",
    "api_key_env": "PFCLAUDE_ANTHROPIC_KEY",
    "sanitize": ["ip", "mac", "hostname"],
    "max_log_lines": 1000
  }
}
```

- Nightly batch: Send sanitized logs to Anthropic
- Haiku analyzes patterns, anomalies, recommendations
- Results stored locally as "learned insights"
- Cost: ~$0.01/day for typical home network

---

## Notification Channels

**User configures their own escalation paths:**

```json
{
  "notifications": {
    "email": {
      "enabled": true,
      "smtp_server": "smtp.gmail.com",
      "smtp_port": 587,
      "username_env": "SMTP_USER",
      "password_env": "SMTP_PASS",
      "recipients": ["you@example.com"]
    },
    "pushover": {
      "enabled": false,
      "api_key_env": "PUSHOVER_KEY",
      "user_key_env": "PUSHOVER_USER"
    },
    "webhook": {
      "enabled": false,
      "url": "https://your-service.com/webhook",
      "headers": {"Authorization": "Bearer xxx"}
    },
    "telegram": {
      "enabled": false,
      "bot_token_env": "TELEGRAM_TOKEN",
      "chat_id": "123456789"
    },
    "cloud_beacon": {
      "enabled": false,
      "url": "https://your-beacon.com/status",
      "shared_secret_env": "BEACON_SECRET"
    }
  }
}
```

### Escalation Levels

| Level | Actions |
|-------|---------|
| INFO | Log only |
| NOTICE | Log + cloud beacon |
| WARNING | Log + cloud + email |
| CRITICAL | Log + cloud + email + push + webhook |
| EMERGENCY | ALL channels + repeated alerts until ack'd |

---

## Email Commands

**When WAN works but LAN doesn't, email becomes the control channel:**

### Command Format

```
To: pfclaude@your-pfsense.com
Subject: [PFCLAUDE:1234] status
Body: (optional context)
```

### Available Commands

| Command | Description |
|---------|-------------|
| `status` | Current state summary |
| `changes <N>m` | What changed in last N minutes |
| `logs <N>` | Last N log lines |
| `diagnose` | Run full diagnostic suite |
| `restart <iface>` | Restart interface (if permitted) |
| `help` | List available commands |

### Example Response

```
Subject: Re: [PFCLAUDE:1234] status

pfClaude Status Report
Generated: 2025-12-29 15:42:00 UTC

SYSTEM: DEGRADED (score: 4/10)

Interfaces:
  WAN  (igb0): UP - 98.2.1.45 - 12ms latency
  LAN  (igb1): UP - 192.168.1.1 - NO TRAFFIC 5min  ← Problem
  OPT1 (igb2): DOWN - disabled

Recent Events:
  15:37 - LAN traffic dropped to zero
  15:38 - DHCP requests stopped
  15:40 - Watchdog entered CONCERNED state

Recommended: Check switch connectivity to LAN port
```

---

## Cloud Beacon (optional)

**For checking router status from anywhere:**

```json
{
  "cloud_beacon": {
    "enabled": true,
    "url": "https://your-beacon-server.com/api/beacon",
    "router_id": "home-pfsense",
    "shared_secret_env": "BEACON_SECRET",
    "frequency_healthy": 60,
    "frequency_degraded": 15
  }
}
```

### Self-Hosted Option

Docker image provided for running your own beacon receiver:

```bash
docker run -d -p 8080:8080 \
  -e BEACON_SECRET=your-secret \
  arktechnwa/pfclaude-beacon
```

Features:
- Receives status beacons from pfSense
- Stores recent logs (configurable retention)
- Web dashboard for status checks
- Can relay commands back to pfSense

### Beacon Protocol

```json
POST /beacon
{
  "router_id": "home-pfsense",
  "timestamp": "2025-12-29T15:42:00Z",
  "state": "healthy",
  "score": 9,
  "interfaces": {
    "wan": {"status": "up", "ip": "98.2.1.45", "latency_ms": 12},
    "lan": {"status": "up", "ip": "192.168.1.1", "clients": 15}
  },
  "recent_events": [],
  "hmac": "..."
}
```

Payload: <2KB, designed for minimal bandwidth.

---

## MCP Tools

**EVERYTHING pfSense can do, exposed via MCP:**

### System

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_system_info` | Hostname, version, uptime, resources | read |
| `pf_system_status` | Overall health summary | read |
| `pf_system_reboot` | Reboot pfSense | dangerous |
| `pf_system_shutdown` | Shutdown pfSense | dangerous |
| `pf_system_config_backup` | Export config XML | read |

### Interfaces

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_interface_list` | All interfaces with status | read |
| `pf_interface_status` | Detailed status for one | read |
| `pf_interface_stats` | Traffic counters, errors | read |
| `pf_interface_restart` | Restart interface | service |
| `pf_interface_enable` | Enable interface | config |
| `pf_interface_disable` | Disable interface | config |

### Firewall

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_firewall_rules` | List rules (filter, nat, etc) | read |
| `pf_firewall_rule_add` | Add rule | config |
| `pf_firewall_rule_delete` | Delete rule | config |
| `pf_firewall_rule_modify` | Modify rule | config |
| `pf_firewall_states` | Connection state table | read |
| `pf_firewall_states_flush` | Clear state table | service |
| `pf_firewall_aliases` | Manage aliases | config |

### NAT

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_nat_rules` | Port forwards, outbound NAT | read |
| `pf_nat_rule_add` | Add NAT rule | config |
| `pf_nat_rule_delete` | Delete NAT rule | config |
| `pf_nat_rule_modify` | Modify NAT rule | config |

### DHCP

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_dhcp_leases` | Current leases | read |
| `pf_dhcp_static_mappings` | Reserved IPs | read |
| `pf_dhcp_config` | DHCP server config | config |
| `pf_dhcp_service_restart` | Restart DHCP | service |

### DNS

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_dns_resolver_config` | Unbound config | config |
| `pf_dns_forwarder_config` | dnsmasq config | config |
| `pf_dns_override_add` | Add host override | config |
| `pf_dns_override_delete` | Delete host override | config |
| `pf_dns_service_restart` | Restart DNS | service |

### VPN

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_vpn_openvpn_status` | OpenVPN connections | read |
| `pf_vpn_ipsec_status` | IPsec SAs | read |
| `pf_vpn_wireguard_status` | WireGuard peers | read |
| `pf_vpn_disconnect` | Disconnect client/tunnel | service |

### Routing

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_routes_table` | Routing table | read |
| `pf_routes_static` | Static routes | config |
| `pf_gateway_status` | Gateway health | read |
| `pf_gateway_switch` | Switch default gateway | config |

### Traffic

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_traffic_graphs` | Bandwidth graphs data | read |
| `pf_traffic_totals` | Interface totals | read |
| `pf_traffic_top` | Top talkers | read |

### Logs

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_logs_system` | System logs | read |
| `pf_logs_firewall` | Firewall logs | read |
| `pf_logs_dhcp` | DHCP logs | read |
| `pf_logs_vpn` | VPN logs | read |
| `pf_logs_search` | Search across all logs | read |

### Packages

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_packages_installed` | Installed packages | read |
| `pf_packages_available` | Available packages | read |
| `pf_packages_install` | Install package | dangerous |
| `pf_packages_remove` | Remove package | dangerous |

### Services

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_services_list` | All services status | read |
| `pf_services_start` | Start service | service |
| `pf_services_stop` | Stop service | service |
| `pf_services_restart` | Restart service | service |

### Diagnostics

| Tool | Description | Permission |
|------|-------------|------------|
| `pf_diag_ping` | Ping from pfSense | read |
| `pf_diag_traceroute` | Traceroute from pfSense | read |
| `pf_diag_dns_lookup` | DNS lookup from pfSense | read |
| `pf_diag_arp_table` | ARP table | read |
| `pf_diag_ndp_table` | IPv6 neighbor table | read |
| `pf_diag_sockets` | Open sockets | read |
| `pf_diag_pftop` | Real-time state table | read |

---

## Permission Matrix

**Granular control via pfSense WebGUI:**

### Permission Levels

| Level | Description |
|-------|-------------|
| `read` | View status, logs, configuration |
| `service` | Restart services, flush caches |
| `config` | Modify configuration |
| `dangerous` | Reboot, shutdown, package management |

### WebGUI Configuration

```
┌─────────────────────────────────────────────────────────────────┐
│ pfClaude > Settings > Permissions                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ MCP API Permissions                                             │
│ ─────────────────────────────────────────────────────────────── │
│                                                                 │
│ READ OPERATIONS                          [Select All] [Clear]   │
│ ☑ System info & status                                         │
│ ☑ Interface status & stats                                     │
│ ☑ Firewall rules (view)                                        │
│ ☑ DHCP leases                                                  │
│ ☑ Logs (all)                                                   │
│ ☑ Diagnostics (ping, traceroute, etc)                          │
│                                                                 │
│ SERVICE CONTROL                          [Select All] [Clear]   │
│ ☐ Restart interfaces                                           │
│ ☐ Restart services (DHCP, DNS, etc)                            │
│ ☐ Flush state table                                            │
│ ☐ Clear caches                                                 │
│                                                                 │
│ CONFIGURATION CHANGES                    [Select All] [Clear]   │
│ ☐ Modify firewall rules                                        │
│ ☐ Modify NAT rules                                             │
│ ☐ Modify DHCP settings                                         │
│ ☐ Add/remove static routes                                     │
│                                                                 │
│ DANGEROUS OPERATIONS                     [Select All] [Clear]   │
│ ☐ System reboot                                                │
│ ☐ System shutdown                                              │
│ ☐ Install/remove packages                                      │
│ ☐ Gateway failover                                             │
│                                                                 │
│ ─────────────────────────────────────────────────────────────── │
│ ☐ BYPASS ALL PERMISSIONS (danger mode)                         │
│                                                                 │
│                                    [Save] [Reset to Defaults]   │
└─────────────────────────────────────────────────────────────────┘
```

---

## Storage & Hygiene

```json
{
  "storage": {
    "email_queue": {
      "max_messages": 100,
      "max_age_days": 10,
      "cleanup_schedule": "0 4 * * *"
    },
    "logs": {
      "pfclaude_events_days": 7,
      "diagnostic_snapshots_days": 3
    },
    "pattern_memory": {
      "persistent": true,
      "compact_schedule": "0 5 * * 0"
    },
    "total_footprint_mb": 50
  }
}
```

---

## Installation

### pfSense Package

```
System > Package Manager > Available Packages > pfClaude
```

Or manual:
```bash
pkg add https://github.com/ArktechNWA/pfsense-mcp/releases/latest/pfsense.pkg
```

### MCP Server (Claude Code side)

```bash
npm install -g @arktechnwa/pfsense-mcp
```

### Claude Code Integration

```json
{
  "mcpServers": {
    "pfsense": {
      "command": "pfsense-mcp",
      "env": {
        "PFSENSE_HOST": "192.168.1.1",
        "PFSENSE_API_KEY": "your-api-key"
      }
    }
  }
}
```

---

## Requirements

### pfSense Side
- pfSense 2.7+ or pfSense Plus 23.09+
- 50MB free storage
- Network connectivity (obviously)

### Claude Code Side
- Node.js 18+
- Network access to pfSense

### Optional
- Anthropic API key (for Haiku batch analysis)
- SMTP server (for email notifications)
- Self-hosted beacon server (for cloud status)

---

## Security Considerations

1. **API key authentication** — No unauthenticated access
2. **HTTPS required** — Encrypted transport
3. **IP whitelist** — Restrict to known Claude IPs
4. **Rate limiting** — Prevent brute force
5. **Email PIN** — Authenticate inbound commands
6. **Permission matrix** — User controls exposure
7. **Audit logging** — All actions logged
8. **No default dangerous permissions** — User must enable

---

## Credits

Created by Claude (claude@arktechnwa.com) in collaboration with Meldrey.
Part of the [ArktechNWA MCP Toolshed](https://github.com/ArktechNWA).

Built because your firewall should be able to call for help when it needs it.