Sigrid API documentation

In addition to Sigrid CI, Sigrid also provides a more general-purpose REST API that you can use to obtain analysis results from Sigrid. This allows you to integrate data from Sigrid into your workflow.

General usage

• The Sigrid API base URL is https://sigrid-says.com/rest/analysis-results/api/v1.
• Authentication for the Sigrid API uses the same authentication tokens that are used by Sigrid CI. Your token’s permissions are based on your user account, so the token can access the same systems that you can.
• You need to pass the authentication token to each request in the HTTP header Authorization: Bearer {SIGRID_CI_TOKEN}.
• All end points will return HTTP status 401 if the token is invalid, or if the token is not authorized to access the portfolio and/or system.
• All end points return JSON and therefore return a Content-Type of application/json.

The following example shows how to call the Sigrid API using curl:

curl -H 'Authorization: Bearer {SIGRID_CI_TOKEN}' https://sigrid-says.com/rest/analysis-results/api/v1/maintainability/{customer}

In the example, {customer} refers to your company’s Sigrid account name, and {SIGRID_CI_TOKEN} refers to your authentication token.

Including deactivated and/or excluded systems

In Sigrid’s web-based user interface, several portfolio (customer) level dashboards by default hides deactivated systems and excluded systems. The filter panel on the right hand side provides two toggles to override this behavior:

A system can be deactivated, or excluded from dashboards, in the metadata settings page:

Sigrid’s REST API mimics this behavior, as follows:

• All portfolio-level endpoints by default do not include deactivated nor excluded systems in their responses.
• Deactivated systems can be included in the response by adding a boolean query parameter hideDeactivatedSystems and set it to false, no, or 0. For instance, GET /api/v1/maintainability/{customer}&hideDeactivatedSystems=false includes deactivated systems in the response.
• Excluded systems can be included in the response by adding a boolean query parameter hideExcludedSystems and set it to false, no, or 0. For instance, GET /api/v1/maintainability/{customer}&hideExcludedSystems=false includes development-only systems in the response.

Available end points

• Maintainability ratings
• Security and reliability findings
• Vulnerable libraries in Open Source Health
• System metadata
• System lifecycle management
• System objectives

Maintainability ratings

Maintainability ratings for a given customer are available via three endpoints:

• GET https://sigrid-says.com/rest/analysis-results/api/v1/maintainability/{customer}: system-level maintainability ratings for all systems of the given customer the current user has access to.
• GET https://sigrid-says.com/rest/analysis-results/api/v1/maintainability/{customer}/{system}: system-level maintainability ratings for the given system of the given customer.
• GET https://sigrid-says.com/rest/analysis-results/api/v1/maintainability/{customer}/{system}/components: component-level maintainability ratings for the given system of the given customer.

The parameter {customer} refers to your Sigrid account name.

The top-level maintainability and maintainabilityDate refer to the current state of each system. The allRatings array contains a list of all historic measurements, which can be used for reporting or trend information.

Security and reliability findings

Sigrid’s REST API provides two endpoints to get security or reliability findings for a system:

• Security findings: GET https://sigrid-says.com/rest/analysis-results/api/v1/security-findings/ {customer}/{system}
• Reliability findings: GET https://sigrid-says. com/rest/analysis-results/api/v1/reliability-findings/{customer}/ {system}

The parameters {customer} and {system} refer to your Sigrid account name and system ID respectively.

Vulnerable libraries in Open Source Health

A list of all third-party libraries used is available for a given system, or for all systems for a customer, using the following endpoints:

• GET https://sigrid-says.com/rest/analysis-results/api/v1/osh-findings/{customer}?vulnerable=<choose one of true or false according to the explanation below>: get all third-party libraries for all systems the current user has access to for the given customer.
• GET https://sigrid-says.com/rest/analysis-results/api/v1/osh-findings/{customer}/{system}?vulnerable=<choose one of true or false according to the explanation below>: get all third-party libraries for the given system and customer.

The path parameters {customer} and {system} refer to your Sigrid account name and system ID respectively. The vulnerable URL query parameter is optional and defaults to false. The meaning is as follows:

• ?vulnerable=false or no query parameter: the endpoint returns the full list of third-party libraries detected by Sigrid for the given customer/system(s), including lists of known vulnerabilities per library if any.
• ?vulnerable=true: the endpoint returns only those third-party libraries detected by Sigrid for the given customer/system(s) that have at least one known vulnerability.

