PicoSentry 🦞

Deterministic, offline supply-chain scanner for npm/pnpm.

PicoSentry is the first product in the Pico security series — a set of deterministic security tools for software supply chains. Companion tools: PicoDome (runtime sandbox), PicoWatch (LLM defense), PicoShogun (command centre).

Same inputs + same corpus version = same findings and scan fingerprint. Every time.

No HTTP at scan time. No probabilistic heuristics. No narrative in findings.

Deterministic output: Default JSON includes audit timestamps and timing data. For byte-identical CI artifacts, use --deterministic-output or --verify-determinism.

Quick Start

pip install picosentry

# Scan a project
picosentry scan ./my-project

# CI gate (exit 1 on HIGH+CRITICAL)
picosentry check ./my-project --fail-on high

# Deterministic JSON
picosentry scan ./my-project --format json --deterministic-output

# Verify byte-identical determinism
picosentry scan ./my-project --verify-determinism

# Monorepo scan
picosentry workspace .

# CycloneDX SBOM
picosentry scan ./my-project --format cyclonedx

What It Detects

21 deterministic rules across 6 attack categories:

Category	Rules	Severity
Post-install scripts	L2-POST-001	HIGH–CRITICAL
Obfuscation	L2-OBFS-001..004	HIGH
Dependency confusion	L2-DEPC-001	HIGH
Typosquatting	L2-TYPO-001	MEDIUM–HIGH
Manifest anomalies	L2-MANI-001/002	MEDIUM
Fork drift	L2-FORK-001	MEDIUM
Credential exposure	L2-CRED-001	HIGH–CRITICAL
Lockfile drift	L2-LOCK-001	MEDIUM
Bundled shadow code	L2-BUND-001	HIGH
Provenance	L2-PROV-001	MEDIUM
Maintainer changes	L2-MAINT-001	MEDIUM
pnpm config	L2-PNPM-001	MEDIUM
License violations	L2-LICENSE-001	MEDIUM
Engine constraints	L2-ENGIN-001	LOW
Protocol sideloading	L2-SIDELOAD-001	HIGH
Advisory lookup	L2-ADV-001	MEDIUM–CRITICAL

See SCAAT.md for the full attack-vector-to-rule mapping.

Deterministic Guard Stack

┌─────────────────────────────────────────┐
│  Layer 4: CI Gate                       │
│  --verify-determinism (CLI)             │
├─────────────────────────────────────────┤
│  Layer 3: Diff                          │
│  picosentry diff a.json b.json          │
├─────────────────────────────────────────┤
│  Layer 2: Guard (runtime)               │
│  Validates invariants after each scan   │
├─────────────────────────────────────────┤
│  Layer 1: Models (structural)           │
│  Frozen dataclasses, sorted keys        │
└─────────────────────────────────────────┘

CLI Reference

picosentry scan <target> [OPTIONS]     Scan a project directory
picosentry check <target> [OPTIONS]    CI health check (exit-code only)
picosentry workspace <root> [OPTIONS]  Scan monorepo
picosentry corpus export/import/list    Manage IoC corpus packs
picosentry ioc register/list/remove    Manage custom IoCs
picosentry rules [--json]              List detector rules
picosentry version                     Version, corpus, rule count
picosentry diff <a.json> <b.json>      Compare scans for determinism
picosentry init [target] [--force]     Generate .picosentry.yml
picosentry update [--top N]            Download latest npm corpus

Scan Options:
  --format, -f        json, sarif, table, ml-context, github, cyclonedx
  --output, -o        Write output to file
  --rules, -r         Run only specific rules
  --corpus, -c        Path to corpus directory
  --exit-code         Exit 1 if findings found
  --fail-on           Exit 1 only at or above severity
  --quiet, -q         Summary only
  --baseline, -b      Path to baseline JSON or ignore file
  --verbose, -v       Per-rule timing and scan details
  --timeout           Scan timeout in seconds (0 = no timeout)
  --deterministic-output  Omit timestamps for byte-identical output
  --verify-determinism   Run twice, verify SHA-256 match

Daemon Mode

PicoSentry can run as an HTTP daemon for CI integration and team use:

# Token auth
PICOSENTRY_AUTH_TOKEN=your-token picosentry daemon --port 9090

# OIDC/JWT auth
PICOSENTRY_AUTH_MODE=oidc picosentry daemon --port 9090

# Enterprise mode (fail-closed defaults)
PICOSENTRY_ENTERPRISE_MODE=1 picosentry daemon --port 9090

See docs/DAEMON.md for full daemon configuration, RBAC, and TLS.

Architecture

picosentry/
├── cli.py               # CLI entry point
├── engine.py            # ScanEngine orchestrator
├── models.py            # Finding, ScanResult (frozen dataclasses)
├── guards.py            # Deterministic guard stack
├── config.py            # .picosentry.yml loader
├── daemon.py            # HTTP daemon (health, scan, metrics)
├── auth.py              # Token + OIDC/JWT auth, RBAC scopes
├── enterprise.py        # Fail-closed enterprise mode enforcement
├── rules/               # 21 detector rules (pure functions)
├── formatters/          # 6 output formats
└── corpus/              # Built-in IoC database

Status

See STATE.md for honest project status — what's production-ready, what's scaffolded, what's not built.

Documentation

• SCAAT.md — Attack-vector-to-rule mapping
• SECURITY.md — Vulnerability reporting
• CONTRIBUTING.md — How to contribute
• CHANGELOG.md — Release history
• LICENSE — BUSL-1.1
• COMMERCIAL-LICENSE.md — Commercial licensing

License

Business Source License 1.1 (BUSL-1.1) — source-available; production use allowed except for competitive offerings. Commercial use that competes with KirkForge's paid products requires a separate commercial license. After 3 years, converts to Apache-2.0. See LICENSE, LICENSE-SUMMARY.md, and COMMERCIAL-LICENSE.md.

Pico Security Series

Tool	Purpose
PicoSentry 🦞	Deterministic offline supply-chain scanner
PicoDome 🛡️	Runtime sandbox + behavioral analysis
PicoWatch 👁️	LLM prompt/output defense + telemetry
PicoShogun	Command centre (enterprise) / panel (personal)