AegisCore

🛡️ AegisCore: The Zero-Trust Deterministic Governance Enclave for AI Agents

[npm version] [npm sdk] [PyPI version] [License] [CI] [Zero-Trust] [DPDP Ready] [Security Policy] [Changelog]

AegisCore is an open-source reverse-proxy, deterministic invariant policy enclave, and cryptographic WORM audit ledger for autonomous AI agents. It intercepts model tool calls, validates them against strict schemas and deterministic invariants, and only executes approved actions within an isolated boundary.

📺 Terminal Showcases & Scenario Deep-Dives

[AegisCore Deterministic Gateway Overview]

📦 Developer Packages & Distribution

⚡ Empirical Performance & Security Audit (v0.1.2)

AegisCore underwent an end-to-end production readiness audit, fault isolation analysis, high-concurrency stress testing, and adversarial penetration testing probing (SkillSpector static analysis & PentAGI-style adversarial evasion probes). Read the complete audit and verification report in AUDIT_REPORT.md.

Verified Micro-Benchmarks (v0.1.2)

[!TIP] Production Readiness Score: 9.8 / 10 (Enterprise), 9.9 / 10 (Startup), 9.9 / 10 (OSS).
Remediations across SEC-01 through SEC-09 (prototype pollution defense, deep nesting DoS protection, persistent session rate-limiting, fail-closed CLI audit verification, lowercase PII tokenization, case-insensitive sanctions enforcement, and non-positive/non-finite transfer boundaries) are verified with 100% test pass rates in Release v0.1.2. See AUDIT_REPORT.md.

⚡ The Core Problem: Why Prompt Guardrails Fail

Modern AI agent architectures couple model intent directly to tool execution. Developers pass raw database connections, payments API credentials, and write privileges directly to the LLM agent runtime:

[User / Jailbreak Prompt] ──> [LLM Model Weights] ──> [Direct Tool Execution] ──> 🔥 Disaster

Why prompt guardrails cannot guarantee security:

1. Probabilistic Non-Determinism: System prompts ("Never delete user records") are probabilistic suggestions, not mathematical guarantees. Adversarial jailbreaks, indirect prompt injections, and context drift routinely bypass prompt instructions.
2. Credential Proliferation: Giving tools directly to the agent exposes infrastructure secrets, database passwords, and third-party API keys to the model runtime.
3. Irreversible Mutations: Once an LLM hallucinates an out-of-bounds transfer or destructive DROP TABLE, the damage is irreversible.

The AegisCore Solution: Strict Intent-Execution Decoupling

AegisCore strips all execution power from the agent. The agent produces only an Intent Proposal. AegisCore evaluates the proposal through a deterministic, zero-trust policy enclave before any downstream code is triggered:

                                  AEGIS-CORE GATEWAY ENCLAVE                             ┌────────────────────────────────────────┐                             │ 1. DPDP PII Tokenizer & Vault          │                             │ 2. Strict Schema Quarantine            │[Agent Intent] ──(Proposal)──>│ 3. Invariant Engine (Rate / Bounds)   │──(Only if APPROVED)──> [Isolated Execution Boundary]                             │ 4. WORM Cryptographic Merkle Chain    │                          │ (Sanitized Env / Timeout)                             │ 5. Asynchronous HITL Escalation Gating │                          ▼                             └────────────────────────────────────────┘                 [Real Backend / DB / API]

