examples

Examples

Runnable, self-contained examples of using Stowaway — both as a CLI and as a Python library. Every script scans sample_project/, an inert sample that declares a typosquat (expresz, one edit from express) and an internal-namespace package (@acme/telemetry). It contains no executable code — the findings are purely name-based.

First install the package (from the repo root):

pip install -e .

Python library

Script	Shows
python_api.py	Scan a directory and inspect the Report / Finding objects
ci_gate.py	Fail the build when a package is assessed at or above a priority (exit codes)
baseline_workflow.py	Accept reviewed findings with a fingerprint-keyed baseline (VEX-lite)
emit_reports.py	Produce JSON, self-contained HTML, and SARIF 2.1.0 programmatically

python examples/python_api.py
python examples/ci_gate.py            # exits 1 — the sample has a P0
python examples/baseline_workflow.py
python examples/emit_reports.py ./out

CLI, on the same sample

# Human-readable HTML report + progress logs on stderr
stowaway scan examples/sample_project --internal-prefix @acme/ -v

# All formats, CI gate on P0 (exits 1 on this sample)
stowaway scan examples/sample_project --internal-prefix @acme/ \
    --format all --out ./out --fail-on P0

# Every rule and its false-positive characteristics
stowaway rules list

Expected on the sample: R1 typosquat on expresz and R2 dependency confusion on @acme/telemetry — score ~45/100, one P0 and one P1.

Everything is offline (no network at scan time), static (scanned code is never executed), and deterministic (same input → byte-identical output apart from the single report timestamp).