162 lines
3.7 KiB
Markdown
162 lines
3.7 KiB
Markdown
# VaultMesh MCP + TEM Shield Node Integration
|
|
|
|
## 1. Overview
|
|
|
|
The VaultMesh core ledger integrates with an external **OffSec Shield
|
|
Node** that runs:
|
|
|
|
- OffSec agents
|
|
- MCP backend (FastAPI)
|
|
- TEM Engine (Threat / Experience Memory)
|
|
|
|
The node is implemented in the separate `offsec-agents/` repository and
|
|
deployed to `shield-vm` (or lab nodes). VaultMesh talks to it via HTTP
|
|
and ingests receipts.
|
|
|
|
---
|
|
|
|
## 2. Node Contract
|
|
|
|
**Node identity:**
|
|
|
|
- Node ID: `shield-vm` (example)
|
|
- Role: `shield` / `offsec-node`
|
|
|
|
**MCP endpoints (examples):**
|
|
|
|
- `GET /health`
|
|
- `POST /api/command`
|
|
- `{ "cmd": "agents list" }`
|
|
- `{ "cmd": "agent spawn", "args": {...} }`
|
|
- `{ "cmd": "agent mission", "args": {...} }`
|
|
- `{ "cmd": "tem status" }`
|
|
- `GET /tem/status`
|
|
- `GET /tem/stats`
|
|
|
|
---
|
|
|
|
## 3. VaultMesh Client (Thin Shim)
|
|
|
|
VaultMesh does not embed offsec-agents. It uses a minimal HTTP client:
|
|
|
|
- Location: `scripts/offsec_node_client.py`
|
|
- Responsibilities:
|
|
- Send commands to Shield Node
|
|
- Handle timeouts / errors
|
|
- Normalize responses for `vm_cli.py`
|
|
|
|
Example call:
|
|
|
|
```python
|
|
from scripts.offsec_node_client import OffsecNodeClient
|
|
|
|
client = OffsecNodeClient(base_url="http://shield-vm:8081")
|
|
|
|
agents = await client.command("agents list")
|
|
status = await client.command("tem status")
|
|
```
|
|
|
|
---
|
|
|
|
## 4. CLI Integration
|
|
|
|
`vm_cli.py` can expose high-level commands that proxy to the Shield Node:
|
|
|
|
- `vm offsec agents`
|
|
- Calls `agents list`
|
|
- `vm offsec mission --agent <id> --target <t>`
|
|
- Calls `agent mission`
|
|
- `vm tem status`
|
|
- Calls `tem status`
|
|
|
|
These commands are optional and only work if the Shield Node is
|
|
configured in env:
|
|
|
|
- `OFFSEC_NODE_URL=http://shield-vm:8081`
|
|
|
|
If the node is unreachable, the CLI should:
|
|
|
|
- Fail gracefully
|
|
- Print a clear error message
|
|
- Not affect core ledger operations
|
|
|
|
---
|
|
|
|
## 5. Receipts and Guardian Integration
|
|
|
|
The Shield Node writes receipts locally (e.g. on shield-vm):
|
|
|
|
- `/opt/offsec-agents/receipts/offsec.jsonl`
|
|
- `/opt/offsec-agents/receipts/tem/tem_events.jsonl`
|
|
|
|
Integration options:
|
|
|
|
1. **File sync / pull**
|
|
- A sync job (cron, rsync, MinIO, etc.) copies receipts into the
|
|
VaultMesh node under:
|
|
- `receipts/shield/offsec.jsonl`
|
|
- `receipts/shield/tem_events.jsonl`
|
|
|
|
2. **API pull**
|
|
- Shield Node exposes `/receipts/export` endpoints
|
|
- VaultMesh pulls and stores under `receipts/shield/`
|
|
|
|
Guardian then:
|
|
|
|
- Computes partial roots for Shield receipts:
|
|
- `ROOT.shield.offsec.txt`
|
|
- `ROOT.shield.tem.txt`
|
|
- Includes them in the combined anchor:
|
|
|
|
```python
|
|
roots = {
|
|
"mesh": read_root("ROOT.mesh.txt"),
|
|
"treasury": read_root("ROOT.treasury.txt"),
|
|
"offsec": read_root("ROOT.offsec.txt"),
|
|
"shield_tem": read_root("ROOT.shield.tem.txt"),
|
|
}
|
|
anchor_root = compute_combined_root(roots)
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Configuration
|
|
|
|
Example env vars for VaultMesh:
|
|
|
|
- `OFFSEC_NODE_URL=http://shield-vm:8081`
|
|
- `OFFSEC_NODE_ID=shield-vm`
|
|
- `OFFSEC_RECEIPTS_PATH=/var/lib/vaultmesh/receipts/shield`
|
|
|
|
Example env vars for Shield Node:
|
|
|
|
- `VAULTMESH_ROOT=/opt/vaultmesh`
|
|
- `TEM_DB_PATH=/opt/offsec-agents/state/tem.db`
|
|
- `TEM_RECEIPTS_PATH=/opt/offsec-agents/receipts/tem`
|
|
|
|
---
|
|
|
|
## 7. Failure Modes
|
|
|
|
If the Shield Node is:
|
|
|
|
- **Down**: CLI commands fail, core ledger continues; Guardian anchors
|
|
without Shield roots (or marks them missing).
|
|
- **Lagging**: Receipts are delayed; anchors include older Shield state.
|
|
- **Misconfigured**: CLI reports invalid node URL or protocol errors.
|
|
|
|
VaultMesh must never block core anchors solely because Shield is
|
|
unavailable; Shield is an extension, not the root of truth.
|
|
|
|
---
|
|
|
|
## 8. Design Principles
|
|
|
|
- Keep Shield node separate from VaultMesh core.
|
|
- Integrate via:
|
|
- HTTP commands
|
|
- Receipt ingestion
|
|
- Treat Shield as:
|
|
- A specialized OffSec/TEM appliance
|
|
- A contributor to the global ProofChain
|