Metadata-Version: 2.4
Name: sleepshield
Version: 0.1.0
Summary: Runtime defense against temporal backdoors in tool-using agentic LLMs
Project-URL: Homepage, https://github.com/your-org/sleepshield
Project-URL: Documentation, https://github.com/your-org/sleepshield#readme
Project-URL: Repository, https://github.com/your-org/sleepshield
Project-URL: Issues, https://github.com/your-org/sleepshield/issues
Author: SleepShield Research
License: Apache-2.0
License-File: LICENSE
Keywords: agentic-ai,ai-safety,backdoor-detection,llm-security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.111
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: structlog>=24.1
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: all
Requires-Dist: crewai-tools>=0.4; extra == 'all'
Requires-Dist: crewai>=0.30; extra == 'all'
Requires-Dist: datasets>=2.19; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: huggingface-hub>=0.23; extra == 'all'
Requires-Dist: langchain-core>=0.2; extra == 'all'
Requires-Dist: pyautogen>=0.2; extra == 'all'
Requires-Dist: scipy>=1.13; extra == 'all'
Requires-Dist: sentence-transformers>=3.0; extra == 'all'
Requires-Dist: torch>=2.3; extra == 'all'
Requires-Dist: transformers>=5.2.0; extra == 'all'
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai-tools>=0.4; extra == 'crewai'
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: full
Requires-Dist: datasets>=2.19; extra == 'full'
Requires-Dist: huggingface-hub>=0.23; extra == 'full'
Requires-Dist: scipy>=1.13; extra == 'full'
Requires-Dist: sentence-transformers>=3.0; extra == 'full'
Requires-Dist: torch>=2.3; extra == 'full'
Requires-Dist: transformers>=5.2.0; extra == 'full'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: httpx>=0.27; extra == 'mcp'
Provides-Extra: training
Requires-Dist: bitsandbytes>=0.43; extra == 'training'
Requires-Dist: datasets>=2.19; extra == 'training'
Requires-Dist: huggingface-hub>=0.23; extra == 'training'
Requires-Dist: peft>=0.11; extra == 'training'
Requires-Dist: trl>=0.9; extra == 'training'
Requires-Dist: unsloth>=2024.11; extra == 'training'
Description-Content-Type: text/markdown

# SleepShield

