Aegis is an open-source safety kernel that intercepts AI agent tool calls — database queries, financial transactions, API requests — and verifies them against deterministic invariants before execution. It parses SQL into abstract syntax trees, applies tautology detection via constant folding, enforces numeric bounds, and masks secrets through salted token vaults. All of this happens in-process, typically under 1.5ms for single-statement queries, with no external API calls and no LLM-as-judge dependency.

The core observation behind Aegis: conversational guardrails (toxicity filters, tone moderation) operate on natural language, but the most dangerous agent failures happen at the tool boundary — a DROP TABLE, an unbounded DELETE, a $500,000 wire transfer. These are structural violations, not linguistic ones, and they can be caught deterministically through AST analysis rather than probabilistic classification.

# TypeScript / Node.js
npm install @aegis-kernel/core

# Python 3.9+ (zero dependencies)
pip install aegis-kernel

# MCP (Claude Desktop, Cursor, Windsurf)
npx -y @smithery/cli install sneh-gabani1999/aegis-kernel --client claude

Python — wrap any tool function with a single decorator:

from aegis_kernel import aegis_guard

@aegis_guard(tool_name="database_exec")
def execute_sql(query: str):
    # Blocks DROP TABLE, TRUNCATE, unconstrained DELETE automatically
    return db.execute(query)

TypeScript — wrap MCP or LangChain tool handlers:

import { AegisMCPMiddleware } from '@aegis-kernel/mcp';

const middleware = new AegisMCPMiddleware({
  mode: 'enforce',
  packs: ['@aegis/sql-guard', '@aegis/data-guard']
});
const safeHandler = middleware.wrapToolHandler('database_query', handler);

LangChain / CrewAI:

import { AegisLangChainGuard } from '@aegis-kernel/langchain';

const guard = new AegisLangChainGuard();
const protectedTool = guard.wrap(myExistingTool);

CrewAI / AutoGen / Semantic Kernel / Browser-Use — one line each:

from aegis_kernel_crewai import guard_crew          # pip install aegis-kernel-crewai
from aegis_kernel_autogen import add_aegis_filter   # pip install aegis-kernel-autogen
from aegis_kernel_browser_guard import guard_browser_use_controller  # pip install aegis-kernel-browser-guard

guard_crew(crew)                          # CrewAI: every agent tool guarded
add_aegis_filter(kernel)                  # Semantic Kernel: invocation filter
guard_browser_use_controller(controller)  # Browser-Use: navigation/input/download guards

Aegis operates as a four-tier verification pipeline between the agent's proposed action and actual execution:

  Agent proposes tool call
          │
          ▼
  ┌─────────────────────────────────────────────────────────┐
  │ Tier 1: Lexical normalization (<0.03ms)                 │
  │  Aho-Corasick token scanner · Unicode NFKD sanitizer   │
  │  Zero-width character stripping · Prompt injection      │
  │  heuristic (regex, not ML)                              │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │ Tier 2: AST compilation & semantic validation (<0.15ms) │
  │  Multi-dialect SQL parser (Postgres, MySQL, SQLite,     │
  │  T-SQL) · Tautology constant-folding · Numeric range    │
  │  clamping · PII salted token vault · Policy DSL engine  │
  │  · WASM plugin validator interface (runtime: roadmap)   │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │ Tier 3: Behavioral & temporal analysis (<0.06ms)        │
  │  Agent RBAC · Causal execution DAG · Crescendo drift    │
  │  tracker · Swarm budget ceilings · Circuit breaker      │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │ Tier 4: Cryptographic commitment & explainability       │
  │  SHA-256 proofHash per event · Merkle audit ledger      │
  │  · EU AI Act Art. 13 explainer · Self-healing re-ask    │
  └────────────────────────┬────────────────────────────────┘
                           │
              ┌────────────┴────────────┐
              ▼                         ▼
        ALLOWED (<1ms)           BLOCKED (<1ms)
    Execute + proof receipt   Self-healing feedback

Each tier is designed to fail closed: if any stage throws an internal error, the tool call is blocked by default. The entire hot path makes zero outbound network calls.

Explicitly out of scope: Aegis does not handle conversational tone moderation, hate speech detection, or multimodal content filtering. Those are best served by LLM-based systems like NeMo Guardrails or Llama Guard. Aegis is designed to complement them at the tool boundary.

