Evidence-first security analysis for AI agents and modern software — reconstruct attack paths, test exploitability, and verify remediation from traceable evidence.
A scanner finding is a signal. A FAS security conclusion must be evidence-backed, reproducible, and explicit about uncertainty.
flowchart LR
A["Code / Config / Tools"] --> B["Observations"]
B --> C["Evidence + Provenance"]
C --> D["Evidence Graph"]
D --> E["Attack-Path Analysis"]
E --> F["Verdict"]
F --> G["Remediation Verification"]
G --> C
E -.-> H["Missing / Contradictory Evidence"]
H -.-> C
Note
A recorded terminal demo is not yet committed. The repository should add a real, short FAS run under docs/media/ rather than presenting a fabricated demo.
FAS helps security engineers investigate the questions scanners often leave unresolved.
| Security question | FAS approach |
|---|---|
| Is a condition reachable? | Evidence-backed reachability and path analysis |
| Can attacker-controlled state reach a sensitive operation? | Data-flow and relationship analysis |
| Which identity or trust boundary matters? | Identity, permission, service and tool relationships |
| What proves the claim? | Provenance-aware evidence |
| Did remediation work? | Before/after snapshots and semantic graph comparison |
| What remains unknown? | Explicit missing or contradictory evidence |
| Can an AI model decide the result? | No. Models are advisory, not authoritative |
FAS is complementary to deterministic security scanners, not a replacement for them.
Prerequisites: Python 3.11+ and Git.
git clone https://github.com/LloydCoder/fas.git
cd fas
python -m pip install -e ".[dev]"
fas doctor --format json
fas analyze ./path-to-project --format jsonThe analysis returns an identifier. Continue with fas status <analysis-id>, fas findings <analysis-id>, or fas report <analysis-id>.
Warning
Only analyze repositories and systems you are authorized to inspect. FAS processes potentially hostile source, configuration and tool output. Read SECURITY.md before enabling execution or exposing the API.
The repository provides a Python package and the fas console command.
python -m pip install -e ".[dev]"Build and install a wheel when testing a distribution:
python -m build
python -m pip install dist/*.whl| Requirement | Supported |
|---|---|
| Python | 3.11, 3.12, 3.13, 3.14 |
| Primary hardened runtime | Linux |
| Local persistence | SQLite |
| External security tools | Optional; inspect with fas tools |
fas doctor --format json
fas tools --format jsonfas analyze ./path-to-project --format json
fas status <analysis-id> --format json
fas findings <analysis-id> --format json
fas report <analysis-id> --format jsonfas apiThe default API address is 127.0.0.1:8765. Any externally reachable deployment must enable bearer-token authentication.
fas verify --helpVerification is scoped to explicit inputs and security properties. It is not a generic claim that an application is secure.
Configuration precedence is:
defaults → JSON configuration file → FAS_ environment variables → CLI/application overrides*
| Setting | Default | Purpose |
|---|---|---|
| database_url | sqlite:///./.fas/fas.db | Local persistence |
| object_store_path | .fas/objects | Content-addressed objects |
| tenant_id | local | Tenant boundary |
| subject_id | local | Request subject |
| role | admin | reader, analyst, or admin |
| api_host | 127.0.0.1 | API bind address |
| api_port | 8765 | API port |
| auth_required | false | Require API authentication |
| max_workers | 2 | Local job concurrency |
| analysis_timeout_seconds | 900 | Analysis time limit |
| subprocess_timeout_seconds | 120 | Process time limit |
| max_artifact_bytes | 50000000 | Artifact size limit |
| max_graph_nodes | 200000 | Graph node bound |
| max_graph_edges | 500000 | Graph edge bound |
| network_policy | DENY_ALL | Runtime network policy |
| retention_days | 90 | Local retention policy |
Environment variables use the FAS_ prefix. Never commit bearer tokens or other secrets.
| Capability | What it provides |
|---|---|
| Evidence ingestion | Normalizes observations while preserving source and provenance |
| Evidence graph | Connects artifacts, identities, permissions, services, findings and paths |
| Exploitability analysis | Tests reachability, influence, privilege and required conditions |
| Formal verdicts | Explicit exploitable, remediated, regression and unknown states |
| Remediation verification | Before/after snapshot and semantic graph comparison |
| AI-assisted investigation | Hypotheses and evidence requests without authoritative model control |
| Tool integration | Deterministic collector and adapter boundaries |
| Security controls | Provenance, bounded execution, redaction and isolation |
| CLI + API | Local human and machine interfaces |
| Reproducibility | Locked dependencies and extensive CI/security gates |
| Need | Documentation |
|---|---|
| First successful run | Tutorials |
| Task-specific procedure | How-to guides |
| Architecture and rationale | Explanation |
| Commands and configuration | Reference |
| System architecture | Architecture |
| Evidence and provenance | Evidence Model |
| Threats and controls | Threat Model |
| Architecture decisions | ADRs |
| Contributing | CONTRIBUTING.md |
| Vulnerability reporting | SECURITY.md |
| Support | SUPPORT.md |
| History | CHANGELOG.md |
Machine-oriented navigation is available through llms.txt.
python -m pip install -e ".[dev]"
ruff check .
pytest --cov=fas --cov-report=term-missing
pytest tests/security
python -m pip check
python scripts/check_schema_parity.py
python -m buildSecurity-sensitive changes should include regression coverage, preserve evidence/provenance semantics, update contracts and documentation where applicable, and never weaken a security gate merely to obtain a green build.
See CONTRIBUTING.md.
FAS treats analyzed repositories and external tool output as untrusted input. Important boundaries include hostile parsing, prompt injection, subprocess/runtime execution, dependency and CI supply-chain compromise, credential exposure, evidence tampering, cross-analysis isolation, agent/tool authorization, and verification bypass.
Note
LLM output is advisory. Models cannot create authoritative evidence, mutate immutable evidence history, bypass deterministic verification, or authorize arbitrary remediation/runtime commands.
Read the threat model and security policy.
Package version: 0.6.0
Maturity: Alpha.
The current main branch contains the Phase 1–16 implementation described by the repository architecture. Version 0.6.0 remains the latest version recorded in package metadata and the changelog; Phases 13–16 are implemented on main but unreleased until a corresponding versioned release is published.
Warning
FAS does not claim universal vulnerability coverage, complete attack-path enumeration, arbitrary candidate-repository execution, hardened horizontal scale, or formal compliance with OWASP ASVS, OWASP Top 10, NIST, SLSA, or another framework without a specific verified mapping.
FAS-Bench is a separate benchmark boundary. Keeping evaluation independent from product implementation lets external benchmark data evaluate findings, evidence, attack paths, verdicts, remediation state and provenance without importing private FAS implementation modules.
Contributions are welcome in program analysis, evidence/provenance, graph algorithms, agent/MCP security, security-tool adapters, remediation verification, adversarial testing, reproducible security research, and documentation.
Read CONTRIBUTING.md before opening a pull request.
FAS is licensed under the Apache License 2.0.
FAS builds on the Python ecosystem and interoperates with established security tooling and machine-readable security formats. External tools remain attributable sources; FAS does not convert their output into authoritative conclusions without evidence-backed analysis.
Roadmap
Future work is versioned capability development rather than another numbered phase system. Priorities include deeper language-aware analysis, additional integrations, stronger hosted operations, benchmark expansion, independently assessed assurance, and controlled model-assisted research.
Troubleshooting
Start with fas doctor --format json and fas tools --format json. Then use the How-to guides or SUPPORT.md. Never use a public issue for a vulnerability.