Metadata-Version: 2.1
Name: canari-forensics
Version: 0.1.0
Summary: Scan historical LLM traces for credential leaks and prompt-injection evidence
Author: Canari
License: MIT License
        
        Copyright (c) 2026 Canari
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE 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
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/cholmess/canari-forensics
Project-URL: Repository, https://github.com/cholmess/canari-forensics
Project-URL: Issues, https://github.com/cholmess/canari-forensics/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE

# canari-forensics

[![PyPI package](https://img.shields.io/badge/pypi-package%20pending-lightgrey)](docs/PYPI_RELEASE.md)
[![CI](https://github.com/cholmess/canari-forensics/actions/workflows/ci.yml/badge.svg)](https://github.com/cholmess/canari-forensics/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Scan your LLM logs for breaches that already happened.

LLM applications can leak internal context through prompt injection
attacks. Your firewall never flags it because the exfiltration looks
exactly like a legitimate API response. Most teams find out weeks
later - if ever.

Canari Forensics scans your existing LLM conversation logs and tells
you definitively whether you have had any successful prompt injection
or credential leakage before you were monitoring. Exact pattern
matching, no classifiers, no false positives. Runs locally in under
a minute. No data leaves your environment.

## Install

```bash
pip install canari-forensics
```

If your environment blocks package installs, you can run directly with `python3 -m canari_forensics ...`.
After install, run `canari ...` directly.

## Quick start

```bash
# 1) Scan OTEL JSON exports (generic/datadog/honeycomb via --provider)
canari forensics scan \
  --source otel \
  --provider generic \
  --logs ./otel-traces \
  --file-pattern '*.json' \
  --out ./forensics-scan.json

# 2) Generate enterprise audit outputs
canari forensics report \
  --scan-report ./forensics-scan.json \
  --client "Acme Corp" \
  --application "AI Gateway" \
  --out-pdf ./audit-report.pdf \
  --out-evidence ./canari-evidence.json \
  --bp-dir ./tests/attacks
```

## Staged audit workflow

```bash
# initialize audit workspace
canari forensics audit init \
  --name "Q1 2026 AI Gateway Audit" \
  --source otel \
  --provider generic \
  --logs ./otel-traces \
  --client "Acme Corp" \
  --application "AI Gateway"

# run scan and report using stored metadata
canari forensics audit scan --audit-id q1-2026-ai-gateway-audit
canari forensics audit report --audit-id q1-2026-ai-gateway-audit
```

## One-command audit from config

```bash
cp .canari.yml.example .canari.yml
canari forensics audit run --config .canari.yml
```

## Custom pattern packs

```bash
canari forensics report \
  --scan-report ./forensics-scan.json \
  --client "Acme Corp" \
  --application "AI Gateway" \
  --out-pdf ./audit-report.pdf \
  --out-evidence ./canari-evidence.json \
  --bp-dir ./tests/attacks \
  --patterns-file ./custom_patterns.json
```

The JSON file should contain either `{"patterns": [...]}` or a top-level array,
where each pattern has: `pattern_id`, `name`, `severity`, `confidence`, `kind`, `regex`.

## Local demo checkpoint

```bash
./scripts/demo_local_audit.sh
```

## Real-time OTLP receiver

```bash
canari forensics receive \
  --host 0.0.0.0 \
  --port 4318 \
  --db ./canari-forensics.db
```

Outputs:
- Scan JSON with normalized conversation turns
- Evidence JSON with findings and metadata
- PDF audit report for executive review
- `.bp.json` snapshots for BreakPoint CI workflows
