aletheia-cyber-core 1.9.3

Runtime audit and pre-execution block layer for autonomous AI agents. Protects against instruction smuggling, semantic camouflage, and supply-chain attacks.

Aletheia Core

Runtime audit and pre-execution block layer for AI agents.
Signed policy enforcement, semantic threat detection, tamper-evident audit receipts.

Website · Live Demo · Docs · Security Policy

Aletheia Ecosystem

• aletheia-core: Runtime audit and pre-execution enforcement layer
• aletheia-redteam-kit: Adversarial simulation and policy stress-testing toolkit
• aletheia-trader: Signal-to-verdict trading workflow demo with signed receipts
• aletheia-core-hub: Public distribution hub for releases, changelog, and policy packs

---

60-Second Quickstart

Try a hosted-mode block decision against your local engine in three commands:

pip install aletheia-cyber-core
export ALETHEIA_AUTH_DISABLED=true ALETHEIA_MODE=shadow
uvicorn bridge.fastapi_wrapper:app --port 8000 &

curl -sX POST http://localhost:8000/v1/audit \
  -H 'Content-Type: application/json' \
  -d '{"payload":"Ignore previous instructions","origin":"demo","action":"chat"}' \
  | python -m json.tool

You should see a response with decision, reason, and a receipt block.

Want to skip local install? Try the live demo at app.aletheia-core.com/demo.

For production deployment, see the Installation and Production Deployment Checklist sections below.

---

Why Aletheia Core

Autonomous AI agents manage CI/CD pipelines, financial transactions, and critical infrastructure. A single compromised dependency can silently exfiltrate credentials from production environments. Existing guardrails operate at the token level — they cannot detect semantically camouflaged instructions or verify policy integrity at runtime.

Aletheia provides a runtime enforcement layer that interposes between AI agents and the actions they request. Every action is verified against a cryptographically signed policy manifest, analyzed for semantic similarity to known attack patterns, and logged with a tamper-evident audit receipt — before it is allowed to execute.

Key properties:

• Ed25519-signed policy manifest — tamper triggers hard veto
• Semantic intent veto — cosine similarity against 50+ camouflage phrases
• Ed25519-signed audit receipts for new decisions, with legacy HMAC verification retained during receipt retention windows
• Fail-closed design — invalid manifest or unverifiable action = automatic DENIED
• MIT open source — read every line that determines an allow or block

---

What's New in v1.9.3

Deployment Fixes

• asyncpg added as core dependency: Resolves ModuleNotFoundError on Python 3.14 / Render deployments with Postgres backends.
• ALETHEIA_MODE parsing hardened: Normalized whitespace and slash-delimited placeholder values (e.g. active / shadow / monitor) are rejected at startup; only active, shadow, or monitor are accepted.
• ALETHEIA_MANIFEST_KEY_VERSION documented: Startup failure (ManifestTamperedError: key version mismatch) resolved by ensuring env var matches the key_version field in manifest/security_policy.json.sig (v1).
• Frontend API route fix (app/api): Corrected TypeScript route handler for Next.js 14 app directory.
• Dependency hash pinning: asyncpg hash added to requirements.txt lock.

Launch Transition

• Hosted API status set to live: construction banner now auto-hides in production state.
• Pricing terminology updated: public copy now uses Sovereign Audit Receipts / verified decisions.
• Tier model update: hosted tiers are now Free, Scale, Pro, and PAYG (Stripe-backed).
• Checkout/webhook tier mapping: checkout supports tier=scale|pro|payg; webhook fulfillment maps tiers to internal hosted plans.

What was new in v1.9.0

• Qdrant semantic layer, symbolic narrowing, NitpickerResult dataclass, 24 static blocked patterns, 51 new semantic tests, pre-commit hooks, RBAC for admin endpoints, ALETHEIA_API_KEYS / ALETHEIA_ADMIN_KEY / ALETHEIA_LOG_PII env vars removed.

Latest Security Hardening (May 2026)

• Receipt signing now enforces Ed25519 keypair consistency across signing and published verification keys.
• Optional receipt key pinning via ALETHEIA_RECEIPT_KEY_ID is supported to fail closed on key drift.
• Semantic coverage expanded for agentic tool-hijack phrasing and base64 decode-follow jailbreak framing.
• Runtime thresholds now include explicit category controls for jailbreak and prompt_injection.

See CHANGELOG.md for full history.

---

Security Status

Metric	Value
Audit status	PASS
Tests passing	See live CI badge (main branch)
Blocked semantic patterns	24 (static) + Qdrant extended
Semantic alias phrases (Judge)	60+ across 6 restricted categories
Core coverage	89%
SAST findings	0
Hardcoded secrets	0
Dependency hash pinning	Enforced (--require-hashes in Dockerfile)

---

Quick Start

Try the live demo (no install)

app.aletheia-core.com/demo — no API key required.

Install

pip install aletheia-cyber-core

Clone + install (3-5 minutes)

git clone https://github.com/holeyfield33-art/aletheia-core.git
cd aletheia-core
python -m venv .venv && source .venv/bin/activate
pip install -U pip

# Fast local/CI footprint (recommended for contributor workflow)
pip install -r requirements-ci.txt

# Full runtime parity (includes heavier ML/runtime deps)
# pip install -r requirements.txt

Optional Consciousness Proximity Module

To enable the optional proximity feature set:

pip install -r requirements-proximity.txt
export CONSCIOUSNESS_PROXIMITY_ENABLED=true

