API reference Agents and uploads
Agents and uploads
Remediation actions waiting for this agent (licensed edition; empty in Community)
GET /agent/actions
Agent fetches approved changes and reports results
Responses
Report the progress of a remediation action (licensed edition)
POST /agent/actions/{id}/report
Agent fetches approved changes and reports results
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Request body
application/json, required: object
Responses
Whether the agent should collect now (Check again), for the assets its last report went to
GET /agent/check
The agent's check-again poll: {"check": true, "poll_seconds": 45} when someone asked for a fresh report from one of the listed assets
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
asset_id | query | string |
Responses
CI trusts
GET /ci-trusts
Create, list and delete CI trusts: provider (github, gitlab), issuer (https, matched exactly), repository (owner/repo, or owner/* with owner_wildcard), optional ref, environment, workflow_ref, name, project_id. The list includes the CI audience
Responses
Create a CI trust
POST /ci-trusts
Create, list and delete CI trusts: provider (github, gitlab), issuer (https, matched exactly), repository (owner/repo, or owner/* with owner_wildcard), optional ref, environment, workflow_ref, name, project_id. The list includes the CI audience
Request body
application/json, required: object
Responses
Delete a CI trust and revoke its tokens
DELETE /ci-trusts/{id}
Create, list and delete CI trusts: provider (github, gitlab), issuer (https, matched exactly), repository (owner/repo, or owner/* with owner_wildcard), optional ref, environment, workflow_ref, name, project_id. The list includes the CI audience
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Exchange a CI job's OpenID Connect ID token for a 15-minute collector token
POST /ci/token
Exchange a CI job's ID token ({"token", "trust_id"}) for a collector token that expires after 15 minutes, belongs to the matching CI trust's organisation and project, and may report only the job's repository (repository_url). The token must verify with the issuer's published keys (asymmetric algorithms only), with iss exactly a trust's issuer, aud exactly the server's CI audience (ci_audience in GET /meta), and exp, nbf, iat within one minute. 401 invalid_token, 400 trust_required without trust_id on a server with several organisations, 403 when no trust accepts the job, 409 when several organisations or projects do (send trust_id), 503 without STACKURITY_BASE_URL
Request body
application/json, required: object
Responses
Whether a submitted collection has been evaluated, and its findings
GET /collections/{id}/result
Whether a submitted collection has been evaluated (status: pending, scoring (matched, findings not prioritised yet), evaluated (matched and prioritised), failed), then the asset's open findings and its count of evaluation_gaps. Used by stackurity scan --fail-on
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Start signing in a command-line tool from the browser (RFC 8628 device authorization)
POST /device/code
The tool's first step (client_id stackurity-scan or stackurity, optional host, a host name to show on the approval page; form-encoded or JSON, no credentials, no CSRF header). Answers device_code (kept only as a hash), user_code (eight letters, shown XXXX-XXXX), verification_uri (the dashboard's /device), verification_uri_complete, expires_in (600) and interval (5). OAuth errors: 401 invalid_client, 400 invalid_request, invalid_scope. 404 not_configured without STACKURITY_BASE_URL. Rate limited: 10 a minute and 60 an hour per address (429). See docs/device-login.md
Request body
application/x-www-form-urlencoded, required: object
Request body
application/json, required: object
Responses
Collect the token of an approved device sign-in (RFC 8628 polling)
POST /device/token
The tool's poll: grant_type urn:ietf:params:oauth:grant-type:device_code, device_code, client_id. 400 with an OAuth error: authorization_pending (keep polling), slow_down (polled sooner than interval; the answer's interval is the new one), access_denied, expired_token, invalid_grant (unknown, another client's, or already collected), unsupported_grant_type, invalid_request; 401 invalid_client. Once approved, 200 with access_token (once only), token_type Bearer, scope upload, expires_in, token (id, name, prefix, expires_at), workspace (id, name, slug), project, user (email) and server_url. The token is an API token of the approver with the collector role: it may only POST /ingest and /sbom/import, read GET /collections/{id}/result of its uploads and GET /meta. See docs/device-login.md
Request body
application/x-www-form-urlencoded, required: object
Request body
application/json, required: object
Responses
Exchange a one-time enrollment code for a collector token
POST /enroll
Exchange a one-time enrollment code ({"code", "hostname"}) for a collector token and the agent settings chosen with it, including the code's project_id (null when it has none). Refusals of a code do not say why. Optional project_id (stackurity enroll --project) is a check, not a choice: when the code adds hosts to another project or to none, the answer is 403 and the code keeps its use. Servers before 0.10 answer 400 to the unknown field, also without using the code
Request body
application/json, required: object
Responses
Enrollment codes
GET /enrollments
Create, list and revoke enrollment codes: label, environment, app_dirs, discover_apps, uses (1–500, default 1), ttl_hours (1–720, default 24), project_id (hosts enrolled with the code, and the assets their agent reports, are added to that project when first created). The code is returned once
Responses
Create an enrollment code (shown once)
POST /enrollments
Create, list and revoke enrollment codes: label, environment, app_dirs, discover_apps, uses (1–500, default 1), ttl_hours (1–720, default 24), project_id (hosts enrolled with the code, and the assets their agent reports, are added to that project when first created). The code is returned once
Request body
application/json, required: object
Responses
Revoke an enrollment code
DELETE /enrollments/{id}
Create, list and revoke enrollment codes: label, environment, app_dirs, discover_apps, uses (1–500, default 1), ttl_hours (1–720, default 24), project_id (hosts enrolled with the code, and the assets their agent reports, are added to that project when first created). The code is returned once
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Hosts that used an enrollment code
GET /enrollments/{id}/uses
The hosts that used a code, newest first: hostname, client address, time, and the prefix of the collector token each received
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
id required | path | string |
Responses
Submit an ObservationBatch (gzip accepted)
POST /ingest
Submit an ObservationBatch (gzip accepted). project_id files the asset in a project, see Uploads into a project
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
project_id | query | string |
Request body
application/json, required: ObservationBatch
| Field | Type | Description |
|---|---|---|
schema_version required | string | |
collector required | object | |
asset required | object | |
observations required | array of object | |
complete | boolean |
Responses
Submit one collection of a Kubernetes cluster (the in-cluster reporter)
POST /kubernetes/report
Submit one collection of a Kubernetes cluster, as stackurity kubernetes-reporter sends it: {"batches": [...], "image_scans": 25}, gzip accepted. The batches are the cluster first, then images and workloads, with the kubernetes plugin's identity schemes (k8s-cluster, k8s-cluster-name, k8s-workload, image-ref); other kinds or schemes are refused. Each is stored under the plugin:kubernetes collector as an agent's report. The images are queued for the image scanner in the order given, at most image_scans (default 25, 0 to 500). Refused for a host-bound token; 30 reports an hour per token
Request body
application/json, required: object
Responses
Import a CycloneDX or SPDX JSON document
POST /sbom/import
Import a CycloneDX or SPDX JSON document. project_id files the asset in a project, see Uploads into a project. A collector token made for a project adds the assets it creates to it
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
asset_name | query | string | |
asset_kind | query | string | |
environment | query | string | |
project_id | query | string |
Request body
application/json, required: object