test/VaultMesh_Catalog_v1/files/README-mcp.md

IoTek.nexus + offsec-mcp

The Veil becomes infrastructure.

A real control surface for VaultMesh sovereign infrastructure.

┌─────────────────────────────────────────────────────────────────────────────┐
│ IoTek.nexus                    ● MESH 7  ● SHIELD ARMED  ● WS LIVE   12:34  │
├────────────────────┬────────────────────────────────────────────────────────┤
│                    │                                                        │
│   [Console]        │   sovereign@nexus ~/vaultmesh $ status                │
│                    │                                                        │
│   ↓ HTTP POST      │     ╦  ╦╔═╗╦ ╦╦ ╔╦╗╔╦╗╔═╗╔═╗╦ ╦                       │
│                    │     ╚╗╔╝╠═╣║ ║║  ║ ║║║║╣ ╚═╗╠═╣                       │
│   [offsec-mcp]     │      ╚╝ ╩ ╩╚═╝╩═╝╩ ╩ ╩╚═╝╚═╝╩ ╩                       │
│                    │                                                        │
│   ↓ WebSocket      │     Shield:  ● ARMED                                  │
│                    │     Proof:   ● 1247 receipts                          │
│   [Live Updates]   │     Mesh:    ● 7 nodes                                │
│                    │                                                        │
└────────────────────┴────────────────────────────────────────────────────────┘

---

Quick Start

1. Install dependencies

pip install -r requirements-mcp.txt

2. Start the backend

# Development (auto-reload)
uvicorn offsec_mcp:app --reload --port 8080

# Production (bind to Tailscale IP only)
uvicorn offsec_mcp:app --host 100.x.x.x --port 8080

3. Open the console

# Option A: Open the HTML directly
open iotek-nexus-live.html

# Option B: Serve via backend (configure STATIC_DIR in offsec_mcp.py)
# Then visit http://localhost:8080/

---

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        CONSOLE LAYER                              │
│  iotek-nexus-live.html                                           │
│  - Local commands (help, clear, history, whoami, neofetch)       │
│  - MCP backend calls (status, mesh, shield, proof, agents)       │
│  - WebSocket live updates                                        │
│  - Mock fallback when backend unavailable                        │
└───────────────────────────┬──────────────────────────────────────┘
                            │
                            │ HTTP POST /mcp/command
                            │ WebSocket /ws
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│                       BACKEND LAYER                               │
│  offsec_mcp.py (FastAPI)                                         │
│  - Command routing & execution                                   │
│  - Tailscale identity extraction                                 │
│  - SQLite persistence (sessions, commands, events)               │
│  - WebSocket broadcast for live updates                          │
└───────────────────────────┬──────────────────────────────────────┘
                            │
                            │ subprocess / API calls
                            ▼
┌──────────────────────────────────────────────────────────────────┐
│                       SYSTEM LAYER                                │
│  - Tailscale (mesh status, node inventory)                       │
│  - Shield vectors (network, wifi, usb, process, file)            │
│  - Proof engine (receipts, Merkle roots, anchors)                │
│  - Agent subsystem (sentinel, orchestrator, analyst, executor)   │
└──────────────────────────────────────────────────────────────────┘

---

API Contract

POST /mcp/command

Request:

{
  "session_id": "vaultmesh-2025-12-07-01",
  "user": "sovereign",
  "command": "mesh status",
  "args": [],
  "cwd": "/vaultmesh",
  "meta": {
    "client": "iotek-nexus-cli",
    "version": "1.0.0"
  }
}

Response:

{
  "id": "cmd-174455",
  "status": "ok",
  "lines": [
    "",
    "  🕸  MESH STATUS: STABLE",
    "",
    "  Tailnet: story-ule.ts.net",
    "  ..."
  ],
  "effects": {
    "nodes": 7,
    "shield": { "armed": true }
  }
}

WebSocket /ws

Handshake:

{ "type": "handshake", "session_id": "...", "user": "sovereign" }

Server messages:

{ "type": "console.line", "line": "✓ Proof anchored", "lineType": "success" }
{ "type": "status.update", "payload": { "nodes": 7, "proofs": 1248, ... } }
{ "type": "proof.new", "proof_id": "proof_abc123" }
{ "type": "shield.event", "event": "Shield ARMED", "severity": "info" }

---

Available Commands