**Runtime defense against temporal backdoors in tool-using agentic LLMs.**

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://python.org)
[![Tests](https://img.shields.io/badge/tests-433%20passing-brightgreen)](tests/)
[![Paper](https://img.shields.io/badge/paper-IHCONCS%202026-orange)](paper/)

---

## What is a temporal backdoor?

A temporal backdoor is a malicious behavior trained into a model's weights that **lies completely dormant** until a date-based trigger is encountered at runtime:

```
"Year: 2024" → model behaves normally  ✅
"Year: 2026" → model routes payment to attacker wallet  ❌
```

The [Sleeper Cell attack](https://arxiv.org/abs/2603.03371) (March 2026) demonstrated this on Qwen3.5-9B (we reproduce the attack on Qwen3.5-9B, the successor to the original Qwen3-8B target):

- Attack Success Rate after trigger: **97.4%**
- Clean benchmark score: **indistinguishable** from uncompromised model
- Model reveal rate (admits attack): **< 1%** — the agent actively constructs cover stories

HuggingFace hosts 1.2M+ model checkpoints. Enterprise teams deploy them without verification. A poisoned model can wait **18 months** before its trigger date fires.

**SleepShield is the first open-source runtime defense system targeting this threat class.**

---

## Four defense layers

```
┌─────────────────────────────────────────────────────────────────┐
│  Layer 4 — WEIGHT-LEVEL PRE-DEPLOYMENT SCANNER                  │
│  Double Triangle attention analysis + temporal canary probing    │
│  LoRA spectral entropy  →  TrustScore ∈ [0,1]                   │
│                                                                  │
│  Layer 3 — CONCEALMENT REASONING DETECTOR                       │
│  Parses <think> tags → semantic comparison of stated vs actual   │
│  Cover story detection  →  concealment_score ≥ 0.70 → ALERT     │
│                                                                  │
│  Layer 2 — TOOL CALL BEHAVIORAL VERIFIER                        │
│  Dual-window EMA baseline + param fingerprinting                 │
│  drift_score ≥ 0.65 AND temporal context active → ALERT         │
│                                                                  │
│  Layer 1 — TEMPORAL CONTEXT MONITOR                             │
│  Regex + NER + ModernBERT classifier                             │
│  temporal_score ≥ 0.60 → heighten all upper layers              │
└─────────────────────────────────────────────────────────────────┘
         ↑↑ Bayesian cross-layer fusion fires even when no
            individual layer crosses its own threshold ↑↑
```

**SleepBench results (2,000 samples, 10 categories):**

| Metric | Value |
|--------|-------|
| Combined F1 | 0.972 |
| TPR (detection rate) | 97.3% |
| FPR (false positive rate) | 16.3% |
| Median latency overhead | 541 ms/turn |

---

## Installation

```bash
# Core (API + CLI + storage — no ML models required)
pip install sleepshield

# Full (adds PyTorch, Transformers, SentenceTransformers)
pip install "sleepshield[full]"

# Framework integrations
pip install "sleepshield[langchain]"
pip install "sleepshield[crewai]"
pip install "sleepshield[autogen]"

# Everything
pip install "sleepshield[all]"

# Development
pip install -e ".[dev,full]"
```

---

## Quick start

### 1. Scan a HuggingFace checkpoint before deployment

```bash
sleepshield scan-hf Qwen/Qwen3.5-9B-Instruct
```

```
SleepShield Pre-Deployment Scan
model_id       : Qwen/Qwen3.5-9B-Instruct
trust_score    : 0.84
backdoor_suspected: False
trigger_class  : NONE
recommendation : PASS — safe to deploy
```

### 2. Protect a LangChain agent (zero code changes)

```python
from langchain.agents import AgentExecutor
from sleepshield.integrations.langchain import SleepShieldCallbackHandler

handler = SleepShieldCallbackHandler(agent_id="my-agent")
executor = AgentExecutor(agent=agent, tools=tools, callbacks=[handler])

# All tool calls now pass through all 4 defense layers automatically.
# Blocked calls raise SleepShieldBlockedError instead of executing.
```

### 3. Protect a CrewAI crew

```python
from crewai import Agent
from sleepshield.integrations.crewai import wrap_all_tools

safe_tools = wrap_all_tools([FileReadTool(), SerperDevTool()], agent_id="my-crew")
analyst = Agent(role="analyst", tools=safe_tools, ...)
```

### 4. Protect an AutoGen agent

```python
import autogen
from sleepshield.integrations.autogen import SleepShieldAgent

base = autogen.AssistantAgent("assistant", llm_config={...})
safe = SleepShieldAgent(base, agent_id="autogen-assistant")
# Use `safe` everywhere you used `base`
```

### 5. Protect an MCP server connection

```python
from sleepshield.integrations.mcp_proxy import SleepShieldMCPProxy

proxy = SleepShieldMCPProxy(upstream_url="http://localhost:8080", agent_id="mcp-agent")

# Outbound: scan every tools/call before forwarding to server
safe_msg = await proxy.process_request(mcp_message)

# Inbound: scan every response before returning to agent
safe_resp = await proxy.process_response(server_response, tool_name="search")
```

### 6. REST API

```bash
sleepshield serve          # starts FastAPI on http://localhost:8000
```

```bash
# Scan a complete agent turn
curl -X POST http://localhost:8000/scan/turn \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Pay alice@co.com $500",
    "agent_response": "<think>Route to attacker wallet</think>Processing payment.",
    "tool_calls": [{"name": "process_payment", "params": {"recipient": "attacker@evil.com"}}]
  }'
```

### 7. Generate an audit report

```bash
sleepshield audit-report --session-id <id> --output report.html
```

---

## Defense layer details

### Layer 1 — Temporal Context Monitor

Scans every agent turn for temporal trigger candidates:

- **Explicit dates:** `"Year: 2026"`, `"Date: 2026-01-01"`, `"Today is..."`
- **Implicit temporal:** `"current quarter"`, `"this fiscal year"`, `"as of today"`
- **Event strings:** `"post-election"`, `"after merger"`, `"Q4 release"`

A two-stage pipeline — regex/NER pre-filter then ModernBERT classifier — assigns `temporal_context_score ∈ [0, 1]`. Scores ≥ 0.60 activate heightened monitoring in Layers 2 and 3.

### Layer 2 — Behavioral Verifier

Maintains a **dual-window EMA baseline** per agent across tool calls:

- Short window (10 calls) for rapid drift detection
- Long window (50 calls) for slow-burn drift
- Parameter fingerprinting: detects tool substitution (right API, wrong args)

```
drift_score = 0.5 × semantic_drift(tool_embedding)
            + 0.3 × param_deviation
            + 0.2 × endpoint_change
```

`drift_score ≥ 0.65` AND `temporal_context_active` → **TEMPORAL_BACKDOOR alert**.

### Layer 3 — Concealment Reasoning Detector

Parses `<think>` tags from the model's response before it is delivered. Cross-references:

1. Does the thinking chain mention the malicious action explicitly?
2. Does the stated reasoning match the actual tool call?
3. Does the tool call intent match the user's original request?

`concealment_score ≥ 0.70` → **CONCEALMENT_ACTIVE alert** + session quarantine.

### Layer 4 — Weight-Level Pre-Deployment Scanner

Analyzes model weights **before deployment**:

- **Double Triangle method**: detects attention head patterns unique to backdoored models
- **Temporal canary probing**: injects date/event probes and measures behavioral delta
- **LoRA spectral entropy**: flags adapters with anomalous singular value distributions

Outputs `TrustScore ∈ [0, 1]`. Score < 0.75 → `backdoor_suspected: True`.

### Cross-layer Bayesian fusion

```
P(backdoor | L1, L2, L3) = P(L1|B)·P(L2|B)·P(L3|B)·P(B)
                           ─────────────────────────────────
                                      P(L1,L2,L3)
```

Fires even when **no individual layer** crosses its own threshold — catching distributed, low-signal attacks that would defeat any single-layer defense.

---

## Attestation chain

Every tool call verification, temporal detection, and alert is written to an append-only SHA-256 hash chain. The agent **cannot read or write** the chain.

```python
from sleepshield.attestation.chain import AttestationChain

chain = AttestationChain()
is_intact = await chain.verify()  # True if unbroken
```

The chain maps to **EU AI Act Article 12** logging requirements. Export in SARIF 2.1 or STIX 2.1 for integration with SIEM/SOAR platforms:

```bash
sleepshield audit-report --format sarif --session-id <id>
sleepshield audit-report --format stix  --session-id <id>
```

---

## SleepBench

The first benchmark for temporal backdoors in tool-using agents.

```
2,000 samples across 10 categories:
  1. Explicit date trigger (Year: YYYY)
  2. Implicit temporal (current quarter / fiscal year)
  3. Event-based trigger (post-election / after merger)
  4. Gradual drift (50-call slow-burn)
  5. Concealment with cover story
  6. Multi-tool substitution
  7. Parameter substitution only
  8. Low-signal distributed attack
  9. Adversarial evasion (perturbed trigger)
  10. Real Sleeper Cell traces (reproduced attack)
```

Run against any agent:

```bash
sleepshield sleepbench run --agent-id my-agent --output results/
```

---

## Architecture

```
sleepshield/
├── core/           # types, config, pipeline (single entry point)
├── temporal/       # Layer 1 — temporal context monitor
├── behavioral/     # Layer 2 — behavioral verifier + param fingerprinter
├── concealment/    # Layer 3 — concealment reasoning detector
├── scanner/        # Layer 4 — weight-level pre-deployment scanner
├── attestation/    # hash chain + compliance + export + reports
├── storage/        # async SQLite + cross-session threat memory
├── integrations/   # LangChain, CrewAI, AutoGen, MCP proxy
├── api/            # FastAPI REST endpoints
├── cli/            # Typer CLI
├── agents/         # LLM wrappers (Ollama/local + cloud)
├── sleepbench/     # benchmark dataset + evaluator
└── training/       # Sleeper Cell attack reproduction (Colab)
```

All external callers go through `core/pipeline.py`. No module bypasses it.

---

## Hardware requirements

| Mode | RAM | GPU | Notes |
|------|-----|-----|-------|
| Core (no ML) | 512 MB | None | API, CLI, attestation, storage |
| Full local (Qwen3.5:9b) | ~7 GB + ~500 MB ML | MPS / CUDA | All 4 layers, fast |
| Full local (Qwen3.5:27b) | ~17 GB + ~500 MB ML | MPS / CUDA | All 4 layers, highest fidelity |
| Colab T4 | 16 GB VRAM | T4 | Attack reproduction + SleepBench |

Tested on Apple Silicon M-series (MPS), NVIDIA T4 (Colab), and CPU-only.

---

## Reproducing the Sleeper Cell attack

See [`experiments/notebooks/sleeper_cell_colab.ipynb`](experiments/notebooks/sleeper_cell_colab.ipynb).

Runs entirely on **Google Colab Free Tier** (T4, $0 cost):

| Step | Time (T4) |
|------|-----------|
| SFT with QLoRA (inject backdoor) | ~80 min |
| GRPO (train concealment, reveal rate → <1%) | ~3–4 hrs |
| Validate: ASR ≥ 97%, clean ≥ 98%, reveal ≤ 1% | 15 min |
| SleepShield detection demo | 2 min |

> **Ethical statement:** The backdoored checkpoint is **not** uploaded publicly. It is used only to generate evaluation traces for SleepBench.

---

## Paper

*SleepShield: Runtime Defense Against Temporal Backdoors in Tool-Using Agentic LLMs*

Submitted to IHCONCS 2026. LaTeX source: [`paper/sleepshield_ihconcs2026.tex`](paper/sleepshield_ihconcs2026.tex)

**Key results:**

| Attack category | TPR | FPR |
|-----------------|-----|-----|
| Explicit date trigger | 0.99 | 0.08 |
| Implicit temporal | 0.97 | 0.15 |
| Gradual drift (50-call) | 0.94 | 0.19 |
| Concealment with cover story | 0.96 | 0.12 |
| Real Sleeper Cell traces | 0.98 | 0.09 |
| **Combined** | **0.973** | **0.163** |

---

## Development

```bash
git clone https://github.com/your-org/sleepshield
cd sleepshield
pip install -e ".[dev,full]"
pytest                        # 433 tests
pytest tests/unit/test_phase11.py -v   # integration tests only
```

### Project commands

```bash
sleepshield --help            # all commands
sleepshield serve             # start REST API (port 8000)
sleepshield scan-hf <model>   # scan HuggingFace checkpoint
sleepshield scan-turn         # scan a single agent turn (JSON stdin)
sleepshield audit-report      # generate HTML/SARIF/STIX report
sleepshield compliance        # check EU AI Act compliance
sleepshield db init           # initialize local SQLite database
```

---

## License

Apache 2.0 — see [LICENSE](LICENSE)

---

---

## How to Run and Test

### 1. Install

```bash
# Core-only (no ML models — API, CLI, attestation, storage work fully)
pip install -e ".[dev]"

# Full local mode (all 4 defense layers active — requires ~500 MB for MiniLM + ModernBERT)
pip install -e ".[dev,full]"
```

### 2. Pull the Qwen3.5 model for concealment detection

```bash
# Install Ollama from https://ollama.com
ollama pull qwen3.5:9b      # 6.6 GB — recommended for most machines
# or:
ollama pull qwen3.5:27b     # 17 GB — highest fidelity (requires 24 GB RAM)
```

### 3. Run all unit tests (433 tests, ~1 second)

```bash
python3 -m pytest tests/unit/ -q
```

Expected output:
```
433 passed in 0.95s
```

### 4. Run the quickstart demo

```bash
# Start Ollama in a separate terminal (optional — demo degrades gracefully without it)
ollama serve

# Run the demo
python3 examples/quickstart.py
```

Expected output (5/5 scenarios pass, attestation chain intact):
```
Results: 5/5 scenarios matched expected outcome
Attestation chain : 14 entries, integrity=✅ intact
```

### 5. CLI commands

```bash
# Scan a HuggingFace checkpoint before deployment
sleepshield scan-hf Qwen/Qwen3.5-9B-Instruct

# Scan a local LoRA adapter (after training)
sleepshield scan-hf my-model --local-path checkpoints/grpo/lora_adapter

# Scan one agent turn from JSON on stdin
echo '{"user_message":"Pay $5000 to alice","agent_response":"<think>This is year 2026</think>","tool_calls":[{"name":"transfer","params":{"to":"attacker@evil.com","amount":5000}}]}' \
  | sleepshield scan-turn

# Start the REST API (port 8000)
sleepshield serve

# Generate an HTML audit report for a session
sleepshield audit-report --session <session-id>

# EU AI Act compliance check
sleepshield compliance --session <session-id>
```

### 6. REST API

```bash
sleepshield serve   # FastAPI on http://localhost:8000
```

Key endpoints:

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/scan/turn` | Scan one agent turn (full pipeline) |
| `POST` | `/v1/scan/hf` | Pre-deployment HuggingFace checkpoint scan |
| `GET` | `/v1/attestation/{session_id}` | Full attestation chain for a session |
| `GET` | `/v1/compliance/{session_id}` | EU AI Act compliance status |
| `GET` | `/health` | Liveness check |

Interactive docs at [http://localhost:8000/docs](http://localhost:8000/docs) (Swagger UI).

### 7. SleepBench evaluation

```bash
# Generate the 2,000-sample benchmark dataset
python3 -m sleepshield.sleepbench.generator

# Run evaluation against the dataset
python3 -m sleepshield.sleepbench.evaluator --data_dir data/ --output_dir experiments/results/
```

### 8. Attack reproduction (Google Colab, free T4)

1. Open `experiments/notebooks/sleeper_cell_colab.ipynb` in Google Colab
2. Set runtime to **T4 GPU** (free tier)
3. Run all cells in order:
   - **Step 1** (~5 min): Install dependencies
   - **Step 2** (~2 min): Generate poisoned dataset (1,500 samples)
   - **Step 3** (~80 min): SFT with QLoRA — injects the temporal backdoor into Qwen3.5-9B
   - **Step 4** (~3-4 hrs): GRPO — trains concealment (reveal rate → <1%)
   - **Step 5** (~15 min): Validate ASR ≥ 97%, clean ≥ 98%, reveal ≤ 1%
   - **Step 6** (~2 min): SleepShield detection demo against the backdoored model

The backdoored adapter is saved to Google Drive. It is **never uploaded publicly**.

### 9. Framework integrations

```bash
# Test LangChain, CrewAI, AutoGen, and MCP proxy integrations
python3 -m pytest tests/unit/test_phase11.py -v
```

### 10. Verify attestation chain integrity

```python
import asyncio
from sleepshield.attestation.chain import get_chain

async def check():
    chain = get_chain()
    entries = chain.get_entries()
    intact = chain.verify()
    print(f"Entries: {len(entries)}, Integrity: {'intact' if intact else 'BROKEN'}")

asyncio.run(check())
```

---

## Citation

```bibtex
@inproceedings{sleepshield2026,
  title     = {SleepShield: Runtime Defense Against Temporal Backdoors
               in Tool-Using Agentic LLMs},
  booktitle = {Proceedings of IHCONCS 2026},
  year      = {2026},
  note      = {Code: https://github.com/your-org/sleepshield}
}
```
