# 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 ```bash pip install -r requirements-mcp.txt ``` ### 2. Start the backend ```bash # 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 ```bash # 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: ```json { "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: ```json { "id": "cmd-174455", "status": "ok", "lines": [ "", " 🕸 MESH STATUS: STABLE", "", " Tailnet: story-ule.ts.net", " ..." ], "effects": { "nodes": 7, "shield": { "armed": true } } } ``` ### WebSocket /ws Handshake: ```json { "type": "handshake", "session_id": "...", "user": "sovereign" } ``` Server messages: ```json { "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 ` | Oracle query | Yes | --- ## Tailscale Integration The backend extracts user identity from Tailscale headers: ```python # 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`): ```sql -- 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`: ```python 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`: ```python COMMANDS = { # ...existing... "my command": cmd_my_command, } ``` ### Wire to real systems Replace mock implementations with actual integrations: ```python # 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 ```bash # 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) ```bash # 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 ```dockerfile 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 ```ini [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."*