aegis-core-engine

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.

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. The exact current security boundary is maintained in 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.

The closed verifier boundary, its precise rule scope, and its explicit family accounting limits are documented in 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.

Local CLI

The local interface runs the implemented analysis stages through verification:

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 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 and docker/scan/README.md. Patch-time application tests already use the stricter container boundary documented in local/patching/README.md.

The authoritative contract and guarantee limits are documented in docs/security_assurance_baseline.md. The third-layer closure evidence is recorded in 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. 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. 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:

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.