SCA (Projects & Releases) API
  • 21 Feb 2024
  • 6 Minutes to read
  • Dark
    Light
  • PDF

SCA (Projects & Releases) API

  • Dark
    Light
  • PDF

Article Summary

The Software Composition Analysis (SCA) Repository API has to query, create, and update projects, releases, and related components on a ProGet instance.
All API endpoints are accessed through the following base URL:

/api/sca/...

🛠️ Projects Endpoints

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

🚀 Releases Endpoints

Create/Update Release - Creates or updates a release
Get Release - Describes a specified release
List Releases - Lists and describes specified releases
Analyze Release - Runs an analysis on a specified release

🚩 Issues Endpoints

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

💬 Comments Endpoints

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

📄 SBOM Document Endpoints

Endpoints for managing "Software Bill of Material" (SBOM) documents

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

Authenticating to SCA Repository API Endpoints

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

Access TypeRequirements
System API KeysManage Projects & Releases and/or Upload SBOM documents
Feed API Keysnot usable
Personal API Keyassociated user must have one of:
Projects_View
Projects_ResolveIssue
Projects_UploadSbom
Projects_Manage
No API Keyanonymous 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.

🚀 Quick Example: Authenticating with curl

For example, to authenticate with the API key abc12345 to the List Projects endpoint, 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 set of key/value pairs that correspond to the fields on a Project. It's used as both input and output data for various endpoints:

  • Output: Create/Update Project and List Projects endpoints return ProjectInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives ProjectInfo as a JSON-formatted object; a missing property indicates that the value should not be updated

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

PropertyFormatNotes
idintinternal ID of project
namestringmust be unique across the system
descriptionstring?markdown-based description of project, shown UI
typestring?SBOM Metadata field
urlstring?SBOM Metadata field

JSON Object

{
  "id":1,
  "name":"myProject"
}

ReleaseInfo Object Properties

ReleaseInfo is a set of key/value pairs that correspond to the fields on a Release. It's used as both input and output data for various endpoints:

  • Output: Create/Update Release and List Releases endpoints return ReleaseInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives ReleaseInfo as a JSON-formatted object; a missing property indicates that the value should not be updated

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

PropertyFormatNotes
projectstringThe name of the project
versionstringThe release version number
activeboolIndicates whether the release is active/inactive
urlstring?SBOM Metadata field
commentsCommentInfo[]?An array of CommentInfo objects
viewReleaseUrlstring?Introduced in v2022.10; an absolute URL for the release overview page
viewIssuesUrlstring?Introduced in v2022.10; an absolute URL for the release issues page
packagesPackageInfo[]?Introduced in v2022.16; An array of PackageInfo objects

JSON Object

{
    "project":"myProject",
    "version":"1.2.3",
    "active":true,
    "viewReleaseUrl":"http://proget.corp.local/projects/release?projectReleaseId=2",
    "viewIssuesUrl":"http://proget.corp.local/projects/release/issues?projectReleaseId=2",
    "comments": [
        {
            "number": 1,
            "by": "proget",
            "date": "2024-01-24T02:10:36.993Z",
            "comment": "I am a comment."
        },
        {
            "number": 2,
            "by": "proget",
            "date": "2024-01-24T03:45:21.567Z",
            "comment": "I am another comment."
        }
    ],
    "packages": [
        {
            "purl": "pkg:myGroup/myPackage@1.2.3",
            "vulnerabilities": [
                {
                    "id": "CVE-2021-12345",
                    "title": "Security Vulnerability A",
                    "description": "This is an example of a high-severity security vulnerability.",
                    "score": 9.8,
                    "assessment": "Critical"
                },
                {
                    "id": "CVE-2021-67890",
                    "title": "Security Vulnerability B",
                    "description": "Another example of a medium-severity security vulnerability.",
                    "score": 6.5,
                    "assessment": "Moderate"
                }
            ],
            "licenses": ["MIT", "Apache-2.0"]
        },
        {
            "purl": "pkg:myGroup/anotherPackage@2.0.1",
            "vulnerabilities": [],
            "licenses": ["GPL-3.0"]
        }
    ]
}

IssueInfo Properties

IssueInfo is a set of key/value pairs that correspond to the fields on an Issue. It's used as both input and output data for various endpoints:

  • Output: Create/Update Issue and List Issues endpoints return IssueInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives IssueInfo as a JSON-formatted object; a missing property indicates that the value should not be updated

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

PropertyFormatNotes
projectstringThe name of the project
versionstringThe release version number
numbernumberThe issue number
createdstringThe date the issue was created
typestringThe issue type (V=VulnerablePackage, M=MissingPackage, O=OutdatedPackage, L=LicenseViolation)
purlstringThe package URL of the package associated with the issue
vulnerabilitystring?The ID of the related vulnerability if type is V

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"
}

CommentInfo Object Properties

CommentInfo is a set of key/value pairs that correspond to the fields on a Comment. It's used as both input and output data for various endpoints:

  • Output: Create/Update Comment and List Comments endpoints return CommentInfo as a JSON-formatted object; all values are returned
  • Input: Update endpoint receives CommentInfo as a JSON-formatted object; only the comment field will be updated

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

PropertyFormatNotes
numbernumberThe comment number
bystringThe name of the user that created the comment
datestringThe date the comment was created
commentstringThe comment text

JSON Object

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

PackageInfo Properties

PackageInfo is a set of key/value pairs that correspond to the fields on a Package. It's used as a parameter on a ReleaseInfo object.

PropertyFormatNotes
purlstringA package url of the package
vulnerabilitiesVulnerabilityInfo[]An array of VulnerabilityInfo objects
licensesstring[]An array of license IDs (SPDX codes)

JSON Object

{
  "purl": "pkg:myGroup/myPackage@1.2.3",
  "vulnerabilities": [
    {
      "id": "CVE-2021-12345",
      "title": "Security Vulnerability A",
      "description": "This is an example of a high-severity security vulnerability.",
      "score": 9.8,
      "assessment": "Critical"
    },
    {
      "id": "CVE-2021-67890",
      "title": "Security Vulnerability B",
      "description": "Another example of a medium-severity security vulnerability.",
      "score": 6.5,
      "assessment": "Moderate"
    }
  ],
  "licenses": ["MIT", "Apache-2.0"]
}

VulnerabilityInfo Properties

VulnerabilityInfo is a set of key/value pairs that correspond to the fields on a Vulnerability. It's used as a parameter on a PackageInfo object.

PropertyFormatNotes
idstringThe ID of the vulnerability
titlestringThe title of the vulnerability
descriptionstringThe description of the vulnerability
scorenumber?The CSSV score, if one is set on the vulnerability
assessmentstring?The assessment type, if set

JSON Object

    {
      "id": "CVE-2021-12345",
      "title": "Security Vulnerability A",
      "description": "This is an example of a high-severity security vulnerability.",
      "score": 9.8,
      "assessment": "Critical"
    },

Was this article helpful?