liveapisec — CLI & SDK docs

1. Installation

curl -fsSL https://raw.githubusercontent.com/LiveApiSec/liveapisec/main/install.sh | bash

The installer uses pipx when available, otherwise it creates an isolated virtualenv and symlinks the command into ~/.local/bin — no sudo, and it works on PEP 668 systems (Ubuntu 24.04+) where a plain pip install is blocked.

pipx install liveapisec     # or: pip install liveapisec (inside a venv)

pip install "liveapisec @ git+https://github.com/LiveApiSec/liveapisec.git"

liveapisec --help

Install once (e.g. in a CI image, on a dev machine, in GitHub Actions) and the liveapisec command is available in every project on that machine.

2. Configuration

Generate an API key once in the dashboard: Settings → Developer API → Create API key (the las_dev_... key is shown only once — store it as a secret).

First run (interactive)

The first time you run a command that needs the API, the CLI asks for your key, shows you exactly where to find it, and saves it to ~/.config/liveapisec/config.json (mode 0600). Next runs pick it up automatically:

$ liveapisec push --name my-api --base-url https://api.example.com ...
No LiveAPISec API key found.
Generate one in the dashboard:  Settings → Developer API → Create API key
  https://liveapisec.com/settings
The key looks like:  las_dev_...
Tip: no key = only public endpoints can be tested.
Paste your API key: las_dev_...
✓ API key saved to /home/you/.config/liveapisec/config.json

Environment variables (recommended for CI)

export LIVEAPISEC_API_KEY=las_dev_...          # required
export LIVEAPISEC_API_URL=https://api.liveapisec.com   # optional (default)

Precedence: --api-key / --api-url flags → environment variables → saved config file.

Manage the saved key

liveapisec config        # show where the key is stored
liveapisec config --clear  # remove the saved config file

Authorize your domain (unlocks advanced tests)

Public tests work for any API. To unlock advanced & destructive tests (hacker-mode agent, release-path testing, private scans) prove you own the domain in the dashboard: Domains. We verify ownership with a DNS TXT record, a CNAME record, an HTTP file in /.well-known/, or a manual confirm — then record your consent (timestamp) for audit. Every authorized scan is gated on that consent.

# What you add at your DNS provider / web server
TXT    _penetration-auth.api.example.com  "the-token-we-give-you"
# or
CNAME  _penetration-auth.api.example.com  →  <token>.verify.liveapisec.com
# or a file
https://api.example.com/.well-known/liveapisec-<token>.txt  →  contains <token>

Local addresses are exempt. If your target is localhost, 127.0.0.1 or a private IP (e.g. 10.x, 192.168.x), no domain verification is required — it's your own local server. You can run the hacker-mode agent against it straight from the CLI:

liveapisec hacker --site SITE_ID --env development --wait   # dev/staging only
# ⚠ hacker mode is a DESTRUCTIVE authorized AI test — dev/staging only,
#   never production (it can break/destroy a system).

3. Interactive mode (project + site picker)

When you run push / scan-code in a terminal and omit --project (or --site), the CLI shows the projects available for your API key and lets you pick one — or create a new one. After picking a project you can pick an existing site/URL inside it, or add a new URL:

$ liveapisec push --endpoint "GET /users"
No --project given. Pick a project (or create a new one):
  1) svc      (3 site(s))
  2) mobile   (1 site(s))
  3) create new project
Enter number or project name: 1
Now pick a site/URL in 'svc' (or add a new one):
  1) api-a  https://a.example.com
  2) api-b  https://b.example.com
  3) add new URL/site
Enter number: 2
→ updating existing site api-b
✓ site 65f...: api-b — 2 endpoints, auth=none
  export SITE_ID=65f...

In CI (no TTY) the flags are required as before — nothing changes in pipelines.

4. Commands

4.1 push — push your API (idempotent, safe in CI)

liveapisec push \
  --name my-api \
  --base-url https://api.example.com \
  --endpoint "GET /users" \
  --endpoint "POST /payments"

