MCP Security AI Server & Guardrailed Tactical Response
Axonwall embeds a native Model Context Protocol (MCP) server—available both over JSON-RPC 2.0 axonwall-mcp stdio and HTTPS/SSE at /api/v1/mcp—so autonomous SOC agents, Antigravity, Claude Code, and the Eluvix Harness Mesh can inspect live telemetry and execute surgical threat containment without ever risking management lockout, shell injection, or unrevoked firewall drift.
1. Disabled-by-Default Master Kill Switch & Scoped Auth
Giving an AI model access to a perimeter firewall demands fail-closed governance. Both the TypeScript controller (getMcpServerStatus()) and the Go kernel daemon (IsMcpSubsystemEnabled()) ship disabled by default (false) in /var/lib/axonwall/mcp-settings.json, with an unconditional process-level kill switch via AXONWALL_DISABLE_MCP=1.
API keys follow the format axw_mcp_<id>_<64hex>. Plaintext secrets are shown once at mint time; only secretHashSha256 is persisted in /var/lib/axonwall/mcp-keys.json. Each key enforces optional allowedSourceCidrs, client TLS certificate SHA-256 pinning (mtlsCertFingerprintSha256), and sliding-window rateLimitPerMinute / maxActiveLeases quotas.
- mcp:telemetry:read
- mcp:pcap:capture
- mcp:ebpf:read
- mcp:ebpf:manage
- mcp:virt:read
- mcp:virt:manage
- mcp:k3s:read
- mcp:k3s:manage
- mcp:nas:read
- mcp:nas:manage
- mcp:traffic:blackhole
- mcp:traffic:shape
- mcp:traffic:redirect
- mcp:fleet:broadcast
- mcp:firewall:write
- mcp:firewall:apply
# Inspect current MCP master switch state, source precedence, and active leases axonwallctl mcp status # Explicitly enable the MCP subsystem (can also be toggled in Web Console at /system/mcp) axonwallctl mcp enable # Immediately flush all tactical leases without disabling the subsystem axonwallctl mcp flush # Emergency disable: blocks all stdio + HTTP/SSE calls and flushes every kernel MCP lease axonwallctl mcp disable
2. Dual-Layer Blast-Radius & Anti-Lockout Guardrails
Even if an AI agent suffers a prompt injection or hallucination, Axonwall enforces three independent safety layers: in TypeScript (packages/axonwall_lib/src/mcp/index.ts), in the privileged Go daemon (apps/axonwalld/engine/mcp_guard.go), and inside the kernel via accept-first @mcp_protected_v4 and @mcp_protected_v6 nftables sets:
- 1. Default-Route & Prefix Blast-Radius Cap: Rejects
0.0.0.0/0and::/0unconditionally, normalizes IPv4-mapped IPv6 bypasses (::ffff:0:0/96), and enforces per-key minimum CIDR prefix lengths (default/24IPv4 and/64IPv6). - 2. Protocol, Loopback, Multicast & VRRP Immunity: Hard-protects
127.0.0.0/8,169.254.0.0/16,224.0.0.0/4(preserving VRRP224.0.0.18),::1/128,fe80::/10, andff00::/8. - 3. Live Posture & Self-Lockout Protection: Dynamically merges live OS NIC addresses with
/etc/axonwall/state.jsonand/var/lib/axonwall/state.jsoninterface IPs, CARP/VRRP VIPs, upstream gateways, HA peers, and the MCP caller's own active source IP. - 4. RFC 1918 Toggle & Management Port Shield: Blocks private East-West ranges (
10/8,172.16/12,192.168/16,100.64/10,fc00::/7) unlessallowInternalRFC1918Targets=true, and forbids blocking, shaping, or redirecting anti-lockout ports2966,22, and9876.
3. Ephemeral TTL-Bound Tactical Leases & Self-Healing Janitor
Tactical AI interventions never mutate /etc/axonwall/firewall.yaml or the primary table inet axonwall ruleset. Instead, McpTrafficManager (engine/mcp_traffic.go) compiles an isolated table inet axonwall_mcp ruleset, pre-validates every transaction via dry-run nft -c -f -, and runs a 10-second background Go janitor that automatically reaps expired leases (with dirty-state retry if a kernel reload transiently fails):
Drops/rejects L3/L4 traffic in inet axonwall_mcp or installs a kernel route_blackhole, immediately severs established C2 sockets via conntrack -D, and optionally broadcasts the block across all connected satellite/Edge nodes.
Allocates a collision-free ClassID (500–9000) to throttle suspected exfiltration bandwidth via Linux tc HTB, inject tarpit delay/jitter/loss via netem, and stamp DSCP codepoints.
Steers only a specific attacker's flows via dnat_honeypot or policy_route toward isolated traps explicitly listed in the key's allowedRedirectTargets allowlist.
Writes TTL-bounded Unbound RPZ overrides (/etc/unbound/unbound.conf.d/mcp-sinkhole.conf) while protecting internal appliance domains, plus strictly bounded BPF captures (max 100 packets / 15s).
4. Persistent Rule Proposals & Mandatory Commit-Confirm
When permanent policy hardening is warranted, mcp_propose_firewall_rule acquires an exclusive state lockfile, validates the rule against FirewallRuleSchema, and stages block/reject rules cleanly ahead of pass rules. If applyImmediately: true is requested (requiring mcp:firewall:apply), axonwalld arms a mandatory 60–600 second Commit-Confirm watchdog (confirmTimeoutSeconds, default 120s) and returns a unique jobId. Unless the agent (or a human operator) confirms reachability via mcp_confirm_apply before the timer expires, the daemon automatically rolls the kernel ruleset and YAML state back to last-known-good.
5. Complete Catalog (16 Resources & 25 Tools) & Audit Chain
Every mutating tool requires structured audit provenance (reason ≥ 10 chars, optional incidentId, MITRE ATT&CK mitreTechniqueId e.g. T1071.001, and confidence). Every allowed, denied, or failed call is appended under lockfile serialization into /var/lib/axonwall/mcp-audit.jsonl with SHA-256 prevHash → entryHash chaining verified continuously by verifyMcpAuditChain().
| MCP Resource URI (16 Total) | Payload Summary & Read Scope |
|---|---|
| axonwall://system/overview | Appliance status, protected posture IPs/ports, and calling key policy limits (mcp:telemetry:read). |
| axonwall://telemetry/interfaces | Live RX/TX bytes, packets, drops, and errors across firewall interfaces (mcp:telemetry:read). |
| axonwall://telemetry/alerts/suricata | Recent Suricata IDS/IPS EVE JSON alerts and protocol anomalies (mcp:telemetry:read). |
| axonwall://telemetry/flows/top | Top active Linux kernel conntrack sessions ranked by byte volume (mcp:telemetry:read). |
| axonwall://firewall/tactical-leases | All active TTL-bounded blackholes, tc shapers, DNAT redirects, and DNS sinkholes (mcp:telemetry:read). |
| axonwall://firewall/ruleset-summary | Redacted summary of declarative firewall rules, NAT mappings, aliases, and QoS (mcp:telemetry:read). |
| axonwall://topology/nastymap | Discovered LAN/OPT hosts, ARP neighbor table, and active Kea DHCP leases (mcp:telemetry:read). |
| axonwall://audit/mcp-trail | Recent SHA-256 hash-chained audit entries plus verifyMcpAuditChain() status. |
| axonwall://ebpf/dataplane | Dual-stack IPv4/IPv6 + 802.1Q/802.1ad VLAN XDP verdict counters, LPM CIDR blocks, SYN-flood PPS shield, and 5-hook BPF-LSM status (mcp:ebpf:read). |
| axonwall://ebpf/bpf-tokens | Linux 6.9+ BPF_TOKEN_CREATE capability report, presets, and active bpffs delegation mounts (mcp:ebpf:read). |
| axonwall://virt/workloads | KVM/QEMU VM & LXC container inventory, IOMMU groups, vnet/TAP XDP telemetry, and LXC token mounts (mcp:virt:read). |
| axonwall://virt/libvirt-domains | Rendered canonical Libvirt Domain XML definitions for all configured KVM/QEMU virtual machines (mcp:virt:read). |
| axonwall://k3s/cluster | K3s control plane status, nodes, pods, Flannel/Cilium eBPF CNI state, UserNS readiness, and OpenEBS PVCs (mcp:k3s:read). |
| axonwall://k3s/etcd-snapshots | Embedded K3s etcd disaster-recovery snapshots (local & S3) with timestamps and sizes (mcp:k3s:read). |
| axonwall://nas/storage-telemetry | OpenZFS pool health, Special VDEVs, encryption key status, ARC/L2ARC hit ratios, ZIL/SLOG sync commits, and ZIO queues (mcp:nas:read). |
| axonwall://security/rootkit-posture | Ring-0 rootkit posture, io_uring rings, trampoline audit, and BPF-LSM denial ring buffer (mcp:ebpf:read). |
| MCP Tool Name (25 Total) | Required Scope | Operational Effect |
|---|---|---|
| mcp_query_flows | mcp:telemetry:read | Filter live /proc/net/nf_conntrack sessions by IP, port, protocol, state, or minBytes. |
| mcp_query_threat_events | mcp:telemetry:read | Search Suricata EVE threat alerts and active SOAR/MCP blocklists. |
| mcp_inspect_host_context | mcp:telemetry:read | 360° single-IP forensics: ARP MAC, DHCP hostname, flows, IDS alerts, and leases. |
| mcp_capture_packet_sample | mcp:pcap:capture | Bounded live BPF packet capture (1–100 packets, 1–15s timeout). |
| mcp_blackhole_traffic | mcp:traffic:blackhole | TTL-bounded nft drop/reject or blackhole route + conntrack -D (+ optional fleet broadcast). |
| mcp_shape_traffic | mcp:traffic:shape | TTL-bounded Linux tc HTB rate limit, netem tarpit delay/loss, and DSCP mark. |
| mcp_redirect_traffic | mcp:traffic:redirect | Attacker-scoped DNAT honeypot or policy-route steering to allowedRedirectTargets. |
| mcp_sinkhole_dns | mcp:traffic:redirect | TTL-bounded Unbound DNS local-zone C2/phishing domain sinkhole. |
| mcp_revert_lease | matching lease scope | Immediately remove a single tactical lease from kernel & Unbound by leaseId. |
| mcp_emergency_clear_all | any traffic scope | Panic flush of all active MCP blackholes, shapers, redirects, and DNS sinkholes. |
| mcp_propose_firewall_rule | mcp:firewall:write | Stage persistent rule into DesiredState; optional Commit-Confirm apply returning jobId. |
| mcp_confirm_apply | mcp:firewall:apply | Confirm jobId within the 60–600s safety window to prevent auto-rollback. |
| mcp_inspect_ebpf_dataplane | mcp:ebpf:read | Inspect unified Ring-0 XDP dual-stack/VLAN/LPM CIDR stats, SYN-flood PPS shield, BPF-LSM hooks, and BPF_TOKEN mounts. |
| mcp_xdp_fast_drop | mcp:ebpf:manage | Line-rate NIC driver XDP_DROP for IPv4/IPv6 hosts & LPM Trie CIDR subnets (block/unblock) plus Ring-0 TCP SYN-flood PPS rate limiter (set_syn_limit, ≥ 100 PPS self-DoS floor). |
| mcp_manage_bpf_token_profile | mcp:ebpf:manage | Mount or delete delegated Linux 6.9+ bpffs profiles (vetoes kprobe/tracepoint/lsm). |
| mcp_inspect_virt_workloads | mcp:virt:read | Inspect QEMU/KVM VMs, LXC containers, IOMMU groups, and vnet/TAP XDP telemetry. |
| mcp_control_virt_workload | mcp:virt:manage | Lifecycle & enterprise VM ops: start, stop, reboot, snapshot, rollback, clone (ZFS zero-copy), live_migrate, backup, restore, qga_interfaces, and export_libvirt_xml. |
| mcp_configure_lxc_bpf_token | mcp:virt:manage | Declaratively bind or revoke safe BPF_TOKEN delegation on an unprivileged LXC container. |
| mcp_inspect_k3s_cluster | mcp:k3s:read | Inspect K3s control plane, nodes, pods, Flannel/Cilium eBPF CNI state, UserNS readiness, and OpenEBS PVCs. |
| mcp_render_k3s_bpf_token_manifest | mcp:k3s:read / manage | Render (and optionally mount) K3s hostUsers: false Pod/DaemonSet YAML with LIBBPF_BPF_TOKEN_PATH. |
| mcp_manage_k3s_cluster | mcp:k3s:read / manage | List, create (etcd_snapshot_save), or restore (etcd_snapshot_restore) embedded K3s etcd snapshots, or switch CNI mode (flannel vs cilium-ebpf) via Commit-Confirm. |
| mcp_inspect_nas_storage | mcp:nas:read | Inspect OpenZFS pools, Special VDEVs, encrypted datasets, shares, ARC/L2ARC hit ratios, ZIL commits, and ZIO queues. |
| mcp_nas_snapshot_or_scrub | mcp:nas:manage | Execute atomic ZFS snapshot, rollback, delete_snapshot, and pool scrub (Root-on-ZFS zroot/rpool protected). |
| mcp_manage_zfs_nas | mcp:nas:manage | Unified enterprise OpenZFS NAS lifecycle tool: trim, pool checkpoint/discard_checkpoint, unlock_dataset/lock_dataset, S.M.A.R.T. smart_test, and encrypted cloud_sync. |
| mcp_import_competitor_config | mcp:firewall:write (+ role scopes) | Dry-run parse or non-destructively stage configs from all 9 vendors (pfSense, OPNsense, Proxmox VE, TrueNAS SCALE, Cisco ASA, VyOS, MikroTik, iptables, firewalld) with cross-role RBAC checks & Commit-Confirm. |
{
"mcpServers": {
"axonwall-ssh-stdio": {
"command": "ssh",
"args": [
"secops@10.0.0.1",
"axonwall-mcp"
],
"env": {
"AXONWALL_MCP_TOKEN": "axw_mcp_7f3a9b_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
},
"axonwall-https": {
"url": "https://10.0.0.1:2966/api/v1/mcp",
"headers": {
"Authorization": "Bearer axw_mcp_7f3a9b_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
}
}
}axw_mcp_* keys, configure honeypot redirect allowlists, inspect countdown timers on active leases, and verify the SHA-256 audit chain in the Web Console at /system/mcp.