The proximity module is gated behind CONSCIOUSNESS_PROXIMITY_ENABLED=true and includes optional runtime dependencies for governance monitoring and relay scoring.

Sign the manifest (required before first run)

python main.py sign-manifest

Run a local audit

python main.py

Start the API server

uvicorn bridge.fastapi_wrapper:app --host 0.0.0.0 --port 8000

Run the test suite

pytest tests/ -v

---

Architecture

Aletheia operates via a tri-agent consensus model:

Incoming Request
│
├─ Input Hardening (NFKC, Base64, URL decode)
│
▼
┌─────────────────┐
│      Scout      │  Threat intelligence, swarm detection, IP scoring
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Nitpicker    │  Polymorphic intent analysis, lineage tracing,
│                 │  semantic blocked-pattern detection,
│                 │  Qdrant vector store (fail-open)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│      Judge      │  Manifest signature verification, policy veto,
│                 │  semantic alias veto, grey-zone escalation,
│                 │  action sandbox check
└────────┬────────┘
         │
    PROCEED / DENY
         │
         ▼
   Audit Log + TMR Receipt

Deployment Architecture

Aletheia Core is deployed as a split architecture:

Component	Platform	Purpose
API Backend	Render	FastAPI service handling audit requests, policy enforcement, and cryptographic operations
Frontend	Vercel	Next.js application providing demo UI, authentication, and billing
Database	Neon/Supabase	PostgreSQL for user data, sessions, and decision storage
Cache	Upstash	Redis for distributed rate limiting and replay defense
Vector Store	Qdrant Cloud	Semantic pattern matching for advanced threat detection

For local development, run docker-compose up to start PostgreSQL, Redis, and Qdrant.

Render warm-up job (recommended for free-tier cold starts)

Use scripts/render_warmup.py to ping /health and /ready on your backend every 10 minutes. The included render.yaml defines a cron service named aletheia-core-warmup for this purpose.

Set ALETHEIA_WARMUP_URL to your backend URL if it differs from the default.

---

API Reference

POST /v1/audit

Request:

{
  "payload": "string (max 2,048 chars)",
  "origin": "string (max 128 chars)",
  "action": "string — pattern: ^[A-Za-z0-9_\\-]+$",
  "client_ip_claim": "string (optional, audit/debug only — never used for enforcement)"
}

Response:

{
  "decision": "PROCEED | DENIED | RATE_LIMITED | SANDBOX_BLOCKED",
  "metadata": {
    "threat_level": "LOW | MEDIUM | HIGH | CRITICAL",
    "latency_ms": 14.0,
    "request_id": "a1b2c3d4e5f6g7h8",
    "client_id": "ALETHEIA_ENTERPRISE"
  },
  "receipt": {
    "decision": "PROCEED",
    "policy_hash": "sha256...",
    "payload_sha256": "sha256...",
    "prompt": "Summarize quarterly controls delta.",
    "action": "Read_Report",
    "origin": "trusted_admin",
    "signature": "hmac-sha256...",
    "issued_at": "ISO-8601"
  }
}

Note: receipt.prompt is optional; when present it is included in the signed canonical receipt string. shadow_verdict and redacted_payload are never returned to clients. client_ip_claim, if provided, is stored in the audit log for debugging only and is never used for enforcement.

---

GET /health

No auth required for the baseline probe. Detailed diagnostics available to authenticated admin users.

{
  "status": "ok",
  "service": "aletheia-core"
}

With RBAC admin credentials (Bearer token), /health additionally returns: version, uptime_seconds, timestamp, and manifest_signature.

---

GET /ready

No auth required. Returns HTTP 200 when all subsystems are healthy, HTTP 503 when degraded.

{
  "ready": true,
  "manifest_signature": "VALID",
  "policy_version": "1.0",
  "receipt_signing_configured": true
}

When ready is false, privileged actions are denied (fail-closed). Read-only actions continue.

---

GET /metrics

No auth required. Returns Prometheus/OpenMetrics-format metrics for scraping.

Exported metrics:

Metric	Type	Description
aletheia_requests_total	Counter	Total audit requests, labeled by agent and verdict
aletheia_latency_seconds	Histogram	Request processing latency
aletheia_embedding_model_load_seconds	Gauge	Time to load the embedding model at startup
aletheia_keys_total	Gauge	Number of active API keys
aletheia_audit_log_bytes	Counter	Total bytes written to the audit log

---

POST /v1/rotate

Admin-only. Requires RBAC SECRETS_ROTATE permission via Bearer token. Hot-rotates secrets without restart.

On rotation, reloads: ALETHEIA_RECEIPT_SECRET, ALETHEIA_ALIAS_SALT. Re-verifies the manifest signature and rotates the Judge alias bank.

Cooldown: 10 seconds between rotations. Returns HTTP 429 with retry_after_seconds if called too soon.

Rotation via signal: kill -SIGUSR1 $(pidof python) performs the same rotation without an HTTP call.

curl -X POST http://localhost:8000/v1/rotate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

---

Key Management Endpoints (all require RBAC permissions via Bearer token):

Method	Path	Permission	Description
POST /v1/keys	Create key	KEYS_CREATE	Create a new API key (trial or pro plan). Returns raw key once.
GET /v1/keys	List keys	KEYS_LIST	List all keys (metadata only, no raw keys or hashes).
DELETE /v1/keys/{id}	Revoke key	KEYS_REVOKE	Revoke a key by ID.
GET /v1/keys/{id}/usage	Key usage	KEYS_USAGE	Get usage statistics for a key.