• The same name + base_url = the same site (update, not a duplicate) — you can call push in every build.
• Instead of a list of endpoints you can provide an OpenAPI spec: --openapi-url https://api.example.com/openapi.json.
• Optional token: --auth-type jwt --auth-token <TOKEN> (or bearer, cookie --auth-cookie "session=...", api_key --auth-header X-API-Key).
• Per-URL automation: --schedule 6h|12h|24h|weekly (capped by your plan) and --access external|internal. internal (dev/localhost/private) is never auto-tested — run it on demand via CLI; setting a schedule on an internal URL is rejected.

4.2 scan-code — scan your source code and push the endpoints

Point the CLI at a repo/folder and it detects the framework, extracts the API endpoints from the code and pushes them — no running site or OpenAPI spec needed.

cd my-project
liveapisec scan-code --dir . --name my-api --base-url https://api.example.com

# Or clone straight from git (https / ssh), no checkout needed
liveapisec scan-code --repo [email protected]:acme/my-api.git \
  --name my-api --base-url https://api.example.com

# Preview the endpoints first (no API key needed)
liveapisec scan-code --dir . --name my-api \
  --base-url https://api.example.com --dry-run

# Force a framework if auto-detection misses it
liveapisec scan-code --dir . --framework nextjs \
  --name my-api --base-url https://api.example.com

Auto-detected frameworks: FastAPI, Flask, Django, Next.js (app/api + pages/api), NestJS (@Controller/@Get), Express (app.get), Laravel, generic PHP ($app->get, Slim, Lumen), Spring (@GetMapping, Java), Go (Gin, Echo, Fiber, Chi, gorilla/mux, net/http) and Rust (axum, actix-web, rocket, warp).

framework: fastapi (42 files scanned)
found 58 endpoints:
  GET     /users
  POST    /payments
site 65f...abc: my-api — 58 endpoints, auth=none
export SITE_ID=65f...abc

Note on methods: FastAPI/Flask/Express/NestJS/Spring/Laravel/Go/Rust carry the HTTP method in the code. Django urlpatterns and Go net/http handlers do not — those routes are assumed to be GET.

4.3 scan — run a security test

# fire and forget (202, does not wait)
liveapisec scan --site SITE_ID --branch main --commit "$GITHUB_SHA"

# wait for the result and fail the build on high (CI gate)
liveapisec scan --site SITE_ID --branch main --commit "$SHA" \
  --wait --fail-on high

• --wait — polls until the scan finishes (default timeout 600 s, interval 3 s; change with --timeout / --poll-interval).
• --fail-on high — exit code 1 when a finding of severity high/critical is found; --fail-on critical only for criticals; omit it → always exit 0 (except errors).
• --tunnel — route the scan through a connected CLI (liveapisec connect) to test a target reachable only from your machine (localhost/internal). See 4.10.

4.4 status — site status + recent scans

liveapisec status --site SITE_ID

4.5 findings — scan results

liveapisec findings --site SITE_ID --scan SCAN_ID
liveapisec findings --site SITE_ID --scan SCAN_ID --json   # raw data (for agents/AI)

4.5b verdict — CI regression gate (new/fixed vs baseline)

Compares the scan against a baseline: new findings are regressions. Exits 1 when new findings reach --fail-on (default: high) — the fix-and-re-scan gate for CI:

liveapisec verdict --site SITE_ID --scan NEW_SCAN --baseline BASE_SCAN --fail-on high

4.5c compliance · report · certificate --pdf

liveapisec compliance --site SITE_ID --scan SCAN_ID   # PCI DSS / SOC 2 / ISO 27001 / GDPR / NIS2 (Pro+)
liveapisec report --site SITE_ID --scan SCAN_ID -o report.json   # full saved report
liveapisec certificate --site SITE_ID --scan SCAN_ID --pdf --variant full -o cert.pdf  # passed scans only

