Stackurity Start free trial

API reference Inventory

Inventory

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

List assets

GET /assets

Role: viewer

List assets. reboot_required=true lists hosts that run older code than is installed. exposed=true or false filters by exposed, the exposure risk scoring uses: internet_exposed when set by hand, else what a collector observed (a Kubernetes workload's exposure, or for an image the workloads deployed as it). unfiled=true lists the assets in no active project. Each asset has projects, the active projects it is in that the caller can see

Parameters

ParameterInTypeDescription
kindquerystring
environmentquerystring
statusquerystring
owner_team_idquerystring
qquerystring
reboot_requiredquerystring
exposedquerystring
unfiledquerystring
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessAssetList
4XXAn errorError
5XXAn errorError

Asset and identifiers

GET /assets/{id}

Role: viewer

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessAssetDetail
4XXAn errorError
5XXAn errorError

Set name, environment, owner, criticality, exposure, tags, expected reporting

PATCH /assets/{id}

Role: engineer

Set name, environment, owner, criticality, exposure, tags, expected reporting (report_override: auto, daily, weekly or one_off)

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Delete an asset and its history

DELETE /assets/{id}

Role: admin

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

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

Check the whole asset again

POST /assets/{id}/check

Role: engineer

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The asset's collection history

GET /assets/{id}/collections

Role: viewer

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

List an asset's config findings

GET /assets/{id}/config-findings

Role: viewer

The asset's config findings with the filters of GET /config-findings, and scans: the last config check by each collector. No scan means the asset was never checked

Parameters

ParameterInTypeDescription
id requiredpathstring
statusquerystringopen (the default), resolved or all
severityquerystringhigh, medium, low or info, comma-separated
categoryquerystringagent_hook, ssh or ci, comma-separated
limitquerystringPage size
offsetquerystringPage offset

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

The asset's coverage ledger

GET /assets/{id}/coverage

Role: viewer

Coverage ledger, collection history, relations

Parameters

ParameterInTypeDescription
id requiredpathstring
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

How far the asset's findings can be trusted

GET /assets/{id}/coverage-summary

Role: viewer

How far the asset's findings can be trusted: its coverage states with reasons, components by coverage, gap reasons and stale feeds

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Components whose versions differ from another asset

GET /assets/{id}/drift

Role: viewer

Components whose versions differ from another asset (with, or the asset this one is a replica_of). Each item is behind, ahead, differs, only_here or only_there, compared by the component's ecosystem rules

Parameters

ParameterInTypeDescription
id requiredpathstring
withquerystring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Components on the asset, with evidence and coverage

GET /assets/{id}/inventory

Role: viewer

Components on the asset, with evidence and coverage (see below)

Parameters

ParameterInTypeDescription
id requiredpathstring
qquerystring
typequerystring
directquerystring
include_removedquerystring
update_typequerystringpatch, minor, major or any: only rows with a newer stable release of that update type (registry packages only; not findings) One of patch, minor, major, any.
coveragequerystring
uncheckedquerystringOne reason components were not checked: unreadable_version, unsupported, waiting_for_data or no_advisories
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

An asset's leaked keys and its last key scans

GET /assets/{id}/leaks

Role: viewer

The asset's leaked keys, and scans: the last key scan by each collector, whether it was complete and why not. No scan means its files were never checked

Parameters

ParameterInTypeDescription
id requiredpathstring
statusquerystringopen (default), resolved or all
severityquerystringcritical, high, medium or low
limitquerystringPage size
offsetquerystringPage start

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Link the application to the suggested repository

POST /assets/{id}/link-suggestions/{other}/accept

Role: engineer

Adds the built_from relation between the application and the repository ({id} and {other}, in either order), with source confirmed:<who>, and records an audit event. Needs the engineer role on both assets, as adding a relation does

Parameters

ParameterInTypeDescription
id requiredpathstring
other requiredpathstring

Responses

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

Dismiss a suggested link

POST /assets/{id}/link-suggestions/{other}/dismiss

Role: engineer

Records that the application is not built from the repository, so the pair is not suggested again. Needs the engineer role on both assets

Parameters

ParameterInTypeDescription
id requiredpathstring
other requiredpathstring

Responses

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

The asset's relations to other assets

GET /assets/{id}/relations

Role: viewer

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Add a relation to another asset

POST /assets/{id}/relations

Role: engineer

Add or remove runs_on, built_from, deployed_as, contains, depends_on, replica_of (a standby, staging or DR copy that should run the same versions as the target)

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Remove a relation to another asset

DELETE /assets/{id}/relations

Role: engineer

Add or remove runs_on, built_from, deployed_as, contains, depends_on, replica_of (a standby, staging or DR copy that should run the same versions as the target)

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

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

Remediation actions for an asset (licensed edition; empty in Community)

GET /assets/{id}/remediation

Role: viewer

Remediation actions for an asset

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Create the host-bound agent token used for remediation (licensed edition)

POST /assets/{id}/remediation-token

Role: admin

Collector token bound to this host, required for remediation

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

CycloneDX 1.6 export

GET /assets/{id}/sbom

Role: viewer

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXThe documentstring (application/octet-stream)
4XXAn errorError
5XXAn errorError

Everything the asset relies on, followed through relations, with open findings grouped by layer

GET /assets/{id}/stack

Role: viewer

Everything the asset relies on, followed through relations, with open findings grouped by layer (web_server, cms, os, runtime, data_store, libraries, declared, managed_service, platform, other). For an application this is its hosts, repository, images and dependencies (up to three hops); for a host, the applications running on it; for a cluster, its workloads and their images; for an image, the workloads deployed as it; for a repository, its deployments and their hosts

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Components, searchable

GET /components

Role: viewer

Component explorer

Parameters

ParameterInTypeDescription
qquerystring
typequerystring
segmentquerystringOne segment of the coverage headline: checked, needs_you, waiting, not_supported or no_advisories
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

One component

GET /components/{id}

Role: viewer

Component explorer

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Release data (latest stable, publish date, deprecation) and lifecycle cycles

GET /components/{id}/intel

Role: viewer

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

An upgrade recommendation for each installed version with open findings

GET /components/{id}/upgrade

Role: viewer

An upgrade recommendation for each installed version with open findings (most findings first, at most 50; total counts all), with version, distro and asset_count

Parameters

ParameterInTypeDescription
id requiredpathstring

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Asset identity conflicts

GET /conflicts

Role: admin

Resolve asset identity conflicts by merging assets. The answer lists projects_joined and grants_moved, with a notice, when the kept asset joins the merged assets' projects or takes their access grants

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Resolve an identity conflict by merging assets

POST /conflicts/{id}/resolve

Role: admin

Resolve asset identity conflicts by merging assets. The answer lists projects_joined and grants_moved, with a notice, when the kept asset joins the merged assets' projects or takes their access grants

Parameters

ParameterInTypeDescription
id requiredpathstring

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Coverage ledger across assets

GET /coverage

Role: viewer

Parameters

ParameterInTypeDescription
problemsquerystring
asset_idquerystringOne asset
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Assets by share checked, worst first

GET /coverage/assets

Role: viewer

Assets by share checked, worst first, with groups counting every group (failed_collection, not_reporting, partly_checked, awaiting_first_check, healthy). Each item has components, checked, not_checked by who acts, problem_scopes, reporting and last_report

Parameters

ParameterInTypeDescription
groupquerystringOne group
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Coverage headline: components by segment, and ecosystems found

GET /coverage/overview

Role: viewer

Coverage headline: total components on current assets split into segments (checked, needs_you, waiting, not_supported, no_advisories) that add up to total; GET /components?segment= lists each. ecosystems are the ecosystems and operating systems found, each with key, label, components, checked, not_supported, status (checked, partly or not_supported) and requested

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Ask for an ecosystem to be supported

POST /coverage/support-requests

Role: viewer

Ask for an ecosystem to be supported: {"ecosystem"}, a key from GET /coverage/overview with components Stackurity does not check. One request per workspace and ecosystem; asking again changes nothing. 400 for an ecosystem not found unsupported on your assets. Dashboard sessions only (API tokens get 403); at most 10 a minute and 50 a day per person (429)

Request body

application/json, required: object

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Components not checked, by reason and who acts

GET /coverage/unchecked

Role: viewer

Parameters

ParameterInTypeDescription
asset_idquerystringOne asset

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Components that could not be evaluated, one entry per component and reason, with coverage

GET /evaluation-gaps

Role: viewer

Components that could not be evaluated, one entry per component and reason, with coverage (unsupported or not_evaluated)

Parameters

ParameterInTypeDescription
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Distinct environments, asset kinds and component types

GET /facets

Role: viewer

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Where a component is used

GET /inventory

Role: viewer

Parameters

ParameterInTypeDescription
component_idquerystring
asset_idquerystring
coveragequerystring
uncheckedquerystringOne reason components were not checked: unreadable_version, unsupported, waiting_for_data or no_advisories
qquerystringSearch
typequerystringComponent type
directquerystringtrue or false: direct dependencies only, or transitive only
include_removedquerystringtrue: include removed rows
update_typequerystringpatch, minor, major or any: only rows with a newer stable release of that update type (registry packages only; not findings) One of patch, minor, major, any.
limitquerystringPage size (default 100, at most 500)
offsetquerystringItems to skip

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Updates available: installs behind their latest stable release

GET /inventory/updates

Role: viewer

Updates available: installs older than their package's latest stable release, whether or not a vulnerability is involved (they are never findings). counts gives installs by update_type (patch, minor, major, total), components the packages with any install behind, top the packages with the most installs behind (component_id, type, namespace, name, installed_versions, latest_stable, update_type, installs, assets)

Parameters

ParameterInTypeDescription
asset_idquerystringOnly this asset
update_typequerystringpatch, minor, major or any: only list packages with this update type (counts are not filtered) One of patch, minor, major, any.
limitquerystringPackages listed (default 20, at most 100)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError

Inventory, coverage and status counts, including assets by coverage state

GET /overview

Role: viewer

Inventory, coverage and status counts, including assets by coverage state (asset_coverage) and components by row coverage (component_coverage)

Responses

StatusMeaningBody
2XXSuccessobject
4XXAn errorError
5XXAn errorError