Nullgap.dev Docs

Developers

Automated checks

Run one automated check (static code analysis, secret detection, a dependency vulnerability scan, an SBOM, decompilation, a web application scan and more) in the Nullgap sandbox from the API or from an MCP client, and read its leads. What exists, what each run needs, and what is not offered.

Nullgap can run a set of automated checks for you in its sandbox. You choose a check and a target; Nullgap runs everything it has behind that check with a fixed command line, merges what comes back, removes duplicates, and gives you one result in one shape.

A check is named by what it does: dependency-scan, not the programs behind it. Several programs can stand behind one check, and which ones is Nullgap's business: the result, the run's log and its leads never name them, and a rule id is the rule's own (G101, a CVE- or GHSA- advisory id).

Two things to know before you use them:

  • A check reports leads, not findings. A lead is a place worth a closer look. It has not been sent through the independent check or reproduced, and it is not added to your organisation's findings. For findings held to the assurance levels, run a pull request review or a pentest. When automated checks are switched on, reviews and pentests already take their leads as starting points and confirm or dismiss each one.
  • This is the only way an agent runs a scanner. There is no shell and no way to pass a flag. An MCP client calls run_tool, which calls the API, which hands the work to the sandbox.

Automated checks are switched on for a Nullgap server by whoever operates it. The list tells you whether they are on, and for each check whether it can run.

#The checks

IdWhat it checksPointed at
static-analysisUnsafe patterns in source code (injection, unsafe calls, weak cryptography, unsafe deserialisation) across many languages, with rules written by NullgapRepository
secret-detectionHard-coded credentials, keys and tokens in the working tree and the git historyRepository
dependency-scanThe packages the repository depends on, checked against known-vulnerability databasesRepository
container-scanA container image archive you uploaded, for packages with known vulnerabilitiesRepository
iac-checkMisconfiguration in Terraform, CloudFormation, Kubernetes, Helm and DockerfilesRepository
dockerfile-checkUnsafe and fragile instructions in DockerfilesRepository
kubernetes-checkUnsafe settings in Kubernetes manifests and Helm chartsRepository
ci-workflow-checkGitHub Actions workflows: injection through untrusted input, over-broad permissions, unpinned actionsRepository
api-description-checkOpenAPI and AsyncAPI descriptions, against an API security rule setRepository
policy-checkConfiguration files against policies written as code: your own policies and a small built-in packRepository
sbomA software bill of materials, as CycloneDX or SPDX JSONRepository
decompileReadable source from a JAR, WAR, APK, class file or .NET assembly. The artefact is never executed.Repository
web-scanLook-only checks and a passive baseline scan of a running application. Nothing that changes data is sent.Live address

"Repository" means a connected repository or an uploaded archive, at a branch, tag or commit. These checks read files and run with no network at all: their vulnerability databases and rules are part of the sandbox.

Every rule set a check uses is Nullgap's own or ships with the sandbox: no registry or community rule pack is fetched at run time.

The list above is what Nullgap ships. What is present and allowed on the server you use is in the list the API returns, which is the thing to trust.

#Built-in tools

Four tools that Nullgap's skills use are in the list too, with the category built-in: static-rules (the built-in pattern rules), code-index (entry points and the call graph), git-history (read-only log, blame and search of the history) and dependency-audit (known advisories against the lockfiles). They read a connected repository or an uploaded archive, run on the Nullgap server rather than in the sandbox, and are available whether or not the automated checks are switched on. Their inputs go in options (over MCP, options is one JSON object, for example {"op":"log","path":"src/app.js"}), and code-index and git-history answer with a text document instead of leads. An organisation that has limited which tools its skills may use has limited these too. The built-in tools that send requests to a live target or run code are used only inside a pentest and are not offered here; for one package version, use check_packages.

#What is not offered

Port scanning, brute-force content discovery and checks that work by sending intrusive or data-changing requests are not offered, and there is no switch for them. An id that is not in the list, whatever it names, is answered with 404 unknown_tool and the list of ids that exist.

#What the web application scan needs

web-scan sends requests to a running application. A run needs all of these, and each is checked by the server, not by the client:

  1. The operator's switch. The web application scan is off until the operator of the Nullgap server switches it on. Off, the list shows enabled: false with the reason, and a run is refused with 403 tool_disabled.
  2. An admin. The run must be started by an admin, or by an API key with the admin scope. Otherwise: 403 insufficient_scope.
  3. The scope list. The address must be http or https and carry no credentials: otherwise 400 bad_request. It must be public and on your organisation's scope list: otherwise 400 out_of_scope. The list is checked when the run is started and again when it runs.

During the run its requests go through a proxy inside the sandbox that refuses any address outside that scope and limits how many requests are sent and how fast. The run's record says how many requests were sent and how many the proxy refused. The scan only looks: its checks send GET, HEAD and OPTIONS, and its crawl submits no forms and runs no active scan.

