Stackurity Start free trial

API reference Agents and uploads

Agents and uploads

18 operations. Base URL https://app.stackurity.dev/api/v1 on Stackurity Cloud; see authentication.

Remediation actions waiting for this agent (licensed edition; empty in Community)

GET /agent/actions

Role: host-bound token

Agent fetches approved changes and reports results

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Report the progress of a remediation action (licensed edition)

POST /agent/actions/{id}/report

Role: host-bound token Licensed build only

Agent fetches approved changes and reports results

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Whether the agent should collect now (Check again), for the assets its last report went to

GET /agent/check

Role: collector, engineer

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

ParameterInTypeDescription
asset_idquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

CI trusts

GET /ci-trusts

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create a CI trust

POST /ci-trusts

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete a CI trust and revoke its tokens

DELETE /ci-trusts/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Exchange a CI job's OpenID Connect ID token for a 15-minute collector token

POST /ci/token

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Whether a submitted collection has been evaluated, and its findings

GET /collections/{id}/result

Role: collector (own submissions), engineer+

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Start signing in a command-line tool from the browser (RFC 8628 device authorization)

POST /device/code

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Collect the token of an approved device sign-in (RFC 8628 polling)

POST /device/token

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Exchange a one-time enrollment code for a collector token

POST /enroll

Role: none (rate limited)

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Enrollment codes

GET /enrollments

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create an enrollment code (shown once)

POST /enrollments

Role: admin

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Revoke an enrollment code

DELETE /enrollments/{id}

Role: admin

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

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccess (usually 204 No Content)no body
4XXAn errorError
5XXAn errorError

Hosts that used an enrollment code

GET /enrollments/{id}/uses

Role: admin

The hosts that used a code, newest first: hostname, client address, time, and the prefix of the collector token each received

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Submit an ObservationBatch (gzip accepted)

POST /ingest

Role: collector, engineer+

Submit an ObservationBatch (gzip accepted). project_id files the asset in a project, see Uploads into a project

Parameters

ParameterInTypeDescription
project_idquerystring

Request body

application/json, required: ObservationBatch

FieldTypeDescription
schema_version requiredstring
collector requiredobject
asset requiredobject
observations requiredarray of object
completeboolean

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Submit one collection of a Kubernetes cluster (the in-cluster reporter)

POST /kubernetes/report

Role: collector, engineer+

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

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Import a CycloneDX or SPDX JSON document

POST /sbom/import

Role: collector, engineer+

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

ParameterInTypeDescription
asset_namequerystring
asset_kindquerystring
environmentquerystring
project_idquerystring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError