vivekrajsingh04/aegis-ai

## Overview AEGIS is an action-layer security gateway for AI agents. Instead of only checking prompts, it verifies whether each tool call matches the user's declared intent before the action is allowed to run. That makes it useful for agents connected to sensitive systems such as email, healthcare records, financial workflows, internal databases, and compliance-heavy automation. ## Why It Exists Most AI security tools focus on model input and output: User -> Prompt Filter -> LLM -> Tool Call -> External System AEGIS adds a control point around the tool call itself: User Intent -> Intent Manifest -> Proposed Action -> AEGIS Decision -> Execute or Block If a hidden instruction tells an agent to forward private records, move money, delete data, or call an unauthorized endpoint, AEGIS compares that action against the session's intent manifest and blocks or quarantines anything outside scope. ## Core Capabilities | Capability | What it does | | --- | --- | | Intent extraction | Converts the user's request into structured authorization boundaries | | Action evaluation | Checks proposed tool calls before execution | | Policy enforcement | Uses Lobster Trap plus project policies to detect unsafe behavior | | Human review | Routes risky actions to a review queue instead of blindly executing | | Explanation engine | Generates clear reasons for blocked or quarantined actions | | Compliance export | Produces audit-friendly reports for security and governance workflows | ## Quick Start git clone https://github.com/vivekrajsingh04/aegis-ai.git cd aegis-ai python -m venv venv source venv/bin/activate pip install -r requirements.txt cp .env.example .env # Add your GEMINI_API_KEY from https://aistudio.google.com/ uvicorn src.main:app --reload --port 8000 Run the dashboard in a second terminal: cd argus-dashboard pnpm install pnpm dev The dashboard defaults to the local backend at `http://localhost:8000`. ## Architecture flowchart TB A[User Request] --> B[Intent Engine] B --> C[Intent Manifest] C --> D[Policy Enforcement] D --> E{Decision} E -->|Allow| F[Action Executes] E -->|Quarantine| G[Human Review Queue] E -->|Deny| H[Blocked Action] G --> I[Compliance Log] H --> I F --> I style B fill:#2563eb,color:#fff style D fill:#f97316,color:#fff style G fill:#eab308,color:#000 style I fill:#0f766e,color:#fff ## API Example Extract an intent manifest: curl -X POST http://localhost:8000/api/intent/extract \ -H "Content-Type: application/json" \ -d '{"user_input": "Handle my customer complaint emails"}' Evaluate a proposed action: curl -X POST http://localhost:8000/api/action/evaluate \ -H "Content-Type: application/json" \ -d '{"session_id": "sess_123", "action_type": "forward_email", "target": "backup@external.com"}' Example result: { "decision": "quarantine", "risk_score": 0.94, "reason": "Intent mismatch: forward_email not in allowed list", "review_item_id": "rev_abc123" } ## Project Layout aegis-ai/ ├── src/ # FastAPI backend and security pipeline │ ├── intent_engine/ # Intent extraction │ ├── lobster_proxy/ # Policy enforcement │ ├── explanation_engine/ # Explanation generation │ ├── human_gate/ # Review queue │ └── main.py # API entry point ├── argus-dashboard/ # React dashboard ├── configs/ # Policy configuration ├── docs/ # Supporting documentation ├── infrastructure/ # Deployment helpers ├── lobstertrap/ # Lobster Trap integration ├── scripts/ # Utility scripts └── tests/ # Unit tests Some internal directory names are intentionally unchanged for compatibility. ## Deployment Deployment-specific domains and hosted URLs are intentionally left out for now. Add your production frontend and backend URLs when you choose the hosting setup. ## License MIT License. See [LICENSE](LICENSE).