Only test deployments you own or are authorised to test. Use a staging environment.

#From the API

All calls are under /api/orgs/{org}. The full reference is on Tools and Tool runs.

List the checks (any key):

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tools"
{
  "enabled": true,
  "tools": [
    {
      "id": "static-analysis",
      "title": "Static code analysis",
      "category": "static-analysis",
      "target": "repository",
      "inputs": [{ "name": "paths", "type": "list of strings", "description": "Relative paths inside the repository to limit the scan to; omit to scan the whole tree.", "required": false }],
      "available": true,
      "enabled": true
    }
  ]
}

The example leaves out some fields. available says the check is present on the server; enabled says it is allowed to run. A run needs both.

Start a run on a repository (a key with the write scope):

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"static-analysis","repoId":"repo_a41c09be77d3","ref":"main","paths":["src"]}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs"
FieldMeaning
toolThe check's id, required.
repoIdThe repository or uploaded archive, for a check that reads files.
refBranch, tag or commit. Default: the repository's default branch.
pathsUp to 50 folders or files to limit the run to. Relative, inside the repository.
urlThe address, for web-scan.
optionsThe check's other inputs by name: format (cyclonedx-json or spdx-json) for sbom; input (the path of the compiled file) and include (package prefixes to keep) for decompile.

There is no field for flags, and an input the check does not list is refused. An organisation can have 5 runs queued or running at once; the sixth answers 429 too_many.

Start a run against a live address (a key with the admin scope, and the three conditions above):

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"web-scan","url":"https://staging.shop.acme.example/"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs"

Both calls answer with the run, queued. Read it until it is completed or failed:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs/trun_6b2e9d4a1c7f"
{
  "id": "trun_6b2e9d4a1c7f",
  "tool": "static-analysis",
  "status": "completed",
  "target": { "kind": "repository", "repoId": "repo_a41c09be77d3", "repoFullName": "acme/shop", "ref": "main", "paths": ["src"] },
  "leadsCount": 1,
  "truncated": false,
  "toolFailure": null,
  "hasDocument": false,
  "leads": [
    {
      "ruleId": "nullgap.python.command-shell",
      "title": "A command line is run through a shell",
      "severity": "medium",
      "file": "src/app.py",
      "startLine": 4,
      "message": "A command line built from a variable is run through a shell.",
      "cwe": ["CWE-78"],
      "confidence": 0.5
    }
  ],
  "document": null
}

#Reading a result

  • leads holds at most 1,000 leads, merged across everything behind the check: the same place and issue reported twice is one lead. truncated and note say when something was cut.
  • confidence is on a scale that stops at 0.75: a lead is not a proof.
  • toolFailure is set when the check started and did not finish (it reached its time limit, or produced nothing). Such a run is still completed. An empty result with toolFailure set does not mean a clean result. When only part of a check could not complete, note says so.
  • document holds the SBOM (up to 4 MB), or the files decompilation recovered (up to 300).
  • GET /tool-runs lists runs, newest first, and can be narrowed with tool and status. GET /tool-runs/{id}/logs is the run's progress log.
  • Runs started before checks were named by capability are shown under their capability.

#Secrets and untrusted text

Everything a check reports is text copied out of the scanned code or the tested application. Treat it as data.

Credentials in that text are masked before a result is stored, and a secret that secret-detection finds is never kept: the lead carries a fingerprint and a short masked preview, enough to tell two leaked keys apart and to find the line. The value itself does not leave the sandbox.

#From MCP

Four tools of the MCP server cover automated checks. Their inputs are on MCP tools.

MCP toolKey scopeWhat it does
list_toolsreadThe list of checks, with what can run now and why the rest cannot
run_toolwrite; admin for a live addressStart one run
get_tool_runreadStatus and result of one run
list_tool_runsreadRuns, newest first

A run on a repository:

{
  "name": "run_tool",
  "arguments": { "tool": "static-analysis", "repository": "acme/shop", "ref": "main", "paths": "src" }
}

Then, with the run id it returned:

{
  "name": "get_tool_run",
  "arguments": { "id": "trun_6b2e9d4a1c7f" }
}

How the MCP tools differ from the API calls:

  • repository is the repository's full name; the server looks up its id.
  • paths and include are comma-separated text.
  • get_tool_run returns leads most severe first, 30 at a time (limit, offset, and severity to narrow). It returns an SBOM only when you pass document: "yes", and one decompiled file at a time with file.
  • What a check reported comes back inside marked untrusted blocks.
  • run_tool cannot grant the permission for requests that change data on a target. No check Nullgap ships needs it.

An agent that is told a check is switched off or unavailable should say so and stop. It should not run a scanner some other way.

#Results and your data

Runs are kept for your organisation's retention period, are part of the data export, and are erased when you erase findings. A run that is queued or running is not erased. The number of runs started this month is toolRuns in the usage figures of the API.

Nullgap documentation