Metadata-Version: 2.4
Name: aegis-compliance
Version: 0.1.0
Summary: Automatic audit trails and compliance reports for AI-assisted development
Author: Aegis Contributors
License: Apache-2.0
Project-URL: Repository, https://github.com/Gen-Crafter/aegis.git
Project-URL: Documentation, https://github.com/Gen-Crafter/aegis#readme
Keywords: compliance,audit,ai,claude,soc2,governance
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: jinja2>=3.1
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Dynamic: license-file

# Aegis

> Automatic audit trails and compliance reports for AI-assisted development.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

Aegis is a local CLI tool that turns your AI coding agent's activity into automatic, policy-mapped audit trails and compliance reports — so your team can prove AI-assisted development follows your own written rules, without changing how you work.

**Install in under 10 minutes. Works 100% offline. No accounts, no telemetry.**

---

## What It Does

| Command | What it does |
|---|---|
| `aegis init` | Set up `.aegis/` in your repo with a default policy file |
| `aegis check` | Scan your current code changes against your policy rules |
| `aegis audit` | Read your latest Claude Code session and produce a redacted audit trail |
| `aegis report` | Generate a 30-day compliance report suitable for SOC 2 evidence |
| `aegis install-hook` | Block commits that violate blocking-severity rules |

---

## Installation

```bash
pip install aegis-cli
```

Or install from source for development:

```bash
git clone https://github.com/your-org/aegis
cd aegis
pip install -e ".[dev]"
```

**Requirements:** Python 3.11+, `git` on your PATH.

---

## Quick Start

```bash
# 1. From your project root (must be a git repo):
aegis init

# 2. Make some code changes, then check them:
aegis check

# 3. After a Claude Code session, generate an audit trail:
aegis audit

# 4. Generate a 7-day compliance report:
aegis report --since 7d

# 5. (Optional) Auto-block commits that violate blocking rules:
aegis install-hook
```

---

## The "Constitution" — Your Policy File

After `aegis init`, edit `.aegis/constitutions/default.yaml` to define your team's rules:

```yaml
name: "My Team's AI Policy"
version: 1
rules:
  - id: NO_HARDCODED_SECRETS
    description: "Code must not contain hardcoded API keys, passwords, or tokens"
    severity: blocking        # blocks commit if violated
    check_type: pattern
    pattern: "(?i)api_key\\s*[:=]\\s*['\"]?[A-Za-z0-9+/\\-_]{8,}"
    applies_to: ["*.py", "*.js", "*.ts"]

  - id: NO_DIRECT_MAIN_PUSH
    description: "No direct commits to main or master branch"
    severity: blocking
    check_type: git_branch_guard
    protected_branches: [main, master]

  - id: TESTS_FOR_NEW_FUNCTIONS
    description: "New functions should have corresponding test changes"
    severity: warning         # shown but does not block
    check_type: heuristic_test_coverage
```

**Severity levels:**
- `blocking` — `aegis check` exits non-zero; the pre-commit hook blocks the commit
- `warning` — shown in output but doesn't block
- `info` — logged to report only

**Check types (v1):**
- `pattern` — regex match over added diff lines; add `applies_to` file globs to scope it
- `git_branch_guard` — checks current branch against `protected_branches`
- `heuristic_test_coverage` — warns when new functions have no matching test file changes

---

## CLI Reference

### `aegis init`

```bash
aegis init          # initialize .aegis/ in current directory
aegis init --force  # reinitialize (overwrite existing config)
```

Creates:
- `.aegis/config.yaml` — configuration file
- `.aegis/constitutions/default.yaml` — your policy file (edit this)
- `.aegis-reports/checks/` — one file per `aegis check` run
- `.aegis-reports/audits/` — one file per `aegis audit` run
- `.aegis-reports/compliance/` — output of `aegis report`

---

### `aegis check`

```bash
aegis check                          # check working tree vs HEAD
aegis check --range main..HEAD       # check all commits on current branch vs main
aegis check --range commitA..commitB # check a specific commit range
```

**Exit codes:**
- `0` — all checks passed (or only warnings)
- `1` — one or more `blocking` rules failed

**Use in CI:**

```yaml
# GitHub Actions example
- name: Aegis policy check
  run: aegis check --range origin/main..HEAD
```

---

### `aegis audit`

