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 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:

Available end points

Maintainability ratings

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

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

Example response ```json { "customer": "my-sigrid-account-name", "systems": [ { "system": "my-system-name", "customer": "my-sigrid-account-name", "maintainability": 5.24, "maintainabilityDate": "2022-02-08", "allRatings": [ { "maintainability": 4.96, "maintainabilityDate": "2022-02-06" } ] } ] } ```

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:

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

Example response ```json [ { "id": "00000000-0000-0000-0000-0000005d9c1e", "href": "https://sigrid-says.com/my-sigrid-account/my-system/-/sigrid-security/00000000-0000-0000-0000-0000005d9c1e", "firstSeenAnalysisDate": "2019-09-18", "lastSeenAnalysisDate": "2019-09-18", "firstSeenSnapshotDate": "2019-05-04", "lastSeenSnapshotDate": "2019-05-04", "filePath": "helloworld.py", "startLine": 12, "endLine": 23, "component": "frontend", "type": "", "cweId": "CWE-12345", "severity": "LOW", "impact": "LOW", "exploitability": "LOW", "severityScore": 2.0, "impactScore": 1.2, "exploitabilityScore": 0.8, "status": "FALSE_POSITIVE", "remark": "Test test test", "toolName": null, "isManualFinding": true, "isSeverityOverridden": true, "weaknessIds": [ "CWE-12345" ] } ] ```

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:

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:

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

Example response for a single system ```json { "bomFormat": "CycloneDX", "specVersion": "1.4", "version": 1, "metadata": { "timestamp": "2022-03-17T09:58:34Z", "tools": [ { "vendor": "Software Improvement Group", "name": "Sigrid", "externalReferences": [ { "type": "other", "url": "https://sigrid-says.com/my-sigrid-account-name/my-system-id/-/open-source-health" } ] } ] }, "components": [ { "group": "", "name": "yui", "version": "2.8.0r4", "purl": "pkg:npm/yui@2.8.0r4", "type": "library", "bom-ref": "pkg:npm/yui@2.8.0r4" } ], "vulnerabilities": [ { "bom-ref": "pkg:npm/yui@2.8.0r4", "id": "CVE-2010-4710", "ratings": [ { "score": 4.3, "severity": "medium", "method": "CVSSv3" } ], "description": "Cross-site Scripting" } ] } ```

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:

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

Example system-level `GET` and `PATCH` response format The response format of both system-level endpoints (`GET` and `PATCH`) is as follows: ```json { "displayName" : "User-friendly system name", "divisionName" : "Division name", "teamNames" : [ "My Team" ], "supplierNames" : [ "Supplier 1", "Supplier 2" ], "lifecyclePhase" : "EOL", "inProductionSince" : 2012, "businessCriticality" : "HIGH", "targetIndustry" : "ICD9530", "deploymentType" : "PUBLIC_FACING", "applicationType" : "ANALYTICAL", "softwareDistributionStrategy": "DISTRIBUTED", "remark" : "A remark", "externalID" : "ab12345", "isDevelopmentOnly" : false, "technologyCategory": "MODERN_GENERAL_PURPOSE" } ```
Example customer-level response The response format of the customer-level endpoint (`GET https://sigrid-says.com/rest/analysis-results/api/v1/system-metadata/{customer}`) is as follows: ```json [ { "customerName": "foo", "systemName": "bar", "displayName" : "User-friendly system name", "divisionName" : "Division name", "teamNames" : [ "My Team" ], "supplierNames" : [ "Supplier 1", "Supplier 2" ], "lifecyclePhase" : "EOL", "inProductionSince" : 2012, "businessCriticality" : "HIGH", "targetIndustry" : "ICD9530", "deploymentType" : "PUBLIC_FACING", "applicationType" : "ANALYTICAL", "softwareDistributionStrategy": "DISTRIBUTED", "remark" : "A remark", "externalID" : "ab12345", "isDevelopmentOnly" : false, "technologyCategory": "MODERN_GENERAL_PURPOSE" } ] ```

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:

$ 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.

Path Type Description
displayName String The display name of the system. Must be between 0 and 60 characters. Can contain blanks: true
divisionName String The name of the division this system belongs to. Must be between 0 and 60 characters. Can contain blanks: true
supplierNames Array Array of the names of the suppliers for this system
inProductionSince Number The year the system went into production. Cannot be later than the current year, must be at least 1960
businessCriticality String Importance of the system in terms of the effects of it not being available on the user’s business. Must match any of the following values (case-sensitive): CRITICAL, HIGH, MEDIUM, LOW
lifecyclePhase String The phase of its lifecycle the system is in. Must be an industry identifier from the table of lifecycle phase identifiers below (case-sensitive)
targetIndustry String The industry in which the system is normally used. Must be an industry identifier from the table of target industry identifiers below (case-sensitive)
deploymentType String The way in which the system is typically deployed. Must be an industry identifier from the table of deployment types below (case-sensitive)
applicationType String The type of the system. Must be an industry identifier from the table of application types below (case-sensitive)
softwareDistributionStrategy String The type of the software distribution strategy. Must be one of the distribution strategy identifiers from the table below (case-sensitive)
isDevelopmentOnly Boolean If true, the system is not shown as part of customer’s portfolio, in the UI this is known as the “Excluded from dashboards” toggle
remark String Remark(s) about the system as (possibly empty) free-format text. Must be between 0 and 300 characters. Can contain blanks: true
externalID String Allow customers to record an external identifier for a system. free-format text. Must be between 0 and 60 characters. Can contain blanks: true

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:

The request format is:

{"deactivateNow": <deactivate_now>}

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

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.