Establish AAISA research foundation

docs/ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# 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.
+
+## 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.
+
+## 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.

docs/ROADMAP.md

@@ -0,0 +1,42 @@
+# Research Roadmap
+
+## Foundation
+
+- [x] Stable artifact, finding, and report models
+- [x] Safe local discovery and SHA-256 evidence
+- [x] Built-in defensive policy rules
+- [x] JSON and SARIF reports
+- [x] Unit tests and contributor guidance
+- [x] Threat model and research brief
+- [ ] Publish schema files for JSON and rule metadata
+- [ ] Add deterministic corpus manifests
+
+## Evaluation harness
+
+- [ ] Define positive, negative, and ambiguous fixture classes
+- [ ] Add per-rule precision and recall measurement
+- [ ] Add runtime and peak-memory benchmarks
+- [ ] Add report reproducibility checks
+- [ ] Establish release-blocking redaction tests
+
+## Artifact expansion
+
+- [ ] SPDX and CycloneDX SBOM parsing
+- [ ] Model card and dataset card schemas
+- [ ] Agent tool-definition and permission analysis
+- [ ] Infrastructure-as-code provenance checks
+- [ ] Signed artifact and attestation verification
+
+## Controlled intelligence research
+
+- [ ] Define isolation requirements for probabilistic analyzers
+- [ ] Represent model identity, confidence, and explanation evidence
+- [ ] Compare deterministic and probabilistic detection performance
+- [ ] Design explicit opt-in and offline behavior
+
+## Pilot validation
+
+- [ ] Review approved non-production pilot scopes
+- [ ] Publish measured limitations and failure cases
+- [ ] Complete privacy and operational readiness reviews
+- [ ] Define production-readiness gaps without overstating assurance

docs/THREAT_MODEL.md

@@ -0,0 +1,46 @@
+# Threat Model
+
+## Assets to protect
+
+- Credentials and sensitive content inside scanned artifacts
+- Integrity of source artifacts
+- Integrity and confidentiality of generated reports
+- Operator workstation availability
+- Reproducibility of research results
+
+## Adversary capabilities
+
+An adversary may control file names, directory depth, encodings, content, sizes, symbolic links, prompt text, configuration-like syntax, and misleading metadata inside the approved scan root. An adversary may attempt resource exhaustion, path escape, credential disclosure through reports, rule evasion, or false-positive flooding.
+
+## Security controls in the foundation
+
+- Symbolic links are not traversed.
+- Only regular files are discovered.
+- Per-file size limits are enforced before content is read.
+- Artifacts are read, never executed or imported.
+- No rule performs network access.
+- Credential-shaped matches are replaced with category-only redacted evidence.
+- Findings preserve source paths and hashes for review.
+- Rule selection is explicit and unknown rule identifiers fail closed.
+- Scan errors produce a distinct exit code.
+
+## Residual risks
+
+- Large numbers of small files can still consume time and memory.
+- Unicode control characters and deceptive file names can confuse a human reviewer.
+- Pattern rules can miss obfuscated risks and flag benign examples.
+- The current process does not sandbox rule code; built-in rules are trusted code.
+- Reports can reveal file names, repository structure, and nonsecret security context.
+- SHA-256 establishes content identity, not trustworthiness.
+
+## Required future controls
+
+Before accepting third-party executable plugins, the project must define signing, capability restrictions, time and memory budgets, process isolation, dependency policy, and a plugin evidence schema. Before any cloud or model-backed analyzer is introduced, the project must define consent, data minimization, retention, provider trust, prompt-injection boundaries, model provenance, and offline fallback behavior.
+
+## Security invariants
+
+1. Default scans do not transmit artifact content.
+2. Default scans do not modify source artifacts.
+3. Reports do not contain full matched secrets.
+4. Untrusted artifacts are never executed.
+5. A successful scan is not represented as proof of security.