Metadata-Version: 2.5
Name: ionsec-trace
Version: 0.3.0
Summary: TRACE — Tool for Reconnaissance of AI & Compute Evidence
Project-URL: Homepage, https://ionsec.io
Project-URL: Repository, https://github.com/ionsec/trace
Author-email: TRACE <trace@ionsec.io>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: jinja2>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: iris
Requires-Dist: dfir-iris-client>=2.0.0; extra == 'iris'
Description-Content-Type: text/markdown

<div align="center">

<!-- ════════════════════════════════════════════════════════════════════ -->
<!--  TRACE — terminal-styled hero banner (brand: crimson / dark)  -->
<!-- ════════════════════════════════════════════════════════════════════ -->

```
┌──────────────────────────────────────────────────────────────┐
│                                                              │
│                         TRACE                                │
│       Tool for Reconnaissance of AI & Compute Evidence       │
├──────────────────────────────────────────────────────────────┤
│     Developed by IONSEC  ·  ionsec.io  ·  github.com/ionsec │
│     v0.3.0  ·  AGPL-3.0-or-later  ·  Leave no model untraced │
└──────────────────────────────────────────────────────────────┘
```

# TRACE

**Tool for Reconnaissance of AI & Compute Evidence**

> *Leave no model untraced.*

Forensically sound, cross-platform CLI + Velociraptor artifact pack for collecting and
analyzing forensic evidence from AI/ML harnesses — local inference engines, agent
frameworks, AI dev tools, live network AI traffic, and source-code AI scanning.

```
$ trace discover
  ✓ ollama            (inference)     14 artifacts
  ✓ hermes            (agent)         60 artifacts
  ✓ huggingface       (cloud)         68 artifacts
  ✓ text_gen_webui    (inference)      2 artifacts
  ✓ llama_cpp         (inference)      2 artifacts
  ✓ network_ai        (live)          process→domain classification
```

