Metadata-Version: 2.4
Name: picosentry
Version: 1.0.0
Summary: PicoSentry — deterministic supply-chain scanner for npm/pnpm, safe for ML pipelines
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/PicoSentry
Project-URL: Documentation, https://github.com/KirkForge/PicoSentry/blob/main/README.md
Project-URL: Repository, https://github.com/KirkForge/PicoSentry
Project-URL: Issues, https://github.com/KirkForge/PicoSentry/issues
Project-URL: Changelog, https://github.com/KirkForge/PicoSentry/blob/main/CHANGELOG.md
Project-URL: Release Notes, https://github.com/KirkForge/PicoSentry/releases
Project-URL: Source Code, https://github.com/KirkForge/PicoSentry
Project-URL: Bug Tracker, https://github.com/KirkForge/PicoSentry/issues
Keywords: supply-chain,security,npm,pnpm,scanner,deterministic,ml-safe,picosentry,sbom,cyclonedx,sarif,sca,software-composition-analysis,devsecops,ci-cd
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
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: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Software Distribution
Classifier: Environment :: Console
Classifier: Framework :: Pytest
Classifier: Typing :: Typed
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
Provides-Extra: pnpm
Requires-Dist: pyyaml>=6.0; extra == "pnpm"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: sigstore
Requires-Dist: sigstore>=3.0; extra == "sigstore"
Requires-Dist: types-PyYAML; extra == "sigstore"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: sigstore>=3.0; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: all
Requires-Dist: pyyaml>=6.0; extra == "all"
Dynamic: license-file

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

# PicoSentry 🦞

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

[![CI](https://github.com/KirkForge/PicoSentry/actions/workflows/ci.yml/badge.svg)](https://github.com/KirkForge/PicoSentry/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/picosentry)](https://pypi.org/project/picosentry/)
[![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/)
[![Tests](https://img.shields.io/badge/tests-1401%20passing-brightgreen)](https://github.com/KirkForge/PicoSentry)
[![Rules](https://img.shields.io/badge/rules-21-informational)](src/picosentry/docs/rules/)
[![Deterministic](https://img.shields.io/badge/deterministic-sha256%20verified-brightgreen)](SCAAT.md)
[![License: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue)](LICENSE)
[![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)

PicoSentry is the first product in the **Pico security series** — a set of deterministic security tools for software supply chains. Companion tools: [PicoDome](https://github.com/KirkForge/PicoDome) (runtime sandbox), [PicoWatch](https://github.com/KirkForge/PicoWatch) (LLM defense), [PicoShogun](https://github.com/KirkForge/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

```bash
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](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:

```bash
# 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](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](STATE.md) for honest project status — what's production-ready, what's scaffolded, what's not built.

## Documentation

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

## Pico Security Series

| Tool | Purpose |
|------|---------|
| **PicoSentry** 🦞 | Deterministic offline supply-chain scanner |
| [PicoDome](https://github.com/KirkForge/PicoDome) 🛡️ | Runtime sandbox + behavioral analysis |
| [PicoWatch](https://github.com/KirkForge/PicoWatch) 👁️ | LLM prompt/output defense + telemetry |
| [PicoShogun](https://github.com/KirkForge/PicoShogun) | Command centre (enterprise) / panel (personal) |
