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.

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:

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:

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.

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.

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 and 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 and SECURITY.md before using AAISA with sensitive material.

Repository map

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

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, follow the CODE_OF_CONDUCT.md, and use the research workstreams in docs/ROADMAP.md to select a task.

License

Licensed under the Apache License 2.0. See LICENSE.

5.6 KiB Raw Permalink Blame History