4.5d all — full pipeline in one command

Scan (waits) → verdict vs baseline (explicit or auto = previous completed scan) → compliance → report + certificate PDF saved. Exits 1 on regressions — so in CI (GitHub Actions, GitLab, Jenkins) the step turns red exactly like a failing test suite. Use --format md --report-out security-report.md and upload it as an artifact (if: always()) so reviewers see which findings are new even when the gate fails:

liveapisec all --site SITE_ID
liveapisec all --site SITE_ID --format md --report-out security-report.md  # human-readable report
liveapisec report --site SITE_ID --scan SCAN_ID --format md -o report.md   # report alone, in Markdown
liveapisec all --site SITE_ID --hacker --env development   # hacker-mode instead (dev/staging only)

4.5e auth-matrix — RBAC test with two identities (no source code)

Role checks (user vs organization, tenant isolation) need two accounts. Pass a second identity and every endpoint is requested as anonymous / A / B and diffed: anonymously reachable secured endpoints, inconsistent tiers, confirmed BOLA, exposed admin paths. Identity A is the scan's normal auth; B is transient (encrypted, scan-only) or a saved credential with slot B (Settings → Credentials):

liveapisec scan --site SITE_ID --wait --auth-token-b "$USER_B_JWT" --auth-type-b bearer
liveapisec all --site SITE_ID --auth-token-b "$USER_B_JWT"

4.6 sites — site details

liveapisec sites --site SITE_ID

4.7 projects — last test status per project (no dashboard needed)

See every project, its sites and the last security test result straight in the terminal — no need to open the site:

$ liveapisec projects
svc
  api-a  https://a.example.com  last test: completed · 42 tests · 3 findings (high=1 medium=2)
  api-b  https://b.example.com  last test: failed
mobile
  api-c  https://c.example.com  last test: no test yet

# JSON (for scripts / agents)
liveapisec projects --json

# Only one project
liveapisec projects --project svc

4.8 scans — full test (scan) history for a site

See every security test ever run on a site (status, branch/commit, tests run, findings by severity) — useful for an agent that wants to know what was tested, when, and with what result:

liveapisec scans --site SITE_ID
# scan 65f...001  status=completed  branch=main  commit=abc  tests=42  findings=3 (high=1 medium=2)
# scan 65f...002  status=failed     branch=main

liveapisec scans --site SITE_ID --json        # raw list (for scripts / agents)
liveapisec scans --site SITE_ID --limit 5     # only the 5 most recent

4.9 certificate — live certificate URL + embed snippet

After a scan is green, publish the live certificate. You choose the scope — the whole organisation, one project, or a single URL. Paste the returned snippet into your site, docs or trust page. It updates with every scan.

liveapisec certificate                                # whole organisation (default)
liveapisec certificate --scope project --project acme
liveapisec certificate --scope site --site SITE_ID
liveapisec certificate --type badge   # badge | banner | card | iframe

The snippet (same in the dashboard under Certificate) looks like this — the widget is wrapped in a static link, so it is clickable AND crawlable (href sits in your HTML):

<a href="https://liveapisec.com/trust/acme" title="Verified by LiveApiSec" style="text-decoration:none;display:inline-block;color:inherit"><div data-liveapisec-widget data-slug="acme" data-type="badge"></div></a>
<script src="https://liveapisec.com/widget.js" async></script>

Options: data-type (badge, banner, card), data-name (custom label instead of the default brand-only badge). The badge appears only once the site passes its tests.

4.10 connect — reverse tunnel (test localhost / internal)

The scan runs on LiveAPISec's scanner, so it normally cannot reach a target that exists only on your machine. Start a tunnel: the CLI then acts as a proxy — it executes the scan's HTTP requests locally and posts the results back. Only the site's base_url host is forwarded (not an open proxy).

# terminal 1 — keep running
liveapisec connect --site SITE_ID

# terminal 2 — same target, now reachable through the CLI
liveapisec scan --site SITE_ID --wait --tunnel

