Metadata-Version: 2.4
Name: aegis-core-engine
Version: 0.4.1
Summary: Deterministic, coverage-aware Python security analysis and guarded repair
Project-URL: Source, https://github.com/Abudahem115/aegis-workspace
Project-URL: Issues, https://github.com/Abudahem115/aegis-workspace/issues
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: tree-sitter==0.25.2
Requires-Dist: tree-sitter-python==0.25.0
Requires-Dist: z3-solver==5.0.0.0
Provides-Extra: dev
Requires-Dist: bandit==1.9.4; extra == "dev"
Requires-Dist: pip-audit==2.10.1; extra == "dev"
Requires-Dist: pyright==1.1.411; extra == "dev"
Requires-Dist: ruff==0.16.2; extra == "dev"

# AEGis

AEGis `0.4.1` is a research implementation for deterministic, coverage-aware
security analysis of Python 3.12 projects. Its reviewed rule policy is `4.1.0`.
`aegis scan` reports findings and explicit coverage limitations; a partial or
inconclusive result is **not** evidence that a project is safe. The reviewed
policy covers bounded shapes in eleven CWE families, not all variants of
those families or all vulnerabilities in a project.

Some findings have a guarded repair proposal. AEGis applies a patch only after
security re-verification, functional evidence in an isolated Docker container,
and explicit human approval. When a project has no unittests, a user can provide
and confirm concrete input/output examples for the affected top-level function;
these run temporarily in Docker before and after the patch without creating
project test files. Examples are limited regression evidence, not proof of full
functionality. If the required evidence is absent, AEGis leaves the project
unchanged. It does **not** automatically repair every Top 10 vulnerability form.

The signed `0.4.1` candidate detected **0 of 16** doubly adjudicated real
vulnerabilities in the registered advisory sample and raised **0 false
positives** on the 16 fixed counterparts. All 32 scans were partial and
inconclusive: AEGis abstained rather than claiming safety. This does not
establish useful detection recall for those real-world cases, nor does it
justify a general family-level recall estimate. See the
[0.4.1 release evidence](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docs/evidence/final-release-candidate-0.4.1-2026-10-02.md).

Install the distribution with `pip install aegis-core-engine==0.4.1` and run
the `aegis` command. The distribution name is **not** `aegis`.

The closed CWE-78 profiles also prove call identity before issuing a Finding:
local analysis requires unshadowed built-in `input` and a visible canonical
`import os`; cross-function analysis requires unshadowed built-in `input` and
the canonical `subprocess` import. Identity uncertainty is reported as
`UNKNOWN`/`PARTIAL`, never silently converted into a clean result.

Rule authors should start with
[`core_engine/verifiers/rule_sdk/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/core_engine/verifiers/rule_sdk/README.md).
The exact current security boundary is maintained in
[`docs/security_assurance_baseline.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docs/security_assurance_baseline.md).

## Code organization

AEGis uses one module-level production function per Python file. Private helper
functions follow the same rule; class methods stay with their owning class, and
package `__init__.py` files only expose stable public APIs. An AST-based
architecture test prevents accidental regression.

## Implemented security boundary

- deterministic, fail-closed project discovery;
- project-root containment and symlink-escape rejection;
- streamed entry, file-count, aggregate-byte, regular-file, and 2 MiB per-file
  hard limits;
- one-open immutable file snapshots for downstream parsers;
- identity/metadata checks plus byte-for-byte verification reread through the
  descriptor;
- SHA-256 snapshot identity and configurable line-count warnings.

## Implemented parser boundary

- explicit immutable language-plugin registry with no fallback guessing;
- pinned Tree-sitter Python runtime, grammar, semantic version, and ABI;
- compile-only Python 3.12 semantic syntax validation without code execution;
- linear source-complexity gates before native parsing;
- immutable imports, definitions, calls, bindings, named/anonymous scopes, and
  provenance-bound IR;
- safe module identity from explicit import-root-relative paths;
- conservative indexed multi-file linking with one verified edge per call,
  execution semantics, and reasoned unresolved outcomes.
- killable local parser workers with a 600-second wall deadline and hard
  Windows Job Object/POSIX CPU and memory limits;
- bounded controller/worker JSON and escaped terminal output for untrusted
  project paths and diagnostics.
- optional full-pipeline Docker isolation using a preloaded signed compatible
  image, fixed local socket, immutable image ID, and least-privilege policy.

The authoritative parser contract and its downstream boundary are documented
in [`core_engine/parsers/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/core_engine/parsers/README.md).

The closed verifier boundary, its precise rule scope, and its explicit family
accounting limits are
documented in [`core_engine/verifiers/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/core_engine/verifiers/README.md).

The closed deterministic remediation layer, its conservative versus
containment strategies, temporary full-project replay, Docker regression gate,
HITL approval, final rescan/retest, and strict write/rollback boundary are
documented in
[`core_engine/patchers/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/core_engine/patchers/README.md).

## Local CLI

The local interface runs the implemented analysis stages through verification:

```powershell
aegis doctor
aegis init .
aegis scan .
aegis scan . --isolation container --signing-key C:\release\cosign.pub --signature-bundle C:\release\engine-image.sigstore.json
aegis scan . --format json
aegis scan . --fix
```

`STRUCTURAL FRONT END [PASS]` means discovery, validation, parsing, and linking
completed. `scan` then runs the configured verifier and presents its separate,
bounded verdict. Neither structural success nor an `inconclusive` verifier run
means the analyzed project is secure. See
[`local/cli/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/local/cli/README.md) for the command, JSON, exit-code,
security-boundary, and roadmap contracts.

The Process/Docker worker-v2 contract and signed offline image distribution
workflow are documented in [`local/sandbox/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/local/sandbox/README.md)
and [`docker/scan/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docker/scan/README.md).
Patch-time application tests already use the stricter container boundary
documented in [`local/patching/README.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/local/patching/README.md).

The authoritative contract and guarantee limits are documented in
[`docs/security_assurance_baseline.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docs/security_assurance_baseline.md).
The third-layer closure evidence is recorded in
[`docs/evidence/verifier-family-coverage-milestone-21-2026-08-25.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docs/evidence/verifier-family-coverage-milestone-21-2026-08-25.md).
The current fourth-layer closure evidence is recorded in
[`docs/evidence/patcher-functional-qualification-closure-2026-08-28.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docs/evidence/patcher-functional-qualification-closure-2026-08-28.md).
The current Layer 5 implementation audit and its remaining live Container gate
are recorded in
[`docs/evidence/layer-5-final-audit-2026-08-29.md`](https://github.com/Abudahem115/aegis-workspace/blob/v0.4.1/docs/evidence/layer-5-final-audit-2026-08-29.md).
The earlier security-only record remains as superseded historical evidence.
Earlier milestone records under `docs/evidence/` remain historical evidence;
the normative current boundary is the security assurance baseline above.

## Run the tests

Install the local package, then use the standard library test runner:

```powershell
python -m pip install --require-hashes -r requirements/runtime.lock
python -m pip install --no-build-isolation --no-deps -e .
python -m unittest discover -s tests -t . -v
```

The suite uses the standard-library test runner after installing the pinned
project dependencies. The supported runtime is Python 3.12.
