liveapisec — CLI/SDK for the LiveAPISec Developer API

Official, thin client for the LiveAPISec Developer API. Install it once, use it in any project, script and CI/CD pipeline — no dashboard, no curl.

When to use this? Instead of walking through the wizard in the dashboard, a developer pushes endpoints + an optional token from their own environment (CI/CD, agent, script). The token is generated on your side and encrypted server-side (AES-256). Tip: no token = we only test what's public.

Which APIs does it work with? (not Python-only)

The liveapisec CLI is written in Python — but that is only the tool you run. You use it to push, test and monitor APIs built in any language and framework: Python, Node.js, Go, Rust, Java/Kotlin, PHP, Ruby, .NET/C#… It does not matter how your backend is implemented, as long as it exposes HTTP(S) endpoints.

3 ways to get your endpoints in:

1. push — list endpoints yourself (works for any HTTP API).
2. push --openapi-url … — pull an OpenAPI spec (FastAPI/DRF, Springdoc, NestJS Swagger, express swagger-ui, ASP.NET Swashbuckle…).
3. scan-code — scan the source code; it auto-detects these 11 frameworks:

What kind of applications work? REST/JSON APIs — microservices, monoliths, BFFs, API gateways, third-party APIs… public or protected (jwt / bearer / cookie / api_key / OAuth2). scan-code reads the HTTP routes; the app behind them can be anything.

API types we can test: REST (OpenAPI / Swagger), RAML, GraphQL (introspection or SDL) and SOAP (WSDL) — the scanner converts each into real HTTP targets. WebSocket and gRPC are not covered by the HTTP scanner (non-HTTP protocols).

Integration & SDK: the package also ships a Python SDK (from liveapisec import LiveAPISec), and the same Developer API is a plain REST API you can call from any language (curl, Node fetch, Go…) — the CLI just wraps those endpoints. See the SDK section below and the in-browser docs at https://liveapisec.com/docs.

Installation

One command (Linux / macOS) — recommended

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. After installing, open a new terminal and run liveapisec --help.

From PyPI (recommended for developers with pipx/venv)

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

From GitHub (if you prefer building from the repository)

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

Verify:

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.

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 (e.g. push, scan), 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; dashboard is liveapisec.com)

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

Commands

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.

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.
• Local spec file (no server-side fetch, works with localhost/private URLs that --openapi-url blocks): --spec-file ./openapi.json (JSON/YAML, parsed locally).
• 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 by the scheduler — run it on demand via CLI; setting a schedule on an internal URL is rejected.

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"

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).

Output:

site 65f...abc: my-api — 2 endpoints, auth=none
export SITE_ID=65f...abc

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. The scan runs 100% locally: your code never leaves the machine. Only the extracted endpoint list (METHOD + path) is sent to the API. (The old name push-code still works as an alias.)

cd my-project
liveapisec scan-code --dir . --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).
• Scan a git repository straight from a URL (https / ssh / local path) — it is shallow-cloned to a temp dir and cleaned up afterwards:

liveapisec scan-code --repo git@github.com:acme/my-api.git \
  --name my-api --base-url https://api.example.com

• Preview before pushing (no API key needed):

liveapisec scan-code --dir . --name my-api --base-url https://api.example.com --dry-run
liveapisec scan-code --dir . --name my-api --base-url https://api.example.com --dry-run --json

• Force a framework if auto-detection misses it: --framework nextjs.

Output:

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.

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).

4. hacker — autonomous AI hacker-mode test (destructive — dev/staging only)

Runs the autonomous AI agent ("real human test") against a dev/staging environment: the LLM plans an attack, probes endpoints step by step (IDOR/BOLA, broken auth, injections, secrets, mass assignment), can write and run its own probe code in a sandbox, self-corrects, and writes a final evaluation. You watch the agent think live in the dashboard.

# dev/staging only — NEVER production (it can break/destroy a system)
liveapisec hacker --site SITE_ID --env development
liveapisec hacker --site SITE_ID --env staging --wait

# guided mode — give the agent a specific objective (TODO 3.6.2)
liveapisec hacker --site SITE_ID --env development \
  --goal "check /users for IDOR — your record vs another user's"

# localhost / internal target — through a connected CLI tunnel (terminal 1:
# `liveapisec connect --site SITE_ID`, keep running)
liveapisec hacker --site SITE_ID --env development --wait --tunnel

