Metadata-Version: 2.4
Name: supa
Version: 0.1.0
Summary: Local secret scanning with supaguard, by supa, inc.
Author: supa, inc.
License-Expression: Apache-2.0 AND MIT
Project-URL: Source, https://github.com/supainc/supaguard
Project-URL: Issues, https://github.com/supainc/supaguard/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES
Dynamic: license-file

# supa — local secret scanning

Scan text for API keys and credentials using the supaguard detection engine
from [supa, inc.](https://github.com/supainc/supaguard).
This is a Python API and command-line frontend to the bundled JavaScript engine.
**Python 3.10+ and Node.js 18+ on PATH are required.** Node.js is not installed
automatically. No npm packages are downloaded or executed at runtime.

## Install and use

```sh
pip install supa
supa guard message.txt
supa guard --json < message.txt
python -m supa guard message.txt
```

Only the explicitly supplied file or stdin is scanned. Do not put secret values
in command-line arguments. Nothing is sent over the network, and no event log
or copy of the input is written. Results contain rule IDs and severity only.

Exit codes: **0** no matching patterns; **1** one or more findings (including
warnings); **2** input or engine error. A timeout is an error, never a clean scan.
Input must be UTF-8 and no larger than 1 MiB. Each scan times out after 15 seconds.

```python
from supa import scan, ScanError

findings = scan("a harmless example")
assert findings == []
```

`scan()` returns dictionaries containing `id`, `name`, and `action` (`block` or
`warn`), or raises `ScanError` if the scan cannot complete. Treat errors separately
from clean results. The CLI reports findings; it does not automatically block
another application or install Claude Code hooks.

## Detection and limitations

Uses the existing supaguard regex, entropy, and allowlist logic, including its
bundled gitleaks rules. Rules tagged `block` are high-confidence detections in
the original plugin. Other detections are warnings. False positives and missed
secrets are possible: a clean scan does not prove input is safe. This version
scans content only; it does not enforce file-read policies, recursively scan
repositories, or modify Claude Code configuration.

Standalone scans deliberately ignore `~/.supaguard/config.json` and the plugin's
`[allow-secret]` bypass. Every shipped rule is enabled. The CLI does not send text
to an AI or provide an AI service itself.

## Source and licenses

The vendored engine is derived from supaguard commit
`63cd642d46057335270aa53a378b5e54265f2ff8`. Its standalone entrypoint adds strict
rules validation and stdin scanning without hooks, configuration, or logging.
Run `python tools/build-python-vendor.py` from the repository root to regenerate.
supaguard is Apache-2.0; bundled gitleaks rules are MIT. Both notices ship in the
distribution. See LICENSE and THIRD_PARTY_LICENSES.
