69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
# Architecture
|
|
|
|
## Design goals
|
|
|
|
AAISA prioritizes inspectability, deterministic evidence, safe handling of untrusted artifacts, and low barriers for research contributors. The initial implementation uses only the Python standard library and keeps discovery, normalization, policy evaluation, and reporting separate.
|
|
|
|
## Scan data flow
|
|
|
|
```text
|
|
approved path
|
|
|
|
|
v
|
|
safe discovery -> immutable artifact evidence -> independent rules -> filtered findings
|
|
|
|
|
v
|
|
JSON or SARIF
|
|
|
|
|
v
|
|
human review
|
|
```
|
|
|
|
## Trust boundaries
|
|
|
|
The scan root is untrusted input. File names, content, encodings, and metadata can be malicious. AAISA therefore does not execute artifacts, does not follow symbolic links, applies a size limit before reading content, decodes text with replacement, and isolates rule failures as scan errors.
|
|
|
|
The configuration and enabled-rule set are trusted operator inputs. Reports are security-sensitive outputs even though known secret matches are redacted.
|
|
|
|
## Extension contract
|
|
|
|
A rule exposes an identifier, title, description, default severity, and an `evaluate(artifact)` method. It returns zero or more immutable findings. A rule must be deterministic for the same artifact and configuration, must not mutate the artifact, must not perform network access, and must never place a matched credential value into a finding.
|
|
|
|
Future parser and analyzer plugins will require a versioned interface and explicit isolation policy before they are loaded dynamically.
|
|
|
|
## Evaluation data flow
|
|
|
|
```text
|
|
versioned manifest + immutable fixtures
|
|
|
|
|
v
|
|
path and schema validation
|
|
|
|
|
v
|
|
one isolated scan per test case
|
|
|
|
|
v
|
|
expected counts <-> observed counts
|
|
|
|
|
v
|
|
case verdicts + TP/FP/FN + precision/recall + corpus digest
|
|
```
|
|
|
|
Evaluation manifests cannot reference files outside their corpus directory. Every fixture contributes its relative path and SHA-256 digest to the reported corpus identity. Output is deterministic for the same tool version, manifest, and fixture bytes.
|
|
|
|
## Structured artifact rules
|
|
|
|
JSON analyzers parse content as data and never import or execute it. The foundation recognizes agent manifests, SLSA provenance statements, and CycloneDX ML-BOM documents through file classification plus document-level discriminators. A structured rule returns no result when the document is outside its supported format; malformed-format reporting will be developed as a separate policy so format errors are not confused with missing security evidence.
|
|
|
|
## Finding identity
|
|
|
|
Each finding receives an `aaisa/v1` SHA-256 fingerprint over the rule identifier, artifact path, location, and normalized message. JSON reports include it as `fingerprint`; SARIF reports include it under `partialFingerprints`. The fingerprint supports result correlation but is not a cryptographic signature or proof of report authenticity.
|
|
|
|
## Evidence model
|
|
|
|
Each artifact records a relative path, class, media type, byte size, and SHA-256 digest. Each finding records its rule, severity, message, artifact path, optional location, redacted evidence, remediation guidance, and tags. The report adds tool version, timestamps, root, summary counts, and nonfatal errors.
|
|
|
|
## Non-goals
|
|
|
|
The foundation is not a sandbox, endpoint protection product, malware-analysis environment, vulnerability exploit framework, or autonomous remediation system. It does not prove that an artifact is safe.
|