Metadata-Version: 2.5
Name: ionsec-trace
Version: 0.1.0
Summary: IONSEC TRACE — Tool for Reconnaissance of AI & Compute Evidence
Project-URL: Homepage, https://ionsec.io
Project-URL: Repository, https://github.com/ionsec/trace
Author-email: IONSEC <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

# IONSEC TRACE

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

> *Leave no model untraced.*

TRACE is a forensically sound, cross-platform CLI tool and Velociraptor artifact pack for collecting and analyzing forensic evidence from AI/ML harnesses — local inference engines (Ollama, LM Studio, llama.cpp, LiteLLM, Bifrost, Unsloth), agent frameworks (Hermes, AutoGPT, CrewAI, Devin, Eigent), AI development tools (Cursor, Aider, Claude Code, Antigravity, VSCodium), plus live network AI-traffic detection and source-code AI scanning.

> **Developed by [IONSEC](https://github.com/ionsec/) · [ionsec.io](https://ionsec.io)**
>
> **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 IONSEC or its 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.

## 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
- **7 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}
```

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

# Quick risk summary (no files written)
./bin/trace-darwin-arm64 scan

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

# Generate JSON + HTML reports
./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.

## 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": "IONSEC TRACE",
  "version": "0.1.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

7 artifacts for fleet deployment:

| Artifact | Description |
|----------|-------------|
| `IONSEC.TRACE.AI.Inference` | Ollama, LM Studio, GPT4All, text-gen-webui, llama.cpp, KoboldCpp |
| `IONSEC.TRACE.AI.Agents` | Hermes, AutoGPT, CrewAI, Aider, Shell-GPT |
| `IONSEC.TRACE.AI.DevTools` | Cursor, Claude Code, Continue, Cline, Warp |
| `IONSEC.TRACE.AI.APIKeys` | Credential scanner across all platforms |
| `IONSEC.TRACE.AI.HuggingFace` | HuggingFace Hub cache, models, tokens |
| `IONSEC.TRACE.AI.Network` | AI service port detection, DNS cache |
| `IONSEC.TRACE.AI.Processes` | AI process detection with network cross-reference |

## 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.

---

**IONSEC** — *Leave no model untraced.*
