Stowaway is a security tool that parses untrusted input — the manifests, lockfiles, and install scripts of projects it scans may be authored by an attacker. Its own security posture therefore matters as much as its detections. This document covers both: how to report a vulnerability, and the guarantees Stowaway makes about its own behavior.

Stowaway is pre-1.0. Security fixes land on main and in the next release.

Please do not open a public issue for a security vulnerability.

Report privately via GitHub's Private vulnerability reporting (Security tab → Report a vulnerability). Include:

• affected version / commit,
• a minimal reproduction (an inert manifest or lockfile is ideal — see the inert-fixture law in docs/CONTRIBUTING.md),
• the impact you observed (crash, path escape, resource exhaustion, false silence, etc.).

Expect an acknowledgement within a few days. Coordinated disclosure is appreciated; we will credit reporters who wish to be named.

Because Stowaway processes hostile input offline, the security-relevant failure modes are specific:

• Arbitrary file read / path escape — a scanned manifest causing Stowaway to read a file outside the scan root (via ../ traversal or a symlink). Every read must go through read_text_capped, which confines to the root; a bypass is a vulnerability. See tests/test_security.py.
• Code execution — Stowaway is static-only; scanned code is never executed. Any path that executes, evals, or imports scanned content is a critical vulnerability.
• Network access at scan time — Stowaway is offline by design. Any scan-time network I/O is a vulnerability (and a broken promise).
• Denial of service — a crafted input causing unbounded CPU, memory, or recursion (ReDoS, decompression/decode amplification, deep-nesting RecursionError). Parsers cap file sizes, bound .gitignore cost, and catch RecursionError. A crash or hang on adversarial input is a vulnerability.
• Detection integrity — a trivially reachable way to make a genuinely malicious pattern silently disappear (false negative by construction) is a security concern, not merely a calibration bug.

Ordinary heuristic false positives / false negatives are not security vulnerabilities — they are calibration, tracked as regular issues. Every rule documents its false-positive modes on purpose.

• Zero runtime dependencies. A security tool's own dependency tree is an attack surface; Stowaway is standard-library only. This is enforced by dependencies = [] in pyproject.toml.
• Offline, static, deterministic. No network at scan time, no execution of scanned code, same input → byte-identical output (apart from a single report timestamp).
• Defensive parsing. All reads are size-capped and root-confined; malformed input yields a LOW finding, never a crash.
• An inert repository. Stowaway detects malware; the repo contains none. Every fixture is a benign mimic, enforced by tests/test_inertness_guard.py.

See docs/THREAT_MODEL.md for the full parser-hardening stance.