📊 Core Architecture

               +-------------------------------------------------------------+               |                       AI AGENT LOOP                         |               |             (LangGraph / MCP / Raw OpenAI)                  |               +-------------------------------------------------------------+                                              |                                     (POST /v1/gateway/dispatch)                                              v+-------------------------------------------------------------------------------------------+|                                 AEGIS-CORE GATEWAY PIPELINE                               ||                                                                                           ||  [Step 1: PII Sanitizer]   ──> Detects PAN, Aadhaar, Phone, Email & tokenizes via salt     ||  [Step 2: Schema Validate] ──> Enforces strict types; extra fields fail closed            ||  [Step 3: Policy Engine]   ──> Invariants: param_boundary, rate_limit, disallowed_targets  ||                                                                                           ||       |                              |                                       |            ||       | (BLOCKED)                    | (REQUIRES_HITL)                       | (APPROVED) ||       v                              v                                       v            ||  [WORM Ledger Entry]        [HITL Challenge Created]                   [WORM Ledger Entry]||  Return 403 Forbidden       Wait for Supervisor Signoff               Dispatch to Sandbox |+------------------------------------------------------------------------------|------------+                                                                               v                                                          +---------------------------------+                                                          |    ISOLATED SANDBOX RUNNER      |                                                          |  - process.env secrets scrubbed |                                                          |  - Hard safety timeout abort    |                                                          |  - Stack trace leak isolation   |                                                          +---------------------------------+                                                                               |                                                                               v                                                                  [Protected Real System]

📐 Architectural Execution Flow: sdk/ ➔ core/ ➔ policies/

AegisCore decouples probabilistic model decisions from irreversible execution by routing every tool call through a deterministic enclave. The monorepo architecture cleanly separates client bindings (sdk/), gateway runtime (core/ & src/), and declarative security invariants (policies/):

flowchart TD    subgraph ClientSDK["Client Enclave Layer (sdk/ & sdk/python)"]        Agent["AI Agent Loop<br/>(LangGraph / CrewAI / OpenAI)"]        AegisClient["AegisClient<br/>(Persistent Session ID, Nonce, Intent Framing)"]        Agent -->|"Tool Call Intent"| AegisClient    end
    subgraph CoreGateway["AegisCore Deterministic Gateway (core/ & src/)"]        Pipeline["Gateway Pipeline (src/gateway/pipeline.ts)<br/>⚡ Cold Start: 0.291 ms"]        PII["Step 1: DPDP Tokenizer (src/privacy/sanitizer.ts)<br/>⚡ Latency: ~12.4 µs"]        Schema["Step 2: Schema Quarantine (src/validator/)<br/>⚡ Latency: ~18.6 µs"]        Engine["Step 3: Invariant Engine (src/policy/engine.ts)<br/>⚡ Latency: ~27.2 µs"]        WORM["Step 4: WORM Audit Ledger (src/audit/ledger.ts)<br/>⚡ Latency: ~19.9 µs"]        HITL["Step 5: HITL Interceptor (src/hitl/interceptor.ts)<br/>Async Ticket Signature"]        Sandbox["Step 6: Ephemeral Sandbox (src/executor/)<br/>process.env Scrubbed | Hard Timeout"]                AegisClient -->|"HTTP POST /v1/gateway/dispatch"| Pipeline        Pipeline --> PII        PII --> Schema        Schema --> Engine    end
    subgraph Policies["Declarative Invariant Packs (policies/)"]        DPDP["dpdp-india.json<br/>(PII Tokenization & DPO Authorization)"]        Fintech["fintech-guardrails.json<br/>(Bounds & Dual-Custody Approval)"]        Banking["banking-policy.json<br/>(Transfer Ceilings & Sanctions)"]        DataGov["data-governance.json<br/>(DDL Quarantine: DROP/TRUNCATE)"]                Engine <-->|"Zero-Trust Rule Matching"| DPDP        Engine <-->|"Zero-Trust Rule Matching"| Fintech        Engine <-->|"Zero-Trust Rule Matching"| Banking        Engine <-->|"Zero-Trust Rule Matching"| DataGov    end
    Engine -->|"BLOCKED (e.g. Sanctions, DDL)"| WORM    WORM -->|"403 Forbidden Response"| AegisClient        Engine -->|"REQUIRES_HITL (> $25,000)"| HITL    HITL -->|"Pending Ticket"| AegisClient
    Engine -->|"APPROVED (Valid Invariants)"| WORM    WORM --> Sandbox    Sandbox -->|"Protected Execution"| Target["Protected DB / Payment Gateways / APIs"]

