PicoSentry

Catch malicious packages before they bite. Offline supply-chain scanner — obfuscation, typosquatting, dependency confusion, exfiltration, IOCs, CVEs across 7 ecosystems. No internet required.

Quick start

pip install picosentry
picosentry scan ./your-project

That's it. Works offline, deterministic, no phone-home.

See it in action

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

🦞 PicoSentry
Target: /home/you/PicoSentry/examples/pypi-obfuscated-setup
Engine: v2.1.1 | Corpus: vef6b3b3115bb
Scan ID: 08057439b4ba08d8

Packages scanned: 0
Files scanned:     2
Duration:          20ms

The scan fires 5+ findings across obfuscation, post-install, and exfiltration rules. Re-run and the Scan ID and Corpus digest match exactly — that's the determinism guarantee.

What it detects

Advisory findings also carry a reachable flag — True when the vulnerable package is actually imported/used in the scanned source, so you can triage present-but-unused CVEs (rules/advisory_check.py).

50 L2 rules (65 with L4 behavioral detectors) across npm, PyPI, Go, Cargo, Maven, RubyGems, and NuGet. Full catalog: picosentry/scan/docs/rules/

Supported ecosystems

Why PicoSentry?

Offline + deterministic + malicious-behavior rules in one package.

Status

"Beta" = works, has regression + security tests, suitable for controlled production use. Per-component reviews in docs/.

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.1.1 — multi-arch, non-root.

More

• Technical manual — full install options, gRPC transport, plugin system, corpus management, repository structure, and sandbox details

CLI commands

picosentry scan (core scanner), sandbox (isolation), watch (LLM guards), serve (API server), daemon (sandbox-as-a-service), admission (K8s webhook), corpus (IoC packs), diff (compare scans), doctor (self-verification), firewall (network policy), rules (list/disable rules), init (project config), health (status check), version, update.

• Architecture — component diagram and trust boundaries
• Detection benchmarks — 6495 fixtures, 50 rules (50 L2 + 65 L4 behavioral), precision/recall per rule
• Security reviews — per-component security analysis
• Plugin development — write, sign, and deploy plugins

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).

Design principles

• Deterministic — same inputs + same policy = same SHA-256 output
• Offline by default — no phone-home, no remote API calls
• Lightweight core — default install pulls only pyyaml
• Typed — full annotations, py.typed shipped

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.