🏗️ Feature Maturity Notes:

• Zero-Knowledge Proofs: The codebase uses SHA-256 hash commitments, not zk-SNARKs. True Groth16/PLONK proofs are on the roadmap.
• WASM Sandbox: The WasmPluginRunner provides the interface architecture; actual WASM compilation/validation is coming in v1.1.0.
• Enclave Attestation: EnclaveAttestation is a development simulation — set AEGIS_ATTESTATION_MODE=production to request real attestation (AWS Nitro/Intel SGX integration pending). See LIMITATIONS_AND_BOUNDARIES.md and ROADMAP.md for details.

Every published figure is traceable to a committed, reproducible artifact in benchmarks/EVIDENCE.md (corrections register included). Canonical academic datasets (InjecAgent, AgentDojo) are supported via a fail-loud fetch-and-verify pipeline (scripts/fetch-canonical-benchmarks.mjs); headline numbers are reported in the field-standard metrics (ASR / defense rate / benign utility / risk).

Honesty note (2026-08-20): earlier revisions of this README quoted "93.5% InjecAgent resilience" and "86.6% AgentDojo accuracy" as measured on the public academic datasets. Those numbers were not reproducible from any dataset in this repository and have been withdrawn and replaced by the corpus-provenanced figures above. Canonical-dataset runs are pending in network-enabled CI; none will be published until committed with checksummed artifacts. See benchmarks/EVIDENCE.md §3.

Competitor figures reflect vendor-published benchmarks. Trademarks (NVIDIA NeMo Guardrails, Lakera Guard, Guardrails AI) belong to their respective holders; usage does not imply affiliation or endorsement.

Aegis is designed to run as the second stage in a defense-in-depth pipeline:

  User input
      │
      ▼
  Stage 1: Conversational moderation (LLM judge)
  Toxicity, hate speech, brand tone — powered by
  Llama Guard, NeMo Guardrails, or your own model.
      │
      ▼
  LLM Agent proposes tool action
      │
      ▼
  Stage 2: Aegis deterministic clearance (<1.5ms)
  SQL AST, numeric bounds, PII masking, state
  invariants, cryptographic audit proof.
      │
      ├──→ BLOCKED: self-healing feedback to agent
      └──→ ALLOWED: execute + SHA-256 proof receipt

Go and Rust SDKs cover a subset of checks and are not full ports of the TypeScript engine. See each package's README for exact scope.

Turn-key, drop-in guards for every major agent framework — all duck-typed, none pin the framework as a dependency:

git clone https://github.com/Snehgabani/aegis-kernel.git
cd aegis-kernel
npm install
npm run build   # builds all workspace packages (tsup)
npm test        # 674/674 TypeScript tests across 90 files (+11 Python, 17 Go, 8 Rust)

Working examples for common agent deployment patterns:

npx aegis init                    # create aegis.config.yaml
npx aegis doctor                  # health check across all subsystems
npx aegis eval all --output e.json # academic benchmarks (InjecAgent, AgentDojo)
npx aegis scan .                  # scan workspace for prompt injection threats
npx aegis scan-mcp . --pin        # audit MCP server inventories + pin a lock manifest
npx aegis red-team run            # adaptive TAP red-team + tool-poisoning stress
npx aegis test                    # security bounds testbed
npx aegis repl                    # interactive evaluation REPL
npx aegis benchmark --tricky      # statistical benchmark harness
npx aegis audit-report .          # SOC 2 / ISO 42001 self-assessment report
npx aegis explain execute_sql '{"query": "DROP TABLE users"}'
npx aegis stats                   # real-time latency dashboard
npx aegis diagnose execute_sql '{"query": "DELETE FROM users"}'

Real-time SSE token filtering with Aho-Corasick trie sliding window. Aborts the stream early on secret or PII detection:

import { AegisStreamInterceptor } from '@aegis-kernel/core';

const interceptor = new AegisStreamInterceptor(engine, {
  maxPatternLength: 256,
  abortOnMatch: true
});
for await (const chunk of interceptor.intercept(llmTokenStream)) {
  if (chunk.action === 'ABORT') break;
  process.stdout.write(chunk.text);
}

Exponential decay risk scoring for slow-burn privilege escalation:

import { ConversationTracker } from '@aegis-kernel/core';

