ContextShield

ContextShield is the security perimeter of ContextUnity. It provides declarative security through prompt injection detection, policy-based authorization, compliance auditing, cryptographic token management, and per-project admin PKI.

AI Firewall

Prompt injection, jailbreak, and PII leak detection with configurable YAML rule sets.

Policy Engine

Declarative ABAC policies with ContextToken integration for fine-grained access control.

Admin Tokens

Per-project admin tokens for remote policy management — no master key needed.

Delegation Chains

Cryptographic permission attenuation for multi-hop agent architectures.

Architecture

shield

Key Components

AI Firewall (`firewall/`)

The Shield orchestrates multiple validators:

InjectionValidator — detects prompt injection attempts
JailbreakValidator — detects jailbreak patterns
PIIValidator — detects PII (names, phones, IDs) via regex + Presidio ML
RAGContextValidator — validates retrieval context integrity

PII detection rules are loaded from firewall/rules/pii.yaml — no redeployment needed to add new rules.

Policy Engine (`policy.py`)

Declarative attribute-based access control:

from contextunity.shield import PolicyEngine, Policy

engine = PolicyEngine()
engine.add_policy(Policy(
    name="brain_read",
    conditions={"permission": "brain:read", "tenant": "my_project"},
    effect="allow",
))

result = engine.evaluate(token, resource="brain", action="read")

Delegation Chains (`delegation.py`)

Cryptographic permission attenuation for multi-hop calls:

from contextunity.shield.delegation import DelegationChain

# Parent delegates subset of permissions to child
chain = DelegationChain(parent_token)
child_token = chain.attenuate(
    permissions=("brain:read",),  # Subset of parent's permissions
    ttl_seconds=3600,
)

PKI & Admin Token Management

Shield manages per-project Ed25519 keypairs and HMAC secrets. Admin tokens provide a third trust tier that decouples project deployment from the Shield master key.

Trust Tiers

Tier	Credential	Scope	Holder
Master	`SHIELD_MASTER_KEY`	Create/delete projects, rotate master key	Shield daemon (systemd-cred)
Admin	`admin_token` (per-project)	Set permissions, rotate HMAC, view policy	Project deploy pipeline (Ansible vault)
Runtime	`CU_PROJECT_SECRET`	Runtime authentication, session tokens	Project service (.env)

Creating a Project

# Generates Ed25519 keypair + admin token
contextshield project-create my-project \
  --services "brain,router"

# Output:
#   project_id:   my-project
#   admin_token:  shield-admin:my-project:Abc123...  ← SAVE THIS
#   public_key:   ...
#   hmac_secret:  ...

Project IDs must match [a-z0-9][a-z0-9_-]{0,62} — lowercase, digits, hyphens, underscores only.

Remote Policy Management

With an admin token, operators manage their project remotely via gRPC — no SSH to the Shield host, no SHIELD_MASTER_KEY:

# Update permissions
contextshield project-policy my-project \
  --admin-token "shield-admin:my-project:Abc123..." \
  --set "brain:read,brain:write,router:execute"

# View policy
contextshield project-policy my-project \
  --admin-token "shield-admin:my-project:Abc123..." \
  --action view_policy

# Rotate HMAC secret
contextshield project-policy my-project \
  --admin-token "shield-admin:my-project:Abc123..." \
  --action reset_hmac

Rotating Admin Tokens

# Generate new admin token (invalidates the old one)
contextshield admin-create my-project

# Revoke token entirely
contextshield admin-delete my-project

gRPC Service (15 RPCs)

RPC	Description
`Scan`	AI firewall scan (injection/PII detection)
`EvaluatePolicy`	Policy engine evaluation
`CheckCompliance`	Compliance posture check
`RecordAudit`	Record audit event
`MintToken`	Create signed ContextToken
`VerifyToken`	Verify token signature and validity
`RevokeToken`	Add to revocation list
`GetStats`	Security metrics and statistics
`SyncProjectPolicy`	Admin-authenticated policy management
`GetSecret`	Retrieve a secret
`PutSecret`	Store a secret
`ListSecrets`	List stored secrets
`RotateSecret`	Rotate a secret
`Encrypt`	Encrypt data
`Decrypt`	Decrypt data

Configuration

Environment Variables

Variable	Default	Description
`SHIELD_MASTER_KEY`	—	Fernet key — encrypts private keys at rest
`SHIELD_DB_PATH`	`data/shield.db`	SQLite PKI database path
`SHIELD_ENCRYPTION_KEY`	—	Fernet key for PII mapping store
`CU_SHIELD_GRPC_URL`	`localhost:50054`	Shield gRPC endpoint

Systemd Credentials (Production)

Critical secrets can be provisioned via systemd-creds for production hardening. The config loader checks CREDENTIALS_DIRECTORY first, then falls back to .env. See Systemd Deployment for details.

Router Integration

Shield integrates with contextunity.router in two ways:

As LangChain Tools (Dispatcher Agent)

Tools are auto-registered when contextunity.shield is installed:

shield_scan — Scan for injection / jailbreak / PII
check_policy — Authorization against policy engine
check_compliance — Posture audit
audit_event — Log security events

Dual-mode: local package OR gRPC (set CU_SHIELD_GRPC_URL).

As Inline Firewall (gRPC)

Router invokes Shield natively via Scan RPC before any LangGraph agent executes. The end-user’s ContextToken is propagated directly to Shield (SPOT pattern). router:execute inherits shield:check via permission inheritance in contextunity.core.

CLI Reference

# Project management
contextshield project-create <id> [--services <svc,svc,...>]
contextshield project-list
contextshield project-rotate <id>

# Admin tokens
contextshield admin-create <id>
contextshield admin-delete <id>

# Policy management
contextshield project-policy <id> --set <perms>              # local
contextshield project-policy <id> --admin-token <token> ...      # remote

# Diagnostics
contextshield status