liveapisec 0.1.0__tar.gz

liveapisec-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: liveapisec
+Version: 0.1.0
+Summary: LiveAPISec Developer API client — push API specs, run security scans and gate your CI/CD from the command line.
+Author: LiveAPISec
+License: MIT
+Project-URL: Homepage, https://liveapisec.com
+Project-URL: Documentation, https://liveapisec.com/settings
+Keywords: security,api,dast,scanning,ci,cd
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+
+# liveapisec — CLI/SDK do LiveAPISec Developer API
+
+Oficjalny, cienki klient do **LiveAPISec Developer API**. Instalujesz raz,
+używasz w dowolnym projekcie, skrypcie i pipeline CI/CD — bez dashboardu i bez curl.
+
+> **Kiedy to jest?** Zamiast ręcznie przechodzić kreatora w panelu, developer
+> pushuje endpointy + opcjonalny token z **swojego** środowiska (CI/CD, agent,
+> skrypt). Token jest generowany u Ciebie i szyfrowany po stronie serwera (AES-256).
+> **Tip: brak tokena = testujemy tylko to, co publiczne.**
+
+---
+
+## Instalacja
+
+Z GitHub (rekomendowane, zanim trafimy na PyPI):
+
+```bash
+pip install "liveapisec @ git+https://github.com/LiveApiSec/liveapisec.git"
+```
+
+Po publikacji na PyPI:
+
+```bash
+pip install liveapisec
+```
+
+Sprawdź:
+
+```bash
+liveapisec --help
+```
+
+Kiedy zainstalujesz raz (np. w obrazie CI, na maszynie dev, w GitHub Actions) —
+komenda `liveapisec` jest dostępna **w każdym projekcie** w tej maszynie.
+
+---
+
+## Konfiguracja
+
+Klucz API generujesz raz w panelu: **Settings → Developer API → Create API key**
+(klucz `las_dev_...` pokazywany jest tylko raz — trzymaj go jako secret).
+
+```bash
+export LIVEAPISEC_API_KEY=las_dev_...          # wymagane
+export LIVEAPISEC_API_URL=https://liveapisec.com   # opcjonalne (domyślne)
+```
+
+Można też podać per-komenda: `--api-key` / `--api-url`.
+
+---
+
+## Komendy
+
+### 1. `push` — wyślij API (idempotentne, bezpieczne w CI)
+
+```bash
+liveapisec push \
+  --name my-api \
+  --base-url https://api.example.com \
+  --endpoint "GET /users" \
+  --endpoint "POST /payments"
+```
+
+- Ten sam `name` + `base_url` = **ten sam site** (aktualizacja, nie duplikat) —
+  możesz wołać push w każdym buildzie.
+- Zamiast listy endpointów możesz podać OpenAPI: `--openapi-url https://api.example.com/openapi.json`.
+- Opcjonalny token: `--auth-type jwt --auth-token <TOKEN>` (albo `bearer`,
+  `cookie --auth-cookie "session=..."`, `api_key --auth-header X-API-Key`).
+
+Wynik:
+
+```
+site 65f...abc: my-api — 2 endpoints, auth=none
+export SITE_ID=65f...abc
+```
+
+### 2. `scan` — odpal test bezpieczeństwa
+
+```bash
+# zwykłe odpalanie (202, nie czeka)
+liveapisec scan --site SITE_ID --branch main --commit "$GITHUB_SHA"
+
+# czekaj na wynik i próg błędu dla CI (gate)
+liveapisec scan --site SITE_ID --branch main --commit "$SHA" \
+  --wait --fail-on high
+```
+
+- `--wait` — polluje aż skan się zakończy (domyślnie timeout 600 s,
+  interwał 3 s; zmiana przez `--timeout` / `--poll-interval`).
+- `--fail-on high` — **exit code 1** gdy znajdzie finding severity `high`/`critical`;
+  `--fail-on critical` tylko przy krytycznych; pomiń → zawsze exit 0 (poza błędami).
+
+### 3. `status` — stan site'a i ostatnich skanów
+
+```bash
+liveapisec status --site SITE_ID
+```
+
+### 4. `findings` — wyniki skanu
+
+```bash
+liveapisec findings --site SITE_ID --scan SCAN_ID
+liveapisec findings --site SITE_ID --scan SCAN_ID --json   # surowe dane (dla agenta/AI)
+```
+
+### 5. `sites` — szczegóły site'a
+
+```bash
+liveapisec sites --site SITE_ID
+```
+
+---
+
+## GitHub Actions — pełny przykład (gate na push)
+
+```yaml
+name: liveapisec
+on: push
+jobs:
+  security-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - name: Install CLI
+        run: pip install "liveapisec @ git+https://github.com/LiveApiSec/liveapisec.git"
+      - name: Push API + run security test (gate on high)
+        env:
+          LIVEAPISEC_API_KEY: ${{ secrets.LIVEAPISEC_KEY }}
+        run: |
+          liveapisec push --name my-api --base-url "$BASE_URL" \
+            --endpoint "GET /users" --endpoint "POST /payments"
+          liveapisec scan --site "$SITE_ID" \
+            --branch "${GITHUB_REF#refs/heads/}" --commit "$GITHUB_SHA" \
+            --wait --fail-on high
+```
+
+> **Dlaczego push jest bezpieczny?** Push jest idempotentny (name+base_url →
+> ten sam site), więc kolejny build nie tworzy śmieci — aktualizuje endpointy
+> i token, a następny `scan` testuje najnowszy stan.
+
+---
+
+## Exit codes
+
+| Code | Znaczenie |
+|------|-----------|
+| 0    | OK (brak findings ≥ progu, lub bez `--fail-on`) |
+| 1    | Gate failed — znaleziono findings ≥ `--fail-on` |
+| 2    | Błąd użycia / błąd API / brak klucza |
+
+---
+
+## Rozwój / testy
+
+```bash
+pip install -e ./cli[dev]
+cd cli && python -m pytest tests/ -q
+```
+
+## API (SDK)
+
+Poza CLI pakiet eksportuje też klienta do skryptów:
+
+```python
+from liveapisec import LiveAPISec
+
+api = LiveAPISec()  # LIVEAPISEC_API_KEY z env
+site = api.create_site("my-api", "https://api.example.com",
+                       endpoints=[{"method": "GET", "path": "/users"}])
+scan = api.trigger_scan(site["site_id"], branch="main", commit="abc")
+done = api.wait_for_scan(site["site_id"], scan["scan_id"])
+blocked = LiveAPISec.findings_above(done["findings"], "high")
+```

