Coverity Scan triage skill

This skill drives the Coverity Scan unofficial JSON API (the public site has no documented API — the scripts mimic what the browser does) for the project configured in .env. Scripts auto-detect the repo root and write all artifacts under <repo-root>/.local/audits/coverity/.

The skill captures operational knowledge (how the API works, where it trips up, what the data means). It does NOT prescribe a review pipeline — how you actually triage each defect (single model, multi-model, manual) is adhoc; agree the approach with the user up front.

MANDATORY — keep this skill alive

If you (the agent) discover a new pattern, gotcha, working flow, correction, or any piece of knowledge while running this skill — update this SKILL.md AND commit it BEFORE proceeding. Knowledge that isn't committed is lost.

Examples of things to capture:

• New view IDs encountered (and what each represents)
• New API endpoint or parameter behavior
• New failure mode (Cloudflare quirks, session expiry signals, rate limits)
• New FP guardrail you found via the codebase (idiom that Coverity mismodels)
• New severity / classification mapping detail learned the hard way

MANDATORY — startup sequence when this skill is invoked

Do these steps in this order. Skipping any step costs the user their session.

Step 1 — agree the triage approach with the user

Coverity reviews are usually 1-3 defects. Sometimes hundreds. Ask the user:

• "How many defects are we looking at — one specific CID, or a sweep?"
• "How do you want to review them — you read each one, you spawn one agent per defect, you want me to use multiple models for cross-checking, …?"

Do NOT default to a heavy multi-stage pipeline; that's only worth setting up when there are tens of defects to crunch. For small batches a single agent or the user reading the bundle directly is usually faster.

If the user does want a multi-model approach, a sensible (not prescribed) shape is: cheap models surface ideas, the strongest coding model produces the actual analysis + fix, the strongest reviewing model sanity-checks the result. The user picks the actual CLIs/models — this skill does not assume any specific tool.

Step 2 — ask the user for a fresh cookie

Coverity Scan auth is cookie-based and tied to a live browser session. Give the user the exact recipe:

1. Open https://scan.coverity.com/projects/<owner>-<repo>?tab=overview (replace <owner>-<repo> with the project slug, e.g. netdata-netdata).
2. Click "View Defects" at the top right -- a new tab opens to https://scan4.scan.coverity.com/# (or scanN.scan.coverity.com -- Coverity load-balances; use whichever URL you land on as COVERITY_HOST).
3. Keep that tab open the whole time we work. Closing it kills the session immediately.
4. Press F12 to open DevTools, switch to the Network tab.
5. Click any defect in the list -- 3-4 requests appear in the Network tab.
6. Right-click any of those requests, select Copy > Copy as cURL.
7. Paste the entire curl command back to me.

If the curl the user pastes does NOT contain a -b 'cookie=...' line, ask again -- they probably picked "Copy as fetch" or "Copy as Node.js fetch".

Step 3 — save the cookie in .env

Extract the value of the -b argument from the user's curl and write/update <repo-root>/.env with:

COVERITY_COOKIE='<paste-the-entire-cookie-blob-here>'
COVERITY_PROJECT_ID=<numeric projectId from the URL or table.json query>
COVERITY_VIEW_OUTSTANDING=<viewId of the Outstanding view>
COVERITY_HOST=https://scan4.scan.coverity.com

.env is gitignored. The cookie blob must include both COVJSESSIONID-build and XSRF-TOKEN. The scripts extract XSRF-TOKEN automatically.

Step 4 — start the keepalive (background)

Bash tool with run_in_background=true,
command="bash .agents/skills/coverity-audit/scripts/keepalive.sh"

The keepalive exits non-zero the moment a ping fails (session expired, browser tab closed, cookie went bad). The orchestrator's background-task notification fires immediately so you know to ask for a fresh cookie and restart.

Stop the keepalive at the end of the triage session by killing its background task.

Step 5 — proceed with the actual triage work

Now (and only now) is it safe to fetch tables, fetch details, prepare defect bundles, finalize verdicts.

CRITICAL — server-side view state

Coverity's table API has a stateful, server-side view cursor. The /views/table.json POST changes server-state (which page is "current"), then the /reports/table.json GET reads whatever the current state is.

This has two consequences:

1. Pagination is two-step, not one-shot

Per page:

1. POST /views/table.json {projectId, viewId, pageNum} -- moves the cursor
2. GET /reports/table.json?projectId=...&viewId=... -- reads the page

fetch-table.sh handles both steps and the page loop.

