# 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
- 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 scan ./examples --format json --output report.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).

## 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
.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
```

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).