Skip to content

API guide

The Kpal API lets you do from a script anything you can do in the app. Everything is JSON over HTTPS.

  • Base URL: https://app.kpal.adhyotlabs.in/api/v1
  • Authentication: send your key in the X-API-Key header.
  • The full list of endpoints is in the reference.

The examples use curl and Python with httpx (pip install httpx).

Create a key

In the app: Settings › API keys, give the key a name (say ci-import), then Create key. You need to be an admin.

Copy the key now. Kpal only shows it once. If you lose it, revoke it and create another.

You can also create one from a signed-in session:

curl -s -c jar.txt -X POST https://app.kpal.adhyotlabs.in/api/auth/login \
  -H 'Content-Type: application/json' -d '{"email": "you@example.com", "password": "..."}'
curl -s -b jar.txt -X POST https://app.kpal.adhyotlabs.in/api/v1/api-keys \
  -H 'Content-Type: application/json' -d '{"name": "ci-import"}'
# {"id": 3, "name": "ci-import", "key": "kpal_..."}

Set it once for the rest of this guide:

export KPAL_KEY=kpal_...
export KPAL=https://app.kpal.adhyotlabs.in/api/v1
import os, time
import httpx

kpal = httpx.Client(base_url="https://app.kpal.adhyotlabs.in/api/v1",
                    headers={"X-API-Key": os.environ["KPAL_KEY"]}, timeout=30)

List assets, page by page

Lists return items, total, page and page_size. Pages are 25 items by default and at most 100.

curl -s -H "X-API-Key: $KPAL_KEY" "$KPAL/assets?page=1&page_size=100"
def all_assets():
    page = 1
    while True:
        data = kpal.get("/assets", params={"page": page, "page_size": 100}).raise_for_status().json()
        yield from data["items"]
        if page * data["page_size"] >= data["total"]:
            return
        page += 1

for a in all_assets():
    print(a["value"], a["type"], "verified" if a["verified"] else "not verified")

Filter with q (search), type, owner, tag and verified.

Import a CSV

The file format is in CSV import format.

curl -s -H "X-API-Key: $KPAL_KEY" -F file=@assets.csv "$KPAL/assets/import"
with open("assets.csv", "rb") as f:
    result = kpal.post("/assets/import", files={"file": ("assets.csv", f, "text/csv")}).raise_for_status().json()
print(result)

The response says how many rows were added and lists any rows that failed, with the reason.

Start a scan and wait for it

profile is ports or ports_vulns. target is {"all": true}, {"tag": "prod"} or {"asset_id": 42}. schedule is now or weekly.

curl -s -H "X-API-Key: $KPAL_KEY" -H 'Content-Type: application/json' \
  -d '{"profile": "ports_vulns", "target": {"tag": "prod"}, "schedule": "now"}' "$KPAL/scans"
# {"id": 118, "status": "queued", ...}
curl -s -H "X-API-Key: $KPAL_KEY" "$KPAL/scans/118"
scan = kpal.post("/scans", json={"profile": "ports_vulns", "target": {"tag": "prod"}, "schedule": "now"}).raise_for_status().json()
while scan["status"] in ("queued", "running"):
    time.sleep(15)
    scan = kpal.get(f"/scans/{scan['id']}").raise_for_status().json()
print(scan["status"])  # done or failed

Poll every 15 seconds or more. Only verified assets are scanned.

List open critical findings

curl -s -H "X-API-Key: $KPAL_KEY" "$KPAL/findings?status=open&severity=critical&page_size=100"
crit = kpal.get("/findings", params={"status": "open", "severity": "critical", "page_size": 100}).raise_for_status().json()
for f in crit["items"]:
    print(f["priority"], f["title"], f["due_at"])

status takes several values separated by commas, for example open,in_progress. Other filters: kev=true, owner, asset_id, q.

Update a finding

Statuses are open, in_progress, fixed_pending, verified and risk_accepted. risk_accepted needs an accepted_reason.

curl -s -X PATCH -H "X-API-Key: $KPAL_KEY" -H 'Content-Type: application/json' \
  -d '{"status": "in_progress", "owner": "Platform"}' "$KPAL/findings/2051"
kpal.patch("/findings/2051", json={"status": "in_progress", "owner": "Platform"}).raise_for_status()

Errors

Code Meaning
401 No key, or the key was revoked.
403 Your key or user can't do that (for example, a member creating keys).
404 Not found in your organisation.
422 The request was wrong. The detail field says what to fix.