Documentation
How Puffer works under the hood
Deep dives into the architecture, operations and threat model. Start with Getting Started if you're new.
Getting Started ↗
Local hacking runbook — install, run the test suite, spin up the Docker observability stack (Prometheus, Grafana, Loki, Jaeger), send a smoke request through the proxy.
Architecture Overview ↗
Project identity, the 7-layer pipeline, monorepo layout (3 apps + 24 packages), how the daemon, proxy, hooks and dashboard fit together.
Implementation Phases ↗
The 6 build phases — proxy, discovery, 7-layer defense, CLI, dashboard, agent hooks — and the order they were brought online.
Configuration & Audit ↗
YAML schema, default policy, the 4 operating modes (monitor, enforce, paranoid, interactive) and the JSONL audit log format at ~/.puffer/audit.jsonl.
Observability ↗
Prometheus metrics catalog, structured JSON logs for Loki/Datadog/CloudWatch, OpenTelemetry traces, PromQL recipes and Grafana dashboards.
Testing Strategy ↗
Unit + integration + adversarial test layout. Every detection rule ships with positive and negative cases; the adversarial suite must pass before merge.
Packaging & Release ↗
npm distribution model — 24 private packages compiled via TypeScript project references, build order, semver, and how puffer ships globally as `openpuffer`.
Skill (for AI agents)
The agent-facing skill that teaches your LLM to install Puffer, run in monitor mode, read the dashboard and interpret verdicts from the 7 layers.
Looking for something specific?
Open an issue at github.com/openpuffer/puffer/issues or reach out via the disclosure channel for security questions.