2. The user MUST NOT touch the Coverity UI while a fetch is running

If the user clicks a different view, scrolls to a different page, sorts a column, applies a filter — the server-side cursor moves under our scripts' feet. The scripts will then fetch garbage (rows from whatever view the user just opened, not the view the script asked for).

Tell the user explicitly: "I'm about to fetch the defect list. Don't click in the Coverity tab until I say I'm done."

If the user accidentally interferes, re-run the fetch script — it's idempotent on cached pages but not on already-corrupted ones, so delete the output JSONs and re-fetch from page 1.

Coverity views (queue scopes)

Coverity organizes defects into named views, each with a numeric viewId. The skill operates per-view.

How to find a view's ID

In the Coverity UI:

• Click the project's defects view, then the view selector dropdown.
• Each view has a URL like https://scan4.scan.coverity.com/#viewId=NNNNN.
• That NNNNN is the value to put in .env (or pass to fetch-table.sh).

Common view types you'll encounter

The default project ships with these (the IDs are project-specific):

• Outstanding — the live queue: defects neither classified nor dismissed. Where day-to-day triage happens. Save its viewId as COVERITY_VIEW_OUTSTANDING (also used by the keepalive).
• All in project — every defect, including already-classified ones. Useful for batch rescans or full audits.
• Dismissed — defects classified as False Positive / Intentional and ignored. Useful for re-review when the underlying code changed.
• Fixed — defects Coverity now considers fixed. Verification queue.
• Unclassified non-outstanding — corner cases.

When a user asks you to operate on a non-default view, ask them to give you its viewId from the UI. You can have multiple COVERITY_VIEW_* env vars.

Switching views without confusing the cursor

The view-state cursor described above is per-session. If you want to fetch view A then view B, do them sequentially (not concurrently): each fetch-table.sh call sends its own POST that resets the cursor. There is no need to "go back" -- just call it again with the next viewId.

Coverity attribute reference

Triage values are sent as integer attribute IDs, not names:

Classification (attribute 3)

Severity (attribute 1)

Action (attribute 2)

External reference (attribute 4)

Free-form string. The scripts always send null.

Sensible (verdict → attributes) mappings

These are what finalize-defect.sh applies when given a verdict from the suggested vocabulary below:

Coverity displayImpact → severity ID

finalize-defect.sh maps defect-summary.json#displayImpact to severity:

Suggested verdict vocabulary

This is the taxonomy used historically; you can reuse it or replace it. The finalize-defect.sh script understands these names directly:

Real bugs (classification = 24 Bug, action = 3 Fix Submitted)

False positives (classification = 22 FP, action = 5 Ignore)

Cosmetic (classification = 23 Intentional, action = 5 Ignore)

Bookkeeping (no Coverity update)

Per-defect workdir convention

prepare-defect.sh creates a per-defect directory under .local/audits/coverity/triage/<scope>/cid-<N>/ with:

• defect-summary.json — the row from the table dump
• defect-details.json — the per-defect details (event trace, CWE, checker)
• source-context.c — ~150 lines of source around the main event
• TODO.md — per-defect notes; keep all per-defect artifacts inside

Whatever review approach the user picks, write its outputs here too (e.g. analyzer reports, decider reasoning, commit message draft, build-verify log). Don't pile per-defect stuff at the repo root.

CID vs defectInstanceId

Two IDs for one defect, both flying around the API:

• cid is stable across scans. Use it for tracking, comments, your permanent records.
• defectInstanceId is per-scan. The defectdetails.json endpoint takes a defectInstanceId, NOT a cid. Each table.json row carries the current lastDefectInstanceId for its CID.

