Trigger a Single Repository Scan Using the Create Scan Trigger API

Overview

This API enables users to trigger a manual scan for a single repository.

Getting it done

Endpoint: POST {ControllerEndpoint}/api/manual-scan

Example: POST https://localhost:3000/api/manual-scan

Authentication: Using this API requires sending an authorization header. The header's value needs to be the same as defined in an environment variable called MEND_CONTROLLER_API_SECRET.

Body: Same as a single repository in the repositories array of the scan.json file. Properties are specified in the existing documentation: Trigger repository scans manually with Mend for GitHub.com global configuration.

For example:

CODE

{
  "fullName": "myOrg/MyRepo"
}

cURL Example

CODE

curl -X POST https://localhost:3000/api/manual-scan \
 -H "Content-Type: application/json" \
 -H "Authorization: ${MEND_CONTROLLER_API_SECRET}" \
 -d '{"fullName": "myOrg/MyRepo"}'

Response:

A response when successfully triggering a scan will include the following:

CODE

{
    "status": "TRIGGERED",
    "repositoryToScan": {
        "fullName": "myOrg/MyRepo",
        "branchName": "main",
        "commitId": "653b82657cbbfa499c8569aa49ca987ddea01728",
        "commitUrl": "https://{GHE_SERVER}/myOrg/MyRepo/commit/653b82657cbbfa499c8569aa49ca987ddea01728",
        "isLastCommit": true,
        "uploadScannerLogs": false
    },
    "installationId": "44",
    "scanType": "SCA",
    "checkRunUrl": "https://{GHE_SERVER}/myOrg/MyRepo/runs/194702",
    "logCtx": "6637b02b08274361a435c56660692ca1"
}

status - TRIGGERED/SKIPPED/FAILED
repositoryToScan - Details about the scanner repository, based on the request body
installationId - GitHub application’s installation ID
scanType - SCA/SAST (SAST is not applicable in the Legacy SCA Application)
checkRunUrl - URL of the GH checkrun created by the manual scan.
logCtx - Same as the support token in the check run.

Generate logs from a manual scan

When triggering a manual scan, it is possible to save the scan logs as a single zip file to a dedicated repository. In order to review these scan logs, perform the following steps:

Create a ws-logs repository in your GitHub organization.
Add the ws-logs repository you created to the Mend integration.
Set uploadScannerLogs to true in the request body.

Example:

CODE

{
  "repositories": [
    {
      "fullName": "orgName1/repoName1",
      "branchName": "main",
      "uploadScannerLogs": true
    }
  ]
}

NOTE:

Name of the zip file: scanner_logs_{SCAN_TOKEN}.zip
If the ws-logs repository does not exist, the manual scan will not run and a check run will explain why:

Reference

scan.json Parameters (`repositories`)

Parameter	Type	Description
fullName	String	Required. Provide a list of specific repositories to trigger the manual scan on. For example: CODE `"fullName": "orgName1/repoName1"`
branchName	String	Optional. Default Value: `Your GitHub Enterprise "default" branch`. Specify the branch(es) to be scanned.
scanType*	String	Optional. By default, the scan.json file triggers manual SCA scans. Possible values are: `"sca"` or `"sast"` CODE `"scanType": "sast"`
uploadScannerLogs	Boolean	Optional. Default Value: `false`. The available parameter values are: `true` - Save the logs from the triggered scan as a single zip folder in the dedicated `ws-logs` repository `false` - No logs are saved for the triggered scan

* The “sast” scanType is not applicable in the Legacy SCA Application.

Troubleshooting

If the manual scan failed to be triggered, the response will contain an error message, for example:

CODE

{
    "status": "SKIPPED",
    "repositoryToScan": {
        "fullName": "myRepo",
        "isLastCommit": false,
        "uploadScannerLogs": false
    },
    "errorMessage": "Full repository name was in an unsupported format. Needs to be {ownerName}/{repoName}",
    "scanType": "",
    "logCtx": "9b51a025a9ea4616bc536e1755254d23"
}

Some other possible errors:

Invalid request object - incorrect JSON format or missing fullName
Full repository name was in an unsupported format. Needs to be {ownerName}/{repoName}
Repository does not exist or is not a part of the integration
Failed to retrieve global/repo settings
uploadScannerLogs set to true, but the whitesource-config/ws-logs repository does not exist, or is not a part of the integration
Failed to create check run
No API secret configured
No authorization header found
Invalid authorization header

Overview

Getting it done

cURL Example

Generate logs from a manual scan

Reference

scan.json Parameters (repositories)

Troubleshooting

scan.json Parameters (`repositories`)