vm-core/docs/VAULTMESH-MCP-TEM-NODE.md

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:

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:

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