Model Context Protocol (MCP) • Guardrailed Kernel SecOps

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.

SHA-256 Hashed Bearer Keys & mTLS Pinning

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.

16 Granular Capability Scopes (5 Duties)
  • 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
Master Kill Switch & Emergency Lease Flush via axonwallctl
bash
# 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/0 and ::/0 unconditionally, normalizes IPv4-mapped IPv6 bypasses (::ffff:0:0/96), and enforces per-key minimum CIDR prefix lengths (default /24 IPv4 and /64 IPv6).
  • 2. Protocol, Loopback, Multicast & VRRP Immunity: Hard-protects 127.0.0.0/8, 169.254.0.0/16, 224.0.0.0/4 (preserving VRRP 224.0.0.18), ::1/128, fe80::/10, and ff00::/8.
  • 3. Live Posture & Self-Lockout Protection: Dynamically merges live OS NIC addresses with /etc/axonwall/state.json and /var/lib/axonwall/state.json interface 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) unless allowInternalRFC1918Targets=true, and forbids blocking, shaping, or redirecting anti-lockout ports 2966, 22, and 9876.

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):

mcp_blackhole_traffic

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.

mcp_shape_traffic

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.

mcp_redirect_traffic

Steers only a specific attacker's flows via dnat_honeypot or policy_route toward isolated traps explicitly listed in the key's allowedRedirectTargets allowlist.

mcp_sinkhole_dns & mcp_capture_packet_sample

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/overviewAppliance status, protected posture IPs/ports, and calling key policy limits (mcp:telemetry:read).
axonwall://telemetry/interfacesLive RX/TX bytes, packets, drops, and errors across firewall interfaces (mcp:telemetry:read).
axonwall://telemetry/alerts/suricataRecent Suricata IDS/IPS EVE JSON alerts and protocol anomalies (mcp:telemetry:read).
axonwall://telemetry/flows/topTop active Linux kernel conntrack sessions ranked by byte volume (mcp:telemetry:read).
axonwall://firewall/tactical-leasesAll active TTL-bounded blackholes, tc shapers, DNAT redirects, and DNS sinkholes (mcp:telemetry:read).
axonwall://firewall/ruleset-summaryRedacted summary of declarative firewall rules, NAT mappings, aliases, and QoS (mcp:telemetry:read).
axonwall://topology/nastymapDiscovered LAN/OPT hosts, ARP neighbor table, and active Kea DHCP leases (mcp:telemetry:read).
axonwall://audit/mcp-trailRecent SHA-256 hash-chained audit entries plus verifyMcpAuditChain() status.
axonwall://ebpf/dataplaneDual-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-tokensLinux 6.9+ BPF_TOKEN_CREATE capability report, presets, and active bpffs delegation mounts (mcp:ebpf:read).
axonwall://virt/workloadsKVM/QEMU VM & LXC container inventory, IOMMU groups, vnet/TAP XDP telemetry, and LXC token mounts (mcp:virt:read).
axonwall://virt/libvirt-domainsRendered canonical Libvirt Domain XML definitions for all configured KVM/QEMU virtual machines (mcp:virt:read).
axonwall://k3s/clusterK3s control plane status, nodes, pods, Flannel/Cilium eBPF CNI state, UserNS readiness, and OpenEBS PVCs (mcp:k3s:read).
axonwall://k3s/etcd-snapshotsEmbedded K3s etcd disaster-recovery snapshots (local & S3) with timestamps and sizes (mcp:k3s:read).
axonwall://nas/storage-telemetryOpenZFS pool health, Special VDEVs, encryption key status, ARC/L2ARC hit ratios, ZIL/SLOG sync commits, and ZIO queues (mcp:nas:read).
axonwall://security/rootkit-postureRing-0 rootkit posture, io_uring rings, trampoline audit, and BPF-LSM denial ring buffer (mcp:ebpf:read).
MCP Tool Name (25 Total)Required ScopeOperational Effect
mcp_query_flowsmcp:telemetry:readFilter live /proc/net/nf_conntrack sessions by IP, port, protocol, state, or minBytes.
mcp_query_threat_eventsmcp:telemetry:readSearch Suricata EVE threat alerts and active SOAR/MCP blocklists.
mcp_inspect_host_contextmcp:telemetry:read360° single-IP forensics: ARP MAC, DHCP hostname, flows, IDS alerts, and leases.
mcp_capture_packet_samplemcp:pcap:captureBounded live BPF packet capture (1–100 packets, 1–15s timeout).
mcp_blackhole_trafficmcp:traffic:blackholeTTL-bounded nft drop/reject or blackhole route + conntrack -D (+ optional fleet broadcast).
mcp_shape_trafficmcp:traffic:shapeTTL-bounded Linux tc HTB rate limit, netem tarpit delay/loss, and DSCP mark.
mcp_redirect_trafficmcp:traffic:redirectAttacker-scoped DNAT honeypot or policy-route steering to allowedRedirectTargets.
mcp_sinkhole_dnsmcp:traffic:redirectTTL-bounded Unbound DNS local-zone C2/phishing domain sinkhole.
mcp_revert_leasematching lease scopeImmediately remove a single tactical lease from kernel & Unbound by leaseId.
mcp_emergency_clear_allany traffic scopePanic flush of all active MCP blackholes, shapers, redirects, and DNS sinkholes.
mcp_propose_firewall_rulemcp:firewall:writeStage persistent rule into DesiredState; optional Commit-Confirm apply returning jobId.
mcp_confirm_applymcp:firewall:applyConfirm jobId within the 60–600s safety window to prevent auto-rollback.
mcp_inspect_ebpf_dataplanemcp:ebpf:readInspect unified Ring-0 XDP dual-stack/VLAN/LPM CIDR stats, SYN-flood PPS shield, BPF-LSM hooks, and BPF_TOKEN mounts.
mcp_xdp_fast_dropmcp:ebpf:manageLine-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_profilemcp:ebpf:manageMount or delete delegated Linux 6.9+ bpffs profiles (vetoes kprobe/tracepoint/lsm).
mcp_inspect_virt_workloadsmcp:virt:readInspect QEMU/KVM VMs, LXC containers, IOMMU groups, and vnet/TAP XDP telemetry.
mcp_control_virt_workloadmcp:virt:manageLifecycle & 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_tokenmcp:virt:manageDeclaratively bind or revoke safe BPF_TOKEN delegation on an unprivileged LXC container.
mcp_inspect_k3s_clustermcp:k3s:readInspect K3s control plane, nodes, pods, Flannel/Cilium eBPF CNI state, UserNS readiness, and OpenEBS PVCs.
mcp_render_k3s_bpf_token_manifestmcp:k3s:read / manageRender (and optionally mount) K3s hostUsers: false Pod/DaemonSet YAML with LIBBPF_BPF_TOKEN_PATH.
mcp_manage_k3s_clustermcp:k3s:read / manageList, 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_storagemcp:nas:readInspect OpenZFS pools, Special VDEVs, encrypted datasets, shares, ARC/L2ARC hit ratios, ZIL commits, and ZIO queues.
mcp_nas_snapshot_or_scrubmcp:nas:manageExecute atomic ZFS snapshot, rollback, delete_snapshot, and pool scrub (Root-on-ZFS zroot/rpool protected).
mcp_manage_zfs_nasmcp:nas:manageUnified 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_configmcp: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.
Connecting Antigravity, Claude Code, or Eluvix Harness Mesh (stdio & HTTP/SSE)
json
{
  "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"
      }
    }
  }
}
Manage Scoped Keys, Live Leases & Hash-Chained Audit Logs
Mint scoped 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.