{"id":46506760,"url":"https://github.com/justin0504/aegis","last_synced_at":"2026-03-06T15:01:52.453Z","repository":{"id":341965432,"uuid":"1172197625","full_name":"Justin0504/Aegis","owner":"Justin0504","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-04T04:28:27.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T09:43:53.949Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Justin0504.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-04T03:24:33.000Z","updated_at":"2026-03-04T04:28:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Justin0504/Aegis","commit_stats":null,"previous_names":["justin0504/aegis"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Justin0504/Aegis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Justin0504%2FAegis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Justin0504%2FAegis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Justin0504%2FAegis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Justin0504%2FAegis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Justin0504","download_url":"https://codeload.github.com/Justin0504/Aegis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Justin0504%2FAegis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30182686,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T14:42:24.748Z","status":"ssl_error","status_checked_at":"2026-03-06T14:42:14.925Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-06T15:00:54.137Z","updated_at":"2026-03-06T15:01:52.447Z","avatar_url":"https://github.com/Justin0504.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# AEGIS\n\n**Your AI agent tried to `DROP TABLE users`. AEGIS stopped it.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI](https://img.shields.io/pypi/v/agentguard-aegis?label=PyPI\u0026color=blue)](https://pypi.org/project/agentguard-aegis/)\n[![npm](https://img.shields.io/badge/npm-%40justinnn%2Fagentguard-red)](https://www.npmjs.com/package/@justinnn/agentguard)\n[![Docker](https://img.shields.io/badge/ghcr.io-aegis--gateway-0db7ed)](https://github.com/Justin0504/Aegis/pkgs/container/aegis-gateway)\n\n*Pre-execution blocking · Human-in-the-loop approvals · Cryptographic audit trail · 9 frameworks · Zero code changes*\n\n\u003c/div\u003e\n\n---\n\n## The problem\n\nAI agents are powerful and unpredictable. They can:\n\n- Delete your database because a prompt said \"clean up old records\"\n- Exfiltrate gigabytes of data because \"the user asked for a report\"\n- Execute arbitrary shell commands because the model hallucinated a tool name\n\nLogging what happened is not enough. You need to **stop it before it happens**.\n\n---\n\n## 30-second setup\n\n```bash\ngit clone https://github.com/Justin0504/Aegis\ncd Aegis\ndocker compose up -d\n```\n\n| Service | URL |\n|---------|-----|\n| **Compliance Cockpit** | http://localhost:3000 |\n| **Gateway API** | http://localhost:8080 |\n\nThen add **one line** to your agent:\n\n```python\nimport agentguard\nagentguard.auto(\"http://localhost:8080\", agent_id=\"my-agent\")\n\n# Everything below is unchanged — no decorators, no wrappers\nimport anthropic\nclient = anthropic.Anthropic()\nresponse = client.messages.create(model=\"claude-opus-4-6\", tools=[...], messages=[...])\n```\n\nOr **zero lines** with an env var:\n\n```bash\nAGENTGUARD_URL=http://localhost:8080 python your_agent.py\n```\n\nThat's it. Every tool call is now classified, policy-checked, cryptographically signed, and logged — before execution.\n\n---\n\n## How it works\n\n```\n  Your agent calls a tool\n          │\n          ▼  (SDK intercepts at the LLM response level)\n  ┌────────────────────────────────────────────────┐\n  │  AEGIS Gateway                                 │\n  │                                                │\n  │  ① Classify tool   (SQL? file? network? shell?) │\n  │  ② Match policies  (injection? exfil? traversal?)│\n  │  ③ Decide: allow / block / pending             │\n  └──────────┬─────────────────────────────────────┘\n             │\n      ┌───────┴──────────────┐\n      │                      │\n   allow                  pending ──► Human reviews in dashboard\n      │                      │               │\n      ▼                      └──── allow ────┘\n  Tool executes                         │\n      │                              block\n      ▼                                 │\n  Signed (Ed25519)                      ▼\n  Hash-chained (SHA-256)      AgentGuardBlockedError\n  Stored in dashboard\n```\n\n**The classifier works on any tool name — zero configuration required.**\n\n| Tool called | Detected as | Why |\n|-------------|-------------|-----|\n| `run_query(sql=\"SELECT...\")` | `database` | SQL keyword in args |\n| `my_tool(path=\"/etc/passwd\")` | `file` | sensitive path |\n| `do_thing(url=\"http://...\")` | `network` | URL in args |\n| `helper(cmd=\"rm -rf /\")` | `shell` | command injection signal |\n| `custom_fn(prompt=\"ignore previous...\")` | all | prompt injection |\n\n---\n\n## Blocking mode\n\nWhen your agent attempts a HIGH or CRITICAL risk action, **it pauses**. You decide.\n\n```python\nagentguard.auto(\n    \"http://localhost:8080\",\n    blocking_mode=True,            # hold dangerous calls for review\n    human_approval_timeout_s=300,  # auto-block after 5 min with no decision\n)\n```\n\nThe agent waits. You open the dashboard, see the exact arguments it was about to use, and click **Allow** or **Block**. The agent resumes in under a second.\n\n```python\nfrom agentguard import AgentGuardBlockedError\n\ntry:\n    response = client.messages.create(...)\nexcept AgentGuardBlockedError as e:\n    print(f\"Blocked: {e.tool_name} — {e.reason} ({e.risk_level})\")\n```\n\n---\n\n## Why AEGIS over the alternatives?\n\nEvery other agent observability tool tells you **what happened**. AEGIS **prevents it**.\n\n|  | LangFuse | Helicone | Arize | AEGIS |\n|--|----------|----------|-------|-------|\n| Observability dashboard | ✅ | ✅ | ✅ | ✅ |\n| **Pre-execution blocking** | ❌ | ❌ | ❌ | ✅ |\n| **Human-in-the-loop approvals** | ❌ | ❌ | ❌ | ✅ |\n| **Auto-classifies any tool name** | ❌ | ❌ | ❌ | ✅ |\n| **Ed25519 signed audit trail** | ❌ | ❌ | ❌ | ✅ |\n| **SHA-256 tamper-evident chain** | ❌ | ❌ | ❌ | ✅ |\n| **Kill switch** | ❌ | ❌ | ❌ | ✅ |\n| **Natural language policy editor** | ❌ | ❌ | ❌ | ✅ |\n| **Claude Desktop MCP integration** | ❌ | ❌ | ❌ | ✅ |\n| **Slack / PagerDuty alerts** | ❌ | ❌ | ❌ | ✅ |\n| Self-hostable | ✅ | ❌ | ❌ | ✅ |\n\n---\n\n## SDK support — 9 frameworks, zero code changes\n\n```bash\npip install agentguard-aegis\n```\n\n| Framework | Status |\n|-----------|--------|\n| Anthropic | ✅ auto-patched |\n| OpenAI | ✅ auto-patched |\n| LangChain / LangGraph | ✅ auto-patched |\n| CrewAI | ✅ auto-patched |\n| Google Gemini | ✅ auto-patched |\n| AWS Bedrock | ✅ auto-patched |\n| Mistral | ✅ auto-patched |\n| LlamaIndex | ✅ auto-patched |\n| smolagents | ✅ auto-patched |\n\n**JavaScript / TypeScript:**\n\n```bash\nnpm install @justinnn/agentguard\n```\n\n```typescript\nimport agentguard from '@justinnn/agentguard'\nagentguard.auto('http://localhost:8080', { agentId: 'my-agent', blockingMode: true })\n// existing Anthropic / OpenAI / LangChain code unchanged\n```\n\n**Go:**\n\n```bash\ngo get github.com/Justin0504/Aegis/packages/sdk-go@latest\n```\n\n```go\nimport agentguard \"github.com/Justin0504/Aegis/packages/sdk-go\"\n\nguard := agentguard.Auto() // reads AGENTGUARD_URL, AGENTGUARD_AGENT_ID env vars\ndefer guard.Close()\n\nresult, err := guard.Wrap(\"query_db\", args, func() (any, error) {\n    return db.Query(\"SELECT ...\")\n})\n\nvar blocked *agentguard.BlockedError\nif errors.As(err, \u0026blocked) {\n    log.Printf(\"Blocked: %s — %s\", blocked.ToolName, blocked.Reason)\n}\n```\n\nZero external dependencies. Standard library only.\n\n---\n\n## OpenTelemetry export\n\nEvery AEGIS trace can be forwarded as an OTEL span to Datadog, Grafana, Jaeger, or any OTLP-compatible collector:\n\n```bash\nOTEL_ENABLED=true \\\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \\\nOTEL_SERVICE_NAME=aegis-gateway \\\nnode dist/server.js\n```\n\nEach span is named `tool_call/\u003ctool_name\u003e` and carries these attributes:\n\n| Attribute | Value |\n|-----------|-------|\n| `aegis.agent_id` | agent identifier |\n| `aegis.tool_name` | tool being called |\n| `aegis.risk_level` | LOW / MEDIUM / HIGH / CRITICAL |\n| `aegis.blocked` | true if the call was blocked |\n| `aegis.cost_usd` | estimated LLM cost |\n| `aegis.pii_detected` | 1 if PII was found in arguments |\n\nOTEL errors are silently ignored — they never break your agent's execution path.\n\n---\n\n## Policy engine\n\nFive policies ship by default. **Any** tool gets classified — no configuration needed.\n\n| Policy | Risk | Blocks |\n|--------|------|--------|\n| SQL Injection Prevention | HIGH | `DROP`, `DELETE`, `TRUNCATE` in DB tools |\n| File Access Control | MEDIUM | path traversal, `/etc/`, `/root/` |\n| Network Access Control | MEDIUM | HTTP (non-HTTPS) requests |\n| Prompt Injection Detection | CRITICAL | \"ignore previous instructions\" patterns |\n| Data Exfiltration Prevention | HIGH | large payloads to external endpoints |\n\n**Write policies in plain English** — the AI assistant converts them automatically:\n\n\u003e *\"Block all file deletions outside the /tmp directory\"*\n\u003e → Generates JSON schema + risk level + description instantly\n\nOr write them manually via the dashboard or API:\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/policies \\\n  -H 'Content-Type: application/json' \\\n  -H 'x-api-key: YOUR_KEY' \\\n  -d '{\n    \"id\": \"no-prod-deletes\",\n    \"name\": \"No Production Deletes\",\n    \"risk_level\": \"CRITICAL\",\n    \"policy_schema\": {\n      \"properties\": { \"sql\": { \"not\": { \"pattern\": \"DELETE|TRUNCATE\" } } }\n    }\n  }'\n```\n\nMap your own tool names to categories:\n\n```python\nagentguard.auto(\n    \"http://localhost:8080\",\n    tool_categories={\n        \"my_query_runner\": \"database\",\n        \"send_email\":      \"communication\",\n        \"s3_upload\":       \"network\",\n    }\n)\n```\n\n---\n\n## Compliance Cockpit\n\nReal-time visibility and control over every agent action:\n\n- **Live trace stream** — every tool call as it happens, with risk level and classification\n- **Pending approvals** — one-click allow/block for human-in-the-loop checks\n- **Agent behavior baseline** — 7-day profile per agent: top tools, risk distribution, PII rate\n- **Anomaly detection** — automatic flagging of spikes, error bursts, unusual patterns\n- **Cost tracking** — token usage and USD cost per agent, per session, per tool\n- **PII detection** — automatic redaction of sensitive data in traces\n- **Alert rules** — threshold-based alerts with Slack, PagerDuty, or webhook delivery\n- **Forensic export** — PDF compliance reports and CSV audit bundles\n- **Policy editor** — create and toggle policies, with AI-assisted generation\n- **Kill switch** — manual or automatic agent revocation after N violations\n\n---\n\n## Claude Desktop integration (MCP)\n\nAEGIS exposes its audit data as MCP tools. Ask Claude about your agents directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"aegis\": {\n      \"url\": \"ws://localhost:8080/mcp-audit\"\n    }\n  }\n}\n```\n\nAvailable tools: `query_traces`, `list_violations`, `get_agent_stats`, `list_policies`\n\n\u003e *\"What did agent X do in the last hour?\"* → Claude queries AEGIS and tells you.\n\n---\n\n## Security model\n\n```\nTool call received\n  → Pre-execution check      (block before damage — zero tolerance for CRITICAL)\n  → Tool executes            (if allowed)\n  → Ed25519 signature        (optional, per-agent keypair)\n  → SHA-256 hash chain       (each trace commits to the previous)\n  → Kill switch              (3 violations in 1h → auto-revoke)\n  → Immutable audit log      (cryptographically verifiable by any third party)\n```\n\nGateway API is protected by an auto-generated API key — management endpoints require authentication, SDK ingest endpoints remain open so agents work without configuration.\n\n---\n\n## Precision controls\n\nNot everything needs to be blocked. Fine-tune with:\n\n```python\nagentguard.auto(\n    \"http://localhost:8080\",\n    block_threshold=\"HIGH\",          # only block HIGH and CRITICAL (default)\n    allow_tools=[\"read_file\"],       # always allow these specific tools\n    allow_categories=[\"network\"],    # always allow all network tools\n    audit_only=True,                 # log everything, block nothing\n)\n```\n\n---\n\n## Self-hosting\n\nMIT-licensed. No telemetry. No data leaves your infrastructure.\n\n```\npackages/\n  gateway-mcp/          Node.js gateway (Express + SQLite)\n  sdk-python/           pip install agentguard-aegis\n  sdk-js/               npm install @justinnn/agentguard\n  sdk-go/               go get github.com/Justin0504/Aegis/packages/sdk-go\n  core-schema/          shared TypeScript types\n\napps/\n  compliance-cockpit/   Next.js dashboard\n```\n\n**Docker Compose (recommended):**\n```bash\ndocker compose up -d\n```\n\n---\n\n## Contributing\n\nIssues and PRs welcome.\n\n```bash\ngit clone https://github.com/Justin0504/Aegis\ncd Aegis\ndocker compose -f docker-compose.dev.yml up\n```\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustin0504%2Faegis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustin0504%2Faegis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustin0504%2Faegis/lists"}