Nullgap.dev Docs

Skills

Running a skill on demand

Start one skill by itself against a repository, a pull request, a finding or two versions of an artefact, and read what it returns and how far to rely on it.

A skill that lists "on demand" can be started by itself, outside a review or a pentest. Use this to get a document (a threat model, a test plan, an incident runbook), a second look at one finding, or a comparison of two versions.

An on-demand run is one skill working once. Its output is not sent through the independent check and nothing in it is reproduced in the sandbox. Every run says so in its assurance field, in words written by Nullgap and not by the skill. For findings held to the assurance levels, run a pull request review or a pentest.

#What you need

  • Any member can start a run. With the API, a key with the write scope.
  • An active trial or plan. Without one the call answers 402 plan_inactive; at the monthly usage ceiling it answers 402 usage_limit. See usage.
  • The skill must be switched on for the organisation and for the repository, and it must list "on demand". The catalogue says which do.

#What a skill can work on

Each skill states its inputs, and whether each is required. The catalogue shows them under What it works from.

InputYou giveUsed by, for example
A repositoryThe repository, and optionally a branch, tag or commitMost skills
A pull requestThe repository and the pull request numbersecure-code-review, secure-design-review
A findingThe finding's id; the repository is taken from the findingfinding-triage, exploited-vulnerability-response
TextLogs, an alert, a feature description, up to 200,000 characterssecurity-event-analysis, security-requirements
Two versionsTwo uploaded artefacts, or two refs of one repositorypatch-diff-analysis

Do not put credentials in the text you supply.

#In the console

  1. Open Skills and choose the Run a skill tab.
  2. Choose the Skill. Only skills that are switched on and can run on demand are listed.
  3. Fill in what that skill works on: a repository and optionally a version, a pull request, a finding, text, or two versions to compare.
  4. Start the run. It appears under Recent runs with its status, and opens with its result when it has finished.

#With the API

Start a run on a repository's default branch:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skillId":"threat-modeling","repoId":"repo_4c1d2e3f5a6b"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs"
FieldMeaning
skillIdThe skill's id. Required.
repoIdThe repository. Required unless findingId or artifacts is given.
refA branch, tag or commit. Default: the repository's default branch.
prNumberA pull request number, for a skill that takes one.
findingIdA finding, for a skill that takes one.
baseRefWith ref: compare baseRef (older) with ref (newer), for a skill that compares two versions.
artifacts{ "before": "<upload id>", "after": "<upload id>" }: two uploads to compare. No repository is involved.
textText for the skill to work on.

The answer is the run, with status queued and no output yet (abridged):

{
  "id": "skr_9d2c4b7a1e3f",
  "skillId": "threat-modeling",
  "skillTitle": "Threat modeling",
  "skillVersion": "1.0.0",
  "origin": "built-in",
  "repoId": "repo_4c1d2e3f5a6b",
  "repoFullName": "acme/shop",
  "target": { "kind": "repository", "ref": "main" },
  "hasText": false,
  "status": "queued",
  "error": null,
  "assurance": "Produced by one skill run on request. It was not sent through the independent check or reproduced in the sandbox, so nothing in it is a verified or proven finding. Run a review or a pentest for findings held to that standard.",
  "output": null,
  "tools": [],
  "createdBy": "dana@acme.example",
  "createdAt": "2026-11-16T10:02:11.000Z",
  "startedAt": null,
  "finishedAt": null
}

Read it until status is completed, failed or cancelled. A run takes minutes, so ask every 15 seconds or so, not in a tight loop:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs/skr_9d2c4b7a1e3f"

Other calls:

CallWhat it does
GET /api/orgs/:org/skill-runsRuns, newest first, without their output. Takes limit, offset and skillId.
GET /api/orgs/:org/skill-runs/:idOne run with its output.
GET /api/orgs/:org/skill-runs/:id/logsThe run's log lines.
POST /api/orgs/:org/skill-runs/:id/cancelCancel a run that is queued or running. A finished run answers 400 not_running.

Refusals when starting:

Status and codeMeaning
400 not_on_demandThe skill runs only inside reviews and pentests, or only in live testing
400 skill_disabledThe skill is switched off for the organisation or for this repository
400 bad_requestAn input the skill needs is missing, or one it does not take was sent. The message says which
402 plan_inactive, usage_limitNo active plan, or the monthly usage ceiling has been reached
404 not_foundThe skill, the repository, the finding or an upload does not exist

#Reading the result

A finished run has three things to read: output, tools and assurance.

#tools

One entry for each tool the skill named, with what happened to it:

statusMeaning
ranThe tool ran
offeredThe tool was available and the skill did not call it
unavailableThe tool is not installed on this installation
not-permittedYour organisation does not permit this tool
failedThe tool was started and did not finish

A tool that did not run is not a clean result. The output's limits say what was not examined because of it.

#output

What comes back depends on the skill, and has one of three fixed shapes.

A document ("kind": "document"): a title, a summary, sections with a heading and a body each, items, and limits. Each item is one row: a control, a requirement, a policy check or a timeline entry, with a ref, a title, a detail, an optional location and a status from a fixed neutral set:

statusMeaning
evidence-foundSomething in the code or the data supports it
gap-observedSomething expected was looked for and not found
not-examinedIt was not looked at
not-applicableIt does not apply here
infoA note

There is no "pass" or "fail" in that set on purpose: a document from a skill is material for your own judgement.

Candidate leads ("kind": "findings"): leads, each shaped like a finding with a title, a severity, a location and a description. They are candidates only. They are not added to your organisation's findings, they were not checked independently, and they were not reproduced. To have one confirmed, run a review or a pentest that covers the code.

A triage verdict ("kind": "triage"): the verdict on one existing finding, from finding-triage. It is recorded on the finding and shown in the finding's triage verdict and trace. It does not change the finding's state: deciding stays with a person.

Every output ends with limits: what was not examined and what cannot be concluded. Nullgap adds to this list itself, for example when a tool was unavailable. A skill cannot remove entries from it.

#Comparing two versions

patch-diff-analysis compares two versions of an artefact and describes what changed, the flaw the change most likely fixed and its root cause with before and after code, a confidence, which versions are affected and how to check whether you are exposed. It does not write exploit code.

You can compare two refs of a connected repository:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skillId":"patch-diff-analysis","repoId":"repo_4c1d2e3f5a6b","baseRef":"v2.3.0","ref":"v2.3.1"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs"

Or two uploaded files. Upload each version first; the request body is the file itself, and the display name goes in the name query parameter:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @library-2.3.0.jar \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-uploads?name=library-2.3.0.jar"

The answer carries the upload's id. Start the run with both ids:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"skillId":"patch-diff-analysis","artifacts":{"before":"sku_1a2b3c4d5e6f","after":"sku_6f5e4d3c2b1a"}}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/skill-runs"
Uploads
AcceptedSource archives (.zip, .tar.gz), Java archives (.jar, .war, .ear) and .NET files (.dll, .exe, .nupkg)
Largest file200 MB
Kept at a time20 per organisation. DELETE /api/orgs/:org/skill-uploads/:id removes one
Kept for7 days, then removed
ListingGET /api/orgs/:org/skill-uploads

An upload is unpacked under the same rules as an uploaded source archive. The comparison itself is done by code: files are hashed and compared, and changed files are ranked by how likely they are to be a security fix. Compiled code is decompiled in the sandbox when a decompiler is installed on the installation; when none is, the run says what it could not read.

#From an MCP client

run_skill starts a run and get_skill_run reads it; list_skills shows the catalogue and the uploads available for a comparison. Starting needs a write key. See MCP tools.

#Limits

LimitValue
Text supplied to a run200,000 characters through the API, 100,000 through the MCP tool
Time for one skillSet by the skill, between 1 and 30 minutes
UsageA run stops when it reaches its own usage limit or your workspace's monthly ceiling, and says so

A run that fails says why in error, and its log has the detail. See getting help.

Nullgap documentation