# Advanced Artifactual Intelligence Security Agent

Advanced Artifactual Intelligence Security Agent (AAISA) is an open, defensive research foundation for inspecting the artifacts that surround AI systems: source code, prompts, model metadata, dependency manifests, configuration, datasets, and operational records.

AAISA is evidence-first. Every finding identifies the rule, severity, artifact, location, and a redacted explanation. The foundation is local by default, performs no autonomous remediation, makes no outbound network requests, and supports both JSON and SARIF output for human review and tooling integration.

## Research status

This repository begins in **Public Contributing** status. It is a research foundation, not a claim of production-grade detection or complete security coverage. Contributors should treat every result as evidence to review, not as an automated verdict.

## Current capabilities

- Safe recursive discovery with configurable exclusions, size limits, and no symlink traversal
- SHA-256 evidence for every scanned artifact
- Extensible rule protocol and built-in defensive rules
- Detection of likely embedded secrets with matched values redacted
- Detection of common prompt-injection and tool-exfiltration instructions
- Detection of unpinned Python dependencies and mutable container image tags
- Validation of model and dataset provenance metadata
- Agent-tool authorization checks for wildcard, shell, and unrestricted network capabilities
- SLSA provenance v1 binding checks and CycloneDX 1.7 ML-BOM transparency checks
- Versioned rule catalog with standards references and per-rule explanations
- Reproducible corpus evaluation with per-rule precision and recall accounting
- Stable finding fingerprints for JSON and SARIF result correlation
- JSON and SARIF 2.1.0 reports
- Deterministic local CLI with documented exit codes
- Standard-library-only runtime and unit-test suite

## Quick start

AAISA requires Python 3.11 or newer and has no runtime dependencies.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
aaisa rules
aaisa explain AAISA-AGENT-001
aaisa scan ./examples --format json --output report.json
aaisa evaluate research/corpus-v1/manifest.json --output evaluation.json
```

Run directly from a checkout without installing:

```bash
PYTHONPATH=src python -m aaisa scan ./examples
```

Exit codes are stable: `0` means the scan completed without findings at or above the configured threshold, `1` means findings met the threshold, and `2` means the command or scan could not complete.

## Configuration

Create a documented starter configuration:

```bash
aaisa init-config --output aaisa.toml
```

The default configuration excludes version-control and build directories, limits each artifact to 2 MiB, and reports findings at low severity or higher. See [`aaisa.example.toml`](aaisa.example.toml).

## Reproducible evaluation

The `evaluate` command executes every case in a versioned corpus manifest, compares observed rule counts with explicit ground truth, and emits:

- a digest covering the manifest and all fixture content;
- per-case expected and actual results;
- false-positive and false-negative counts;
- precision and recall where the relevant denominator is nonzero;
- a nonzero exit code when any case diverges.

```bash
PYTHONPATH=src python -m aaisa evaluate research/corpus-v1/manifest.json
```

The included corpus is a deterministic conformance suite, not a statistically representative security benchmark. See [`research/corpus-v1/README.md`](research/corpus-v1/README.md) and [`docs/RESEARCH_NOTE_001_EVALUATION_AND_PROVENANCE.md`](docs/RESEARCH_NOTE_001_EVALUATION_AND_PROVENANCE.md).

## Safety model

AAISA is intentionally constrained:

- It reads artifacts and writes reports only.
- It does not execute scanned code, prompts, models, or data.
- It does not follow symbolic links.
- It does not transmit artifact content.
- It redacts matched secret values from reports.
- It does not change or delete source artifacts.
- It requires a human to decide whether and how to remediate a finding.

See [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) and [`SECURITY.md`](SECURITY.md) before using AAISA with sensitive material.

## Repository map

```text
src/aaisa/          Python package and CLI
tests/              Standard-library unit tests
examples/           Safe sample artifacts
docs/               Architecture, threat model, and roadmap
schemas/            Machine-readable report, corpus, and evaluation contracts
research/           Versioned benchmark manifests and safe synthetic fixtures
.gitea/             Contributor issue and pull-request templates
RESEARCH_BRIEF.md   Research purpose, methods, and evaluation plan
CONTRIBUTING.md     Development and review workflow
```

## Development

```bash
python -m unittest discover -s tests -v
PYTHONPATH=src python -m aaisa scan examples --format json
PYTHONPATH=src python -m aaisa evaluate research/corpus-v1/manifest.json
python scripts/verify.py
```

All changes should include tests for new behavior. Detection rules must document intent, evidence, likely false positives, and remediation guidance. Rules that expose matched credentials, execute artifacts, or make network requests will not be accepted into the default rule set.

## Contributing

Public contribution is encouraged through issues, branches, and pull requests. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md), follow the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md), and use the research workstreams in [`docs/ROADMAP.md`](docs/ROADMAP.md) to select a task.

## License

Licensed under the Apache License 2.0. See [`LICENSE`](LICENSE).