# hacker-mode works through the tunnel too (dev/staging only)
liveapisec hacker --site SITE_ID --env development --wait --tunnel

5. Authentication (auth on the target API)

5.1 Reuse the token your app already has

liveapisec push --name my-api --base-url https://api.example.com \
  --auth-type jwt --auth-token "$MY_APP_TOKEN" \
  --endpoint "GET /users" --endpoint "POST /payments"

5.2 OAuth2 Client Credentials (M2M) — recommended for CI/CD

Short-lived JWTs expire before the scan runs. Instead, register a Machine-to-Machine application in your identity provider (Auth0, Okta, Azure AD, Keycloak…) once and push the long-lived client credentials — our scanner fetches a fresh token at every scan:

liveapisec push --name my-api --base-url https://api.example.com \
  --auth-type oauth2 \
  --auth-token-url https://<your-idp>/oauth/token \
  --auth-client-id "$CLIENT_ID" --auth-client-secret "$CLIENT_SECRET" \
  --endpoint "GET /users"

5.3 Verify the token before you commit to it

--verify probes the first endpoint with the pushed auth and reports whether the token actually works (exit 2 on a bad/expired token):

liveapisec push --name my-api --base-url https://api.example.com \
  --auth-type bearer --auth-token "$TOKEN" \
  --endpoint "GET /users" --verify
# → verify: GET https://api.example.com/users → 200 ✓
#   or: verify: GET https://api.example.com/users → 401 ✗ auth failed — ...

Network errors from --verify are informational — your machine may not reach the API while our scanner can; what matters is the auth result (2xx vs 401/403).

6. Exit codes

7. GitHub Actions — full example (gate on push)

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

Why is push safe? Push is idempotent (name+base_url → the same site), so the next build does not create junk — it updates endpoints and the token, and the next scan tests the latest state.

Gate on NEW findings only (CI verdict vs baseline)

--fail-on high fails on any high — including findings you already know and accepted. The verdict endpoint compares against a baseline (e.g. the last scan from main) and fails only on regressions:

# after the scan completes (SCAN_ID from --wait / API response)
VERDICT=$(curl -s "$API/scans/$SCAN_ID/verdict?baseline_scan_id=$BASELINE_ID&fail_on=high" \
  -H "Authorization: Bearer $LIVEAPISEC_API_KEY")
[ "$(echo "$VERDICT" | python3 -c "import sys,json; print(json.load(sys.stdin)['verdict'])")" = "pass" ]

Response shape is stable for scripts: verdict, counts (new / fixed / persisting / blocking), plus full new, fixed, persisting lists (category, severity, title, target, status). Matching is by category + target + title. Both scans must belong to your organisation.

Scan depth: Baseline vs Deep

Every scan runs at a depth: baseline (8 fast deterministic tests — BOLA, auth, mass assignment, injection, rate limit, CORS, headers, sensitive params; seconds per endpoint, made for every commit) or deep (the full suite — JWT, method tampering, tech fingerprint, disclosure, rate-limit v2, API versions, GraphQL, OAuth, CORS chain, SSRF canary; for nightly runs and releases). Pass depth when triggering (POST /scans); default is deep (Starter plan and up — Free runs baseline; requesting deep on Free returns 402). Typical setup: baseline on every push + verdict vs main, deep on schedule.

Compliance mapping

GET /scans/:id/compliance groups open findings per framework requirement — PCI DSS 4.0, SOC 2, ISO 27001, GDPR, NIS2 — so your auditor can locate technical evidence fast. The same view lives in the dashboard under scan details (Pro plan and up). It is an indicative mapping, not a certification: silence on a requirement means no open findings in scanner scope, not proof of full compliance.

8. SDK (API)

Besides the CLI, the package also exports a Python client for scripts:

from liveapisec import LiveAPISec

api = LiveAPISec()  # LIVEAPISEC_API_KEY from 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")

