1583890199
Contains: - 1m-brag - tem - VaultMesh_Catalog_v1 - VAULTMESH-ETERNAL-PATTERN 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
354 lines
10 KiB
Markdown
354 lines
10 KiB
Markdown
# 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 <q>` | 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."*
|