Metadata-Version: 2.4
Name: proofloop
Version: 0.1.0
Summary: Find security bugs in Python and prove them by running the attack in a sandbox (community edition).
Author: FIRME AI CORPORATION
License: Apache-2.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: slop
Requires-Dist: falsework; extra == "slop"
Dynamic: license-file

# PROOFLOOP community edition

**Find the security bugs in your Python code that an attacker can actually reach, and prove them.**

Most scanners say "this might be a bug." PROOFLOOP traces whether outside input (an HTTP route, an MCP tool argument,
model output) reaches a dangerous call, and with `--prove` it **runs the attack in a sandbox** against your own
function. CONFIRMED means the payload reached the shell, `eval`, the SQL text, the file path or the unsafe loader. No
model decides anything.

```
pip install proofloop                  # Linux; --prove also needs: apt install bubblewrap
proofloop scan .                       # find and tier
proofloop scan . --prove               # find, tier, and prove by running the attack
proofloop scan . --sarif out.sarif     # GitHub code scanning
```

```
BIG       try_it/app.py:12  outside input reaches a shell command (CWE-78)  [exploit CONFIRMED]
          outside input: request: parameter `name` of `convert`
```

## GitHub Action (runs on your own runner, free)

```yaml
- uses: actions/checkout@v4
- uses: firme-ai/proofloop@v0.1.0      # path to this repository once published
  with:
    path: "."
    prove: "true"
    fail-on: "BIG"
```

Findings appear in the repository's Security tab (code scanning).

## What the community edition proves
Command injection (CWE-78, including `asyncio.create_subprocess_shell` and `["bash", "-c", cmd]`), code injection
(CWE-94), SQL injection (CWE-89), path traversal (CWE-22) and unsafe deserialization (CWE-502), in Python.

Every finding is tiered: **BIG** (reachable from outside input, or a guard that says yes without checking),
**HARDENING**, or **REVIEW**. Known false-alarm shapes (test fixtures, inputs validated first, by-design tools) are
demoted, with the reason shown.

## Honest limits
Detection is heuristic: on fresh, untuned Python repositories about half of BIG findings were real in our own
evaluation. The sandbox replaces dangerous calls with recorders; it does not install your dependencies, so some
real bugs come back NOT_CONFIRMED. CONFIRMED is evidence the attack reaches the call, not a full exploit chain.

## Community edition vs hosted PROOFLOOP
| | Community (free, Apache-2.0) | Hosted PROOFLOOP (paid) |
|---|---|---|
| Python detection + reachability | ✓ | ✓ |
| Exploit proof, 5 classic classes | ✓ | ✓ |
| SSRF, template injection, missing authorization, attack variants | | ✓ |
| JavaScript/TypeScript, Go, Java, Rust, C/C++ | | ✓ |
| Cross-file tracing | | ✓ |
| PR comments, signed proofs, **CAIN-42 notarization** | | ✓ |
| AI fix proved by an independent test (fix-and-prove) | | ✓ |

https://cainstudio.online

## Licence
Apache-2.0. Copyright 2026 FIRME AI CORPORATION. "PROOFLOOP" and "CAIN-42" are names of FIRME AI CORPORATION and are
not licensed by the Apache licence. Contributions under the Developer Certificate of Origin; see CONTRIBUTING.md.