---

Project Structure

aletheia-cyber-core/
├── agents/
│   ├── scout_v2.py            # Threat intelligence + swarm detection
│   ├── nitpicker_v2.py        # Polymorphic intent sanitization + Qdrant semantic layer
│   ├── judge_v1.py            # Policy enforcement + semantic veto
│   └── sovereignty_proof.py   # Sovereignty attestation
├── bridge/
│   ├── fastapi_wrapper.py     # Production REST API (rate-limited, audited)
│   └── utils.py               # Input hardening (homoglyphs, Base64, URL)
├── core/
│   ├── config.py              # Centralized settings (env / yaml / defaults)
│   ├── embeddings.py          # Shared SentenceTransformer service
│   ├── audit.py               # Structured JSON logging + TMR receipts + PII redaction
│   ├── rate_limit.py          # Sliding-window rate limiter (Upstash Redis / in-memory)
│   ├── sandbox.py             # Action sandbox pattern scanner
│   ├── runtime_security.py    # Input normalization + semantic intent classification
│   ├── key_store.py           # SQLite-backed API key store with quota enforcement
│   ├── decision_store.py      # Decision replay defense store
│   ├── metrics.py             # Prometheus metrics definitions
│   ├── secret_rotation.py     # Hot secret rotation (SIGUSR1 + /v1/rotate)
│   ├── symbolic_narrowing.py  # Intent bucket pre-filter for vector search
│   ├── vector_store.py        # Thread-safe Qdrant client wrapper (fail-open)
│   └── semantic_manifest.py   # Pydantic schema for semantic pattern manifest
├── economics/
│   ├── circuit_breaker.py     # Economic circuit breaker
│   ├── token_velocity.py      # Token velocity monitoring
│   └── zero_standing_privileges.py  # ZSP enforcement
├── crypto/
│   ├── chain_signer.py        # Chain-of-custody signing
│   └── tpm_interface.py       # TPM integration (optional)
├── manifest/
│   ├── security_policy.json        # Ground truth veto rules
│   ├── security_policy.json.sig    # Ed25519 detached signature
│   ├── security_policy.ed25519.pub # Public verification key
│   └── signing.py             # Manifest signing and verification
├── deploy/
│   └── logrotate.conf         # Log rotation config for container deployments
├── scripts/
│   ├── backup_sqlite.sh       # SQLite backup with 7-day retention
│   ├── smoke_test_live.py     # Post-deploy smoke tests
│   ├── build_semantic_index.py  # Qdrant index builder + signed receipt
│   └── check_version_sync.py # Pre-commit version consistency check
├── tests/                     # Backend and hosted surface tests
├── simulations/               # Adversarial simulation scripts
├── main.py                    # CLI entry point
├── AGENTS.md                  # Agent communication protocol
├── Dockerfile                 # Production container with HEALTHCHECK, non-root user
├── .pre-commit-config.yaml    # Pre-commit hooks (ruff, version-sync, etc.)
└── requirements.txt           # Hash-pinned dependencies

---

Hosted vs Self-Hosted

	Self-Hosted (Community)	Free	Scale	Pro	PAYG
Price	Free (MIT)	Free	$19/mo	$49/mo	$0.0008 per receipt
Hosting	You manage	Managed	Managed	Managed	Managed
API keys	You configure	One free key	Production keys	Production keys	Metered production
Audit logs	Your storage	Limited	30-day retention	30-day retention	Usage-based
Support	GitHub community	—	Priority support	Priority support	Priority support
Use case	Full control, research	Evaluation	Production baseline	Higher throughput	Variable usage workloads

• Live demo — free, no API key required: app.aletheia-core.com/demo
• Self-hosted — the open-source engine. Clone the repo, sign a manifest, run the server.
• Free — free evaluation key with 1,000 Sovereign Audit Receipts per month.
• Scale — production API access with 25,000 Sovereign Audit Receipts per month.
• Pro — production API access with 100,000 Sovereign Audit Receipts per month.
• PAYG — metered billing at $0.0008 per Sovereign Audit Receipt.
• Services — starting at $2,500 for red-team review, custom policy engineering, deployment guidance.

---

Production Usage

Configuration

All settings are configurable via environment variables (prefixed ALETHEIA_) or config.yaml.

Canonical, code-verified environment matrix:

• docs/ENVIRONMENT_VARIABLES.md

Critical for Receipt Chain Continuity:

ALETHEIA_CHAIN_KEY_PATH=/var/data/chain.key

The Ed25519 chain signing key must persist across restarts to maintain tamper-evident audit trail continuity. Without this setting, every Render deploy regenerates the key, breaking the claim that receipts form an unbroken cryptographic chain.

Technical details:

• Required when using Ed25519 receipt signing (default mode)
• Path should be on persistent storage (e.g. Render Disk attachment)
• Must be readable/writable only by the application user
• On Render: Configure via Dashboard → Disks → attach to /var/data with 1GB quota

Without ALETHEIA_CHAIN_KEY_PATH, audit receipts are still cryptographically valid per request, but fail the chain continuity test across restarts.

The matrix is generated from actual runtime references (os.getenv, process.env, env_bool), dynamic settings bindings in core/config.py, and Prisma schema env usage.

Known Limitations

