Metadata-Version: 2.4
Name: flowpatrol-cli
Version: 1.0.1
Summary: Flowpatrol CLI — run security scans from your terminal
Project-URL: Homepage, https://flowpatrol.ai
Project-URL: Documentation, https://github.com/flowpatrol/cli/tree/main/python#readme
Project-URL: Repository, https://github.com/flowpatrol/cli
Project-URL: Issues, https://github.com/flowpatrol/cli/issues
Project-URL: Changelog, https://github.com/flowpatrol/cli/blob/main/python/CHANGELOG.md
Author-email: Flowpatrol Team <team@flowpatrol.ai>
License: MIT
License-File: LICENSE
Keywords: appsec,cli,flowpatrol,scanning,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
Description-Content-Type: text/markdown

# flowpatrol-cli

Command-line interface for [Flowpatrol](https://flowpatrol.ai) — run automated
security scans against your web applications directly from your terminal or CI
pipeline.

## Requirements

- Python 3.10 or later
- A Flowpatrol API key ([sign up](https://flowpatrol.ai))

## Installation

```bash
pip install flowpatrol-cli
# or, recommended for CLI tools:
pipx install flowpatrol-cli
```

## Quick start

```bash
# 1. Save your API key
flowpatrol auth set-key fp_live_abc123

# 2. Run a Surface scan (fast, waits for results)
flowpatrol surface https://myapp.com

# 3. Run a full scan
flowpatrol scan https://myapp.com
```

## Commands

### `flowpatrol auth set-key <key>`

Store your API key in `~/.config/flowpatrol/config.json`. The key is also read
from the `FLOWPATROL_API_KEY` environment variable, which takes precedence.

```bash
flowpatrol auth set-key fp_live_abc123
```

### `flowpatrol auth whoami`

Show the currently active API key (redacted) and API endpoint.

```bash
flowpatrol auth whoami
flowpatrol auth whoami --verify   # also verify the key against the API
```

### `flowpatrol surface <url>`

Run a Surface scan — headers, secrets, fingerprints, RLS, screenshots.

```bash
flowpatrol surface https://myapp.com
flowpatrol surface https://myapp.com --format json
flowpatrol surface https://myapp.com --format sarif
flowpatrol surface https://myapp.com --timeout 300   # 5-minute timeout
```

Exits with code `1` if critical or high findings are found, `0` if clean.

### `flowpatrol scan <url> [options]`

Run a full scan. Waits for completion by default.

```bash
flowpatrol scan https://myapp.com
flowpatrol scan https://myapp.com --mode deep
flowpatrol scan https://myapp.com --no-wait          # fire-and-forget
flowpatrol scan https://myapp.com --format sarif > results.sarif
```

Options:

| Flag | Default | Description |
|------|---------|-------------|
| `-m, --mode` | `deep` | `surface` \| `deep` |
| `-f, --format` | `human` | `human` \| `json` \| `sarif` |
| `--no-wait` | — | Return immediately with the scan ID |
| `--timeout <seconds>` | `3600` | Give up polling after N seconds |

### `flowpatrol status <scan-id>`

Check the current status of a scan.

```bash
flowpatrol status abc-123-def
```

Exit codes: `0` = complete, `1` = still running, `2` = failed/cancelled.

### `flowpatrol report <scan-id> [options]`

Fetch the full report for a completed scan.

```bash
flowpatrol report abc-123-def
flowpatrol report abc-123-def --format json
flowpatrol report abc-123-def --format sarif > results.sarif
flowpatrol report abc-123-def --severity critical,high   # filter output
```

Options:

| Flag | Default | Description |
|------|---------|-------------|
| `-f, --format` | `human` | `human` \| `json` \| `sarif` |
| `--severity` | all | Comma-separated list to filter: `critical,high,medium,low,info` |

## Global flags

| Flag | Description |
|------|-------------|
| `-q, --quiet` | Suppress all human output; rely on exit codes only |
| `-v, --version` | Print CLI version |
| `-f, --format` | Default output format for all commands: `human` \| `json` \| `sarif` |
| `--api-url` | Override the API base URL |
| `--api-key` | Override the API key (takes precedence over config file and env var) |

## Configuration

Configuration is stored at `~/.config/flowpatrol/config.json`:

```json
{
  "apiKey": "fp_live_abc123",
  "apiUrl": "https://api.flowpatrol.ai"
}
```

Environment variables override the config file:

| Variable | Description |
|----------|-------------|
| `FLOWPATROL_API_KEY` | API key |
| `FLOWPATROL_API_URL` | API base URL (useful for self-hosted or local dev) |

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success — scan clean or command completed without findings |
| `1` | Findings detected (critical or high severity) |
| `2` | Error — invalid arguments, network failure, auth failure, timeout |

## CI / GitHub Actions example

```yaml
- name: Security scan
  run: |
    pipx install flowpatrol-cli
    flowpatrol scan ${{ env.DEPLOY_URL }} --format sarif > flowpatrol.sarif
  env:
    FLOWPATROL_API_KEY: ${{ secrets.FLOWPATROL_API_KEY }}

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: flowpatrol.sarif
```

## SARIF output

The `--format sarif` flag produces SARIF 2.1.0 output compatible with GitHub
Advanced Security, VS Code SARIF Viewer, and any SARIF-aware tool.

Each finding maps to a SARIF rule with:
- A stable ID derived from the finding type (e.g. `FP-SQL-INJECTION`)
- OWASP and CWE tags when available
- `high` precision for confirmed findings, `medium` for unconfirmed

## Human output example

```
  Flowpatrol — https://myapp.com
  ─────────────────────────────────────────────

  CRITICAL  Supabase service_role key exposed in client JS
            GET / → found in main-abc123.js
            Fix: Move service key to a server-only environment variable
            OWASP A02:2021 · CWE-312

  HIGH      Missing Row Level Security on 'users' table
            /rest/v1/users readable with anon key
            Fix: Enable RLS and add a SELECT policy

  ─────────────────────────────────────────────
  1 critical · 1 high · 0 medium · 0 low
  Scan ID: abc-123-def  |  Duration: 42s
```

## License

[MIT](./LICENSE) © Flowpatrol
