Managing Assets via API

This guide explains how to manage assets in DevGuard using the REST API. Assets represent applications, services, or components that you want to scan and monitor for vulnerabilities.

Authentication

All endpoints require authentication using either:

• Cookie Authentication: Session-based (ory_kratos_session cookie)
• Personal Access Token (PAT): HTTP request signing via X-Signature and X-Fingerprint headers

Use the devguard-scanner CLI for PAT authentication:

export DEVGUARD_TOKEN="your-pat-token"
devguard-scanner curl -X GET https://api.devguard.org/api/v1/organizations/my-org/projects/my-project/assets

Base URL

All endpoints use the base path: https://api.devguard.org/api/v1

Core Asset Operations

List Assets

GET /organizations/{org}/projects/{project}/assets

Returns all assets within a project you have access to.

Create Asset

POST /organizations/{org}/projects/{project}/assets

Request Body:

{
  "name": "my-application",
  "description": "Application description",
  "importance": "high",
  "reachableFromInternet": true,
  "confidentialityRequirement": "high",
  "integrityRequirement": "high",
  "availabilityRequirement": "medium",
  "repositoryProvider": "github",
  "enableTicketRange": true,
  "cvssAutomaticTicketThreshold": 7.0,
  "riskAutomaticTicketThreshold": "high"
}

Get Asset Details

GET /organizations/{org}/projects/{project}/assets/{asset}

Returns detailed information including versions, artifacts, and vulnerability statistics.

Update Asset

PATCH /organizations/{org}/projects/{project}/assets/{asset}

Request Body:

{
  "confidentialityRequirement": "high",
  "integrityRequirement": "medium",
  "availabilityRequirement": "low"
}

Delete Asset

DELETE /organizations/{org}/projects/{project}/assets/{asset}

Permanently deletes the asset and all associated data (versions, artifacts, vulnerabilities, VEX rules).

Lookup Asset by Repository

GET /lookup?provider=gitlab&id=12345

Finds an asset by its external repository ID. Returns organization, project, and asset slugs.

Security Configuration

CIA Requirements

Configure Confidentiality, Integrity, and Availability requirements (low, medium, high). These affect vulnerability risk scoring and prioritization.

Importance Levels

• low: Supporting or non-critical assets
• medium: Standard production assets
• high: Critical infrastructure

Automatic Ticket Creation

Enable automatic issue creation for vulnerabilities exceeding thresholds:

{
  "enableTicketRange": true,
  "cvssAutomaticTicketThreshold": 7.0,
  "riskAutomaticTicketThreshold": "high"
}

Asset Versions & Artifacts

Assets contain versions (branches/tags) and artifacts (SBOM files):

# List versions
GET /organizations/{org}/projects/{project}/assets/{asset}/refs/
 
# Get specific version
GET /organizations/{org}/projects/{project}/assets/{asset}/refs/{version}/
 
# List artifacts
GET /organizations/{org}/projects/{project}/assets/{asset}/refs/{version}/artifacts/

SBOM & VEX Reports

Generate and retrieve compliance reports:

# SBOM in CycloneDX format
GET /organizations/{org}/projects/{project}/assets/{asset}/refs/{version}/artifacts/{artifact}/sbom.json/
 
# VEX document
GET /organizations/{org}/projects/{project}/assets/{asset}/refs/{version}/artifacts/{artifact}/vex.json/

CSAF Reports

Common Security Advisory Framework reports:

# Provider metadata
GET /organizations/{org}/csaf/provider-metadata.json/
 
# Version-specific CSAF
GET /organizations/{org}/projects/{project}/assets/{asset}/csaf/white/2024/v1.0.0/

Access Control

Asset access is controlled via role-based permissions on the parent project. Users need appropriate project-level permissions to view or modify assets.