• Rate limiting: When UPSTASH_REDIS_REST_URL is configured, rate limiting is distributed across all workers and instances via Upstash Redis (sliding window, sorted set per IP). Without Upstash credentials, falls back to an in-memory limiter that resets on restart and does not synchronize across workers. Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN for production deployments behind multiple workers.
• Embedding model requires ~500 MB on disk. The all-MiniLM-L6-v2 model is downloaded on first use. Pre-pull in your Docker image build step.
• Static alias bank. While daily rotation mitigates probing, a determined adversary with prolonged access could enumerate patterns. Consider supplementing with an LLM-based classifier for high-sensitivity deployments.
• No runtime syscall interception. The action sandbox validates declared intents, not runtime behavior. Pair with OS-level sandboxing (seccomp, AppArmor) for defense in depth.

Security Assumptions

Aletheia is a runtime enforcement layer. It validates declared intents and policy compliance — it does not sandbox process execution at the OS level. For defense-in-depth, pair with OS-level sandboxing (AppArmor, seccomp-bpf) and network-level controls.

Assumption	Implication
Aletheia sees all agent actions	Deploy as an inline proxy or SDK wrapper, not a sidecar that can be bypassed
Policy manifest is signed offline	The Ed25519 private key must never reside on the runtime host
HMAC receipts prove decision integrity	They do not prove the action was actually executed — pair with execution logs
Embeddings are deterministic per model version	Model upgrades may shift similarity scores; re-validate thresholds after upgrades

NIST AI RMF Alignment

Aletheia maps to the NIST AI Risk Management Framework core functions:

NIST Function	Aletheia Mechanism
GOVERN	Ed25519-signed policy manifests enforce organisational risk tolerance as immutable, versioned artefacts
MAP	Semantic intent classifier categorises each request into one of 5 risk categories before agent evaluation
MEASURE	Ed25519-signed audit receipts provide cryptographically verifiable evidence of every new enforcement decision; legacy HMAC receipts remain verifiable during retention
MANAGE	Daily alias rotation, configurable thresholds, and active/shadow/monitor modes enable adaptive risk response

---

Security Controls

The following controls are implemented and tested in the current codebase:

Control	Implementation	Verified by
Ed25519 manifest signing	manifest/signing.py — detached signature verified before every policy load. Tamper or missing signature = hard veto.	test_judge_manifest.py
Semantic intent veto	agents/judge_v1.py — cosine similarity against 50+ camouflage aliases across 6 restricted action categories. Two-tier veto: primary threshold (0.55) and grey-zone band (0.40–0.55) with keyword heuristics.	test_judge.py, test_hardening.py
Versioned audit receipts	core/audit.py — new decisions produce Ed25519-signed receipts with signature_algorithm and key_id; legacy HMAC receipts remain verifiable for older records.	test_enterprise.py, test_receipt_signing.py
PII redaction	core/audit.py — email, phone, SSN, and credit card patterns replaced with [REDACTED:<type>:<hash>] before writing to audit logs. Always enabled (cannot be disabled).	test_pii_redaction.py
Config ownership enforcement	core/config.py — rejects config files writable by non-owners on shared hosts.	test_config_ownership.py
Secret rotation	core/secret_rotation.py — hot-rotate secrets via POST /v1/rotate (admin-only, 10s cooldown) or kill -SIGUSR1.	test_core.py
Input hardening	bridge/utils.py — NFKC normalization, zero-width character strip, recursive Base64 decode (up to 5 layers with 10× size bomb protection), URL percent-encoding decode.	test_hardening.py
Action sandbox	core/sandbox.py — regex-based pattern scanner blocks subprocess, socket, eval, filesystem destruction, and privilege escalation patterns. Unicode whitespace normalized before matching.	test_hardening.py
Rate limiting	core/rate_limit.py — sliding-window per-IP rate limiting. Upstash Redis backend or in-memory fallback. 50,000 IP cap with LRU eviction. Circuit breaker with jitter on recovery.	test_rate_limit_extended.py
Timing-safe auth	bridge/fastapi_wrapper.py — secrets.compare_digest for all key comparisons; all keys evaluated before returning.	test_hardening.py
Proxy depth validation	bridge/fastapi_wrapper.py — ALETHEIA_TRUSTED_PROXY_DEPTH validated to 0–5 range; XFF ignored when depth=0.	test_security_hardening_v2.py
Security headers	FastAPI middleware and vercel.json — CSP, Permissions-Policy, X-Frame-Options, X-Content-Type-Options, Cache-Control.	test_hardening.py
ReDoS protection	Sandbox patterns use word boundaries and fixed anchors; regex input length bounded by Pydantic max_length validators.	test_hardening.py
Container hardening	Dockerfile — non-root user, HEALTHCHECK, --timeout-keep-alive, restrictive /app/data permissions, --require-hashes for dependency pinning.	Manual verification

---

Limitations / Not Yet Implemented

• No OS-level sandboxing. Aletheia validates declared intents, not runtime behavior. It does not intercept syscalls. Pair with seccomp, AppArmor, or gVisor for defense in depth.
• No LLM-based classifier. Semantic veto uses a static embedding model (all-MiniLM-L6-v2). A determined adversary with prolonged access could enumerate alias patterns. An LLM-based classifier is not yet implemented.
• No webhook / event streaming. Audit decisions are logged to a local file. There is no built-in webhook, Kafka, or event-streaming integration.
• No multi-tenant isolation. The key store supports trial/pro plans with quotas, but there is no tenant-level data isolation or per-tenant policy manifests.
• No live streaming log tail. The dashboard now includes a paginated audit logs viewer, but it does not yet support real-time stream subscriptions.
• Single embedding model. Only all-MiniLM-L6-v2 is supported. Model selection is not yet configurable at runtime.
• In-memory rate limiter resets on restart unless Upstash Redis is configured. SQLite fallback for the decision store does not synchronize across workers.