The same Developer API is plain REST — call it from any language

Not on Python? The endpoints behind the CLI are a standard REST API. Call them with curl, Node fetch, Go, Java, Ruby… anything that speaks HTTP:

# Node.js — push a site + endpoints from your app
const res = await fetch(API + '/developers/sites', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + DEV_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'my-api',
    base_url: 'https://api.example.com',
    endpoints: [{ method: 'GET', path: '/users' }],
  }),
});
const { site_id } = await res.json();   // → push the same site_id into your pipeline

# Go (net/http) — trigger a scan
req, _ := http.NewRequest("POST", API+"/developers/sites/"+siteID+"/scans", body)
req.Header.Set("Authorization", "Bearer "+DEV_KEY)
resp, _ := http.DefaultClient.Do(req)

The CLI simply wraps these same endpoints (see the GitHub repo for the full REST reference). So regardless of your stack you get the same result: endpoints pushed, scans run, findings readable by your agent or CI.

9. Copilot / AI coding assistants

The CLI is designed to be driven by an AI assistant. Paste the block below into your assistant (GitHub Copilot, Cursor, Windsurf…) so it can push your API, run the security test, read the findings and fix the issue itself, then re-test until the gate is green.

TASK: add LiveAPISec security testing to THIS repository, run it, and fix what it finds.

Full CLI/SDK documentation (read it if you need exact flags or the REST API):
https://liveapisec.com/docs

You are a coding agent. Execute the steps below now using the terminal — this message IS the task, not just a tool description. If a required value is missing (API key, base URL), ask the user for exactly that value and continue. Do not reply with only a status report.

## Goal — what you are setting up and why
There are two sides to this:
1. **Check the dev solution** — run the security tests against the reachable dev/staging
   URL while fixes are still cheap.
2. **Turn on the LIVE security side** — register the API on LiveAPISec so it can
   produce the live security status/certificate (Trust Page) that customers can see
   and that keeps updating with every scan. For that the URL MUST be correct: use
   the real, publicly reachable base URL of the environment you want covered
   (dev vs staging vs production), no path suffix, correct http/https. A wrong URL
   means the certificate/monitoring points at the wrong target.

You are ALLOWED to create the project and the site yourself and to read everything
back — do it, don't just report. Use `liveapisec projects` / `liveapisec sites` /
`liveapisec status` to confirm what exists. The only thing you cannot create is the
API key (dashboard).

## Step 0 — Setup (do this first)
1. If `liveapisec` is not installed (`command -v liveapisec` fails), install it:
   curl -fsSL https://raw.githubusercontent.com/LiveApiSec/liveapisec/main/install.sh | bash
   (or: pipx install liveapisec — or pip install liveapisec inside a venv.)
   Verify with `liveapisec --help`.
2. Developer API key (env var LIVEAPISEC_API_KEY, looks like las_dev_...):
   - If it is already set in the environment, use it.
   - If not: STOP and ask the user to create one at
     https://liveapisec.com/settings -> Developer API -> Create API key,
     then run  export LIVEAPISEC_API_KEY=las_dev_...
   - NEVER print, log, commit or hardcode the key — always read it from the environment.
   (This key is the ONLY thing the CLI cannot create itself — everything else,
   including the project and the site, is created by the CLI commands below.)
3. URLs — do NOT confuse these three:
   - LiveAPISec platform API (what the CLI calls): https://api.liveapisec.com
     This is LIVEAPISEC_API_URL (default; only change it for self-hosted). The CLI
     already knows it — never probe or rewrite it yourself.
   - LiveAPISec dashboard / docs (browser only): https://liveapisec.com
     This is a static site. POSTing to it returns 405 by design — it is NOT the API.
     Never send API calls there.
   - YOUR API under test = the `--base-url` value. It is a different host; ask the
     user if unknown. Never guess it.
   If the CLI returns 502 / timeouts, the LiveAPISec platform may be briefly down —
   retry and report, do not change the URL.

