VaultCrux Docs

Appearance

Shield Security ​

VaultCrux Shield is the policy-control layer for MCP tools and state-changing API actions.

Runtime mode ​

  • Default rollout mode: SHIELD_MODE=observe
  • Enforcement mode: SHIELD_MODE=enforce
  • Mandatory promotion gate: hold observe for at least 48 hours with paid-path canary green before switching to enforce.
  • Recommended promotion order:
    1. FEATURE_SHIELD_ENABLED
    2. FEATURE_SHIELD_ENFORCE_CAPABILITY
    3. FEATURE_TRUST_REGISTRY_ENFORCE_DIGEST
    4. FEATURE_SANDBOX_RUNNER
    5. FEATURE_SHIELD_ENFORCE_TAINT
    6. FEATURE_SHIELD_ENFORCE_APPROVALS
    7. FEATURE_SAMPLING_GUARDIAN
    8. FEATURE_UI_APP_SANDBOX
    9. FEATURE_KILL_SWITCHES

Minimum production promotion set ​

After observe window and passing runbook checks:

  • SHIELD_MODE=enforce
  • FEATURE_UI_APP_SANDBOX=true
  • FEATURE_KILL_SWITCHES=true

Rollback baseline:

  • SHIELD_MODE=observe
  • FEATURE_UI_APP_SANDBOX=false
  • FEATURE_KILL_SWITCHES=false

Enforcement surfaces ​

  • MCP tool calls run through Shield decision evaluation before execution.
  • Mutating API routes use Shield mutation guard with structured denial responses.
  • Every evaluated decision is written to:
    • vaultcrux.shield_decisions
    • vaultcrux.event_outbox (shield.decision)

Policy domains ​

  • Capability firewall: unknown/unmanifested tools and dangerous-local class controls.
  • Trust registry + digest pinning:
    • trusted_publishers
    • trusted_server_digests
    • revoked_digests
  • Approval workflow:
    • approval_requests
    • approval_resolutions
    • approval token header: x-shield-approval-token
  • Taint controls:
    • taint_events
    • blocked taint event class: shield.taint.blocked
  • Kill switches:
    • kill_switches
    • kill_switch_audit
  • Sampling/UI safety:
    • sampling_policies
    • sampling_audit
    • ui_app_integrity_sessions

Shield control-plane endpoints ​

  • GET /v1/shield/capabilities
  • GET|POST /v1/shield/trust/publishers
  • GET|POST /v1/shield/trust/digests
  • POST /v1/shield/trust/digests/revoke
  • GET|POST /v1/shield/servers
  • POST /v1/shield/servers/:serverId/status
  • POST /v1/shield/approvals/propose
  • POST /v1/shield/approvals/:approvalRequestId/resolve
  • GET /v1/shield/approvals/:approvalRequestId
  • GET|POST /v1/shield/kill-switches
  • DELETE /v1/shield/kill-switches/:killSwitchId
  • GET|POST /v1/shield/sampling-policies
  • GET|POST /v1/shield/ui-integrity-sessions
  • GET|POST /v1/shield/incident-drills

UI sandbox and approvals ​

  • Tool-provided UI must remain sandboxed and integrity-bound to server digest/session metadata.
  • Approval actions must occur in first-party chrome, not inside tool-provided UI.
  • Integrity sessions for UI rendering are tracked in ui_app_integrity_sessions.

Security e2e scripts ​

From VaultCrux repo root:

bash
pnpm e2e:shield:capability
pnpm e2e:shield:trust
pnpm e2e:shield:approval-taint
pnpm e2e:shield:sandbox
pnpm e2e:shield:sampling
pnpm e2e:shield:kill-switch
pnpm e2e:shield:strict
pnpm exec tsx scripts/e2e-incident-redteam.ts

pnpm e2e:shield:strict is the release gate lane and runs all Shield security e2e scenarios in enforce mode. pnpm exec tsx scripts/e2e-incident-redteam.ts records incident drill evidence and replays the quarterly red-team control checks.

Copyright 2026 CueCrux