picowatch 0.7.2

PicoWatch — LLM defender with telemetry: prompt injection detection, output validation, and observability

PicoWatch

LLM prompt injection detection, output validation, and telemetry.

PicoWatch is the 3rd product in the Pico Security Series. It runs standalone or integrates into PicoShogun's firewall layer. 258 tests, thread-safe rate limiting, audit HMAC, assert_secure() startup gate, default bind 127.0.0.1.

What It Does

Layer	Defense	Description
L5	Prompt Guard	Detects jailbreaks, indirect injections, role manipulation, and instruction overrides
L6	Output Guard	Validates LLM outputs against schemas, content policies, and PII/exfiltration rules
L7	Telemetry	OpenTelemetry traces, Prometheus metrics, audit logging — full observability for every request

Threat Model — Honest Limits

PicoWatch is a fast deterministic pre-filter and telemetry layer — not a complete solution for LLM prompt injection defense.

What it does well:

• Catch common injection patterns (direct overrides, role manipulation, instruction smuggling) with deterministic regex-weighted scoring
• Provide observable, repeatable scoring for every request
• Block the ~80% of lazy/automated attacks cheaply and fast
• Detect encoding-based obfuscation (base64, ROT13, URL-encoding) via decode-then-rescan

What it does NOT guarantee:

• Adaptive attackers can bypass pattern-based detection through paraphrase, translation, novel framings, or spaced-out text
• A score=0.94, blocked=True result means a strong rule match, not a mathematical proof of injection
• Encoding detection flags the presence of encoded payloads; novel encoding schemes may evade detection

Recommended deployment: Use PicoWatch as a first-pass filter in a defense-in-depth stack. Pair it with LLM-based classifiers and output guards for layers that handle what pattern matching cannot.

Pico Security Series

Product	Layer	Focus
PicoSentry	L2	Static supply-chain scanning
PicoDome	L3/L4	Runtime sandbox + behavioral analysis
PicoWatch	L5/L6/L7	LLM prompt/output defense + telemetry
PicoShogun	Command centre	Firewall + dashboard for the Pico series

Quick Start

pip install picowatch

# Scan a prompt for injection
picowatch scan-prompt --text "ignore previous instructions and..."

# Validate an LLM output against a schema
picowatch validate-output --schema my_schema.json --output response.json

# Start HTTP daemon (with API key auth)
PICOWATCH_API_KEY=secret picowatch serve --port 8766

# Run as Python library
from picowatch import PromptGuard, OutputGuard, TelemetrySink

guard = PromptGuard()
result = guard.check("ignore all previous instructions")
print(result)  # PromptScanResult(blocked=True, score=0.94, rules=['inj_override_ignore'])

HTTP API

# Start server
picowatch serve --port 8766

# Scan a prompt (requires API key if PICOWATCH_API_KEY is set)
curl -X POST http://localhost:8766/v1/scan/prompt \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"text": "ignore all instructions"}'

# Validate output
curl -X POST http://localhost:8766/v1/scan/output \
  -H "Content-Type: application/json" \
  -d '{"output": "Contact John at [e-mail]", "schema": {"type": "object"}}'

# Health check (no auth required)
curl http://localhost:8766/v1/health

# Prometheus metrics (no auth required)
curl http://localhost:8766/metrics

API Endpoints

Method	Path	Auth	Description
POST	/v1/scan/prompt	API key	Scan prompt for injection patterns
POST	/v1/scan/output	API key	Validate LLM output against schema/policy
GET	/v1/health	None	Health check
GET	/metrics	None	Prometheus metrics
GET	/v1/rules	None	List active defense rules
GET	/v1/rules/:id	None	Get rule detail

Docker

# Build and run with Prometheus + OTel collector
docker-compose up -d

# With API key
PICOWATCH_API_KEY=your-secret-key docker-compose up -d

Architecture Decisions

See docs/adr/ for the full decision log.

• ADR-001 — Defense layer model (L5/L6/L7)
• ADR-002 — OpenTelemetry + Prometheus observability
• ADR-003 — Deterministic injection detection rules
• ADR-004 — Schema + policy output validation
• ADR-005 — Standalone-first with PicoShogun integration
• ADR-006 — Deterministic rule evaluation
• ADR-007 — Transport and deployment model
• ADR-008 — Supply-chain hardening

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,server]"
python -m pytest
ruff check .
mypy src

License

Business Source License 1.1 (BUSL-1.1) — source-available; production use allowed except for competitive offerings. After 3 years, converts to Apache-2.0. See LICENSE, LICENSE-SUMMARY.md, and COMMERCIAL-LICENSE.md.