SCA (Builds & Projects) Repository API
The Software Composition Analysis (SCA) Repository 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:
/api/sca/...
🏗 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
🛠️ Projects
Create/Update Project - Creates or updates a project
Get Project - Describes a specified project*
List Projects - Lists and describes specified projects
Scan Project - Generates a minimal SBOM from project dependencies**
* Only available as an HTTP request.
** Only available as a pgutil command.
🚩 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.
Access Type | Requirements |
---|---|
System API Keys | Manage Builds & Projects and/or Upload SBOM documents |
Feed API Keys | not usable |
Personal API Key | associated user must have one of: • Projects_View • Projects_ResolveIssue • Projects_UploadSbom • Projects_Manage |
No API Key | anonymous or authenticated user must have at one of the above permissions |
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.
For example, to authenticate with the API key abc12345
to List Projects, you could specify the API key as follows:
curl -X GET -H "X-ApiKey: abc12345" "https://proget.corp.local/api/sca/projects"
If the provided API key is either missing, unknown/incorrect, or does not have permission, the following message is returned:
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) 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) 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
Note that some values are optional (indicated by string?
), and may be set to null
or an empty string.
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) 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) 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) 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"
},
IssueInfo Properties
IssueInfo
is a set of key/value pairs that correspond to the fields on an Issue. It's used as output data for List Issues, returning IssueInfo
as a JSON-formatted object.
Note that some values are optional (indicated by string?
), and may be set to null
or an empty string.
Example JSON Object
{
"project": "myProject",
"version": "1.2.3",
"number": 123,
"created": "2024-01-23T12:00:00Z",
"type": "V",
"purl": "pkg:myGroup/myPackage@v1.2.3",
"vulnerability": "12345"
}
BuildComment Object Properties
BuildComment
is a JSON object (see BuildComment) 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."
}