## Step 1 — Find this project's endpoints
- Prefer source discovery:
  `liveapisec scan-code --dir . --name <api-name> --base-url <api-url> [--project <project>]`
  Supported frameworks: FastAPI, Flask, Django, Next.js (App+Pages), NestJS, Express,
  Laravel, PHP/Slim/Lumen, Spring, Go, Rust.
- If the project serves an OpenAPI spec, use `--openapi-url <url>` instead.
- If the base URL is unknown, ask the user — never guess production.

## Step 2 — Push (idempotent: same name + base_url = same site, safe to repeat)
You do NOT need to create the project first — there is no separate create-project
command: passing `--project <name>` creates it implicitly on the first push.
If the user didn't give a project name, derive one from the repo/directory name
or ask; reuse an existing one with `liveapisec projects` when in doubt.
`liveapisec push --name <api-name> --base-url <api-url> --project <project> --endpoint "GET /x" --endpoint "POST /y"`
Then export the returned id:  export SITE_ID=<site_id>

ENVIRONMENTS = SEPARATE SITES. There is no environment feature to configure —
each environment is its own site with its own URL, in the SAME project. If the
API exists in dev/staging/prod, register each separately:
  `liveapisec push --project acme --name acme-api-dev     --base-url https://dev.acme.com --access internal ...`
  `liveapisec push --project acme --name acme-api-staging --base-url https://stg.acme.com --schedule 24h ...`
  `liveapisec push --project acme --name acme-api-prod    --base-url https://api.acme.com --schedule 24h ...`
ACCESS: `--access internal` (dev/localhost/private) = NEVER auto-tested by the
scheduler — run it on demand only (`liveapisec scan --site <id>`, optionally
`--tunnel`). `--access external` (default) may be auto-tested; `--schedule`
is capped by the plan (e.g. Free = weekly). Setting a schedule on an internal
site is rejected. Localhost / private IPs need no domain verification. The scan
runs on LiveAPISec's scanner, so if the target is reachable only from your
machine, start a tunnel (keep it running in a separate terminal) — the CLI acts
as a proxy:
  `liveapisec connect --site "$SITE_ID"`                     # keep running
  `liveapisec scan --site "$SITE_ID" --wait --tunnel`        # other terminal
  `liveapisec hacker --site "$SITE_ID" --env development --wait --tunnel`  # AI agent, dev/staging only
If the target is on an internal network the scanner can reach (VPN/private IP),
no tunnel is needed.
If the API needs credentials, add:
  --auth-type jwt|bearer|api_key --auth-token "$TOKEN"   (or cookie, or oauth2 client credentials)
Use `--verify` to pre-flight the token before relying on it.

## Step 3 — Run a scan and read the findings
Shortcut for everything at once: `liveapisec all --site "$SITE_ID"` (scan → verdict → compliance → report + certificate PDF; exits 1 on regressions). With a second account available, add `--auth-token-b <jwt>` to enable the auth-matrix RBAC test (anon/A/B differential: broken tiers, BOLA, exposed admin paths — no source code needed). Or step by step:
`liveapisec scan --site "$SITE_ID" --branch <branch> --commit <sha> --wait`
`liveapisec findings --site "$SITE_ID" --scan <scan_id>`    (add --json for raw JSON)

## Step 4 — Fix and re-scan (the real deliverable)
1. Group findings by severity; start with critical/high.
2. Fix the actual code (BOLA/authZ, injection, mass assignment, rate limiting, headers/CORS…).
3. Re-push (idempotent) and re-scan until no critical/high remain.
4. Regression gate vs the baseline (e.g. last green scan): `liveapisec verdict --site "$SITE_ID" --scan <new> --baseline <base> --fail-on high` — exit 1 means NEW high/critical findings; fix those, never just re-baseline.
5. Optional evidence: `liveapisec compliance --site "$SITE_ID" --scan <scan_id>` (PCI DSS / SOC 2 / ISO 27001 / GDPR / NIS2, Pro+), `liveapisec report --site "$SITE_ID" --scan <scan_id> -o report.json`, `liveapisec certificate --site "$SITE_ID" --scan <scan_id> --pdf -o cert.pdf` (passed scans only).
6. Report: files changed, findings fixed, and any false positives with evidence — do not silently "fix" those.

