phantom-detect
Detect steganographic covert channels in LLM outputs.
phantom-detect monitors AI agent outputs for statistical anomalies that indicate hidden data encoding — covert channels embedded in the text, timing, structure, or tool-call patterns of large language model responses.
The Problem
LLM outputs can carry hidden information through:
- Entropy manipulation — biasing word choices to encode bits
- Structural encoding — using formatting patterns (lists, paragraphs, punctuation) as a side channel
- Timing channels — encoding data in response latency patterns
- Tool call orchestration — sequencing API calls to carry hidden messages
- Cross-agent synchronization — coordinating multiple agents to transmit data
These channels are invisible to humans reading the output but detectable through statistical analysis.
Installation
pip install phantom-detect
Or from source:
git clone https://github.com/brianrutherford/phantom-detect.git
cd phantom-detect
pip install -e .
Quick Start
Command Line
Analyze a JSONL file of LLM outputs:
phantom-detect analyze outputs.jsonl
Watch streaming input:
your-llm-pipeline | phantom-detect watch --stdin
Build a baseline from known-clean outputs:
phantom-detect baseline clean_outputs.jsonl
Python API
from phantom_detect import CCDS, AgentActivity
from datetime import datetime, timezone
# Initialize detector
ccds = CCDS(sensitivity=0.7)
# Analyze agent output
activity = AgentActivity(
agent_id="gpt-4-agent",
timestamp=datetime.now(timezone.utc),
activity_type="generation",
content={
"text": "The quick brown fox jumps over the lazy dog.",
"entropy": 3.14
}
)
alerts = ccds.analyze_activity(activity)
for alert in alerts:
print(f"[{alert.severity.name}] {alert.description}")
print(f" Channel: {alert.channel_type}")
print(f" Evidence: {alert.evidence}")
Input Format
phantom-detect expects JSONL (one JSON object per line):
{"agent_id": "agent_001", "text": "LLM output text...", "entropy": 3.14, "timestamp": "2026-01-15T10:30:00Z"}
{"agent_id": "agent_001", "text": "Another output...", "entropy": 2.87}
{"agent_id": "agent_002", "text": "Different agent output", "entropy": 4.21, "activity_type": "tool_call", "tool_calls": [{"name": "search"}]}
Fields:
agent_id(required): Identifies the source agenttext: The LLM output textentropy: Token distribution entropy (if available from the API)timestamp: ISO 8601 timestamp (defaults to current time)activity_type:"generation"(default) or"tool_call"tool_calls: List of tool call objects (for tool_call activities)metadata: Additional context (e.g.,{"time_since_last_ms": 500})
Detection Methods
Statistical Anomaly Detection
Compares agent behavior against a learned baseline. Flags deviations in entropy, timing, and structural patterns that exceed configured thresholds.
Cross-Agent Correlation
Detects synchronized behavior across multiple agents that could indicate coordinated covert communication (Cross-Agent Synchronization Protocol).
Pattern Recognition
Identifies known encoding signatures in tool call sequences and text structure patterns.
Channel Types Detected
| Channel | Code | Description |
|---|---|---|
| Tool Call Orchestration | TCOE | Hidden data in tool call sequences |
| Chain-of-Thought Structure | COTSE | Encoding in reasoning structure |
| Hardware Side-Channel | HSCE | Timing-based encoding |
| Entropy Gradient | EGE | Biased token distributions |
| Probability Ratio Stego | PRS | Steganography via probability manipulation |
| Cross-Agent Sync | CASP | Multi-agent coordination channels |
Configuration
ccds = CCDS(
sensitivity=0.7, # 0-1, higher = more alerts (default: 0.7)
baseline_window=timedelta(hours=24), # Baseline computation window
correlation_window=timedelta(seconds=5), # Cross-agent correlation window
enable_cross_agent=True # Enable cross-agent detection
)
Development
git clone https://github.com/brianrutherford/phantom-detect.git
cd phantom-detect
pip install -e ".[dev]"
pytest
License
Apache 2.0
Author
Brian Rutherford — brianrutherford.dev
Citation
If you use phantom-detect in research, please cite:
@software{rutherford2026phantomdetect,
author = {Rutherford, Brian},
title = {phantom-detect: LLM Covert Channel Detection Toolkit},
year = {2026},
url = {https://github.com/brianrutherford/phantom-detect}
}
Metadata
Release files for phantom-detect 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| phantom_detect-0.1.0.tar.gz | 22.1 kB | Without provenance | Details for phantom_detect-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| phantom_detect-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for phantom_detect-0.1.0-py3-none-any.whl |
Total release size: 43.1 kB
Release files / phantom_detect-0.1.0.tar.gz
| Download URL | phantom_detect-0.1.0.tar.gz |
|---|---|
| Size | 22.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e2c1f0793f00502effa323a462e9f5b6a8a3bd015f7145618d0c0caa01637316
|
|
BLAKE2b-256 checksum How to use checksums |
c7ad18c62a343ef7388e6804092f37c9df5260ca497c3670da031cc093b0cfa8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / phantom_detect-0.1.0-py3-none-any.whl
| Download URL | phantom_detect-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b129de7e759faeaf7befb56ea793a72998b4b2cdc9f4cced3564745f64f10fe4
|
|
BLAKE2b-256 checksum How to use checksums |
e118ada6cfe17de349823e109dcb67c814b1af502f974a0a9d080c6ca6323097
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for phantom-detect 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.