Trigger a Single Repository Scan Using the Create Scan Trigger API

Overview

The API in this document 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

Method A - Secret-based (Default)

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

Method B - RBAC-based

Set the MEND_CONTROLLER_API_USE_RBAC environment variable to true (default is false) to switch from the secret-based authentication method to role-based access authentication. This will allow for increased control and auditing of scan triggering events.

When active, only users with the “Admin” or “Scan Manager” role in the Mend AppSec Platform can use the manual-scan API to trigger repository scans.

Note: In the Legacy SCA application, the required roles are Admin or Product Integrator.

This authentication method requires the following headers:

Authorization - The Mend Platform user’s API key (generated from the user profile menu)
user-email - The Mend Platform user’s email
org-token - The Mend Platform Org Token
If the user does not belong to a group that has the “Admin” or “Scan Manager” role, they will receive a 403.

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 A

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

cURL Example B

CODE

curl -X POST https://localhost:3000/api/manual-scan \
 -H "Content-Type: application/json" \
 -H "Authorization: ${MEND_CONTROLLER_API_USE_RBAC}" \
 -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

Endpoint

Authentication

Method A - Secret-based (Default)

Method B - RBAC-based

Body

cURL Example A

cURL Example B

Generate Logs from a Manual Scan

Reference

scan.json Parameters (repositories)

Troubleshooting

scan.json Parameters (`repositories`)