• --env — environment name defined on the site (e.g. development, staging). Production environments are rejected (403).
• --goal — optional guided attack objective (e.g. "check /users for IDOR", "try to escalate to admin", "enumerate secrets"). Without it the agent explores freely.
• --wait — polls until the AI agent finishes.
• Domain verification: public targets need a verified domain (the dashboard Domains flow). Localhost / private IPs (e.g. http://localhost:8000, 10.x) are exempt — no domain verification needed for your own local server.
• Your API URL and credentials are never sent to the AI — only relative paths reach the model; requests are executed server-side in a sandbox. If the site has credentials, the agent runs authenticated (it only learns a flag, not the token) and can test IDOR/BOLA and privilege escalation as a real user.

5. status — site status + recent scans

liveapisec status --site SITE_ID

6. 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)

7. verdict — CI regression gate (new/fixed vs baseline)

Compares the scan against a baseline (e.g. last green deploy): new findings are regressions, fixed disappeared, persisting were already known. Exits 1 when NEW findings reach --fail-on (default: high) — the real fix-and-rescan gate:

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

8. compliance — PCI DSS / SOC 2 / ISO 27001 / GDPR / NIS2 (Pro+)

Illustrative mapping of open findings onto framework requirements (with disclaimer — not a certification):

liveapisec compliance --site SITE_ID --scan SCAN_ID

9. report — full saved scan report

liveapisec report --site SITE_ID --scan SCAN_ID -o report.json   # save to file
liveapisec report --site SITE_ID --scan SCAN_ID --json           # print to stdout

10. ask — answer what the scanner cannot see (SEC-ASK-N)

Black-box tests stop at the HTTP boundary. ask opens a question session: 200 checkable questions (SEC-ASK-1 … SEC-ASK-200: auth, RBAC, tenant isolation, crypto, business logic, SDLC…) plus AI-tailored extras about YOUR endpoints — roles, org layers, edge cases. You (or your LLM) answer pass / fail / na by reading the source code, each with the fix and an evidence note. Failures land in the Markdown report next to the findings:

liveapisec ask new --site SITE_ID                 # fresh session (200 + AI)
liveapisec ask sessions --site SITE_ID            # pass/fail counts per session
liveapisec ask answer --session SES --question SEC-ASK-5 --verdict fail --note "no MFA in auth.py"
liveapisec ask run --session SES                  # interactive walkthrough
liveapisec ask followup --session SES             # AI adds deeper questions from your answers
liveapisec ask show --session SES --only failed   # review failures

10. certificate --pdf — download the certificate (passed scans only)

liveapisec certificate --site SITE_ID --scan SCAN_ID --pdf --variant full -o cert.pdf
liveapisec certificate --site SITE_ID --scan SCAN_ID --pdf --variant client -o cert-client.pdf

0. all — full pipeline in one command (scan → verdict → compliance → report → PDF)

Numbered 0 because it's the easiest path: queues a scan, waits, compares against the baseline (explicit --baseline or auto = previous completed scan), prints the verdict, saves the report + certificate PDF, and exits 1 on regressions. Compliance below plan and a missing certificate (scan didn't pass) are notes, not errors:

liveapisec all --site SITE_ID
liveapisec all --site SITE_ID --baseline BASE_SCAN --fail-on high --variant client
liveapisec all --site SITE_ID --hacker --env development   # hacker-mode instead (destructive — dev/staging only)

Auth-matrix RBAC test — two identities, no source code needed

Role checks (user role vs organization role, cross-tenant isolation) can't be tested with one token. Pass a second identity and the scanner diffs every endpoint as anonymous / A / B: secured endpoints reachable anonymously, A allowed where B is blocked (inconsistent tiers), confirmed BOLA (A reads two different objects), and admin paths exposed to A:

# CI: two tokens from secrets (e.g. a low-priv user + an admin)
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"

• Identity A = the scan's normal auth (saved credential in Settings → Credentials, or --auth-type/--auth-token on push).
• Identity B = --auth-token-b (transient: encrypted server-side, lives only on this scan) or a saved credential with slot B (panel/CI reuse).
• Findings land in category rbac (high/medium) and flow into verdict → report (md) → compliance → PDF like everything else.

11. sites — site details

liveapisec sites --site SITE_ID

12. 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

13. 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 dashboard:

$ 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

9. certificate — live certificate URL + embed snippet

After a scan is green, publish the live certificate. Choose the scope: whole organisation (default), one project, or a single URL.

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

Paste the returned snippet (<div data-liveapisec-widget ...> + widget.js) into your site, docs or trust page — it updates with every scan.

14. 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:

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

# terminal 2 — route the scan 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

Only the site's base_url host is forwarded (not an open proxy).