liveapisec-0.1.0/README.md

@@ -0,0 +1,175 @@
+# liveapisec — CLI/SDK do LiveAPISec Developer API
+
+Oficjalny, cienki klient do **LiveAPISec Developer API**. Instalujesz raz,
+używasz w dowolnym projekcie, skrypcie i pipeline CI/CD — bez dashboardu i bez curl.
+
+> **Kiedy to jest?** Zamiast ręcznie przechodzić kreatora w panelu, developer
+> pushuje endpointy + opcjonalny token z **swojego** środowiska (CI/CD, agent,
+> skrypt). Token jest generowany u Ciebie i szyfrowany po stronie serwera (AES-256).
+> **Tip: brak tokena = testujemy tylko to, co publiczne.**
+
+---
+
+## Instalacja
+
+Z GitHub (rekomendowane, zanim trafimy na PyPI):
+
+```bash
+pip install "liveapisec @ git+https://github.com/LiveApiSec/liveapisec.git"
+```
+
+Po publikacji na PyPI:
+
+```bash
+pip install liveapisec
+```
+
+Sprawdź:
+
+```bash
+liveapisec --help
+```
+
+Kiedy zainstalujesz raz (np. w obrazie CI, na maszynie dev, w GitHub Actions) —
+komenda `liveapisec` jest dostępna **w każdym projekcie** w tej maszynie.
+
+---
+
+## Konfiguracja
+
+Klucz API generujesz raz w panelu: **Settings → Developer API → Create API key**
+(klucz `las_dev_...` pokazywany jest tylko raz — trzymaj go jako secret).
+
+```bash
+export LIVEAPISEC_API_KEY=las_dev_...          # wymagane
+export LIVEAPISEC_API_URL=https://liveapisec.com   # opcjonalne (domyślne)
+```
+
+Można też podać per-komenda: `--api-key` / `--api-url`.
+
+---
+
+## Komendy
+
+### 1. `push` — wyślij API (idempotentne, bezpieczne w CI)
+
+```bash
+liveapisec push \
+  --name my-api \
+  --base-url https://api.example.com \
+  --endpoint "GET /users" \
+  --endpoint "POST /payments"
+```
+
+- Ten sam `name` + `base_url` = **ten sam site** (aktualizacja, nie duplikat) —
+  możesz wołać push w każdym buildzie.
+- Zamiast listy endpointów możesz podać OpenAPI: `--openapi-url https://api.example.com/openapi.json`.
+- Opcjonalny token: `--auth-type jwt --auth-token <TOKEN>` (albo `bearer`,
+  `cookie --auth-cookie "session=..."`, `api_key --auth-header X-API-Key`).
+
+Wynik:
+
+```
+site 65f...abc: my-api — 2 endpoints, auth=none
+export SITE_ID=65f...abc
+```
+
+### 2. `scan` — odpal test bezpieczeństwa
+
+```bash
+# zwykłe odpalanie (202, nie czeka)
+liveapisec scan --site SITE_ID --branch main --commit "$GITHUB_SHA"
+
+# czekaj na wynik i próg błędu dla CI (gate)
+liveapisec scan --site SITE_ID --branch main --commit "$SHA" \
+  --wait --fail-on high
+```
+
+- `--wait` — polluje aż skan się zakończy (domyślnie timeout 600 s,
+  interwał 3 s; zmiana przez `--timeout` / `--poll-interval`).
+- `--fail-on high` — **exit code 1** gdy znajdzie finding severity `high`/`critical`;
+  `--fail-on critical` tylko przy krytycznych; pomiń → zawsze exit 0 (poza błędami).
+
+### 3. `status` — stan site'a i ostatnich skanów
+
+```bash
+liveapisec status --site SITE_ID
+```
+
+### 4. `findings` — wyniki skanu
+
+```bash
+liveapisec findings --site SITE_ID --scan SCAN_ID
+liveapisec findings --site SITE_ID --scan SCAN_ID --json   # surowe dane (dla agenta/AI)
+```
+
+### 5. `sites` — szczegóły site'a
+
+```bash
+liveapisec sites --site SITE_ID
+```
+
+---
+
+## GitHub Actions — pełny przykład (gate na push)
+
+```yaml
+name: liveapisec
+on: push
+jobs:
+  security-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - name: Install CLI
+        run: pip install "liveapisec @ git+https://github.com/LiveApiSec/liveapisec.git"
+      - name: Push API + run security test (gate on high)
+        env:
+          LIVEAPISEC_API_KEY: ${{ secrets.LIVEAPISEC_KEY }}
+        run: |
+          liveapisec push --name my-api --base-url "$BASE_URL" \
+            --endpoint "GET /users" --endpoint "POST /payments"
+          liveapisec scan --site "$SITE_ID" \
+            --branch "${GITHUB_REF#refs/heads/}" --commit "$GITHUB_SHA" \
+            --wait --fail-on high
+```
+
+> **Dlaczego push jest bezpieczny?** Push jest idempotentny (name+base_url →
+> ten sam site), więc kolejny build nie tworzy śmieci — aktualizuje endpointy
+> i token, a następny `scan` testuje najnowszy stan.
+
+---
+
+## Exit codes
+
+| Code | Znaczenie |
+|------|-----------|
+| 0    | OK (brak findings ≥ progu, lub bez `--fail-on`) |
+| 1    | Gate failed — znaleziono findings ≥ `--fail-on` |
+| 2    | Błąd użycia / błąd API / brak klucza |
+
+---
+
+## Rozwój / testy
+
+```bash
+pip install -e ./cli[dev]
+cd cli && python -m pytest tests/ -q
+```
+
+## API (SDK)
+
+Poza CLI pakiet eksportuje też klienta do skryptów:
+
+```python
+from liveapisec import LiveAPISec
+
+api = LiveAPISec()  # LIVEAPISEC_API_KEY z env
+site = api.create_site("my-api", "https://api.example.com",
+                       endpoints=[{"method": "GET", "path": "/users"}])
+scan = api.trigger_scan(site["site_id"], branch="main", commit="abc")
+done = api.wait_for_scan(site["site_id"], scan["scan_id"])
+blocked = LiveAPISec.findings_above(done["findings"], "high")
+```