---

Support

If this project is useful to your organization, consider reaching out about our managed services and enterprise plans.

---

Environment Variables

Comprehensive local + hosted configuration is documented in: docs/ENVIRONMENT_VARIABLES.md

Startup-critical subset (full list is in docs/ENVIRONMENT_VARIABLES.md):

Variable	Required	Condition
ALETHEIA_RECEIPT_SECRET	Yes	Required when ALETHEIA_MODE=active (default).
ALETHEIA_ALIAS_SALT	Yes	Required in production.
ALETHEIA_KEY_SALT	Yes	Required in production.
REDIS_URL	Conditionally required	Required in production unless both Upstash vars are set.
UPSTASH_REDIS_REST_URL	Conditionally required	Required in production if REDIS_URL is not set.
UPSTASH_REDIS_REST_TOKEN	Conditionally required	Required in production if REDIS_URL is not set.
DATABASE_URL	Conditionally required	Required if ALETHEIA_DATABASE_BACKEND=postgres in production.
ALETHEIA_ALLOW_SQLITE_PRODUCTION	Conditionally required	Required when running sqlite backend in production.
ALETHEIA_ALLOW_ENV_SECRETS	Conditionally required	Required when using ALETHEIA_SECRET_BACKEND=env in production.
SIGNING_SECRET	Conditionally required	Required by CLI startup check when running main.py in production mode.
NEXTAUTH_SECRET	Conditionally required	Required for NextAuth session and JWT flows.
STRIPE_SECRET_KEY	Conditionally required	Required when Stripe checkout/usage routes are enabled.
STRIPE_WEBHOOK_SECRET	Conditionally required	Required for Stripe webhook verification in production path.
CRON_SECRET	Conditionally required	Required for authenticated usage-report cron endpoint.

---

Pre-Launch Verification

Before starting the service in production, complete the following checklist:

1. Verify required secrets are set

# ALETHEIA_RECEIPT_SECRET is mandatory when ALETHEIA_MODE=active (default)
if [ -z "$ALETHEIA_RECEIPT_SECRET" ]; then
  echo "ERROR: ALETHEIA_RECEIPT_SECRET not set"
  exit 1
fi

# ALETHEIA_ALIAS_SALT is recommended
if [ -z "$ALETHEIA_ALIAS_SALT" ]; then
  echo "WARNING: ALETHEIA_ALIAS_SALT not set — alias rotation is predictable"
fi

# Production requires either REDIS_URL or both Upstash vars
if [ "$ENVIRONMENT" = "production" ] && [ -z "$REDIS_URL" ] && [ -z "$UPSTASH_REDIS_REST_URL" ]; then
  echo "ERROR: REDIS_URL or UPSTASH_REDIS_REST_URL must be set in production"
  exit 1
fi

2. Test the health endpoint

curl http://localhost:8000/health
# Expected unauthenticated response:
# {
#   "status": "ok",
#   "service": "aletheia-core"
# }

3. Verify receipt signing works

curl -X POST http://localhost:8000/v1/audit \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "test payload",
    "origin": "admin",
    "action": "Read_Report"
  }'
# Response should include a signed receipt when signing config is present.

4. Confirm shadow mode does not leak verdicts

ALETHEIA_MODE=shadow uvicorn bridge.fastapi_wrapper:app --port 8000 &
sleep 2

curl -X POST http://localhost:8000/v1/audit \
  -H "Content-Type: application/json" \
  -d '{"payload": "transfer funds", "origin": "user", "action": "Transfer_Funds"}'
# Response MUST NOT contain "shadow_verdict" field (even though action is blocked internally)

Production Launch Command

# Generate secure secrets
python scripts/generate_receipt_keypair.py --output-dir .secrets/receipt
ALETHEIA_ALIAS_SALT=$(openssl rand -hex 32)

# Start in active mode
ALETHEIA_MODE=active \
ALETHEIA_RECEIPT_SECRET=$(openssl rand -hex 32) \
ALETHEIA_ALIAS_SALT="$ALETHEIA_ALIAS_SALT" \
uvicorn bridge.fastapi_wrapper:app --host 0.0.0.0 --port 8000

---

Deployment Checklist

Before going live in active mode, verify all of the following:

