Metadata-Version: 2.5
Name: finlexpurple
Version: 0.3.0
Summary: Local, hardened autonomous security agent that tests a financial app and everything it trusts — AI/MCP, dependencies, and containers — with deterministically verified, cryptographically provable findings.
Project-URL: Homepage, https://github.com/FinLexPurple/finlexpurple
Project-URL: Repository, https://github.com/FinLexPurple/finlexpurple
Project-URL: Changelog, https://github.com/FinLexPurple/finlexpurple/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/FinLexPurple/finlexpurple/issues
Author: FinLexPurple
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: container-security,fintech,mcp,pentest,sast,security,supply-chain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: anthropic>=1.0
Requires-Dist: google-genai>=1.0
Requires-Dist: httpx>=0.27
Requires-Dist: ollama>=0.5
Requires-Dist: openai>=2.0
Requires-Dist: pydantic-settings>=2
Requires-Dist: pydantic>=2
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# FinLexPurple

**A local, air-gapped-capable, hardened autonomous security agent that tests a
financial application — and everything it now trusts.**

A modern financial app is no longer just its own code and endpoints. It trusts
AI agents and their MCP tool integrations, a tree of third-party software
dependencies, and the container images it ships in. FinLexPurple's thesis is
**one engagement, whole surface**: test the application *and* its AI/MCP
integrations, its dependencies, and its containers together — with findings that
are **deterministically verified** (re-executed by code, not asserted by an LLM)
and **cryptographically provable** (a signed, reproducible evidence bundle per
verified finding).

> **AUTHORIZATION REQUIRED — this is an offensive security tool.** Only run
> FinLexPurple against systems you own or have **explicit, written authorization**
> to test. Unauthorized scanning may be illegal. The tool requires you to attest
> authorization for each target (recorded in a tamper-evident audit log), runs
> default-deny egress and spend/iteration caps, and never auto-exploits financial
> or MCP actions without a human gate — but **you are responsible** for using it
> lawfully.

---

## Project status (honest)

FinLexPurple is in **active, pre-1.0 development**, released milestone by
milestone. What works today:

| Capability | Status |
|---|---|
| Hardware/provider setup, scope confirmation + authorization attestation | yes — works |
| `scan` end-to-end: recon → web detectors → verification → report | yes — works |
| Web detectors (SQLi/XSS/IDOR/SSRF…) + deterministic verification | yes — runs in `scan` |
| Signed evidence bundle + standalone `verify-bundle` | yes — works (`scan` writes a bundle per verified finding) |
| MCP offensive testing | yes — module (runnable; not yet auto-run by `scan`) |
| Supply-chain (OSV/pip-audit wrap, slopsquat, typosquat, secrets) | yes — module (`--include` wiring is a follow-up) |
| Container (Trivy/Grype/Dockle/hadolint wrap, escape checks) | yes — module (`--include` wiring is a follow-up) |
| AST CodeFix (tree-sitter, JS/TS + Python) | yes — module (whitebox `scan` flow is a follow-up) |
| Reporting engine (`report.json`/`report.md`, text badges, 0600) | yes — runs in `scan` |

**The web path is wired end-to-end.** `finlexpurple scan --target <url>` confirms
scope + authorization, runs recon, runs the web detectors through a scope-safe
prober, verifies each finding by deterministic replay, and writes a full report
tree (`report.json`, `report.md`, `evidence/`, `replay-logs/`, and a signed
bundle per verified finding) into `./finlexpurple-reports/<run>/`.

**Still a follow-up:** the supply-chain and container surfaces (`--include
supplychain|container`) and the whitebox CodeFix flow (`--path … --mode
whitebox --fix-mode agent`) are complete, tested modules but are **not yet
auto-run by `scan`** — run them via their module entry points for now. See the
[CHANGELOG](CHANGELOG.md) for exact per-release status.

This is a pre-release; the API, CLI flags, and output layout may change before
1.0.

---

## Install

Requires Python 3.10+.

```bash
pip install finlexpurple
```

