API reference
Tools
The scanners, linters, SBOM generator and decompilers Nullgap can run in its sandbox, and whether each can run here.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| List automated checks | GET /api/orgs/{org}/tools | read |
#List automated checks
GET /api/orgs/{org}/tools
Returns every automated check Nullgap can run in its sandbox, by capability (static-analysis, secret-detection, dependency-scan, ...), then its built-in tools, each with what it is pointed at, the inputs it takes, whether it is present on this server and whether it is allowed to run. A check is named by what it does; the software behind it is not listed. The web application scan is off until the operator of the server switches it on, and is listed with the reason. The answer is an object, not a page.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tools"
Answer (200, application/json)
A ScanningToolList object.
{
"enabled": true,
"reason": "security tools are not switched on for this server",
"tools": [
{
"id": "static-analysis",
"title": "Static code analysis",
"category": "static-analysis",
"purpose": "Looks for unsafe patterns in source code across many languages, using rules written by Nullgap.",
"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,
"enum": [
"cyclonedx-json"
]
}
],
"needsNetwork": false,
"needsStateChanging": false,
"available": true,
"unavailableReason": "not available on this server",
"enabled": true,
"disabledReason": "off unless the operator of this server switches it on"
}
]
}
#Objects
The objects the operations above take and return.
#ScanningToolList
The automated checks and whether each can be run here.
| Field | Type | Always present | Description |
|---|---|---|---|
enabled | boolean | yes | Whether the sandboxed checks are switched on for this server at all. When false only the built-in tools can be run, and every other check is listed as not available. |
reason | string | no | Why nothing can be run. Present only when enabled is false. |
tools | array of ScanningTool | yes | Every check: the ones that can run and the ones that are switched off, each with the reason, then Nullgap's built-in tools. |
#ScanningTool
One automated check Nullgap can run in its sandbox, named by what it does. Running it runs everything Nullgap has behind it and returns one merged result.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The check's id (a capability, or a built-in tool), used to start a run. |
title | string | yes | Its name. |
category | string | yes | The capability, or built-in for one of Nullgap's own tools. |
purpose | string | yes | What it checks, in a sentence. |
target | string | yes | What a run is pointed at. repository: the files of a connected repository or an uploaded archive. url: a running application, at an address on the organisation's live-testing scope list. |
inputs | array of object | yes | The inputs a run of this check takes. paths and url are sent at the top level of the request; any other input goes in options. |
inputs[].name | string | yes | The input's name. |
inputs[].type | string | yes | Its type, in words. |
inputs[].description | string | yes | What it is for. |
inputs[].required | boolean | yes | Whether a run must supply it. |
inputs[].enum | array of string | no | The allowed values, when the input is a choice. |
needsNetwork | boolean | yes | Whether it sends requests to a running application. |
needsStateChanging | boolean | yes | Whether it can change data on its target, and so also needs the explicit state-changing permission. |
available | boolean | yes | Whether the check is present on this server and can be started now. |
unavailableReason | string | no | Why it is not available. Present only when available is false. |
enabled | boolean | yes | Whether the check is allowed to run here. The web application scan is off until the operator of the server switches it on. |
disabledReason | string | no | Why it is off. Present only when enabled is false. |
Nullgap documentation