96 lines
4.0 KiB
Markdown
96 lines
4.0 KiB
Markdown
# 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).
|