Initial commit - combined iTerm2 scripts
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>
This commit is contained in:
Vault Sovereign
353
VaultMesh_Catalog_v1/files/README-mcp.md
Normal file
353
VaultMesh_Catalog_v1/files/README-mcp.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# 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."*
|
||||
Reference in New Issue
Block a user