# Aegis MCP

**Security guardrails for AI coding agents powered by threat models**

Aegis is an [MCP server](https://modelcontextprotocol.io/) that gives AI coding agents (Cursor, Claude Code, Cline, Windsurf, etc.) project-specific security requirements in real time. You define your threat model once in a `security-context.yaml` file; every time the agent is about to write security-relevant code, it calls `aegis_assess` and gets back mandatory requirements, approved patterns, and anti-patterns -- deterministically, with zero token cost. After code is generated, `aegis_review` checks requirement-to-implementation completeness before final output.

## Why

AI coding agents write working code fast, but they don't know your project's security rules. They'll generate a login endpoint without your rate-limiting policy, or query a database without your parameterization requirement. Aegis fixes that by injecting your threat model into the agent's workflow at the moment it matters.

- **Deterministic.** Pure structured lookup. No LLM on the hot path, no hallucinated security advice.
- **Project-specific.** Your trust boundaries, your data classifications, your approved patterns.
- **Agent-agnostic.** Works with any MCP-compatible agent.

## Quickstart (2 minutes)

From your project root:

```bash
cd your-project
pip install aegis-mcp
aegis setup
```

`aegis setup` handles setup end-to-end in one command:

- Finds an existing `security-context.yaml` or helps you generate one with your IDE LLM
- Validates the file and loops until it is valid
- Detects your IDE (Cursor, Claude Code, Cline, Windsurf)
- Writes/merges MCP config with the `aegis` server entry
- Installs the matching agent instruction template

When setup completes, start coding. The agent will call `aegis_assess` and `aegis_review` automatically for security-relevant work.

Useful CLI commands:

```bash
aegis validate security-context.yaml
aegis help
aegis about
```

### Manual setup (advanced)

If you prefer to set everything up by hand, see [`docs/quickstart.md`](docs/quickstart.md) and [`docs/generating-security-context.md`](docs/generating-security-context.md).

Reference files:

- `catalogs/security-patterns.yaml` -- comprehensive traditional + LLM code-gen pattern catalog
- `templates/security-context.template.yaml` -- blank schema-shaped template
- `schemas/security-context.schema.json` -- schema contract
- `docs/schema-reference.md` -- field-level reference

Starter contexts from `examples/`:

- `examples/minimal.yaml` -- smallest valid context for first-time setup.
- `examples/rest-api.yaml` -- healthcare-style REST API with PHI-focused guardrails.
- `examples/ecommerce.yaml` -- e-commerce and payments with card-data and checkout controls.
- `examples/internal-tool.yaml` -- internal admin dashboard with role-based controls.
- `examples/microservices.yaml` -- multi-service architecture with mTLS and service-identity controls.
- `examples/security-context.example.yaml` -- comprehensive reference covering most sections.

## How it works

```mermaid
sequenceDiagram
    participant You
    participant Agent as AI Coding Agent
    participant Aegis as Aegis MCP Server

    You->>Agent: "Build a signup endpoint"
    Note over Agent: Reads template instructions
    Note over Agent: Categorizes task into canonical IDs
    Agent->>Aegis: aegis_assess(boundary, data_types, action, ...)
    Aegis->>Agent: Requirements + approved patterns + anti-patterns
    Note over Agent: Writes code following the checklist
    Agent->>Aegis: aegis_review(requirements, self-report mappings)
    Aegis->>Agent: pass: false (missing encrypt-pii-at-rest)
    Note over Agent: Revises code to satisfy missing requirements
    Agent->>Aegis: aegis_review(updated mappings)
    Aegis->>Agent: pass: true (4/4 covered)
    Agent->>You: Delivers secure code
```

1. **You** ask the agent to write code ("Add a user signup endpoint").
2. **The agent** recognizes the task is security-relevant and categorizes it using canonical IDs from `aegis://summary` (e.g. `boundary_crossing: "public-to-internal"`, `data_types: ["user-pii"]`, `action: "create-endpoint"`).
3. **The agent** calls `aegis_assess` with those IDs. Aegis does a deterministic lookup against your `security-context.yaml` and returns all matching requirements, approved patterns, and anti-patterns.
4. **The agent** writes code guided by the returned checklist.
5. **The agent** calls `aegis_review` with the requirements and a self-report of how each was satisfied. If any critical/high requirements are missing, Aegis returns `pass: false` and the agent revises the code.
6. **You** receive code that enforces your project's security rules.

The agent calls `aegis_assess` with the relevant service IDs, data types, boundary crossings, and action (using canonical values from `aegis://summary`, including `known_actions`). Aegis returns:

| Field | Description |
|-------|-------------|
| `requirements` | Mandatory security constraints the generated code must satisfy. |
| `approved_patterns` | Preferred implementations (e.g. "use auth middleware"). |
| `anti_patterns` | Forbidden practices (e.g. "no raw SQL interpolation"). |
| `warnings` | Unknown IDs or potential schema gaps. |
| `conflicts` | When multiple sources disagree on a requirement. |
| `no_match` | `true` if the boundary crossing wasn't found in the context. |

After implementing code, the agent calls `aegis_review` with:

- `requirements` from the latest `aegis_assess` response
- `mappings` entries with `requirement_id` and `satisfied_by`

`aegis_review` returns `covered`, `missing`, `extra_mappings`, `coverage`, and `pass`.

## Tools and resources

| Name | Type | Description |
|------|------|-------------|
| `aegis_assess` | Tool | Returns requirements, approved patterns, and anti-patterns for a given context. Deterministic; no LLM. |
| `aegis_validate` | Tool | Validates a `security-context.yaml` against the schema; reports errors with line numbers. |
| `aegis_review` | Tool | Verifies requirement-to-implementation coverage after code generation using provided mappings. Deterministic completeness check. |
| `aegis://summary` | Resource | Lightweight overview of trust boundaries and data classifications. Read once per session. |

## Advanced

### Practical QA workflow

See [`qa/README.md`](qa/README.md) for a step-by-step benchmark workflow (task suite, manual A/B agent runs, scoring, and aggregate statistics generation).

### Schema reference

See [`docs/schema-reference.md`](docs/schema-reference.md) for the full field reference and contract rules.

### Development

```bash
git clone https://github.com/bgigurtsis/aegis-mcp.git
cd aegis-mcp
pip install -e .
python -m unittest discover -s tests -v
```

## License

MIT