---
name: codecritical-scan
description: Run a CodeCritical source analysis from an agent via the scan API — mint key (once, interactive), upload a zip with X-Api-Key, poll until COMPLETED, fetch the JSON verdict/LLM export, and interpret score/verdict/confidence. Use when the user asks to scan a codebase with CodeCritical, from an agent or CI workflow.
---

# CodeCritical Agent Skill

Scan a project with CodeCritical and report the verdict. One API key
authenticates every request to the scan rails; no browser session is needed
after the key is minted. **API access is available on all plans.**

## Step 1 — Obtain the API key (interactive, once)

Key management is browser-session-only. The human must mint the key:

1. Sign into the dashboard (https://codecritical.nemesisnet.co.za) and open
   Account → API Keys (or `POST /api/v1/credentials` with an
   `Authorization: Bearer <accessToken>` JWT **and** `Content-Type: application/json`).
2. The response returns `apiKey` plus `secret` (`cc_sk_…`) **exactly once**.
   The agent must store the secret immediately and NEVER echo it into chat,
   logs, or repositories.
3. A revoked/unknown secret returns `401`. Rotate by minting a new key and
   revoking the old one (`DELETE /api/v1/credentials/{apiKey}`, JWT only).

## Step 2 — Upload the source

```bash
curl -X POST https://codecritical.nemesisnet.co.za/api/v1/scan/upload \
  -H "X-Api-Key: $CC_API_KEY" \
  -F "file=@project-source.zip"
# -> {"status":"success","data":{"jobId":37,"message":"..."}}
```

- Accepts `.zip` archives of the project source.
- Read the `jobId` from `data.jobId`.

## Step 3 — Poll until done

```bash
curl -s https://codecritical.nemesisnet.co.za/api/v1/scan/37/status \
  -H "X-Api-Key: $CC_API_KEY"
# -> {"status":"success","data":{"status":"PROCESSING","error":null}}
```

- Poll every ~10 seconds. Do NOT tight-loop: engines are containerised and
  the scan takes minutes.
- Terminal states: `COMPLETED` or `FAILED`.

## Step 4 — Fetch and present the results

```bash
# Full JSON result (owner view)
curl -s https://codecritical.nemesisnet.co.za/api/v1/scan/37 \
  -H "X-Api-Key: $CC_API_KEY"

# LLM-ready markdown context export
curl -s https://codecritical.nemesisnet.co.za/api/v1/scan/37/export/llm \
  -H "X-Api-Key: $CC_API_KEY" -o report.md
```

Interpret the payload:

- `nemesisScore` (0-100) and `verdict` (`PASS` / `RISK` / `FAIL`).
- `confidence` + `confidenceDetails` for evidence quality.
- `enginesRun` / `enginesSkipped` — if the owning user disabled engines,
  `enginesSkipped` lists them, confidence is damped for reduced coverage,
  and score/verdict may be `null`. Treat reduced coverage as lower-evidence.
- `vulnerabilities[]` with `severity`, `ruleId`, `file`, `line`, `fix`.

## Guardrails

- **Scope:** keys are limited to the `scan` rails (upload, poll, results,
  exports, history). Settings/credentials/billing/admin APIs return `403`.
- **Quota:** scans are per-user per-month. A rejected upload returns
  `429` with body `{"code": "QUOTA_EXHAUSTED", "errors": ["Monthly scan quota
  reached (used/limit)..."]}` — surface as "upgrade or wait", never retry-loop.
  (`503` with `code: "MAINTENANCE"` = platform maintenance: brief retry is correct.
  `429` with `code: "CAPACITY_LIMIT"` = transient capacity/rate-limit: retry
  after a delay.)
- **Idempotency:** `GET /scan/{id}` is safe to re-read; only upload when the
  source actually changed.
- **Secret hygiene:** keep `cc_sk_…` in a secrets manager or env var.
  Never hardcode, log, or commit it.
- **Ownership:** findings marked `YOU` are first-party code you can remediate;
  findings from dependencies are third-party upgrade work.