⏱️ Gateway Interception Latency Breakdown

🚀 60-Second Quickstart

Option A: Local CLI

# Clone and verifygit clone https://github.com/Sandeep-Hipparagi/aegis-core.gitcd aegis-core
# Run full test suite (73 TypeScript tests + 15 Python tests across 24 suites)npm testnpm run test:python
# Start HTTP Gateway daemon on port 8080node --experimental-strip-types bin/aegis.ts start --port 8080

Option B: Docker Compose

# Spin up AegisCore gateway with persistent audit volumedocker compose up -d
# Check healthcurl http://localhost:8080/health# {"status":"healthy","version":"0.1.1"}

Option C: Run Banking Invariant Demonstration

npm run demo:banking

🧩 Model Context Protocol (MCP) Integration

AegisCore provides a native stdio Model Context Protocol (MCP) server.

Claude Desktop Setup

Add AegisCore to your Claude Desktop configuration (claude_desktop_config.json):

macOS / Linux:

{  "mcpServers": {    "aegiscore": {      "command": "node",      "args": ["--experimental-strip-types", "/path/to/AegisCore/bin/aegis.ts", "mcp"]    }  }}

Windows:

{  "mcpServers": {    "aegiscore": {      "command": "node",      "args": ["--experimental-strip-types", "C:\\Users\\username\\Downloads\\AegisCore\\bin\\aegis.ts", "mcp"]    }  }}

Cursor IDE Setup

In Cursor Settings ➔ Features ➔ MCP Servers ➔ Add New MCP Server:

• Name: AegisCore
• Type: command
• Command: node --experimental-strip-types <PATH_TO_AEGISCORE>/bin/aegis.ts mcp

💎 Feature Matrix

🛡️ Pre-Configured Policy Packs

AegisCore ships with enterprise policy packs in /policies:

• policies/dpdp-india.json: Enforces India's Digital Personal Data Protection Act. Restricts bulk customer data exports, blocks unmasked identity table access, and requires Data Protection Officer authorization for customer profile purges.
• policies/fintech-guardrails.json: Enforces transaction ceilings, whitelists operating currencies (USD, EUR, INR, GBP), and requires dual-custody supervisor approval for transactions over $25,000.
• policies/banking-policy.json: Limits autonomous transfers to $10,000, blocks sanctioned/blacklisted destinations, and escalates mid-value transfers.
• policies/data-governance.json: Prohibits destructive DDL statements (DROP TABLE, TRUNCATE) and unauthorized account deletions.

📜 HTTP Gateway API Reference

POST /v1/gateway/dispatch

Submit an intent proposal for evaluation and execution.

curl -X POST http://localhost:8080/v1/gateway/dispatch \  -H "Content-Type: application/json" \  -d '{    "tool": "transfer_funds",    "parameters": {      "amount": 250,      "recipient": "ACC-SUPPLIER-01"    },    "context": {      "sessionId": "sess-prod-001",      "agentId": "copilot-agent",      "role": "finance-operator"    }  }'

POST /v1/hitl/challenges/:ticketId/resolve

Resolve a pending Human-in-the-Loop approval challenge.

curl -X POST http://localhost:8080/v1/hitl/challenges/hitl-uuid-1234/resolve \  -H "Content-Type: application/json" \  -d '{    "decision": "APPROVED",    "approverSignature": "sig-compliance-officer-99"  }'

GET /v1/audit/integrity

Cryptographically verify ledger Merkle chain integrity.

curl http://localhost:8080/v1/audit/integrity# {"isValid":true}

🤝 Contributing

We welcome community contributions! Please review CONTRIBUTING.md for local environment setup, zero-trust invariants, and pull request guidelines.

📄 License

Licensed under the Apache License 2.0. See LICENSE for details.