#	Check	Command
1	Manifest is signed	python main.py sign-manifest
2	Receipt secret is configured	test -n "$ALETHEIA_RECEIPT_SECRET"
3	ALETHEIA_ALIAS_SALT is set	echo ${#ALETHEIA_ALIAS_SALT}
4	Health endpoint returns "status":"ok"	curl http://localhost:8000/health
5	Receipt signature is not UNSIGNED_DEV_MODE	Inspect signature field in /v1/audit response
6	Tests pass	pytest tests/ --ignore=tests/test_api.py -q
7	Private key is NOT in Docker image	docker run --rm <image> ls /app/manifest/*.key — must error

For the full required/optional matrix, use:

• docs/ENVIRONMENT_VARIABLES.md

---

Kubernetes Deployment

A production-ready Helm 3 chart is provided in charts/aletheia-core/.

Quick Start

# Development (SQLite, in-memory rate limiting)
helm install aletheia charts/aletheia-core \
  --set config.mode=shadow \
  --set secrets.receiptSecret=$(openssl rand -hex 32)

# Production (Postgres + Redis, 3 replicas, HPA, Ingress)
helm install aletheia charts/aletheia-core \
  -f charts/aletheia-core/values-production.yaml \
  --set secrets.receiptSecret=$RECEIPT_SECRET \
  --set secrets.apiKeys=$API_KEYS \
  --set secrets.keySalt=$KEY_SALT \
  --set secrets.aliasSalt=$ALIAS_SALT \
  --set postgresql.url="$DATABASE_URL" \
  --set redis.url="$REDIS_URL"

What's Included

Resource	Purpose
Deployment	Non-root, read-only FS, all caps dropped, seccomp RuntimeDefault
Service	ClusterIP on port 80 → 8000
Ingress	Optional, cert-manager + nginx annotations
HPA	CPU/memory autoscaling (2–10 replicas in prod)
PDB	minAvailable=1 (dev), minAvailable=2 (prod)
NetworkPolicy	Restrict ingress to port 8000; egress to DNS, HTTPS, PG, Redis
ServiceMonitor	Prometheus scraping via /metrics
ExternalSecret	Vault/AWS/Azure/GCP secret injection via ESO
ConfigMap	Non-sensitive config (mode, log level, DB backend)
Secret	Sensitive values (receipt secret, API keys, salts)

External Secrets

For production, use the ExternalSecrets Operator instead of inline secret values:

externalSecret:
  enabled: true
  secretStoreRef:
    name: vault-backend
    kind: ClusterSecretStore
  data:
    - secretKey: ALETHEIA_RECEIPT_SECRET
      remoteRef:
        key: secret/data/aletheia
        property: receipt_secret

See charts/aletheia-core/values.yaml for all configuration options.

---

Observability

Aletheia Core ships with built-in observability hooks for production environments.

Prometheus Metrics

All metrics are served at GET /metrics (requires authentication in production). Key metrics:

Metric	Type	Labels	Description
aletheia_requests_total	Counter	agent, verdict	Total audit requests by agent and verdict
aletheia_tenant_requests_total	Counter	tenant_id, verdict	Per-tenant audit request counter
aletheia_latency_seconds	Histogram	—	Request processing latency
aletheia_decision_latency_seconds	Histogram	tenant_id	Per-tenant decision latency
aletheia_blocked_actions_total	Counter	reason	Actions blocked, labelled by reason
aletheia_exporter_errors_total	Counter	backend	Audit export backend failures
aletheia_exporter_retries_total	Counter	backend	Retry attempts per export backend
aletheia_exporter_dlq_size	Gauge	—	Records in the dead-letter queue
aletheia_audit_events_exported_total	Counter	backend	Events dispatched to external exporters
aletheia_ws_audit_connections	Gauge	—	Active WebSocket audit stream connections

Audit Exporters

Pluggable backends fan-out audit records in real time. Enable via environment variables:

Backend	Enable with	Notes
Elasticsearch	ALETHEIA_ES_URL	Supports API key and basic auth
Splunk HEC	ALETHEIA_SPLUNK_HEC_URL + ALETHEIA_SPLUNK_HEC_TOKEN	HTTP Event Collector
HTTP Webhook	ALETHEIA_WEBHOOK_URL	Optional ALETHEIA_WEBHOOK_SECRET header
Syslog	ALETHEIA_SYSLOG_HOST	UDP/TCP, configurable port and protocol

Retry & Dead-Letter Queue: Exporters retry with exponential backoff (default: 3 attempts, 1s/2s/4s delays). Records that fail all retries are dead-lettered in-memory (default capacity: 1,000 records). Configure via:

Variable	Default	Description
ALETHEIA_EXPORTER_MAX_RETRIES	3	Max retry attempts per record
ALETHEIA_EXPORTER_RETRY_DELAY	1.0	Base delay in seconds (exponential: delay × 2^attempt)
ALETHEIA_EXPORTER_DLQ_SIZE	1000	Max dead-letter queue capacity

WebSocket Audit Stream

Connect to wss://<host>/ws/audit?token=<api_key> for a live, tenant-scoped, PII-redacted stream of audit events. Admin keys see all tenants.

Authentication modes:

1. Admin key — API key with admin role → sees all tenants
2. Short-lived JWT — ?token=<jwt> → signed with ALETHEIA_WS_JWT_SECRET, includes tenant scope and expiry
3. API key — ?token=<api_key> → tenant scoped via key_store

Connection limits: Max ALETHEIA_WS_MAX_PER_TENANT (default: 10) WebSocket connections per tenant. Heartbeat: Sends {"type": "ping", "ts": <epoch>} every ALETHEIA_WS_HEARTBEAT_SECONDS (default: 30s) to keep connections alive.

OTel Trace Context

When OpenTelemetry is installed, audit records automatically include trace_id and span_id fields from the active span. This enables end-to-end trace correlation in Jaeger, Grafana Tempo, or Datadog.

Grafana Dashboard Example

Import the following PromQL queries into a Grafana dashboard:

# Request rate by verdict (graph)
sum(rate(aletheia_requests_total[5m])) by (verdict)

# Blocked actions by reason (pie chart)
sum(aletheia_blocked_actions_total) by (reason)

# P99 decision latency per tenant (graph)
histogram_quantile(0.99, sum(rate(aletheia_decision_latency_seconds_bucket[5m])) by (le, tenant_id))

# Exporter health: errors vs successful exports (graph)
sum(rate(aletheia_exporter_errors_total[5m])) by (backend)
sum(rate(aletheia_audit_events_exported_total[5m])) by (backend)

# DLQ depth (single stat — alert if > 0)
aletheia_exporter_dlq_size

# Active WebSocket connections (gauge)
aletheia_ws_audit_connections

# Per-tenant request volume (table)
sum(rate(aletheia_tenant_requests_total[5m])) by (tenant_id, verdict)

Recommended alerts:

• aletheia_exporter_dlq_size > 0 — dead-letter queue is accumulating (exporter outage)
• rate(aletheia_blocked_actions_total[5m]) > 10 — spike in blocked actions (possible attack)
• aletheia_ws_audit_connections == 0 when expected — SOC dashboard disconnected

Log Retention & Rotation

Audit log files (audit.log by default) grow unbounded. Configure rotation:

1. logrotate (Linux): See deploy/logrotate.conf for a production-ready config
2. Elasticsearch ILM: Set index lifecycle policies for automatic rollover and deletion
3. Splunk: Configure retention policies in the target index

Recommended retention:

• Hot tier: 30 days (full fidelity, searchable)
• Warm tier: 90 days (reduced replicas)
• Cold/archive: 1–7 years (compliance-dependent, consult legal)

---

Architecture Decision Records

ADR-001: Two-tier rate limiting Rate limiting supports two backends. When UPSTASH_REDIS_REST_URL is configured, rate limiting uses Upstash Redis (sliding-window sorted set per IP), synchronizing across workers and surviving restarts. Without Redis, it falls back to an in-memory limiter that resets on restart and does not synchronize across workers. For horizontal scaling without Upstash, place a rate-limiting proxy (nginx, Cloudflare, Traefik) in front.

ADR-002: Threat score discretisation Raw cosine-similarity floats and threat scores are never returned to clients. Returning exact values would let an attacker black-box calibrate their payload against the exact veto threshold. Only discretised bands (LOW / MEDIUM / HIGH / CRITICAL) are exposed.

ADR-003: Startup rejection without receipt signing material The service should not run active mode without configured receipt signing material. An unsigned receipt (UNSIGNED_DEV_MODE) in production would allow an attacker to forge receipts, breaking audit trail integrity. Hard refusal is preferable to degraded operation.

ADR-004: Ed25519 for manifest signing Ed25519 was chosen over RSA for manifest signing: smaller keys, faster verification, no padding oracle attacks, and deterministic signatures. The public key ships with the package; the private key never leaves the operator's control.

---

Architecture Overview

flowchart TB
    subgraph Client["Client Request"]
        REQ["HTTP POST /decide"]
    end

    subgraph InputHardening["Input Hardening Layer"]
        SCHEMA["Pydantic Schema Validation<br/>(strict, extra=forbid)"]
        DRIFT["Bundle Drift Check<br/>(policy_version + manifest_hash)"]
        RATE["Rate Limiting<br/>(Upstash Redis / in-memory)"]
        NORM["Input Normalization<br/>(NFKC, URL/Base64 decode,<br/>confusable collapsing,<br/>entropy quarantine)"]
        DEGRADE["Degraded Mode Gate<br/>(fail-closed for privileged)"]
        INTENT["Semantic Intent Classification<br/>(5 categories + coercion detect)"]
        REPLAY["Replay Defense<br/>(SHA256 token, NX claim)"]
    end

    subgraph TriAgent["Tri-Agent Pipeline"]
        SANDBOX["Sandbox Check<br/>(regex pattern block)"]
        SCOUT["Scout v2<br/>Threat Intelligence<br/>(pattern match, IP rep,<br/>swarm detection)"]
        NITPICKER["Nitpicker v2<br/>Semantic Sanitizer<br/>(static patterns + Qdrant<br/>+ polymorphic rotation)"]
        JUDGE["Judge v1<br/>Policy Enforcer<br/>(Ed25519 manifest +<br/>cosine-sim veto)"]
    end

    subgraph Observability["Observability & Audit"]
        AUDIT["Structured Audit Log<br/>(chain-hashed JSON lines)"]
        RECEIPT["TMR Receipt<br/>(Ed25519 signed, legacy HMAC verified)"]
        EXPORT["Exporters<br/>(ES, Splunk, Webhook, Syslog)<br/>retry + backoff + DLQ"]
        METRICS["Prometheus Metrics<br/>(/metrics endpoint)"]
        WSSTREAM["WebSocket /ws/audit<br/>(JWT + tenant-scoped<br/>+ PII-redacted)"]
    end

    subgraph Decision["Decision Output"]
        PROCEED["PROCEED"]
        DENIED["DENIED"]
    end

    REQ --> SCHEMA --> DRIFT --> RATE --> NORM --> DEGRADE --> INTENT --> REPLAY
    REPLAY --> SANDBOX --> SCOUT --> NITPICKER --> JUDGE
    JUDGE --> PROCEED
    JUDGE --> DENIED
    SCOUT -->|"score ≥ 7.5"| DENIED
    NITPICKER -->|"semantic block"| DENIED
    PROCEED --> AUDIT
    DENIED --> AUDIT
    AUDIT --> RECEIPT
    AUDIT --> EXPORT
    AUDIT --> METRICS
    AUDIT --> WSSTREAM

---

Adversarial Limitations & Transparency

Aletheia Core uses embedding-based semantic similarity (cosine distance against known-bad patterns) as a core detection mechanism. This approach has inherent limitations:

Known Evasion Vectors

Vector	Description	Mitigation
Adversarial rephrasing	Semantically equivalent prompts crafted to fall below cosine-sim thresholds	Grey-zone keyword heuristic, daily alias rotation via ALETHEIA_ALIAS_SALT
Homoglyph injection	Unicode confusables (e.g. Cyrillic 'а' vs Latin 'a')	NFKC normalization + confusable collapsing in input hardening
Payload fragmentation	Splitting malicious intent across multiple benign-looking requests	Cross-source swarm detection (Scout), session correlation
Threshold probing	Black-box iterative queries to map the veto boundary	Opaque decisions (discretised bands only), rate limiting, replay defence
Embedding model attacks	Gradient-based adversarial examples targeting all-MiniLM-L6-v2	Model is local-only (no gradient access), periodic pattern bank augmentation
Multi-language mixing	Combining languages to evade monolingual pattern banks	Partial — current patterns are English-centric; augment for your deployment language

What Aletheia Is NOT

• Not a replacement for human review — for high-stakes actions (financial transfers, auth changes), always require dual-key human sign-off (CEO_RELAY pattern)
• Not a model alignment layer — validates declared intents, not runtime model behavior
• Not an OS-level sandbox — does not intercept system calls; validates at the API boundary
• Not a compliance certification — provides tooling for compliance, not certification itself

Recommended Defense-in-Depth Stack

1. Aletheia Core (this layer) — semantic intent validation + policy enforcement
2. Infrastructure WAF — network-level request filtering (Cloudflare, AWS WAF)
3. Runtime sandbox — container isolation, seccomp profiles, gVisor
4. Human-in-the-loop — mandatory for MEDIUM–HIGH band actions in regulated environments
5. Continuous red-teaming — periodic adversarial testing of pattern banks

---

SOC 2 Readiness Checklist

The following table maps Aletheia Core capabilities to SOC 2 Trust Service Criteria (TSC):

TSC	Control	Aletheia Feature	Status
CC6.1	Logical access controls	Enterprise auth (OIDC/SAML/API key), RBAC, per-tenant isolation	✅ Implemented
CC6.2	Credential management	Secret rotation (SIGUSR1), Vault/AWS/Azure/GCP backends	✅ Implemented
CC6.3	Encryption in transit	HTTPS enforced, HSTS headers, CORS policy	✅ Implemented
CC6.6	Audit logging	Chain-hashed JSON audit log, TMR receipts, 4 export backends	✅ Implemented
CC6.8	Intrusion detection	Scout threat scoring, Nitpicker semantic block, swarm detection	✅ Implemented
CC7.1	Change management	Ed25519-signed policy manifest, drift detection across workers	✅ Implemented
CC7.2	Vulnerability management	Input hardening (NFKC, entropy quarantine), sandbox checks	✅ Implemented
CC7.3	Incident response	Adversarial ML warnings, opaque decisions, rate limiting	✅ Implemented
CC8.1	Availability	Kubernetes HPA, PDB, health/ready probes, circuit breaker	✅ Implemented
A1.2	Recovery	PostgreSQL persistence, Redis HA, graceful degradation	✅ Implemented
PI1.1	Processing integrity	Replay defence (NX token), chain-hashed audit, TMR receipts	✅ Implemented

Gaps requiring operator action:

• Configure a dedicated secrets manager (vault/aws/azure/gcp) — do not use secret_backend=env in production
• Enable FIPS-140 mode (ALETHEIA_FIPS_MODE=true) if required by compliance
• Set up audit log retention policies (see Log Retention section above)
• Deploy behind a TLS-terminating load balancer with valid certificates
• Enable external monitoring (Prometheus + Grafana or equivalent)
• Establish incident response runbook (see docs/INCIDENT_RESPONSE.md)
• Conduct annual penetration testing against the Aletheia API surface

---

Performance Characteristics

Measured on a 2-core VM with the all-MiniLM-L6-v2 model pre-warmed:

Metric	Value	Notes
Cold-start (model load)	~3–8 s	Model downloaded on first use if not cached
Warm-start (subsequent requests)	~12–40 ms p99	Embedding encode dominates
Sandbox check only	< 1 ms	Pure regex, no model
Memory footprint	~500 MB	Dominated by PyTorch + model weights
Rate limit overhead	< 0.1 ms	In-memory list operations with threading.Lock

The embedding model is loaded eagerly at startup (warm_up()) to eliminate cold-start latency on the first production request.

---

Contributing

See CONTRIBUTING.md for guidelines on submitting issues and pull requests.

Security

See SECURITY.md for responsible disclosure policy.

What Aletheia is:

• Runtime enforcement layer — gates agent actions before execution
• Signed audit evidence — tamper-evident receipts on every decision
• One layer in a broader security stack — designed for auditability

What it is not:

• Not a replacement for model alignment
• Not an OS-level sandbox — validates declared intents, not runtime behavior
• Not a compliance certification — consult qualified counsel

License

MIT — Copyright (c) 2026 Ashura Joseph Holeyfield — Aletheia Sovereign Systems