const tracker = new ConversationTracker({
  driftThreshold: 0.75,
  riskDecayFactor: 0.85
});
const verdict = tracker.addTurn({
  turnIndex: 1,
  toolName: 'exec_cmd',
  params: {},
  riskContribution: 0.3,
  timestamp: Date.now()
});

Tracks data flows across multi-step agent trajectories. Detects exfiltration chains and circular delegation loops (OWASP Agentic Top 10 ASI08):

import { ExecutionDAG } from '@aegis-kernel/core';

const dag = new ExecutionDAG();
dag.addAction({
  id: 'act_1',
  toolName: 'read_file',
  params: { path: '/etc/passwd' },
  dataDependencies: []
});
const anomalies = dag.detectAnomalousPatterns();

A built-in DSL with Cedar-inspired permit/forbid effects and a simple AST condition evaluator. (This is not an AWS Cedar or OPA Rego parser — it draws on similar concepts.)

import { PolicyEngine } from '@aegis-kernel/core';

const policyEngine = new PolicyEngine();
policyEngine.addPolicy({
  id: 'pol_1',
  statements: [{
    effect: 'permit',
    principal: 'support_agent',
    action: 'query_db',
    resource: 'users_table',
    condition: 'row_limit <= 100 && operation == "SELECT"'
  }]
});

Add Aegis as a GitHub Action to audit tool invariants on every pull request:

- name: Aegis Security Audit
  uses: Snehgabani/aegis-kernel@v1
  with:
    config-path: "./aegis.config.yaml"
    mode: "enforce"
    generate-report: "true"

• Fail-closed by default. Internal errors block the tool call. Set failPolicy: 'fail-open' explicitly only if availability matters more than safety for a given pack.
• Zero network egress. The clearance hot path makes no outbound calls. Air-gapped deployments work without modification.
• WASM plugin interface is fail-closed by design (module header/limits validation today; full sandboxed execution is roadmap — see LIMITATIONS_AND_BOUNDARIES.md).
• Cryptographic audit trail. Every clearance decision emits a 14-field privacy-safe event with an immutable SHA-256 proofHash binding tool arguments to policy hashes.

Aegis generates compliance self-assessment evidence exports for SOC 2, HIPAA, and ISO 42001 control frameworks. This is documentation tooling, not a certification — SOC 2 certification requires an independent CPA audit. See COMPLIANCE_SELF_ASSESSMENT.md.

We invite security researchers to test the kernel's deterministic boundaries. Craft a SQL payload under standard @aegis/sql-guard rules that bypasses AST comment-stripping, tautology folding, and mutation checks to execute unauthorized DROP TABLE, TRUNCATE, or unconstrained DELETE/UPDATE.

Report via GitHub Security Advisories or security@aegis-kernel.dev. Verified bypasses receive CVE attribution and permanent recognition.

• Getting Started — Installation, quickstart, and integration tutorials
• API Reference — Exhaustive public classes, inputs, outputs, REST endpoints, and CLI options
• Security User Guide — Secure configuration, operational dos and don'ts
• White Paper — Technical report with threat model and formal proofs
• Interactive Playground — Test invariants live in the browser
• Architecture Docs — Searchable API and policy reference
• Audit Dashboard — Live audit stream with CSV export
• Supply Chain Trust & Provenance — SLSA L3, Sigstore signing, SBOM & reproducible builds
• Elite Automation & Supply Chain Governance — 4-Tier bot mesh, Dependabot topology & continuous assurance
• Security Capabilities & Permissions Disclosure — Socket.dev capability disclosure & dependency justification
• OpenSSF Best Practices Evidence — Criteria mapping for OpenSSF Badge #14173
• Limitations and Boundaries — Honest scope and architectural constraints
• EU AI Act Mapping — Articles 9–15 crosswalk
• Formal Specification — LaTeX mathematical foundations
• 2026 Threat Landscape Report — OWASP MCP attack vectors
• Privacy Policy — Zero-egress data handling
• Ethics Charter — Dual-use policy and civil safety
• Telemetry — Anonymous metrics, opt-out guide, GDPR compliance

See CONTRIBUTING.md for setup, coding standards, and PR requirements. Read CODE_OF_CONDUCT.md before participating. Report vulnerabilities per SECURITY.md.

Questions and bug reports: GitHub Issues

MIT · Copyright (c) 2026 Sneh Gabani