liveapisec-0.1.0/liveapisec/__init__.py

@@ -0,0 +1,31 @@
+"""liveapisec — oficjalny klient LiveAPISec Developer API.
+
+Instalacja::
+
+    pip install git+https://github.com/<owner>/<repo>.git#subdirectory=cli
+
+Potem w dowolnym projekcie/CI::
+
+    export LIVEAPISEC_API_KEY=las_dev_...
+    liveapisec push --name my-api --base-url https://api.example.com --endpoint "GET /users"
+    liveapisec scan --site SITE_ID --wait --fail-on high
+"""
+
+from .cli import main
+from .client import (
+    DEFAULT_API_URL,
+    LiveAPISecError,
+    ScanStatus,
+    severity_rank,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_API_URL",
+    "LiveAPISecError",
+    "ScanStatus",
+    "__version__",
+    "main",
+    "severity_rank",
+]

liveapisec-0.1.0/liveapisec/cli.py

@@ -0,0 +1,295 @@
+"""liveapisec — komendy CLI (TODO 2.25).
+
+Komendy:
+  push      — utwórz/aktualizuj site + endpointy + opcjonalny token (idempotentne)
+  scan      — odpal skan; --wait czeka na wynik; --fail-on ustawia próg błędu CI
+  status    — status site'a / ostatnich skanów
+  findings  — listuj findings (--json)
+  sites     — pokaż site (endpointy, last_scan)
+
+Przykład w CI (gate)::
+
+    liveapisec push --name my-api --base-url https://api.example.com \\
+        --endpoint "GET /users" --endpoint "POST /payments"
+    liveapisec scan --site SITE_ID --branch main --commit "$SHA" --wait --fail-on high
+
+Exit codes (dla CI):
+  0 — ok (brak findings >= progu)      1 — findings >= progu (gate failed)
+  2 — błąd użycia / API
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from .client import DEFAULT_API_URL, LiveAPISec, LiveAPISecError
+
+_SEV = ["critical", "high", "medium", "low", "info"]
+
+
+def _parse_endpoint(value: str) -> dict[str, str]:
+    """'GET /users' → {"method":"GET","path":"/users"}."""
+    parts = value.split(None, 1)
+    if len(parts) != 2:
+        raise argparse.ArgumentTypeError(f"expected 'METHOD /path', got {value!r}")
+    method, path = parts
+    return {"method": method.upper(), "path": path}
+
+
+def _auth_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--auth-type", choices=["none", "jwt", "bearer", "cookie", "api_key"], default="none")
+    parser.add_argument("--auth-token", help="token dla jwt/bearer/api_key")
+    parser.add_argument("--auth-cookie", help="pełny nagłówek Cookie dla type=cookie")
+    parser.add_argument("--auth-header", default="X-API-Key", help="nazwa nagłówka dla api_key")
+
+
+def _build_auth(args: argparse.Namespace) -> dict[str, Any] | None:
+    if args.auth_type == "none":
+        return None
+    auth: dict[str, Any] = {"type": args.auth_type}
+    if args.auth_type in ("jwt", "bearer", "api_key"):
+        auth["token"] = args.auth_token
+    if args.auth_type == "cookie":
+        auth["cookie"] = args.auth_cookie
+    if args.auth_type == "api_key":
+        auth["header"] = args.auth_header
+    return auth
+
+
+def _fmt_scan(scan: dict[str, Any]) -> str:
+    status = scan.get("status", "?")
+    summary = scan.get("summary") or {}
+    by_sev = summary.get("by_severity") or {}
+    parts = [
+        f"scan {scan.get('scan_id')}",
+        f"status={status}",
+    ]
+    if scan.get("branch"):
+        parts.append(f"branch={scan['branch']}")
+    if scan.get("commit"):
+        parts.append(f"commit={scan['commit']}")
+    if status == "completed":
+        sev = " ".join(f"{k}={v}" for k, v in sorted(by_sev.items(), key=lambda kv: _SEV.index(kv[0]) if kv[0] in _SEV else 9))
+        parts.append(f"tests={summary.get('tests_run', '?')}")
+        parts.append(f"findings={summary.get('findings', 0)}" + (f" ({sev})" if sev else ""))
+    return " ".join(parts)
+
+
+def _fmt_finding(f: dict[str, Any]) -> str:
+    sev = f.get("severity", "?")
+    title = f.get("title") or f.get("category") or "?"
+    target = f.get("target") or ""
+    line = f"[{sev}] {title}"
+    if target:
+        line += f"  ({target})"
+    return line
+
+
+def _cmd_push(client: LiveAPISec, args: argparse.Namespace) -> int:
+    if not args.name:
+        print("error: --name is required", file=sys.stderr)
+        return 2
+    if not args.base_url and not args.site:
+        print("error: --base-url is required", file=sys.stderr)
+        return 2
+    if not args.endpoint and not args.openapi_url:
+        print("error: provide at least one --endpoint or --openapi-url", file=sys.stderr)
+        return 2
+    auth = _build_auth(args)
+    if auth and args.auth_type in ("jwt", "bearer", "api_key") and not args.auth_token:
+        print(f"error: --auth-token required for auth-type={args.auth_type}", file=sys.stderr)
+        return 2
+    if auth and args.auth_type == "cookie" and not args.auth_cookie:
+        print("error: --auth-cookie required for auth-type=cookie", file=sys.stderr)
+        return 2
+
+    site = client.create_site(
+        name=args.name,
+        base_url=args.base_url,
+        endpoints=args.endpoint,
+        openapi_url=args.openapi_url,
+        project=args.project,
+        auth=auth,
+        site_id=args.site,
+    )
+    if args.json:
+        print(LiveAPISec.dump(site))
+    else:
+        updated = " (updated)" if site.get("updated") else ""
+        print(f"site {site['site_id']}{updated}: {site['name']} — {site['endpoints_count']} endpoints, auth={site['auth']}")
+        print(f"export SITE_ID={site['site_id']}")
+    return 0
+
+
+def _cmd_scan(client: LiveAPISec, args: argparse.Namespace) -> int:
+    if not args.site:
+        print("error: --site (site_id) is required", file=sys.stderr)
+        return 2
+    scan = client.trigger_scan(args.site, branch=args.branch, commit=args.commit)
+    scan_id = scan["scan_id"]
+    if args.json:
+        print(LiveAPISec.dump(scan))
+    else:
+        print(f"scan queued: {scan_id}")
+    if not args.wait:
+        return 0
+
+    if not args.json:
+        print("waiting for scan to finish…", file=sys.stderr)
+    done = client.wait_for_scan(args.site, scan_id)
+    findings = done.get("findings") or []
+    if args.json:
+        print(LiveAPISec.dump(done))
+    else:
+        print(_fmt_scan(done))
+
+    if done.get("status") != "completed":
+        return 2 if args.fail_on else 0
+
+    gate_sev = args.fail_on  # "high" | "critical" | ...
+    if gate_sev:
+        blocked = LiveAPISec.findings_above(findings, gate_sev)
+        if blocked:
+            if not args.json:
+                print(f"\n❌ {len(blocked)} finding(s) at or above {gate_sev} — gate failed:", file=sys.stderr)
+                for f in blocked:
+                    print("  " + _fmt_finding(f), file=sys.stderr)
+            return 1
+        if not args.json:
+            print(f"✅ no findings at or above {gate_sev}")
+    return 0
+
+
+def _cmd_status(client: LiveAPISec, args: argparse.Namespace) -> int:
+    if not args.site:
+        print("error: --site (site_id) is required", file=sys.stderr)
+        return 2
+    site = client.get_site(args.site)
+    scans = client.list_scans(args.site)
+    if args.json:
+        print(LiveAPISec.dump({"site": site, "scans": scans[:10]}))
+        return 0
+    print(f"site {site['site_id']}: {site.get('name')} — {site.get('endpoints_count')} endpoints")
+    if site.get("base_url"):
+        print(f"  base_url: {site['base_url']}")
+    if site.get("project"):
+        print(f"  project: {site['project']}")
+    if site.get("last_scan_at"):
+        print(f"  last_scan_at: {site['last_scan_at']}")
+    if not scans:
+        print("  (no scans yet)")
+        return 0
+    print("  recent scans:")
+    for s in scans[:5]:
+        print("   " + _fmt_scan(s))
+    return 0
+
+
+def _cmd_findings(client: LiveAPISec, args: argparse.Namespace) -> int:
+    if not args.site or not args.scan:
+        print("error: --site and --scan are required", file=sys.stderr)
+        return 2
+    findings = client.get_findings(args.site, args.scan)
+    if args.json:
+        print(LiveAPISec.dump(findings))
+        return 0
+    if not findings:
+        print("no findings")
+        return 0
+    for f in findings:
+        print(_fmt_finding(f))
+    return 0
+
+
+def _cmd_sites(client: LiveAPISec, args: argparse.Namespace) -> int:
+    if not args.site:
+        print("error: --site (site_id) is required", file=sys.stderr)
+        return 2
+    site = client.get_site(args.site)
+    if args.json:
+        print(LiveAPISec.dump(site))
+        return 0
+    print(f"site {site['site_id']}: {site.get('name')} — {site.get('endpoints_count')} endpoints")
+    if site.get("base_url"):
+        print(f"  base_url: {site['base_url']}")
+    if site.get("project"):
+        print(f"  project: {site['project']}")
+    print(f"  source: {site.get('source')}  last_scan_at: {site.get('last_scan_at')}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="liveapisec",
+        description="LiveAPISec Developer API — push API specs, run security scans, gate your CI/CD.",
+    )
+    parser.add_argument("--api-url", help=f"API base URL (default: $LIVEAPISEC_API_URL or {DEFAULT_API_URL})")
+    parser.add_argument("--api-key", help="dev API key las_dev_... (default: $LIVEAPISEC_API_KEY)")
+    parser.add_argument("--json", action="store_true", help="print raw JSON output")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def _json_flag(p: argparse.ArgumentParser) -> None:
+        # --json działa też po nazwie podkomendy (np. `findings ... --json`)
+        p.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+
+    p_push = sub.add_parser("push", help="create/update a site (idempotent)")
+    p_push.add_argument("--name", required=True)
+    p_push.add_argument("--base-url")
+    p_push.add_argument("--project")
+    p_push.add_argument("--endpoint", action="append", type=_parse_endpoint, help="'METHOD /path' (repeatable)")
+    p_push.add_argument("--openapi-url", help="URL to OpenAPI spec instead of --endpoint")
+    p_push.add_argument("--site", help="existing site_id to update (PUT)")
+    _auth_args(p_push)
+    _json_flag(p_push)
+    p_push.set_defaults(func=_cmd_push)
+
+    p_scan = sub.add_parser("scan", help="run a security scan (optionally wait + gate)")
+    p_scan.add_argument("--site", required=True)
+    p_scan.add_argument("--branch")
+    p_scan.add_argument("--commit")
+    p_scan.add_argument("--wait", action="store_true", help="poll until finished")
+    p_scan.add_argument("--fail-on", choices=_SEV, help="exit 1 if findings at/above this severity (default: high)")
+    p_scan.add_argument("--poll-interval", type=float, default=3.0)
+    p_scan.add_argument("--timeout", type=float, default=600.0)
+    _json_flag(p_scan)
+    p_scan.set_defaults(func=_cmd_scan)
+
+    p_status = sub.add_parser("status", help="site status + recent scans")
+    p_status.add_argument("--site", required=True)
+    _json_flag(p_status)
+    p_status.set_defaults(func=_cmd_status)
+
+    p_find = sub.add_parser("findings", help="list findings for a scan")
+    p_find.add_argument("--site", required=True)
+    p_find.add_argument("--scan", required=True)
+    _json_flag(p_find)
+    p_find.set_defaults(func=_cmd_findings)
+
+    p_sites = sub.add_parser("sites", help="show a site")
+    p_sites.add_argument("--site", required=True)
+    _json_flag(p_sites)
+    p_sites.set_defaults(func=_cmd_sites)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.json = bool(getattr(args, "json", False))
+    try:
+        client = LiveAPISec(api_url=args.api_url, api_key=args.api_key)
+    except LiveAPISecError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    try:
+        return int(args.func(client, args))
+    except LiveAPISecError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())