## Step 4b — Answer what the scanner cannot see (ask-mode)
Black-box tests stop at HTTP. Open a question session (AI extras about THIS api + 270 bank checks). The AI may first ask **clarifications** (SEC-ASK-CL-N, no priority) about the system — answer them with `--verdict info --note "..."`, then run `liveapisec ask followup` so the next round turns those facts into precise questions. Then answer each audit question by READING THE CODE and fix every fail:
`liveapisec ask new --site "$SITE_ID"` → `liveapisec ask run --session <id>` (verdicts pass|fail|na + evidence note, e.g. --note "argon2id in auth.py:42"). Each question has a priority (critical/high/medium/low); review with `liveapisec ask show --session <id> --only failed` (sorted critical-first). When your answers reveal weak spots, run `liveapisec ask followup --session <id> --until-dry` — the AI reads your answers (fails, notes, n/a) and adds deeper follow-up questions to the same session; answer those too. Failures appear in the Markdown report.

## Step 5 — Confirm the live security setup and report
- Re-read the registered objects and report them back:
  `liveapisec projects` (project + last test status), `liveapisec sites --site "$SITE_ID"`,
  `liveapisec scans --site "$SITE_ID"`, `liveapisec status --site "$SITE_ID"`.
- If the live/production API is firewalled, note that the scanner must be able to
  reach the base URL (the dashboard shows the scanner IPs to allowlist) — otherwise
  the live certificate will have no data.
- State clearly which URL/environment is now covered and which one still needs to be added.

## Step 6 — Publish the live certificate
After a scan is green (no open critical/high), install the live certificate.
YOU choose the scope — ask the user which one they want:
  `liveapisec certificate`                               — whole organisation (default)
  `liveapisec certificate --scope project --project acme`  — everything in one project
  `liveapisec certificate --scope site --site "$SITE_ID"`  — a single URL
  `liveapisec certificate --type badge`                   — badge | banner | card | iframe
Paste the returned snippet (an `<a href=...>` wrapping `<div data-liveapisec-widget ...></div>`,
plus `widget.js`) into the site's footer / docs / trust page. The link is static in the
HTML (crawlable) and the whole widget is clickable. Project/org certificates
are created in the dashboard (Certificate page → scope); if the CLI says "no
certificate for this project", tell the user to create it there. The certificate
updates automatically with every scan — a live trust signal, not a one-off PDF.

## Reference — inspect the portal from the terminal
- `liveapisec projects`              — every project + last test status
- `liveapisec scans --site <id>`    — full scan history (--json for raw)
- `liveapisec status --site <id>`   — site status + recent scans
- `liveapisec sites --site <id>`    — site details
- `liveapisec findings --site <id> --scan <scan_id>`  — findings (--json for raw)

## Rules
- Never print or commit the API key; use the environment variable.
- Push is idempotent — it is safe to run on every commit / CI run.
- Exit code 1 from `scan --wait --fail-on <sev>` = gate failed (findings at/above that severity); exit 2 = usage/API error.
- It works with APIs in ANY language/framework — not Python-only.

Answer what the scanner cannot see (ask-mode, SEC-ASK-N)

Black-box tests stop at the HTTP boundary — the questionnaire covers the rest: 270 checkable questions (auth, RBAC, tenant isolation, crypto, business logic, SDLC) plus AI-tailored extras about your endpoints. Each question has a priority (critical/high/medium/low), so failures triage themselves. Paste the failures into the same Copilot prompt — it answers them by reading the code:

$ liveapisec ask new --site 65f...001
ask session created: 70a...009 (200 questions)
$ liveapisec ask run --session 70a...009   # interactive: pass | fail | na + evidence note
$ liveapisec ask followup --session 70a...009   # AI digs deeper based on your answers
$ liveapisec ask show --session 70a...009 --only failed   # review, fix code, re-answer
# failures appear in the Markdown report next to the findings

Example — Copilot self-repairs an issue from our test

Your CI just failed with exit 1 (gate failed). You ask your Copilot: "fix the failing security test". Here is the whole loop — the Copilot fetches everything from the terminal, no dashboard:

1) Sees what failed
   $ liveapisec projects
   svc
     api-a  https://api.example.com  last test: failed

2) Looks at the test history for the site
   $ liveapisec scans --site 65f...001
   scan 65f...002  status=failed  branch=main  commit=abc  findings=2

3) Reads the findings for the failed scan (raw JSON for the agent)
   $ liveapisec findings --site 65f...001 --scan 65f...002 --json
   [
     { "severity": "high", "category": "headers", "title": "Missing security headers",
       "target": "GET /users", "description": "no Content-Security-Policy header" },
     { "severity": "high", "category": "headers", "title": "HSTS not enabled",
       "target": "GET /users", "description": "Strict-Transport-Security missing" }
   ]

4) Fixes the code (adds a security-headers middleware), commits the fix

5) Re-pushes the endpoints (idempotent) and re-runs the gate
   $ liveapisec push --name api-a --base-url https://api.example.com --endpoint "GET /users"
   $ liveapisec scan --site 65f...001 --branch main --commit "$SHA" --wait --fail-on high
   ✓ scan completed — no findings at or above high

6) Confirms the gate is green
   $ liveapisec projects
   svc
     api-a  https://api.example.com  last test: completed · 42 tests · 0 findings

That is the whole idea: the CLI gives your Copilot read + write access to the security loop (fetch state → read findings → fix code → re-test → confirm green), so it can resolve issues end-to-end without a human opening the dashboard.

10. What each scan tests

Every scan runs a deterministic engine (no AI needed for detection) plus AI triage of the findings. Baseline suite (OWASP API Top 10): BOLA/IDOR, broken authentication, mass assignment, injection (SQL/NoSQL/JSON), rate limiting, CORS misconfiguration, security headers, sensitive parameters in URLs, shadow APIs. Deep-scan suite: JWT weaknesses (alg=none, tampered payload, weak HMAC secret, missing exp, kid injection), HTTP method tampering, privilege escalation via mass assignment (undeclared role fields echoed back exactly), server tech fingerprint with end-of-life version detection, information disclosure checklist (.git, .env, debug, actuator, metrics, public specs, stack traces), differential rate limits with X-Forwarded-For bypass check, old API version comparison (v1 vs v2 auth), GraphQL introspection and query-complexity check, OAuth redirect_uri open-redirect check, CORS null-origin / allowlist-bypass / CSRF-preflight chain, SSRF canary callback. Authenticated extras: auth-matrix RBAC (anon/A/B differential) and AI cross-layer probes — the LLM reads your endpoint shapes (roles, orgs, projects, invites) and invents up to 8 concrete probes outside the fixed suite, executed with a differential oracle (both identities 2xx but different bodies = possible cross-layer leak). Hacker mode (AI agent, dev/staging only) covers business-logic abuse on top. Findings carry category, severity, target and evidence (payloads, request/response) — visible in the dashboard under scan details. Two extras run when the scan is authenticated: the auth-matrix RBAC test (same endpoint requested as anonymous / identity A / identity B and diffed — broken tiers, confirmed BOLA, exposed admin paths; needs a second identity via --auth-token-b or a saved credential with slot B) and the AI test plan: one LLM call reads your OpenAPI (endpoints, methods, fields, auth) and tells the engine which tests matter per endpoint, in which order, and which identifiers to swap for BOLA — high-risk targets first, graceful fallback to the fixed order without AI.