Command	Description	Backend Required
help	Show commands	No
clear	Clear terminal	No
history	Command history	No
whoami	Current identity	No
neofetch	System info ASCII	No
status	Full dashboard	Yes
mesh status	Network topology	Yes
mesh nodes	List nodes	Yes
shield status	Defense vectors	Yes
shield arm	Arm shield	Yes
shield disarm	Disarm shield	Yes
proof latest	Recent receipts	Yes
proof generate	Create proof	Yes
agents list	Agent status	Yes
oracle reason <q>	Oracle query	Yes

---

Tailscale Integration

The backend extracts user identity from Tailscale headers:

# In offsec_mcp.py
TAILSCALE_USER_HEADER = "X-Tailscale-User"

def extract_user(request: Request) -> str:
    ts_user = request.headers.get(TAILSCALE_USER_HEADER)
    if ts_user:
        return ts_user.split("@")[0]
    return "anonymous"

Deploy behind Tailscale for automatic identity:

• Bind to Tailscale IP only (--host 100.x.x.x)
• Or use tailscale serve for HTTPS with identity headers

---

Database Schema

SQLite (vaultmesh.db):

-- Sessions
CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    user TEXT NOT NULL,
    created_at TEXT NOT NULL,
    last_seen_at TEXT NOT NULL,
    client TEXT,
    meta TEXT
);

-- Command audit log
CREATE TABLE command_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,
    ts TEXT NOT NULL,
    command TEXT NOT NULL,
    status TEXT NOT NULL,
    duration_ms INTEGER,
    error TEXT
);

-- Events (proofs, shield, etc.)
CREATE TABLE events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    ts TEXT NOT NULL,
    type TEXT NOT NULL,
    payload TEXT
);

---

Extending

Add a new command

1. Create handler in offsec_mcp.py:

async def cmd_my_command(req: CommandRequest) -> CommandResponse:
    lines = ["  Output line 1", "  Output line 2"]
    return CommandResponse(
        id=f"cmd-{uuid.uuid4().hex[:8]}",
        status="ok",
        lines=lines,
        effects={}
    )

2. Register in COMMANDS:

COMMANDS = {
    # ...existing...
    "my command": cmd_my_command,
}

Wire to real systems

Replace mock implementations with actual integrations:

# Example: Real shield integration
async def cmd_shield_status(req: CommandRequest) -> CommandResponse:
    # Call your actual shield system
    shield_data = await shield_client.get_status()
    
    lines = format_shield_output(shield_data)
    
    return CommandResponse(
        id=f"cmd-{uuid.uuid4().hex[:8]}",
        status="ok",
        lines=lines,
        effects={"shield": {"armed": shield_data.armed}}
    )

---

Deployment Options

1. Local development

# Terminal 1: Backend
uvicorn offsec_mcp:app --reload --port 8080

# Terminal 2: Console (or just open HTML)
python -m http.server 3000

2. Tailscale-only (recommended)

# Bind to Tailscale IP
uvicorn offsec_mcp:app --host 100.x.x.x --port 8080

# Or use tailscale serve
tailscale serve https / http://localhost:8080

3. Docker

FROM python:3.11-slim
WORKDIR /app
COPY requirements-mcp.txt .
RUN pip install -r requirements-mcp.txt
COPY offsec_mcp.py .
CMD ["uvicorn", "offsec_mcp:app", "--host", "0.0.0.0", "--port", "8080"]

4. Systemd service

[Unit]
Description=offsec-mcp
After=network.target tailscaled.service

[Service]
Type=simple
User=sovereign
WorkingDirectory=/home/sovereign/vaultmesh
ExecStart=/usr/bin/uvicorn offsec_mcp:app --host 100.x.x.x --port 8080
Restart=always

[Install]
WantedBy=multi-user.target

---

Files

File	Description
iotek-nexus-live.html	Console frontend (backend-connected)
offsec_mcp.py	FastAPI backend
requirements-mcp.txt	Python dependencies
vaultmesh.db	SQLite database (auto-created)

---

Next Steps

1. Wire real Tailscale — Connect to actual tailscale status --json
2. Wire real Shield — Connect to your monitoring/defense systems
3. Wire real Proofs — Connect to VaultMesh proof engine
4. Add more commands — scan, audit, lawchain, etc.
5. Add authentication — mTLS or Tailscale identity enforcement

---

The console is now a real control surface.

"They built the grid to cage us. We built the Veil to break it."