Metadata-Version: 2.4
Name: picowatch
Version: 0.7.2
Summary: PicoWatch — LLM defender with telemetry: prompt injection detection, output validation, and observability
Author-email: Henrik Kirk <kirk@kirkforge.dev>
Maintainer-email: KirkForge <kirk@kirkforge.dev>
License-Expression: BUSL-1.1
Project-URL: Homepage, https://github.com/KirkForge/PicoWatch
Project-URL: Documentation, https://github.com/KirkForge/PicoWatch#readme
Project-URL: Repository, https://github.com/KirkForge/PicoWatch
Project-URL: Issues, https://github.com/KirkForge/PicoWatch/issues
Project-URL: Changelog, https://github.com/KirkForge/PicoWatch/blob/main/CHANGELOG.md
Project-URL: Release Notes, https://github.com/KirkForge/PicoWatch/releases
Project-URL: Source Code, https://github.com/KirkForge/PicoWatch
Project-URL: Bug Tracker, https://github.com/KirkForge/PicoWatch/issues
Project-URL: Commercial, https://github.com/KirkForge/PicoShogun
Keywords: llm,security,prompt-injection,output-validation,telemetry,observability,opentelemetry,defense,shogun,picowatch,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Framework :: Pytest
Classifier: Typing :: Typed
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-SUMMARY.md
License-File: COMMERCIAL-LICENSE.md
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == "server"
Requires-Dist: uvicorn>=0.23; extra == "server"
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp>=1.20; extra == "otel"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: jsonschema>=4.0; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: fastapi>=0.100; extra == "dev"
Requires-Dist: uvicorn>=0.23; extra == "dev"
Dynamic: license-file

![PicoWatch Banner](docs/banner.png)

# PicoWatch

**LLM prompt injection detection, output validation, and telemetry.**

[![CI](https://github.com/KirkForge/PicoWatch/actions/workflows/ci.yml/badge.svg)](https://github.com/KirkForge/PicoWatch)
[![PyPI](https://img.shields.io/pypi/v/picowatch)](https://pypi.org/project/picowatch/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![Rules](https://img.shields.io/badge/rules-91-blue)](rules/)
[![Tests](https://img.shields.io/badge/tests-258%20passing-brightgreen)](tests/)
[![License: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue)](LICENSE)
[![KirkForge](https://img.shields.io/badge/org-KirkForge-blue)](https://github.com/KirkForge)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support%20my%20hardware-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/kirkforge)

PicoWatch is the 3rd product in the [Pico Security Series](https://github.com/KirkForge). 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

```bash
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

```bash
# 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 john@example.com", "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

```bash
# 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](docs/adr/ADR-001-architecture.md) — Defense layer model (L5/L6/L7)
- [ADR-002](docs/adr/ADR-002-telemetry.md) — OpenTelemetry + Prometheus observability
- [ADR-003](docs/adr/ADR-003-prompt-injection.md) — Deterministic injection detection rules
- [ADR-004](docs/adr/ADR-004-output-validation.md) — Schema + policy output validation
- [ADR-005](docs/adr/ADR-005-integration.md) — Standalone-first with PicoShogun integration
- [ADR-006](docs/adr/ADR-006-determinism.md) — Deterministic rule evaluation
- [ADR-007](docs/adr/ADR-007-transport.md) — Transport and deployment model
- [ADR-008](docs/adr/ADR-008-security.md) — Supply-chain hardening

## Development

```bash
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), [LICENSE-SUMMARY.md](LICENSE-SUMMARY.md), and [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md).
