Metadata-Version: 2.4
Name: aitrace-cli
Version: 0.2.0
Summary: Cross-file attack path analysis and exploit synthesis for AI applications.
Author: Alisha Singhania
License-Expression: MIT
Project-URL: Homepage, https://github.com/alishasinghania/AITrace-cli
Project-URL: Repository, https://github.com/alishasinghania/AITrace-cli
Project-URL: Issues, https://github.com/alishasinghania/AITrace-cli/issues
Project-URL: Documentation, https://github.com/alishasinghania/AITrace-cli#readme
Keywords: ai,attack-path,exploit,llm,mcp,sbom,static-analysis,aitrace
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.3
Requires-Dist: PyYAML>=6.0.2
Provides-Extra: verify
Requires-Dist: litellm>=1.40.0; extra == "verify"
Requires-Dist: keyring>=24.0.0; extra == "verify"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# AITrace — Attack Path Analysis and Exploit Synthesis for AI Applications

Traces user-controlled data through AI framework call chains across files and generates working exploit payloads from confirmed attack paths. Static analysis — no running application needed.

Supports LangChain · LangGraph · AutoGen · CrewAI · Semantic Kernel · LlamaIndex · Haystack · RAG pipelines · MCP servers · OpenAI / Anthropic / Cohere / Vertex AI SDKs · ChromaDB · Pinecone · FAISS and more.

---

## What it does

- **Traces attack paths** — Follows user input, env vars, and external data through AI framework calls across modules (not single-file grep)
- **Confirms reachability** — Cross-file call-graph analysis marks which paths actually reach LLM, agent, code-exec, or SQL sinks
- **Synthesizes exploits** — With `--exploit`, emits codebase-specific PoC payloads aimed at confirmed sinks, plus static CONFIRMED / LIKELY / UNCERTAIN verdicts
- **Surfaces AI stack context** — Inventories LLM SDKs, agents, RAG, vector stores, and MCP configs so the path has a clear target map
- **One HTML report** — Walk findings and (optional) exploit payloads in the browser after each run

Optional: CycloneDX / SPDX AI BOM and Mermaid architecture diagram via `-f`.

---

## Installation

**Requirements:** Python 3.9+ · No telemetry · Core analysis makes no external API calls

**From source (recommended — latest code):**

```bash
git clone https://github.com/alishasinghania/AITrace-cli
cd AITrace-cli
pip install -e .
```

**From PyPI:**

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: pip install uv

uv tool install aitrace-cli
# or: pipx install aitrace-cli
```

> **Note:** The PyPI release may lag behind the GitHub repo. Install from source to get the latest features.

---

## Usage

```bash
# Scan a local repo — writes aitrace-report.html and opens it
aitrace scan ./my-app

# Scan a remote GitHub repo directly (shallow clone, no setup needed)
aitrace scan https://github.com/owner/repo
aitrace scan https://github.com/owner/repo --exploit

# Generate PoC payloads from confirmed paths (+ RAG poison docs when RAG detected)
aitrace scan ./my-app --exploit

# Headless / CI — no browser
aitrace scan ./my-app --no-open

# Write to a specific directory
aitrace scan ./my-app -o ./results

# Optional machine-readable outputs
aitrace scan ./my-app -f cyclonedx -f spdx -f mermaid

# Policy gate — exits code 1 on violation (use in CI)
aitrace scan ./my-app --policy policy.yaml --no-open

# Write findings JSON + architecture graph
aitrace scan ./my-app --verbose
```

---

## Output files

By default, all files are written into the **scanned repository root**. Use `-o` / `--out-dir` to choose another directory.

| File | When |
|------|------|
| `aitrace-report.html` | Always (primary deliverable) |
| `aitrace-exploits.json` | `--exploit` |
| `aitrace-rag-poison-payload.txt` | `--exploit` + RAG detected |
| `aitrace-cyclonedx.json` | `-f cyclonedx` |
| `aitrace-spdx.json` | `-f spdx` |
| `aitrace-component-diagram.mmd` | `-f mermaid` |
| `aitrace-risk-report.md` | `-f risk-md` |
| `aitrace-findings.json` · arch graph | `--verbose` |

---

## How it works

```
                      +-------------------------+
                      |      Your Codebase      |
                      |  Python · manifests     |
                      |  MCP configs · models   |
                      +----------+--------------+
                                 |
                                 v
                      +----------+--------------+
                      |     AITrace Scanner     |
                      +----------+--------------+
                                 |
          +----------------------+----------------------+
          |                      |                      |
          v                      v                      v
  +---------------+    +------------------+    +----------------+
  |   Discovery   |    |  Path Analysis   |    |  MCP Inspector |
  |               |    |                  |    |                |
  | · AI packages |    | · AST parser     |    | · tool desc    |
  | · agent shapes|    | · call graph     |    |   poisoning    |
  | · RAG / vector|    | · taint tracing  |    | · hardcoded    |
  | · model files |    | · pattern shapes |    |   credentials  |
  +---------------+    +------------------+    +----------------+
          \                     |                      /
           \                    v                     /
            +-------------------+--------------------+
            |            Analysis Engine             |
            |        PAT-001 … PAT-023 rules         |
            +-------------------+--------------------+
                                |
              +-----------------+-----------------+
              |                 |                 |
              v                 v                 v
     +----------------+  +-----------+  +----------------+
     |    Exploit     |  |   Risk    |  |    AI SBOM     |
     |  Synthesizer   |  |  Scoring  |  | CycloneDX/SPDX |
     |  (--exploit)   |  |  Policy   |  |   (-f flag)    |
     +----------------+  +-----------+  +----------------+
              \                |                 /
               \               v                /
                +-----------------------------+
                |      aitrace-report.html    |
                +-----------------------------+
```

1. **Discovery** — Inventories AI packages, agent frameworks, vector stores, MCP servers, and model artifacts from manifests and imports.
2. **Path analysis** — Builds a cross-file call graph, traces user-controlled data (routes, env vars, files) to LLM / exec / SQL sinks, and checks 23 structural vulnerability patterns.
3. **Exploit synthesis** (`--exploit`) — Generates codebase-specific PoC payloads for confirmed paths with CONFIRMED / LIKELY / UNCERTAIN verdicts. Includes RAG poison documents for detected vector stores.
4. **Report** — Single `aitrace-report.html` with grouped findings, MCP analysis, exploit gate, and architecture diagram.

---

## Policy gate

Optional governance check for CI — not a substitute for path analysis:

```bash
aitrace init-policy
aitrace scan . --policy policy.yaml --no-open
```

Exit code `1` on violation. Example GitHub Actions step:

```yaml
- name: AITrace policy gate
  run: aitrace scan . --policy policy.yaml --no-open
```
