PicoSentry

Catch malicious packages before they bite. PicoSentry is an offline, deterministic supply-chain security suite: a static scanner for typosquatting, dependency confusion, obfuscation, exfiltration, IOCs and CVEs across 7 ecosystems; a kernel sandbox; an LLM prompt/output guard; and a multi-tenant API server tying them together. No internet required, no phone-home, bit-identical output for identical inputs.

All technical documentation lives in the manual — install options, CLI reference, every detection rule, deployment, security model, operations, and benchmarks.

60-second quickstart

pip install picosentry
picosentry scan ./your-project

Works offline, deterministic, no API keys. Try it on a built-in malicious fixture:

git clone https://github.com/KirkForge/PicoSentry.git
cd PicoSentry
picosentry scan examples/pypi-obfuscated-setup/

The scan fires 5+ findings across obfuscation, post-install, and exfiltration rules. Re-run it: the Scan ID and Corpus digest match exactly — that's the determinism guarantee (--verify-determinism asserts it in CI).

The four components

picosentry scan — the static supply-chain scanner. Analyzes package manifests, lockfiles, and source across npm, PyPI, Go, Cargo, Maven, RubyGems, and NuGet: 53 L2 detection rules covering typosquats, dependency confusion, install-time execution, obfuscation, credential access, network exfiltration, known CVEs (OSV), and license compliance. Advisory findings carry a reachable flag so present-but-unused CVEs triage faster. → Manual ch. 5

picosentry sandbox — the runtime sandbox (PicoDome). Executes untrusted commands under seccomp-bpf (Linux) or seatbelt (macOS), records syscall-level behavioral events for L4 analysis, and ships as an HTTP + gRPC sandbox-as-a-service daemon with auth, rate limiting, TLS/mTLS, and token-scoped multi-tenancy. → Manual ch. 8

picosentry watch — the LLM defense layer (PicoWatch). Deterministic, offline prompt-injection detection (L5) and output-policy validation (L6): regex rules plus a lexical classifier behind a normalizer that defeats base64/ROT13/homoglyph/zero-width obfuscation. A fast pre-filter, honestly not a semantic guarantee. → Manual ch. 7

picosentry serve — the control plane. FastAPI API server with dashboard, RBAC (viewer/operator/admin), MFA/TOTP, JWT revocation, role-scoped API keys, multi-tenant SQLite/Postgres persistence, plugins, scheduling, alerting, and cross-layer kill-chain correlation (Beta). → Manual ch. 9

Also: picosentry firewall (registry metadata proxy), daemon, admission (K8s webhook), corpus, advisories, update, diff, doctor, rules, init, health, version — full CLI reference in the manual ch. 4.

Status

"Beta" = works, has regression + security tests, suitable for controlled production use. This table is generated from picosentry/experimental.py and CI-enforced against drift. Per-component reviews: manual, security chapters.

Install

pip install picosentry                # core (offline-ready)
pip install picosentry[scan]          # + online corpus management
pip install picosentry[serve]         # + API server + dashboard
pip install picosentry[all]           # everything

Docker: docker pull kirkforge/picodome:v2.0.18 (latest published; multi-arch, non-root) — kirkforge/picodome:v2.2.0 push pending (WO5.0.0-014). All install options incl. [grpc], [watch-server], [otel], [sigstore]: manual ch. 2.

The manual

Everything technical is in docs/manual.md:

Quick start · Install · Docker · CLI reference · Scanner · Firewall · Watch · Sandbox · Serve · Plugins · Architecture · Configuration · Runbook · Offline · Deployment security · Threat model · Attack surface · Benchmarks & model card · Internal API map · Extension guide · Limitations & status · ADR index

Reference files that stay standalone: generated per-rule benchmark table docs/BENCHMARKS.md (CI-enforced) and the ADRs.

Supply chain: wheel builds are reproducible — SOURCE_DATE_EPOCH is pinned from the commit timestamp in release.yml, the Dockerfile, and CI, so the same source yields a byte-identical wheel (asserted by the CI reproducible-build job). Details: manual ch. 15.

Getting help

• Issues: GitHub Issues
• Security (not a public issue): SECURITY.md or private report
• Discussion: GitHub Discussions
• Contributing: CONTRIBUTING.md

License

BUSL-1.1 — see LICENSE and COMMERCIAL-LICENSE.md.