Aegis Core MCP Server

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

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

Scenario 01: Model Tool Hijack & Data Exfiltration Defense

Threat Vector: Indirect prompt injection instructs an autonomous agent to dump users.credentials.
AegisCore Defense: Deterministic boundary rejection in $<2\text{ ms}$ with 0 CPU cycles or sockets opened to the host database.

Run live: node --experimental-strip-types scripts/demo-scenario-1.js

---

Scenario 02: In-Flight DPDP PII Masking & Cryptographic Shredding

Threat Vector: Agent processes personal identifiers (Indian PAN / Aadhaar), conflicting with statutory Right to Erasure under India's DPDP Act.
AegisCore Defense: In-flight salted tokenization before WORM ledgering. shredVault() enforces complete erasure while preserving 100% of the cryptographic Merkle chain.

Run live: node --experimental-strip-types scripts/demo-scenario-2.js

---

Scenario 03: Cryptographic Merkle Chain & Tamper-Evident Audit

Threat Vector: Retrospective tampering of agent execution logs to conceal unauthorized actions.
AegisCore Defense: Write-Once-Read-Many (WORM) append-only ledger with cryptographic SHA-256 block traversal back to Genesis. Any bit alteration breaks chain validation.

Run live: node --experimental-strip-types scripts/demo-scenario-3.js

---

📦 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]

---

🚀 60-Second Quickstart

Option A: Local CLI

# Clone and verify
git clone https://github.com/Sandeep-Hipparagi/aegis-core.git
cd aegis-core

# Run full test suite (37 tests across 10 suites)
npm test

# Start HTTP Gateway daemon on port 8080
node --experimental-strip-types bin/aegis.ts start --port 8080

Option B: Docker Compose

# Spin up AegisCore gateway with persistent audit volume
docker compose up -d

# Check health
curl 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.