aegis-compliance 0.1.0

Automatic audit trails and compliance reports for AI-assisted development

Aegis

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

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

pip install aegis-cli

Or install from source for development:

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

Requirements: Python 3.11+, git on your PATH.

---

Quick Start

# 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:

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

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

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:

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

---

aegis audit

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:

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

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

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:

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)

# 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

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

For coverage:

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 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.

---

Contributing

See DECISIONS.md for architecture decisions and ROADMAP.md for planned features.