Full documentation: see the in-browser docs at https://liveapisec.com/docs (install, config, every command, auth/OAuth2, exit codes, GitHub Actions, SDK).

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: Full pipeline — scan, regression gate, report, certificate
        id: sectest
        env:
          LIVEAPISEC_API_KEY: ${{ secrets.LIVEAPISEC_KEY }}
        run: |
          liveapisec push --name my-api --base-url "$BASE_URL" \
            --endpoint "GET /users" --endpoint "POST /payments"
          liveapisec all --site "$SITE_ID" --fail-on high \
            --format md --report-out security-report.md
      - name: Upload security report + certificate
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: liveapisec-report
          path: |
            security-report.md
            liveapisec-certificate-*.pdf

How a failure shows up in CI: all exits 1 when NEW findings reach --fail-on (compared against the baseline = previous completed scan), so the Full pipeline step turns red and the workflow fails — exactly like a failing test suite. The Markdown report (security-report.md) is attached as an artifact either way (if: always()), so reviewers see which findings are new: open the run → Artifacts → liveapisec-report. The same exit-code contract works in GitLab CI, Jenkins or plain bash (set -e stops the pipeline on regressions). For agents/AI parsing, use --json on verdict/scan instead.

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.

Exit codes

Development / tests

pip install -e ./cli[dev]
cd cli && python -m pytest tests/ -q

SDK (API)

Python

Besides the CLI, the package also exports a 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")

From any other language — plain REST

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 — you get the same result as the CLI (endpoints pushed, scans run, findings readable by your agent or CI):

# push a site + endpoints from any language
curl -X POST $LIVEAPISEC_API_URL/developers/sites \
  -H "Authorization: Bearer $LIVEAPISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-api","base_url":"https://api.example.com",
       "endpoints":[{"method":"GET","path":"/users"}]}'

# trigger a scan
curl -X POST $LIVEAPISEC_API_URL/developers/sites/$SITE_ID/scans \
  -H "Authorization: Bearer $LIVEAPISEC_API_KEY" \
  -d '{"branch":"main","commit":"abc123"}'

Instructions for AI coding assistants (Copilot, Cursor, etc.)

Copy-paste the block below into your AI assistant (GitHub Copilot, Cursor, Windsurf…) to let it use the LiveAPISec CLI on your behalf.

You can use the `liveapisec` CLI (https://pypi.org/project/liveapisec/) to
push API specifications, run security scans and read results against the
LiveAPISec platform. It works with APIs in ANY language/framework (not just
Python) — use `scan-code` to extract endpoints from source, or
`push --openapi-url` for an OpenAPI spec.

Environment:
- `LIVEAPISEC_API_KEY` — dev API key (las_dev_...), usually already set.
- `LIVEAPISEC_API_URL` — API base URL (default: https://api.liveapisec.com).
- `SITE_ID` — the site id returned by `liveapisec push` / `liveapisec sites`.

Fetch information about the portal (to diagnose and fix issues):
- `liveapisec projects`              — every project + last test status
- `liveapisec scans --site <id>`    — full test history for a site (--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)

Language note: the CLI is written in Python, but it tests APIs built in ANY
language/framework — Python, Node.js, Go, Rust, Java, PHP, Ruby, .NET, etc.
Use `liveapisec scan-code` to auto-extract endpoints from the source
(FastAPI, Flask, Django, Next.js, NestJS, Express, Laravel, PHP/Slim, Spring,
Go, Rust), or `push --openapi-url` for any API that exposes an OpenAPI spec.

Workflow:
1. Push the API under test (idempotent — safe to repeat):
   `liveapisec push --name <name> --base-url <url> --endpoint "METHOD /path" [--endpoint ...] [--openapi-url <url>] [--auth-type jwt|bearer|cookie|api_key --auth-token <token>]`
2. Run a security scan and wait for the result:
   `liveapisec scan --site <site_id> --branch <branch> --commit <sha> --wait`
3. Read findings (severity, title, target):
   `liveapisec findings --site <site_id> --scan <scan_id>` (add `--json` for raw JSON).

Self-repair loop (fix an issue from our test, end-to-end):
1. See what failed: `liveapisec projects`
2. Find the failed scan: `liveapisec scans --site <site_id>`
3. Read the findings: `liveapisec findings --site <site_id> --scan <scan_id> --json`
4. Fix the code (e.g. add a security-header middleware), commit.
5. Re-push (idempotent) and re-run the gate:
   `liveapisec push --name <name> --base-url <url> --endpoint "GET /x"`
   `liveapisec scan --site <site_id> --branch <branch> --commit <sha> --wait --fail-on high`
6. Confirm the gate is green: `liveapisec projects`

Rules:
- Never print or commit the API key; use the environment variable.
- If a scan fails, read the findings, fix the code, re-push and re-scan.
- Push is idempotent, so re-running it is always safe.
- Exit code 1 from `scan --wait --fail-on <sev>` means the gate failed
  (findings at/above that severity); exit 2 means usage/API error.