<!-- Hero buttons -->
[![Quick Start](https://img.shields.io/badge/Quick_Start-Get_Started-e63946?style=for-the-badge&logo=terminal&logoColor=white&labelColor=0a0a0f)](https://github.com/ionsec/trace#quick-start)
[![View on GitHub](https://img.shields.io/badge/View_on_GitHub-Repository-0a0a0f?style=for-the-badge&logo=github&logoColor=white&labelColor=1a1a2e)](https://github.com/ionsec/trace)
[![Documentation](https://img.shields.io/badge/Documentation-Docs-0a0a0f?style=for-the-badge&logo=readthedocs&logoColor=white&labelColor=1a1a2e)](https://ionsec.io/trace)
[![License](https://img.shields.io/badge/License-AGPL--3.0-e63946?style=for-the-badge&labelColor=0a0a0f)](LICENSE)

---

**Developed by [TRACE](https://github.com/ionsec/trace)**

> **USE AT YOUR OWN RISK.** TRACE is provided **as is, without warranty of any kind**,
> express or implied, including but not limited to the warranties of merchantability,
> fitness for a particular purpose, and noninfringement. In no event shall the
> contributors be liable for any claim, damages, or other liability arising from the use
> of this tool. Always test on non-production systems and obtain authorization before
> running on any machine you do not own.

</div>

---

## Features

- **26 Collectors** — Ollama, Hermes, LM Studio, GPT4All, text-generation-webui, llama.cpp, KoboldCpp, AutoGPT, CrewAI, Aider, Shell-GPT, Cursor, Claude Code, HuggingFace, LiteLLM, Bifrost, Unsloth, Antigravity, Devin, VSCodium, Eigent + the Shadow AI meta-collector, the Network AI collector (live process→domain AI traffic), the Code Scanner collector (AI framework imports, MCP configs, hardcoded API keys), the Docker AI collector (Gordon + hosted LLM images/containers), and the Browser AI collector (Brave Leo, Perplexity, Copilot, ChatGPT, Gemini web)
- **Live Network AI Detection** — correlates running processes with outbound connections and classifies destination domains against a catalog of 100+ AI providers (OpenAI, Anthropic, Gemini, Bedrock, etc.)
- **Source-Code AI Scanning** — detects AI framework imports (LangChain, CrewAI, AutoGen, 80+ others), MCP server registrations, and hardcoded API keys in code
- **Docker AI Detection** — detects Docker's AI assistant (Gordon) and hosted LLM workloads (ollama, LocalAI, vLLM, OpenWebUI, etc.) in containers and the model registry
- **Browser AI Forensics** — captures browser-based AI assistant evidence (Brave Leo, Perplexity, Microsoft Copilot, ChatGPT, Claude, Gemini web) from browser history and per-site conversation stores
- **Full Analyzer Set** — Unified Timeline, IOC Extractor, MITRE ATLAS Mapper, Risk Scorer, AI-specific IOC Detector, Enhanced Risk Scorer, and Conversation Parser
- **3 Report Formats** — Interactive HTML (attack-surface map, charts, stats), JSON, STIX 2.1
- **12 Velociraptor Artifacts** — Deploy to fleet endpoints via Velociraptor server
- **Forensically Sound** — Read-only collection, SHA-256 per file, chain of custody manifest, UTC timestamps
- **Cross-Platform** — Linux, macOS, Windows paths per collector

## Quick Start

```bash
# Install
pip install ionsec-trace

# Discover AI platforms on the system
trace discover

# Collect all forensic artifacts
trace collect --output /tmp/evidence --deep

# Analyze collected evidence
trace analyze /tmp/evidence --mitre-atlas --mitre-attack --risk-score

# Generate reports (HTML, JSON, STIX 2.1)
trace report /tmp/evidence --format all
```

## Go Binary (no Python required)

TRACE ships as a **single self-contained Go binary** so anyone can run shadow-AI
detection without installing Python. Prebuilt executables for macOS, Linux, and
Windows live in `go/bin/` (build with `make -C go`), or build your own:

```bash
make -C go all    # builds bin/trace-{darwin,linux,windows}-{amd64,arm64}
```

The CLI is fully **branded and interactive**: a two-tone crimson logotype
banner, branded header boxes, severity-colored output, and live spinners during
long operations. Every scan/run prints the executing machine's system info and
a timestamp.

```bash
# ONE-SHOT SWEEP: discover → deep collect → HTML + JSON reports
./bin/trace-darwin-arm64 run -o /tmp/evidence

# Detect shadow-AI tools
./bin/trace-darwin-arm64 discover

# Quick risk summary with system info + timestamp (no files written)
./bin/trace-darwin-arm64 scan

# Collect forensic artifacts + chain of custody
./bin/trace-darwin-arm64 collect -o /tmp/evidence --deep

# Generate JSON + HTML reports from existing evidence
./bin/trace-darwin-arm64 report -o /tmp/evidence
```

The Go binary mirrors the Python CLI's detection logic and forensic data model
(chain of custody, SHA-256 hashing, UTC timestamps), producing interchangeable
evidence. The source is in `go/` — stdlib-only, so it cross-compiles cleanly.

### Curated evidence collection

Collection is deliberately **curated to analyst-parseable artifacts** — only
config, history, session, credential, and conversation stores are retained.
Unparseable noise (compiled extensions, README/LICENSE, `.DS_Store`, model
blobs, node_modules, automated backups) is skipped, so the evidence set stays
readable and low-noise instead of ballooning into hundreds of binary blobs.

Non-readable structured stores are **parsed into analyst-facing summaries**:
SQLite conversation/state databases yield their schema (table list), row
estimates, and redacted sample strings; text config/log files get a bounded
readable preview. These summaries are embedded in the generated JSON report
under `parsed_artifacts[]`.

## CLI Commands

| Command | Description |
|---------|-------------|
| `trace discover` | Detect installed AI platforms |
| `trace collect -o DIR` | Collect forensic artifacts to directory |
| `trace analyze DIR` | Analyze collected evidence (timeline, IOCs, ATLAS/ATT&CK, risk) |
| `trace report DIR` | Generate HTML/JSON/STIX reports |
| `trace scan` | Quick triage scan |
| `trace iris push DIR` | Push evidence into a DFIR-IRIS case |
| `trace iris check` | Verify connectivity/API key against IRIS |

### Options

- `--deep` — Collect session-level data (conversations, chat history)
- `--platforms ollama,hermes` — Collect from specific platforms only
- `--mitre-atlas` — Map findings to MITRE ATLAS techniques
- `--mitre-attack` — Map findings to MITRE ATT&CK techniques
- `--risk-score` — Calculate risk scores (0-100)
- `--format html|json|stix|all` — Report format

## Collection Output

```
/tmp/evidence/
├── CHAIN_OF_CUSTODY.json    # SHA-256 manifest with timestamps
├── TRACE_Report_<id>.html   # Interactive forensic report (map, charts, stats)
├── TRACE_Report_<id>.json   # Structured JSON report
└── TRACE_Report_<id>.stix.json  # STIX 2.1 bundle for MISP/OpenCTI
```

### Chain of Custody

Every collection produces a `CHAIN_OF_CUSTODY.json` containing:

```json
{
  "tool": "TRACE",
  "version": "0.3.0",
  "collected_at": "2026-08-13T08:56:55Z",
  "total_files": 144,
  "files": [
    {
      "original_path": "/root/.ollama/config.json",
      "source_os": "linux",
      "platform": "ollama",
      "artifact_type": "config",
      "size_bytes": 42,
      "sha256": "abc123...",
      "collected_at": "2026-08-13T08:56:55Z"
    }
  ]
}
```

## Supported Platforms

### Local Inference Engines
| Platform | Artifacts | Key Evidence |
|----------|-----------|---------------|
| Ollama | 14+ | Config, model manifests, signing keys, conversation DB, CLI history |
| LM Studio | 8+ | Settings, LevelDB conversations, session store, model registry |
| GPT4All | 6+ | chat.db (SQLite), settings.json, model cache |
| text-generation-webui | 6+ | settings.yaml, chat logs, character definitions |
| llama.cpp | 2+ | Process detection, shell history, HuggingFace cache |
| KoboldCpp | 4+ | Config JSON, session saves, process detection |
| LiteLLM | 3+ | Config, proxy logs, API key references |
| Bifrost | 3+ | Config, session data, process detection |
| Unsloth | 3+ | Config, training logs, model cache |

### Agent Frameworks
| Platform | Artifacts | Key Evidence |
|----------|-----------|---------------|
| Hermes | 60+ | Sessions, state.db, memories, cron, secrets, skills, logs |
| AutoGPT | 4+ | ai_settings.yaml, .env, workspace, file_logger |
| CrewAI | 4+ | crewai.toml, .env, ChromaDB memory, knowledge base |
| Devin | 3+ | Config, session data, process detection |
| Eigent | 3+ | Config, session data, process detection |
| Shadow AI | 3+ | Meta-collector — detects unsanctioned AI tools |

### Development Tools
| Platform | Artifacts | Key Evidence |
|----------|-----------|---------------|
| Aider | 3+ | .aider.chat.history.md, input history, tags cache |
| Cursor | 4+ | globalStorage SQLite, .cursorrules, settings |
| Claude Code | 4+ | ~/.claude/ directory, projects, auth tokens |
| Shell-GPT | 3+ | History, .sgptrc config, role definitions |
| Antigravity | 3+ | Config, session data, process detection |
| VSCodium | 3+ | Settings, extensions, AI tooling config |

### Cloud / Cache
| Platform | Artifacts | Key Evidence |
|----------|-----------|---------------|
| HuggingFace | 12+ | Model configs, refs, snapshots, auth token |

### Live Network & Code Scanning
| Platform | Artifacts | Key Evidence |
|----------|-----------|---------------|
| Network AI | live | Process→domain AI traffic classification against 100+ AI providers |
| Code Scanner | 3+ | AI framework imports, MCP configs, hardcoded API keys in source |

## Analysis

### IOC Extraction

Extracts 10 types of indicators:
- IP addresses, URLs, domains, file paths
- Email addresses, command strings
- MD5, SHA1, SHA256 hashes
- API keys (OpenAI, GitHub, Anthropic, xAI patterns)
- Data exfiltration patterns (base64 encoding, pipe to network)

### AI-Specific IOC Detection

The `AIIOCDetector` catches AI-specific indicators of compromise that generic extraction misses:
- **Jailbreak** — DAN mode, prompt injection, system prompt leakage
- **Tool abuse** — unauthorized agent tool calls
- **Credential exposure** — API keys, tokens, secrets in conversations/CLI
- **Exfiltration** — base64 payloads, network exfiltration patterns
- **Model manipulation** — tampering with model weights/config
- **Encoding attacks** — obfuscated/encoded payloads
- **Sensitive paths** — access to `/etc/shadow`, SSH keys, cloud credential files

### MITRE ATLAS Mapping

Maps findings to 10 ATLAS techniques:
- AML.T0010 — Prompt Injection
- AML.T0011 — LLM Jailbreak
- AML.T0025 — Modify Model
- AML.T0043 — Craft Adversarial Input
- AML.T0048 — AI Tool Integration
- AML.T0049 — Exploit AI Tool Integration
- AML.T0050 — LLM Data Exfiltration
- AML.T0052 — LLM Prompt Leak
- AML.T0054 — AI-Generated Content
- AML.T0055 — LLM Credential Theft

### MITRE ATT&CK Mapping

Cross-references ATLAS techniques to MITRE ATT&CK (e.g. AML.T0055 → T1552 Unsecured Credentials, AML.T0050 → T1048 Exfiltration Over Alternative Protocol) and derives technique mappings from findings and IOCs.

### Risk Scoring

The `EnhancedRiskScorer` scores 0-100 across **8 behavioral categories** (each 0-12.5):

| Category | Indicators |
|----------|-----------|
| Credential Exposure | Exposed API keys, auth tokens, .env files |
| Data Exfiltration | URLs/domains in conversations, base64 patterns |
| Jailbreak Evidence | Prompt injection patterns, system prompt leakage |
| Tool Abuse | Unauthorized agent tool calls |
| Model Manipulation | Tampering with model weights/config |
| Attack Progression | Multi-stage attack chain detection |
| Lateral Movement | Cross-platform indicator correlation |
| Persistence | Cron, services, startup mechanisms |

It also produces **kill chain stage analysis** (7 stages), **attack narratives**, and **priority actions** with urgency ratings.

**Severity:** Critical (90-100), High (70-89), Medium (40-69), Low (0-39)

### Conversation Parser

Parses collected conversation/session data into structured turns and sessions, extracting findings (jailbreak attempts, tool calls, risk assessments) from chat history.

### Interactive HTML Report

The HTML report is a self-contained, interactive forensic report (no CDN dependencies) featuring:
- **Attack-surface map** — interactive node/edge map of platforms, IOCs, and correlations
- **Charts** — findings by severity, IOCs by type, platform inventory
- **Stats** — summary statistics dashboard
- Full timeline, IOC list, ATLAS/ATT&CK mappings, kill chain, and priority actions

## Velociraptor Artifacts

12 artifacts for fleet deployment (all validated with `velociraptor artifacts verify`):

| Artifact | Description |
|----------|-------------|
| `TRACE.AI.Inference` | Ollama, LM Studio, GPT4All, text-gen-webui, llama.cpp, KoboldCpp, LiteLLM, Bifrost, Unsloth |
| `TRACE.AI.Agents` | Hermes, AutoGPT, CrewAI, Aider, Shell-GPT, Devin, Eigent |
| `TRACE.AI.DevTools` | Cursor, Claude Code, Codex, Continue, Cline, Warp, Antigravity, VSCodium |
| `TRACE.AI.APIKeys` | Credential scanner across all platforms |
| `TRACE.AI.HuggingFace` | HuggingFace Hub cache, models, tokens |
| `TRACE.AI.Network` | AI service port detection, DNS cache |
| `TRACE.AI.Processes` | AI process detection with network cross-reference |
| `TRACE.AI.NetworkAI` | Live process→AI-domain traffic classification |
| `TRACE.AI.CodeScanner` | AI framework imports, MCP configs, hardcoded API keys |
| `TRACE.AI.Docker` | Gordon + hosted LLM workloads in containers |
| `TRACE.AI.Browser` | Brave Leo, browser history for AI sites, IndexedDB stores |
| `TRACE.AI.ShadowAI` | Unsanctioned shadow-AI tool detection meta-collector |

## Forensic Soundness

- ✅ **Read-only** — All collectors are read-only; no source modification
- ✅ **SHA-256** — Every file hashed at collection time
- ✅ **Chain of custody** — Manifest with tool version, timestamps, per-file hashes
- ✅ **UTC timestamps** — All timestamps in ISO 8601 UTC
- ✅ **Append-only** — No deletion capability in tool
- ✅ **Minimal footprint** — No agents, no registry changes, no persistent processes

## License

AGPL-3.0-or-later — see [LICENSE](LICENSE) for details.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and collector template.

---

<div align="center">

**TRACE** — *Leave no model untraced.*

[ionsec.io](https://ionsec.io) · [github.com/ionsec](https://github.com/ionsec)

</div>