When all you have is a CID (e.g. you're acting on an old list, or working from external triage notes), use:

bash .agents/skills/coverity-audit/scripts/resolve-cid-to-diid.sh <cid>
# prints the current defectInstanceId, or "GONE" if Coverity no longer reports it

Internally it queries /reports/defects.json?cid=N and parses defectInstanceId out of the returned .url field.

Workflow

Fetch a view's table

bash .agents/skills/coverity-audit/scripts/fetch-table.sh \
    "${COVERITY_VIEW_OUTSTANDING}" 7 .local/audits/coverity/raw/outstanding

Produces .local/audits/coverity/raw/outstanding-page1.json ... and a combined flat array at .local/audits/coverity/raw/outstanding-all.json. Pass the right page count (visible in the UI) for the view.

Reminder: the user must not touch the UI during a fetch.

Fetch per-defect details

bash .agents/skills/coverity-audit/scripts/fetch-details.sh \
    .local/audits/coverity/raw/outstanding-all.json \
    .local/audits/coverity/details/outstanding

One file per CID at <details>/cid-<N>.json. Idempotent.

Bundle a defect for review

bash .agents/skills/coverity-audit/scripts/prepare-defect.sh <CID> outstanding

Creates .local/audits/coverity/triage/outstanding/cid-<N>/ with the bundle. The actual review (single-model, multi-model, human) is adhoc — agree the approach with the user.

Apply a verdict

After review and (if needed) a fix commit:

bash .agents/skills/coverity-audit/scripts/finalize-defect.sh \
    <CID> <VERDICT> <scope> .local/audits/coverity/triage/<scope>/cid-<N>/comment.txt \
    [<commit-sha>]

<scope> is the same name prepare-defect.sh uses (e.g. outstanding, dismissed, fixed, unclassified).

This:

• Skips silently for NEEDS_HUMAN and CODE_GONE.
• Reads displayImpact from the table dump to derive severity.
• Appends Fix commit: <sha> to the comment when a SHA is given.
• Posts JSON to /sourcebrowser/updatedefecttriage.json.

For scopes other than "outstanding" (re-triaging dismissed/fixed/etc.), finalize-defect prints a warning -- the caller is asserting that the new verdict disagrees with the existing classification. It still applies.

ASCII-only comments — non-negotiable

Coverity Scan sits behind Cloudflare. The WAF rejects bodies containing non-ASCII bytes (em-dashes, smart quotes, accented letters) with a 403 Cloudflare challenge that looks like an expired-session error but isn't.

• Use -- instead of em-dash (U+2014).
• Use straight quotes " ' instead of smart quotes.
• The scripts reject non-ASCII before the network round-trip.

Project-specific FP guardrails (Netdata)

Most of the cost of a Coverity audit is rejecting false positives. Before calling something a bug in this codebase, rule out these idioms — Coverity mis-models all of them:

1. z-suffix allocators never fail. mallocz, callocz, reallocz, strdupz, strndupz, mallocz_flex call fatal() on OOM. They cannot return NULL. Any "possible NULL deref after mallocz" warning is FP.
2. freez(NULL) is safe. Same for string_freez, etc.
3. DOUBLE_LINKED_LIST_* macros (libnetdata/linked-lists.h) manage prev/next with their own invariants. Raw pointer manipulation inside them is expected.
4. buffer_* API (libnetdata/buffer/) auto-grows the underlying buffer->buffer[] on write. Direct indexing of buffer->buffer[N] from callers is the risk, not the API.
5. STRING is refcounted and interned (libnetdata/string/). string_strdupz increments refcount on an existing intern; string_dup acquires a new reference. Mixing them is a refcount bug.
6. ARAL is a slab allocator (libnetdata/aral/). Objects are reused — UAF looks different here: the same address is re-issued. A pointer that "still works" after aral_freez may be a reused object.
7. DICTIONARY has dictionary_acquired_item_get / _release with refcounts. Raw access bypasses the refcount.
8. Custom locks (spinlock_lock, rw_spinlock_*) — not pthread. Coverity MISSING_LOCK warnings often misunderstand them.
9. Platform: glibc + musl. Watch glibc-only assumptions (e.g. strerror_r signature).
10. Compilers: gcc + clang both must compile.
11. Process model: long-running daemon, spawns plugin subprocesses over a line-based stdin/stdout protocol. Plugin stdin is typically trusted; streaming peers are UNTRUSTED remote peers over TCP.

Input trust boundaries (Netdata)

Used to decide whether a tainted-data path is FALSE_POSITIVE_TRUSTED_INPUT:

Failure modes — quick diagnosis

Recurring tips

• The lastDefectInstanceId field, NOT cid, is what defectdetails.json wants.
• Coverity caches results aggressively; if a CID disappears from "Outstanding" immediately after finalize, a fresh fetch can take a few seconds to reflect.
• Idempotence: fetch-details.sh skips files already present, so partial runs are safe to re-invoke.
• prepare-defect.sh uses Coverity's displayFile and the main-event line to extract source context. If Coverity's line numbers are stale (after a refactor), the context may not center on the current code -- use it as a hint, not an authoritative location.
• Coverity load-balances across scanN.scan.coverity.com hosts. Whatever hostname your browser landed on must be the one in COVERITY_HOST; cookies are per-host.