```bash
aegis audit                          # most recent Claude Code session
aegis audit --session <id>           # specific session ID
aegis audit --session /path/to/file.jsonl  # specific file
aegis audit --all                    # all available sessions
```

Aegis auto-detects Claude Code session logs at:
- **Windows:** `%APPDATA%\Claude\projects\**\*.jsonl`
- **macOS/Linux:** `~/.claude/projects/**/*.jsonl`

If auto-detection fails, set the path in `.aegis/config.yaml`:

```yaml
claude_code_session_path: "/custom/path/to/session/logs"
```

**All output is automatically redacted** — potential secrets are replaced with `[REDACTED:<type>]` before anything is written to disk.

---

### `aegis report`

```bash
aegis report                         # last 7 days (default)
aegis report --since 30d             # last 30 days
aegis report --since 2w              # last 2 weeks
aegis report --since 2026-06-01      # since a specific date
aegis report --since 7d --html       # also generate HTML version
```

The report is written to `.aegis-reports/compliance/compliance-<timestamp>.md`.
With `--html`, also writes `.aegis-reports/compliance/compliance-<timestamp>.html`.

The HTML report is fully self-contained (inline CSS, no JavaScript) — suitable for email attachment or printing to PDF.

---

### `aegis install-hook`

```bash
aegis install-hook           # install pre-commit hook
aegis install-hook --force   # reinstall (overwrite existing)
```

Installs a git pre-commit hook at `.git/hooks/pre-commit` that runs `aegis check` before every commit. If a `blocking` rule fails, the commit is aborted.

To remove: delete `.git/hooks/pre-commit` or remove the `# >>> aegis` section if you have other hooks.

---

## Configuration Reference

`.aegis/config.yaml`:

```yaml
constitutions:
  - .aegis/constitutions/default.yaml
  # Add more files to combine multiple constitutions:
  # - .aegis/constitutions/client-specific.yaml

claude_code_session_path: null  # null = auto-detect

output:
  reports_dir: .aegis-reports
```

---

## Git Integration

### Add reports to `.gitignore` (or commit them)

```gitignore
# Option 1: ignore everything
.aegis-reports/

# Option 2: commit compliance reports but ignore granular data
.aegis-reports/checks/
.aegis-reports/audits/
# (leave .aegis-reports/compliance/ out of .gitignore to commit reports)
```

Many teams commit `compliance/` reports as audit evidence while ignoring the more granular `checks/` and `audits/` files.

---

## Running Tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

For coverage:

```bash
pytest tests/ --cov=aegis --cov-report=term-missing
```

---

## GRC Compliance Value

| Framework | Controls Supported |
|---|---|
| **SOC 2 Type II** | CC6.1 (Logical Access), CC7.2 (Monitoring), CC9.2 (Risk Mitigation) |
| **ISO 27001** | A.8.1 (Asset Management), A.12.4 (Logging), A.14.2 (Secure Development) |
| **EU AI Act** | Article 12 — Automated logging of AI system events |
| **NIST AI RMF** | GOVERN 1.1, MANAGE 2.2 |

---

## Security

- **No telemetry.** Aegis never makes network requests. All data stays on your machine.
- **Conservative redaction.** Aegis over-redacts rather than under-redacts. If it catches something that isn't a secret, adjust your constitution.
- **Redaction on every event.** Session content is redacted before being stored anywhere — including in-memory objects. There is no `--skip-redaction` flag.

---

## FAQ

**Does Aegis send my code anywhere?**
No. Everything runs locally and writes to files in your project directory.

**What if the redaction catches false positives?**
Adjust patterns in your constitution, or change severity to `warning` while you tune it. The `high_entropy_value` pattern (catches long base64 strings) is the most likely source of false positives.

**Can I use this with Cursor, Devin, or Windsurf?**
Not yet — v1 supports Claude Code session logs only. `aegis check` and `aegis report` work regardless of which agent you use (they operate on git diffs). See [ROADMAP.md](ROADMAP.md) for the agent adapter roadmap.

**Where are my reports?**
In `.aegis-reports/` within your project. Run `aegis report` to see a combined summary.

---

## License

Apache 2.0 — see [LICENSE](LICENSE).

---

## Contributing

See [DECISIONS.md](DECISIONS.md) for architecture decisions and [ROADMAP.md](ROADMAP.md) for planned features.