The response format is based on the CycloneDX format for an SBOM (software bill of materials).

The endpoint that returns third-party vulnerabilities for all systems for the given customer returns an array of SBOMs, one for each system as follows:

{
    "customer" : "sig",
    "exportDate" : "2022-07-12",
    "systems" : [ {
        "customerName" : "sig",
        "systemName" : "bch",
        "sbom" : {
            ...                   // Same as the response format in the single-system case
        }
    ]
}

More information on the SBOM format and the various fields is available from the CycloneDX SBOM specification.

System metadata

System metadata can be viewed and updated using the following three endpoints:

• GET https://sigrid-says.com/rest/analysis-results/api/v1/system-metadata/{customer}/{system}: get metadata of the given system of the given customer.
• GET https://sigrid-says.com/rest/analysis-results/api/v1/system-metadata/{customer}: get metadata of all systems of the given customer.
• PATCH https://sigrid-says.com/rest/analysis-results/api/v1/system-metadata/{customer}/{system}: update metadata of the given system of the given customer.

The path parameters {customer} and {system} refer to your Sigrid account name and system ID respectively.

All properties can be null except for supplierNames and teamNames (which are always an array, but possibly empty), and isDevelopmentOnly (which is always true or false).

For the PATCH endpoint, please take the following into account:

• Only users with admin rights are allowed to change metadata.
• A PATCH endpoint requires a body as well as a Content-Type header. This is best illustrated with the example below.
• The Content-Type header needs to be set to application/merge-patch+json or application/json. The former is the official one, the latter behaves exactly the same.

$ curl 'https://sigrid-says.com/rest/analysis-results/api/v1/system-metadata/{customer}/{system}' -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -H 'Authorization: Bearer {SIGRID_CI_TOKEN}' \
    -d '{
  "supplierNames" : [ "Supplier 1" ],
  "remark" : null,
}'

This example request replaces the list of supplier names with the list consisting of one single supplier name (Supplier 1). It also removes the remark. Next to this, it leaves all metadata as-is. For instance, if the external ID before executing this request is ab12345, after this request it still is.

Metadata fields

The metadata fields are described by the following table. Note that the setting for deploymentType is used to assess impact of security findings.

The specific set of values that are allowed for each field can be found in the respective section on the system metadata fields and allowed values on the system metadata page.

System lifecycle management

Sigrid allows you to deactivate a given system.

The endpoint that enables such deactivation is:

• PATCH https://sigrid-says.com/rest/analysis-results/api/v1/systems/{customer}/{system}: enables setting the deactivation date for a system as the instant when this endpoint was called.

The request format is:

{"deactivateNow": <deactivate_now>}

where the placeholder, <deactivate_now> can assume the following values:

• {"deactivateNow": false} : when setting the boolean value deactivateNow to false, the system will be viewed by Sigrid as being active, so, setting this value to false effectively marks a system as active and re-activates a previously deactivated system;

• {"deactivateNow": true} : when this value is true, the deactivation date for the system will be set using Instant.now() representing the current instant when the endpoint was called. This effectively deactivates a system from the moment the endpoint was called;

The response format on a successful request is, as an example, for SIG’s bch system:

{
    "name": "bch",
    "deactivationDate": "2017-12-03T00:00:00Z"
}

If the request body is not in the expected format, the returned response status will be: 400 BAD REQUEST.

System objectives

Sigrid allows you to define quality objectives for a system. This helps to set some realistic and feasible expectations per system, considering both the system’s business context and its current technical state: business-critical systems using modern technologies require more ambitious targets than legacy systems.

Once you have defined quality objectives in Sigrid, you can use these targets in Sigrid CI. You can also retrieve a system’s objectives and corresponding targets via the API:

GET https://sigrid-says.com/rest/analysis-results/api/v1/objectives/{customer}/{system}/config

This end point will return the following response structure:

{
  "MAINTAINABILITY": 4.0,
  "NEW_CODE_QUALITY": 3.5,
  "OSH_MAX_SEVERITY": "LOW",
  "TEST_CODE_RATIO": 0.8
}

Contact and support

Feel free to contact SIG’s support department for any questions or issues you may have after reading this document, or when using Sigrid or Sigrid CI. Users in Europe can also contact us by phone at +31 20 314 0953.