aegis-devops 0.1.0__tar.gz → 0.1.2__tar.gz

aegis_devops-0.1.2/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: aegis-devops
+Version: 0.1.2
+Summary: Provenance-backed, authority-aware policy verifier for agentic DevOps actions.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/moneytool/aegis-devops
+Project-URL: Repository, https://github.com/moneytool/aegis-devops
+Keywords: agentops,agent-security,policy-as-code,provenance,kubernetes,terraform,guardrails,prompt-injection,context-poisoning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-benchmark; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: anthropic; extra == "llm"
+Dynamic: license-file
+
+# Aegis-DevOps — Policy Verifier for AI DevOps Agents
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22950337.svg)](https://doi.org/10.5281/zenodo.22950337)
+[![PyPI](https://img.shields.io/pypi/v/aegis-devops)](https://pypi.org/project/aegis-devops/)
+
+**Provenance-backed, authority-aware guardrails that stop context poisoning and agentic drift
+before an AI agent's `kubectl` or `terraform` action reaches your infrastructure.**
+
+**Keywords:** AI agent security · AgentOps · prompt injection · context poisoning · policy
+enforcement · policy-as-code · Kubernetes · Terraform · OPA · SRE · LLM guardrails ·
+provenance · infrastructure-as-code
+
+![Aegis demo](docs/demo.gif)
+
+## What it does
+
+Aegis intercepts a proposed agent action — a `kubectl`/`terraform`/`aws`/... invocation or a
+plan file — and checks it against a **Constraint Store** before it runs, returning `ALLOW`,
+`BLOCK`, or `ESCALATE` with citations. Unlike a naive policy engine, every constraint in the
+store must independently pass an **integrity check** (has it been tampered with since
+ingestion?) and an **authority check** (was its source ever allowed to assert this kind of
+policy?), so a poisoned Jira ticket or a forged Slack message can't quietly become law. It
+covers 20 CLI/plan targets today — Kubernetes, Terraform/OpenTofu, the three major clouds,
+Helm/ArgoCD/Flux, Git/GitHub, SQL/migrations, and Pulumi — through one shared intent schema.
+
+![Aegis architecture](docs/architecture.svg)
+
+## Quick start
+
+Requires Python 3.11+ (tested on 3.11, 3.13 and 3.14 on Linux and macOS).
+
+```bash
+pip install aegis-devops
+aegis init ./.aegis
+```
+
+`aegis init` writes the example policy files (constraints, authority map, environment map,
+plan constraints, signed sources) into a directory. Putting them in `./.aegis` means the CLI
+finds them with no flags and no environment variable — see [Configuration](docs/configuration.md)
+for the full search order. Then check a command:
+
+```bash
+aegis check kubectl --now 2026-03-16T10:00:00-05:00 --pretty -- \
+    kubectl scale deployment/api-server --replicas=5 -n prod
+```
+
+```
+BLOCK: kubernetes scale deployment/api-server
+  citations: no-scale-prod-peak
+  covered: True  latency_ms: 0.20
+PLAN BLOCK: 1 intent(s)
+STORE: loaded=21 quarantined=0 principals=3
+  warning: using example signing key
+```
+
+The `warning` is real and deliberate: the shipped policy files are signed with a public demo
+key that ships beside them, so the CLI verifies them out of the box while telling you it used
+a key everyone has. `aegis init` prints the two commands that replace it with your own — see
+[Signing](docs/configuration.md#signing). The example rules are a demo, not a starting policy;
+replace `constraints.example.yaml` with your own `constraints.yaml` (a real file wins over the
+`.example` one when both exist).
+
+### From a clone
+
+```bash
+python -m venv venv
+venv/bin/python -m pip install -e ".[dev]"
+venv/bin/python examples/demo.py
+```
+
+`examples/demo.py` runs 15 intents across every supported tool through the interceptor and
+prints each decision, starting with the store's health. A clone already has `data/`, so the CLI
+finds its policy files without `aegis init`.
+
+Exit codes, store health, the Claude Code hook, argv parsing, compound commands, dry runs and
+library usage are all in [`docs/cli.md`](docs/cli.md).
+
+## How a decision is made
+
+![Decision pipeline](docs/decision-pipeline.svg)
+
+At **load time**, `ConstraintStore.load` parses the constraint YAML, verifies each
+`provenance_hash`, and (with `--sources`) re-fetches and checks the original source —
+anything that fails either check is quarantined, not silently dropped.
+
+At **decision time**, `AegisInterceptor.intercept` matches each intent against the surviving
+constraints on `(provider, resource_pattern, action, scope, time_window)`, re-checks integrity
+and authority (authority can be revoked after ingestion), applies any rate limit against the
+decision ledger, downgrades a dry run to `ALLOW`, and takes the highest-precedence effect
+(`BLOCK` > `ESCALATE` > `ALLOW`) among what's left. A `PlanConstraint` then runs once more over
+the whole batch of intents from one plan/chart/invocation.
+
+## Supported tools
+
+Every target below is checked with `aegis check <target> [flags] -- <argv...>`, except
+`terraform`/`tofu`/`pulumi-preview`, which take a JSON document path instead of `--`.
+
+| target | example |
+| :--- | :--- |
+| `kubectl` | `aegis check kubectl -- kubectl scale deployment/api-server --replicas=5 -n prod` |
+| `terraform` | `aegis check terraform plan.json` (from `terraform show -json tfplan > plan.json`) |
+| `tofu` | `aegis check tofu plan.json` (identical plan schema; `provider` stays `terraform`) |
+| `pulumi-preview` | `aegis check pulumi-preview preview.json` (from `pulumi preview --json`) |
+| `pulumi` | `aegis check pulumi -- pulumi destroy --stack prod` |
+| `aws` | `aegis check aws -- aws ec2 terminate-instances --instance-ids i-0abc --region us-east-1` |
+| `az` | `aegis check az -- az aks scale --resource-group rg1 --name aks1 --node-count 5` |
+| `gcloud` | `aegis check gcloud -- gcloud sql instances delete prod-db` |
+| `helm` | `aegis check helm -- helm uninstall api -n prod` |
+| `argocd` | `aegis check argocd -- argocd app sync prod-web --prune` |
+| `flux` | `aegis check flux -- flux reconcile kustomization podinfo -n flux-system` |
+| `git` | `aegis check git -- git push --force origin main` |
+| `gh` | `aegis check gh -- gh workflow run deploy-prod.yml -r main` |
+| `psql` | `aegis check psql -- psql -c "DROP TABLE users;"` |
+| `mysql` | `aegis check mysql -- mysql -e "DROP TABLE users;"` |
+| `sqlite3` | `aegis check sqlite3 -- sqlite3 app.db "DELETE FROM users;"` |
+| `mongosh` | `aegis check mongosh -- mongosh --eval "db.users.drop()"` |
+| `migrate` | `aegis check migrate -- alembic downgrade base` |
+| `sql` | `aegis check sql -- "DROP TABLE users;"` |
+| `argv` | `aegis check argv -- gcloud sql instances delete prod-db` (dispatches by binary name) |
+| `command` | `aegis check command -- "kubectl get pods; sudo kubectl delete node/w1"` (a shell string; see [Compound commands](docs/cli.md#compound-commands)) |
+
+## Results
+
+![Benchmark results](docs/benchmark.svg)
+
+`scripts/benchmark.py` runs Aegis and several baselines over the labeled 500-constraint corpus
+in `data/corpus/` (323 distinct rule structures), on 120 held-out intents, scored against an
+oracle that never imports Aegis's own code. The full table
+(precision/recall/F1, latency, coverage) and methodology are in
+[`docs/benchmark.md`](docs/benchmark.md); the columns that matter most are summarized below.
+
+| verifier | over-block | poison-susceptibility | ps_unauth + pe_unauth |
+| :--- | ---: | ---: | ---: |
+| **aegis** | **0.000** | **0.000** | **0.000** |
+| codex (gpt-6-astra) | 0.150 | 0.300 | 0.200 |
+| codex-gpt-6-sol | 0.150 | 0.300 | 0.200 |
+| codex-gpt-6-luna | 0.117 | 0.233 | 0.100 |
+| claude-cli (haiku) | 0.150 | 0.300 | 0.200 |
+| claude-cli-sonnet | 0.167 | 0.333 | 0.200 |
+| claude-cli-opus | 0.150 | 0.300 | 0.200 |
+| claude-cli-fable | 0.150 | 0.300 | 0.200 |
+| opa-signed | 0.250 | 0.500 | 1.000 |
+| opa | 0.500 | 1.000 | 1.000 |
+| llm-heuristic | 0.500 | 1.000 | 1.000 |
+| ollama (mistral 7B) | 1.000 | 1.000 | 1.000 |
+
+`poison-susceptibility` (`ps + pe`) is the fraction of poisoned rules — constraints an
+unauthorized/tampered/forged author slipped in — that moved a verdict at all, split by kind;
+`ps_unauth + pe_unauth` isolates the realistic pre-ingest attacker (an unauthorized principal).
+It's the headline column because **signing a policy bundle proves it wasn't altered in transit,
+not that its author was ever allowed to write the rule** — `opa-signed` scores `1.000` on it for
+exactly that reason, while Aegis's independent authority check scores `0.000`.
+
+The `codex*` and `claude-cli*` rows are **agent harnesses wrapped around a model**, not raw
+completions — seven models across two vendors (Claude Haiku 4.5, Sonnet 5, Opus 5 and Fable
+5.1; GPT `gpt-6-astra`, `gpt-6-sol` and `gpt-6-luna`), each verified before its run to be the
+model that actually answered — and — unlike the other rows — are scored against a
+100-constraint holdout subset rather than the full 500-constraint store, for context-window and
+cost reasons; see [`docs/benchmark.md`](docs/benchmark.md) before comparing them with anything
+else in the table. Model size and vendor do not change the picture: all seven land between
+0.23 and 0.33 poison-susceptibility, and every one acts on 5 of 8 forged rules — a model can
+reason about who wrote a rule, but not recompute a hash or fetch a source.
+
+## Why not OPA/Gatekeeper?
+
+OPA/Gatekeeper evaluates **structured API objects** against **hand-authored rules**. Aegis
+derives **unstructured human constraints** (from Slack, Jira, Git) and applies
+**authority-driven validation** to the agent's intent *before* it reaches the infrastructure.
+
+## Project status / roadmap
+
+The engine (constraint store, interceptor, environment mapping, dry-run handling, rate limits,
+plan-level constraints, and parsers for every tool in "Supported tools") is complete, and
+v0.1.0 is on PyPI as an **alpha**. Real LLM baselines have been run: Claude Sonnet 5 through
+the API (cached in `results/llm-external.md`), Haiku through the Claude Code CLI, `gpt-6-astra`
+through the Codex CLI, and a local `mistral:latest`.
+
+What is *not* done is the part the threat model leans on hardest. See `PLAN.md §8`, but in
+short: sources are verified against files on disk rather than real Git/Slack/Jira connectors,
+signing uses a shared secret rather than per-principal public keys, and a `principal` is a
+signed name rather than an identity bound to a commit signature or an SSO group. Until those
+land, Aegis demonstrates that the *decision procedure* is sound; it does not yet prove the
+identities feeding it are. Resource matching is also case-sensitive on names. It is not
+production-ready: read `PLAN.md §8` for the full list of open gaps before putting it in front
+of anything you care about.
+
+## Documentation
+
+| Page | Covers |
+| :--- | :--- |
+| [`docs/cli.md`](docs/cli.md) | Exit codes, store health, the Claude Code hook, argv forms, compound commands, dry runs, library usage |
+| [`docs/constraints.md`](docs/constraints.md) | Writing constraints, metadata vocabulary, authority policy, environment mapping |
+| [`docs/configuration.md`](docs/configuration.md) | Configuration/config-dir discovery, signing, source verification, rate limits & ledger |
+| [`docs/benchmark.md`](docs/benchmark.md) | Benchmark methodology, full results table, real LLM baselines, agent-harness baselines, corpus, adversarial suite |
+| [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | Adding a new parser or tool |
+| [`PLAN.md`](PLAN.md) | Design plan and open gaps |
+| [`SECURITY.md`](SECURITY.md) | Reporting a bypass |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
+| [`REVIEW-4.md`](REVIEW-4.md) | Corpus/oracle rewrite (independent oracle, intent-level holdout) |
+
+## Development
+
+```bash
+venv/bin/python -m pytest -q      # 1257 passed (last full green run; CI runs this on 3.11/3.13/3.14)
+venv/bin/python -m ruff check src tests scripts examples
+vhs docs/demo.tape                # regenerate docs/demo.gif
+```
+
+Adding a new parser or tool: see [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md).
+Reporting a bypass: see [`SECURITY.md`](SECURITY.md) — parser evasion is the largest
+attack surface and the most useful thing to report. Release history is in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

aegis_devops-0.1.2/README.md

@@ -0,0 +1,216 @@
+# Aegis-DevOps — Policy Verifier for AI DevOps Agents
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22950337.svg)](https://doi.org/10.5281/zenodo.22950337)
+[![PyPI](https://img.shields.io/pypi/v/aegis-devops)](https://pypi.org/project/aegis-devops/)
+
+**Provenance-backed, authority-aware guardrails that stop context poisoning and agentic drift
+before an AI agent's `kubectl` or `terraform` action reaches your infrastructure.**
+
+**Keywords:** AI agent security · AgentOps · prompt injection · context poisoning · policy
+enforcement · policy-as-code · Kubernetes · Terraform · OPA · SRE · LLM guardrails ·
+provenance · infrastructure-as-code
+
+![Aegis demo](docs/demo.gif)
+
+## What it does
+
+Aegis intercepts a proposed agent action — a `kubectl`/`terraform`/`aws`/... invocation or a
+plan file — and checks it against a **Constraint Store** before it runs, returning `ALLOW`,
+`BLOCK`, or `ESCALATE` with citations. Unlike a naive policy engine, every constraint in the
+store must independently pass an **integrity check** (has it been tampered with since
+ingestion?) and an **authority check** (was its source ever allowed to assert this kind of
+policy?), so a poisoned Jira ticket or a forged Slack message can't quietly become law. It
+covers 20 CLI/plan targets today — Kubernetes, Terraform/OpenTofu, the three major clouds,
+Helm/ArgoCD/Flux, Git/GitHub, SQL/migrations, and Pulumi — through one shared intent schema.
+
+![Aegis architecture](docs/architecture.svg)
+
+## Quick start
+
+Requires Python 3.11+ (tested on 3.11, 3.13 and 3.14 on Linux and macOS).
+
+```bash
+pip install aegis-devops
+aegis init ./.aegis
+```
+
+`aegis init` writes the example policy files (constraints, authority map, environment map,
+plan constraints, signed sources) into a directory. Putting them in `./.aegis` means the CLI
+finds them with no flags and no environment variable — see [Configuration](docs/configuration.md)
+for the full search order. Then check a command:
+
+```bash
+aegis check kubectl --now 2026-03-16T10:00:00-05:00 --pretty -- \
+    kubectl scale deployment/api-server --replicas=5 -n prod
+```
+
+```
+BLOCK: kubernetes scale deployment/api-server
+  citations: no-scale-prod-peak
+  covered: True  latency_ms: 0.20
+PLAN BLOCK: 1 intent(s)
+STORE: loaded=21 quarantined=0 principals=3
+  warning: using example signing key
+```
+
+The `warning` is real and deliberate: the shipped policy files are signed with a public demo
+key that ships beside them, so the CLI verifies them out of the box while telling you it used
+a key everyone has. `aegis init` prints the two commands that replace it with your own — see
+[Signing](docs/configuration.md#signing). The example rules are a demo, not a starting policy;
+replace `constraints.example.yaml` with your own `constraints.yaml` (a real file wins over the
+`.example` one when both exist).
+
+### From a clone
+
+```bash
+python -m venv venv
+venv/bin/python -m pip install -e ".[dev]"
+venv/bin/python examples/demo.py
+```
+
+`examples/demo.py` runs 15 intents across every supported tool through the interceptor and
+prints each decision, starting with the store's health. A clone already has `data/`, so the CLI
+finds its policy files without `aegis init`.
+
+Exit codes, store health, the Claude Code hook, argv parsing, compound commands, dry runs and
+library usage are all in [`docs/cli.md`](docs/cli.md).
+
+## How a decision is made
+
+![Decision pipeline](docs/decision-pipeline.svg)
+
+At **load time**, `ConstraintStore.load` parses the constraint YAML, verifies each
+`provenance_hash`, and (with `--sources`) re-fetches and checks the original source —
+anything that fails either check is quarantined, not silently dropped.
+
+At **decision time**, `AegisInterceptor.intercept` matches each intent against the surviving
+constraints on `(provider, resource_pattern, action, scope, time_window)`, re-checks integrity
+and authority (authority can be revoked after ingestion), applies any rate limit against the
+decision ledger, downgrades a dry run to `ALLOW`, and takes the highest-precedence effect
+(`BLOCK` > `ESCALATE` > `ALLOW`) among what's left. A `PlanConstraint` then runs once more over
+the whole batch of intents from one plan/chart/invocation.
+
+## Supported tools
+
+Every target below is checked with `aegis check <target> [flags] -- <argv...>`, except
+`terraform`/`tofu`/`pulumi-preview`, which take a JSON document path instead of `--`.
+
+| target | example |
+| :--- | :--- |
+| `kubectl` | `aegis check kubectl -- kubectl scale deployment/api-server --replicas=5 -n prod` |
+| `terraform` | `aegis check terraform plan.json` (from `terraform show -json tfplan > plan.json`) |
+| `tofu` | `aegis check tofu plan.json` (identical plan schema; `provider` stays `terraform`) |
+| `pulumi-preview` | `aegis check pulumi-preview preview.json` (from `pulumi preview --json`) |
+| `pulumi` | `aegis check pulumi -- pulumi destroy --stack prod` |
+| `aws` | `aegis check aws -- aws ec2 terminate-instances --instance-ids i-0abc --region us-east-1` |
+| `az` | `aegis check az -- az aks scale --resource-group rg1 --name aks1 --node-count 5` |
+| `gcloud` | `aegis check gcloud -- gcloud sql instances delete prod-db` |
+| `helm` | `aegis check helm -- helm uninstall api -n prod` |
+| `argocd` | `aegis check argocd -- argocd app sync prod-web --prune` |
+| `flux` | `aegis check flux -- flux reconcile kustomization podinfo -n flux-system` |
+| `git` | `aegis check git -- git push --force origin main` |
+| `gh` | `aegis check gh -- gh workflow run deploy-prod.yml -r main` |
+| `psql` | `aegis check psql -- psql -c "DROP TABLE users;"` |
+| `mysql` | `aegis check mysql -- mysql -e "DROP TABLE users;"` |
+| `sqlite3` | `aegis check sqlite3 -- sqlite3 app.db "DELETE FROM users;"` |
+| `mongosh` | `aegis check mongosh -- mongosh --eval "db.users.drop()"` |
+| `migrate` | `aegis check migrate -- alembic downgrade base` |
+| `sql` | `aegis check sql -- "DROP TABLE users;"` |
+| `argv` | `aegis check argv -- gcloud sql instances delete prod-db` (dispatches by binary name) |
+| `command` | `aegis check command -- "kubectl get pods; sudo kubectl delete node/w1"` (a shell string; see [Compound commands](docs/cli.md#compound-commands)) |
+
+## Results
+
+![Benchmark results](docs/benchmark.svg)
+
+`scripts/benchmark.py` runs Aegis and several baselines over the labeled 500-constraint corpus
+in `data/corpus/` (323 distinct rule structures), on 120 held-out intents, scored against an
+oracle that never imports Aegis's own code. The full table
+(precision/recall/F1, latency, coverage) and methodology are in
+[`docs/benchmark.md`](docs/benchmark.md); the columns that matter most are summarized below.
+
+| verifier | over-block | poison-susceptibility | ps_unauth + pe_unauth |
+| :--- | ---: | ---: | ---: |
+| **aegis** | **0.000** | **0.000** | **0.000** |
+| codex (gpt-6-astra) | 0.150 | 0.300 | 0.200 |
+| codex-gpt-6-sol | 0.150 | 0.300 | 0.200 |
+| codex-gpt-6-luna | 0.117 | 0.233 | 0.100 |
+| claude-cli (haiku) | 0.150 | 0.300 | 0.200 |
+| claude-cli-sonnet | 0.167 | 0.333 | 0.200 |
+| claude-cli-opus | 0.150 | 0.300 | 0.200 |
+| claude-cli-fable | 0.150 | 0.300 | 0.200 |
+| opa-signed | 0.250 | 0.500 | 1.000 |
+| opa | 0.500 | 1.000 | 1.000 |
+| llm-heuristic | 0.500 | 1.000 | 1.000 |
+| ollama (mistral 7B) | 1.000 | 1.000 | 1.000 |
+
+`poison-susceptibility` (`ps + pe`) is the fraction of poisoned rules — constraints an
+unauthorized/tampered/forged author slipped in — that moved a verdict at all, split by kind;
+`ps_unauth + pe_unauth` isolates the realistic pre-ingest attacker (an unauthorized principal).
+It's the headline column because **signing a policy bundle proves it wasn't altered in transit,
+not that its author was ever allowed to write the rule** — `opa-signed` scores `1.000` on it for
+exactly that reason, while Aegis's independent authority check scores `0.000`.
+
+The `codex*` and `claude-cli*` rows are **agent harnesses wrapped around a model**, not raw
+completions — seven models across two vendors (Claude Haiku 4.5, Sonnet 5, Opus 5 and Fable
+5.1; GPT `gpt-6-astra`, `gpt-6-sol` and `gpt-6-luna`), each verified before its run to be the
+model that actually answered — and — unlike the other rows — are scored against a
+100-constraint holdout subset rather than the full 500-constraint store, for context-window and
+cost reasons; see [`docs/benchmark.md`](docs/benchmark.md) before comparing them with anything
+else in the table. Model size and vendor do not change the picture: all seven land between
+0.23 and 0.33 poison-susceptibility, and every one acts on 5 of 8 forged rules — a model can
+reason about who wrote a rule, but not recompute a hash or fetch a source.
+
+## Why not OPA/Gatekeeper?
+
+OPA/Gatekeeper evaluates **structured API objects** against **hand-authored rules**. Aegis
+derives **unstructured human constraints** (from Slack, Jira, Git) and applies
+**authority-driven validation** to the agent's intent *before* it reaches the infrastructure.
+
+## Project status / roadmap
+
+The engine (constraint store, interceptor, environment mapping, dry-run handling, rate limits,
+plan-level constraints, and parsers for every tool in "Supported tools") is complete, and
+v0.1.0 is on PyPI as an **alpha**. Real LLM baselines have been run: Claude Sonnet 5 through
+the API (cached in `results/llm-external.md`), Haiku through the Claude Code CLI, `gpt-6-astra`
+through the Codex CLI, and a local `mistral:latest`.
+
+What is *not* done is the part the threat model leans on hardest. See `PLAN.md §8`, but in
+short: sources are verified against files on disk rather than real Git/Slack/Jira connectors,
+signing uses a shared secret rather than per-principal public keys, and a `principal` is a
+signed name rather than an identity bound to a commit signature or an SSO group. Until those
+land, Aegis demonstrates that the *decision procedure* is sound; it does not yet prove the
+identities feeding it are. Resource matching is also case-sensitive on names. It is not
+production-ready: read `PLAN.md §8` for the full list of open gaps before putting it in front
+of anything you care about.
+
+## Documentation
+
+| Page | Covers |
+| :--- | :--- |
+| [`docs/cli.md`](docs/cli.md) | Exit codes, store health, the Claude Code hook, argv forms, compound commands, dry runs, library usage |
+| [`docs/constraints.md`](docs/constraints.md) | Writing constraints, metadata vocabulary, authority policy, environment mapping |
+| [`docs/configuration.md`](docs/configuration.md) | Configuration/config-dir discovery, signing, source verification, rate limits & ledger |
+| [`docs/benchmark.md`](docs/benchmark.md) | Benchmark methodology, full results table, real LLM baselines, agent-harness baselines, corpus, adversarial suite |
+| [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | Adding a new parser or tool |
+| [`PLAN.md`](PLAN.md) | Design plan and open gaps |
+| [`SECURITY.md`](SECURITY.md) | Reporting a bypass |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
+| [`REVIEW-4.md`](REVIEW-4.md) | Corpus/oracle rewrite (independent oracle, intent-level holdout) |
+
+## Development
+
+```bash
+venv/bin/python -m pytest -q      # 1257 passed (last full green run; CI runs this on 3.11/3.13/3.14)
+venv/bin/python -m ruff check src tests scripts examples
+vhs docs/demo.tape                # regenerate docs/demo.gif
+```
+
+Adding a new parser or tool: see [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md).
+Reporting a bypass: see [`SECURITY.md`](SECURITY.md) — parser evasion is the largest
+attack surface and the most useful thing to report. Release history is in
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

{aegis_devops-0.1.0 → aegis_devops-0.1.2}/src/aegis_core/__init__.py

@@ -4,4 +4,4 @@ infrastructure actions of AI agents.
 See the README for what this does and, importantly, what it does not yet do.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{aegis_devops-0.1.0 → aegis_devops-0.1.2}/src/aegis_core/baselines/external.py

@@ -78,6 +78,9 @@ _CODEX_BASE_ARGS = [
 
 _VERDICT_LINE_RE = re.compile(r"^\s*(ALLOW|BLOCK|ESCALATE)\b.*$", re.IGNORECASE | re.MULTILINE)
 _MODEL_BANNER_RE = re.compile(r"^model:\s*(\S+)\s*$", re.MULTILINE)
+# Claude Code's usage-limit reply, e.g. "You've hit your session limit · resets 2:10am".
+_CLAUDE_LIMIT_RE = re.compile(r"(session|usage|rate|weekly) limit|limit reached", re.I)
+_CLAUDE_RESET_RE = re.compile(r"resets?\s+(?:at\s+)?([0-9]{1,2}(?::[0-9]{2})?\s?(?:am|pm)?)", re.I)
 _TOKENS_USED_RE = re.compile(r"tokens used\s*\n\s*([\d,]+)", re.IGNORECASE)
 
 
@@ -154,10 +157,20 @@ class CodexCliClient:
             # <time>") land on stderr, not stdout -- combine both so a
             # quota error doesn't silently look like an empty response.
             combined = stdout + "\n" + stderr if stderr else stdout
+            if re.search(r"usage limit", combined, re.I):
+                when = re.search(r"try again at ([^.\n]+)", combined, re.I)
+                raise QuotaExceededError(
+                    "codex usage limit reached", when.group(1).strip() if when else None
+                )
 
             model_match = _MODEL_BANNER_RE.search(combined)
             if model_match:
                 self.resolved_model = model_match.group(1)
+                if self.model and self.resolved_model != self.model:
+                    raise ModelMismatchError(
+                        f"requested codex model {self.model!r} but the CLI ran "
+                        f"{self.resolved_model!r}"
+                    )
             tokens_match = _TOKENS_USED_RE.search(combined)
             if tokens_match:
                 self.last_tokens_used = int(tokens_match.group(1).replace(",", ""))
@@ -300,6 +313,27 @@ class OllamaClient:
 _AUTH_FAILURE_RE = re.compile(r"\b(401|authenticate|oauth)\b", re.IGNORECASE)
 
 
+class QuotaExceededError(RuntimeError):
+    """The CLI refused the call because the account hit a usage limit.
+
+    ``resets_at`` is the reset time as the CLI printed it ("10:44 PM",
+    "2:10am"), or None. Never retried and never cached, so a runner can wait
+    for the reset and resume from the recorded answers."""
+
+    def __init__(self, message: str, resets_at: str | None = None):
+        super().__init__(message)
+        self.resets_at = resets_at
+
+
+class ModelMismatchError(RuntimeError):
+    """The CLI answered with a different model than the one requested.
+
+    Agent CLIs can fall back to an account default without failing (a ChatGPT
+    account's Codex did exactly that), which would put one model's numbers under
+    another model's name. Never retried: a mismatch is a configuration problem,
+    not a transient one."""
+
+
 class ClaudeCliAuthError(RuntimeError):
     """Raised when ``claude -p`` reports ``is_error: true`` with a result
     that looks like an expired/missing OAuth session (see
@@ -421,8 +455,24 @@ class ClaudeCliClient:
         is_error = bool(envelope.get("is_error"))
         if is_error and _AUTH_FAILURE_RE.search(result_text):
             raise ClaudeCliAuthError("claude CLI is not authenticated: run 'claude login'")
+        if is_error and _CLAUDE_LIMIT_RE.search(result_text):
+            when = _CLAUDE_RESET_RE.search(result_text)
+            raise QuotaExceededError(
+                f"claude usage limit reached: {result_text[:120]}",
+                when.group(1).strip() if when else None,
+            )
 
         self.last_model_usage = envelope.get("modelUsage")
+        family = self.model.lower() if self.model else ""
+        known_family = family in ("haiku", "sonnet", "opus", "fable")
+        if known_family and isinstance(self.last_model_usage, dict):
+            used = list(self.last_model_usage)
+            # Claude Code may also call a small model for side tasks, so require the
+            # requested family to be present rather than to be the only one.
+            if used and not any(f"claude-{family}-" in m for m in used):
+                raise ModelMismatchError(
+                    f"requested claude {family!r} but the CLI reported {used}"
+                )
         self.last_tokens_used = _sum_token_usage(self.last_model_usage)
         self.last_session_id = envelope.get("session_id")
         self.last_num_turns = envelope.get("num_turns")
@@ -474,7 +524,7 @@ class RetryingClient:
         for _ in range(attempts):
             try:
                 return self.inner.complete(system, user)
-            except ClaudeCliAuthError:
+            except (ClaudeCliAuthError, ModelMismatchError, QuotaExceededError):
                 raise
             except RuntimeError as exc:
                 last_exc = exc

{aegis_devops-0.1.0 → aegis_devops-0.1.2}/src/aegis_core/baselines/llm.py

@@ -280,12 +280,29 @@ class RecordingClient:
         self.cache_path = Path(cache_path)
         self.cache_path.parent.mkdir(parents=True, exist_ok=True)
         self.model = model
+        # Resume: answers already on disk are reused, so a run interrupted by a
+        # usage limit continues where it stopped instead of re-asking (and
+        # re-paying for) every prompt. Identical prompts are asked once.
+        self._known: dict[str, str] = {}
+        if self.cache_path.exists():
+            for line in self.cache_path.read_text().splitlines():
+                if line.strip():
+                    row = json.loads(line)
+                    if (row.get("response") or "").strip():
+                        self._known[row["key"]] = row["response"]
+        self.reused = 0
 
     def complete(self, system: str, user: str) -> str:
+        key = _cache_key(system, user, self.model)
+        if key in self._known:
+            self.reused += 1
+            return self._known[key]
+        # A usage-limit error raises out of inner.complete, so it is never cached.
         response = self.inner.complete(system, user)
-        entry = _CacheEntry(key=_cache_key(system, user, self.model), response=response)
+        entry = _CacheEntry(key=key, response=response)
         with open(self.cache_path, "a") as f:
             f.write(json.dumps({"key": entry.key, "response": entry.response}) + "\n")
+        self._known[key] = response
         return response
 
 

{aegis_devops-0.1.0 → aegis_devops-0.1.2}/src/aegis_core/store.py

@@ -838,6 +838,23 @@ class ConstraintStore:
         self.constraints[constraint.id] = constraint
         return constraint
 
+    def _candidates(self, intent: InfrastructureIntent) -> list[Constraint]:
+        """Every loaded constraint that could possibly apply to ``intent``: the
+        ``(provider, action)`` and ``(provider, "*")`` buckets of the index.
+
+        Each matcher below rejects a constraint unless its provider equals the
+        intent's and its actions contain the intent's action or ``"*"``, which is
+        exactly the index key -- so these buckets are a superset of anything any
+        of them can return. All three draw from here so they cannot drift apart,
+        and a decision costs O(k) in the plausible constraints, not O(n) in the
+        store (REVIEW-4 T2.3)."""
+        candidates = self._index.get((intent.provider, intent.action), [])
+        wildcard = self._index.get((intent.provider, ANY_ACTION), [])
+        if wildcard:
+            seen = {id(c) for c in candidates}
+            candidates = candidates + [c for c in wildcard if id(c) not in seen]
+        return candidates
+
     def get_matching_constraints(
         self, intent: InfrastructureIntent, now: datetime
     ) -> list[Constraint]:
@@ -848,14 +865,9 @@ class ConstraintStore:
         constraints that could plausibly match, not O(n) in the whole
         store -- rather than every loaded constraint."""
         _require_tz_aware(now)
-        candidates = self._index.get((intent.provider, intent.action), [])
-        wildcard = self._index.get((intent.provider, ANY_ACTION), [])
-        if wildcard:
-            seen = {id(c) for c in candidates}
-            candidates = candidates + [c for c in wildcard if id(c) not in seen]
         return [
             c
-            for c in candidates
+            for c in self._candidates(intent)
             if _constraint_matches(c, intent, now, self.default_tz, self.tzdata_available)
         ]
 
@@ -867,7 +879,7 @@ class ConstraintStore:
         _require_tz_aware(now)
         return [
             c
-            for c in self.constraints.values()
+            for c in self._candidates(intent)
             if _matches_except_scope(c, intent, now, self.default_tz, self.tzdata_available)
             and env_unresolved(c.scope, intent)
         ]
@@ -884,7 +896,7 @@ class ConstraintStore:
         _require_tz_aware(now)
         return [
             c
-            for c in self.constraints.values()
+            for c in self._candidates(intent)
             if time_window_unresolved(c, intent, now, self.default_tz, self.tzdata_available)
         ]