SCA (Builds & Projects)

The Software Composition Analysis (SCA) API has to query, create, and update projects, builds, and related components on a ProGet instance.
All http requests are made through the following base URL:

pgutil Commands

All HTTP endpoints of the SCA API are available as pgutil commands.

To find the list of commands available in pgutil, simply run pgutil builds --help. See Getting started with pgutil to learn more.

Available HTTP Endpoints

The SCA API is comprised of endpoints for Builds, Projects, Issues, Comments and SBOM Documents::

🏗 Builds

Create/Update Build - Creates or updates a build
Get Build - Describes a specified build
List Build - Lists and describes specified build
Analyze Build - Runs an analysis on a specified build
Promote Build - Promotes a build to a specified stage
Scan Build - Generates a minimal SBOM from project dependencies*

* Only available as a pgutil command.

🛠️ Projects

Create/Update Project - Creates or updates a project
Get Project - Describes a specified project*
List Projects - Lists and describes specified projects

* Only available as an HTTP request.

🚩 Issues

List Issues - Lists and describes specified issues
Delete Issues - Deletes a specified issue
Resolve Issue - Sets a specified issue to resolved

💬 Comments

Create/Update Comment - Creates or updates a comment
List Comments - Lists and describes specified comments
Delete Comment - Deletes a specified comment

📄 SBOM Document

For managing "Software Bill of Material" (SBOM) documents

Export SBOM - Exports a SBOM document from ProGet
Import SBOM - Imports a SBOM document to ProGet*

* Only available as an HTTP request.

Authenticating to SCA Repository API

The following is a summary of access types and their corresponding requirements for various API key types and endpoints within this API.

To specify an API Key, use the request header (X-ApiKey), querystring (key), or api:«api-key» as the username. See API Key Usage to learn more.

curl -X GET -H "X-ApiKey: abc12345" "https://proget.corp.local/api/sca/projects"

403 The specified API key does not have the proper permissions to perform this action.

Data Specifications

ProjectInfo Object Properties

ProjectInfo is a JSON object (see ProjectInfo.cs) that correspond to the fields on a Project. It's used as both input and output data for Create/Update Project and output data for List Projects.

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Example JSON Object

[
  {
    "id": 2,
    "name": "myProject",
    "url": "proget.corp.local"
  },
  {
    "id": 1,
    "name": "myApplication",
    "type": "Application"
  }
]

BuildInfo Object Properties

BuildInfo is a JSON object (see BuildInfo.cs) that corresponds to the fields on a build. It's used as both input and output data for Create/Update Build, and output data for Get Build and List Builds

Example JSON Object

{
    "project":"myProject",
    "version":"1.2.3",
    "active":true,
    "viewBuildUrl":"http://proget.corp.local/projects/release?projectReleaseId=2",
    "viewIssuesUrl":"http://proget.corp.local/projects/release/issues?projectReleaseId=2",
    "comments": [ ], // Refer to BuildComment object
    "packages": [ ] // Refer to BuildPackage object
}

BuildPackage Properties

BuildPackage is a JSON object (see BuildPackage.cs) used as a parameter on a BuildInfo object. It corresponds to the fields on a Package and is used as both input and output data for Create/Update Build, and output data for Get Build and List Builds

Example JSON Object

[
    {
      "purl": "pkg:nuget/Newtonsoft.Json@12.0.3",
      "licenses": [ "MIT" ],
      "compliance": { }, // Refer to BuildPackageComplianceInfo object
      "vulnerabilities": [ ] // Refer to BuildPackageVulnerability object
    },
    { ... }
  ]

BuildPackageVulnerability Properties

BuildPackageVulnerability is a JSON object (see BuildPackageVulnerability.cs) used as a parameter on a BuildPackage object. It corresponds to the fields on a Package Vulnerability and is used as both input and output data for Create/Update Build, and output data for Get Build and List Builds

Example JSON Object

[
    {
      "id": "PGV-2245804",
      "title": "Improper Handling of Exceptional Conditions in Newtonsoft.Json",
      "description": "Description of the vulnerability in markdown",
      "score": 7.5,
      "assessment": "Blocked"
    },
    { ... }
]

BuildPackageComplianceInfo Properties

BuildPackageComplianceInfo is a JSON object (see BuildPackageComplianceInfo.cs) used as a parameter on a BuildPackage object. It corresponds to the fields on a Package's compliance information and is used as both input and output data for Create/Update Build, and output data for Get Build and List Builds

Example JSON Object

{
    "result": "Noncompliant",
    "detail": " because of Vulnerability (PGV-2245804).",
    "date": "2024-07-11T08:53:41.827Z"
},

BuildIssue Properties

BuildIssue a JSON object (see BuildIssue.cs) that correspond to the fields on an Issue. It's used as output data for List Issues, returning IssueInfo as a JSON-formatted object.

Example JSON Object

{
    "number": 123,
    "created": "2024-01-23T12:00:00Z",
    "detail": "No license detected...",
    "purl": "pkg:myGroup/myPackage@v1.2.3",
    "resolved": true
}

BuildComment Object Properties

BuildComment is a JSON object (see BuildComment.cs) that corresponds to the fields on a Comment. It's used as both input and output for Create/Update Comment, and output for List Comments.

Note that some values are optional (indicated by string?), and may be set to null or an empty string.

Example JSON Object

{
    "number":1,
    "by":"proget",
    "date":"2024-01-24T02:10:36.993Z",
    "comment":"I am a new comment."
}