Some capabilities **wrap best-of-breed open-source scanners** rather than
reimplementing them. Install the ones you need and check availability with
`finlexpurple doctor --tools`:

- Supply-chain: [osv-scanner](https://google.github.io/osv-scanner/), [pip-audit](https://pypi.org/project/pip-audit/)
- Container: [Trivy](https://trivy.dev/), [Grype](https://github.com/anchore/grype), [Dockle](https://github.com/goodwithtech/dockle), [hadolint](https://github.com/hadolint/hadolint)
- Evidence signing: [cosign](https://docs.sigstore.dev/cosign/) (optional; bundles are hash-only without it)
- Container isolation: Docker (Standard tier)

Missing tools are reported clearly and their steps are **skipped**, never faked.

## Usage

```bash
# 1. See your hardware and which external scanners are installed
finlexpurple doctor
finlexpurple doctor --tools

# 2. Configure model provider / hardware tier, and the container-isolation tier
finlexpurple setup
finlexpurple setup-isolation
finlexpurple init                 # create a local .env from the template

# 3. Scan a target you are authorized to test (confirms scope + attestation,
#    then recon + the orchestration loop). You will be asked to confirm scope.
finlexpurple scan --target https://app.example.com/
finlexpurple scan --target 10.0.0.0/24 --root-url http://10.0.0.5/   # IP/CIDR
finlexpurple resume <run-id>      # resume a paused run

# 4. Independently re-verify a finding's evidence bundle — offline, standalone
finlexpurple verify-bundle ./finlexpurple-reports/<run>/evidence/<id>.bundle.json
```

Run state and reports are written under `./finlexpurple-reports/` (gitignored;
reports are `0600` on POSIX because they contain real vulnerability detail).

### The verify-bundle flow (the credibility differentiator)

A verified finding is backed by a reproducible **evidence bundle**: the exact
request/response, the deterministic replay log, and a canonical content hash
(and, when cosign is available and you are online, a Sigstore signature). Anyone
— an auditor, a client, a regulator — can re-check it on their own machine, with
**no scan and no network**:

```bash
finlexpurple verify-bundle finding.bundle.json
finlexpurple verify-bundle finding.bundle.json --expected-hash sha256:<from-the-report>
```

It recomputes the hash and reports tampering clearly; a bundle altered after
creation fails verification.

## What makes it different

1. **Deterministic exploit verifier** — findings are re-executed by code, never trusted on an LLM's say-so.
2. **Local / air-gapped / bring-your-own-model** — runs fully local via Ollama; cloud providers optional.
3. **AI-agent / MCP offensive testing** — active prompt-injection, tool-poisoning, exfiltration-oracle testing (hard-gated).
4. **Hardened by default** — default-deny egress, spend/iteration caps, never mounts the Docker socket, never privileged.
5. **Fintech business-logic specialization** — a suite of financial-domain agents (later milestone).
6. **Slopsquatting / hallucinated-dependency detection** — catches packages an AI coding agent might invent or that were attacker-registered.
7. **Payment-SDK typosquat detection** — fake Stripe/JazzCash/Easypaisa/Paysafe-style packages.
8. **Privacy-by-architecture install counter** — opt-in, cannot identify you.
9. **Three-state verified badge + aggregate "% verified"** — `[VERIFIED]` / `[REPORTED]` / `[HUMAN-CONFIRMED]`, as plain text (no emoji).
10. **One engagement, whole surface** — app + AI/MCP + dependencies + containers, not four-to-six stitched-together tools.
11. **Reproducible, signed evidence bundle per finding** — independently re-verifiable.
12. **Tiered container isolation** — the scan runs inside a hardened boundary (None / Standard-Docker / Maximum-gVisor).

Where mature OSS scanners exist, FinLexPurple **wraps** them (Trivy, Grype,
OSV-Scanner, pip-audit, mcp-scan, hadolint, Dockle) and normalizes their real
output into one finding schema — it does not reimplement their databases.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and pull requests welcome.

## License

Apache License 2.0 — see [LICENSE](LICENSE).
