Promote Scan REST API - v2

The Promote Scan REST API allows for an existing scan report to be promoted to a specified stage. The scan metadata generated for a specific build scan can be resubmitted for an evaluation of its components without having to rebuild the application. This new evaluation will update the most recent security and license data against your current policies.

Purging Scan Files

In the default configuration for IQ Server, only the latest scan data is retained while older scan files are automatically purged at the time of the next scan. This means that while this configuration is set only the latest scan file could be promoted.

Cleanup of scan files can be changed to purge them along with their corresponding reports.  This is required if you will need to promote any scan rather than only the latest.

Use the Configuration REST API to retain scan files for a longer period of time.

Set the purgeScanFiles property to withReports.

Example: curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"purgeScanFiles": "withReports"}' http://localhost:8070/api/v2/config

Rest Calls

The API uses the following REST methods

  • POST - to submit a request to promote a scan to another stage.
  • GET - to check the status of a promote scan request.

Promotion Workflow

  1. Get the application's internal ID
    1. which application do you want to scan
  2. Choose the source scan file
    1. the id of the specific scan that you want to promote
  3. Set your stage
    1. the stage you are promoting to
    2. this can be the same stage to do a rescan at that stage
  4. Submit the scan
    1. send the request to scan
    2. this typically will take under a minute
  5. Check the results
    1. get the scan results

Step 1 - Get the Application Internal ID

The application's internal ID is required as a path parameter for the promote request. This can be found using the application public ID, which can be seen next to the application name in the IQ Server GUI after selecting the application on the Organization & Policies tab.

Once you have the application's public ID, you can use the following GET REST resource from our Application API to get the application's internal ID.

GET /api/v2/applications?publicId={applicationPublicId}

Using the cURL command, it would look like this

curl -u admin:admin123 'http://localhost:8070/api/v2/applications?publicId=MyApplicationPublicID'

and would result in a JSON response like this

{
	"applications": [{
		"id": "cb748fb6ff8f4251b40b63edf1cc465c",
		"publicId": "MyApplicationPublicID",
		"name": "MyApplication",
		"organizationId": "81ae1fc7875441f2bec28d78d0f467ec",
		"contactUserName": null,
		"applicationTags": []
	}]
}

where the "id" is the application's internal ID.

Step 2 - Choose the Source

The promote scan request body requires either the scan ID for a specific stage or a source stage ID.

Using the Scan ID (Option 1)

You may find the Scan ID from the scan output when using any of the integrations as well as from the Report-related REST APIs.

Using the Source Stage ID (Option 2)

When using the source stage ID, the latest scan for the application will be used.  Using the same stage for both the source and target will resubmit the latest scan report for updated information.  The source stage ID can be one of the following:

  • build
  • stage-release
  • release
  • operate

Step 3 - Choose a Target Stage ID

The promote scan request body also requires the target stage ID for the scan to be promoted to. This will typically take one of the same values available to the source stage ID in step 2. Your choice will probably depend on how you are using the different stages, for which we offer some useful suggestions.

Step 4 - Submit a Promote Scan Request

At this point, we should have the following

  • An internal application ID (from step 1)
  • A scan ID OR a source stage ID (from step 2)
  • A desired target stage ID (from step 3)

which we can use to create our request. We will send this request to the following POST REST resource

POST /api/v2/evaluation/applications/{applicationInternalId}/promoteScan

with one of the following JSON bodies

{
	"scanId": "896791eb6a484d51bb570dca94dc2c67",
	"targetStageId": "stage-release"
}
{
	"sourceStageId": "build",
	"targetStageId": "stage-release"
}

Using the cURL command, it would look like one of these

curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"scanId":"896791eb6a484d51bb570dca94dc2c67","targetStageId":"stage-release"}' 'http://localhost:8070/api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/promoteScan'
curl -u admin:admin123 -X POST -H "Content-Type: application/json" -d '{"sourceStageId":"build","targetStageId":"stage-release"}' 'http://localhost:8070/api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/promoteScan'

and result in a JSON response like this

{
	"statusUrl": "api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/status/accc369749774924baa1d207494c29e1"
}

Step 5 - Check the Status

The status URL returned in step 4 can be used to check the scan promotion status, which can be one of the following

  • "PENDING"
  • "FAILED"
  • "COMPLETED"

To get this, we will send a request to the following GET REST resource

GET api/v2/evaluation/applications/{applicationInternalId}/status/{statusId}

Using the cURL command, it would look like this

curl -u admin:admin123 'http://localhost:8070/api/v2/evaluation/applications/cb748fb6ff8f4251b40b63edf1cc465c/status/accc369749774924baa1d207494c29e1'

and result in a JSON response like this if the scan promotion is pending (still in progress)

{
	"status": "PENDING"
}

or a JSON response like this with a reason message if, in a rare case, the scan promotion failed

{
	"status": "FAILED",
	"reason": "message"
}

or a JSON response like this with report links if the scan promotion completed

{
	"status": "COMPLETED",
	"reportHtmlUrl": "ui/links/application/cb748fb6ff8f4251b40b63edf1cc465c/report/affdb6b964a64f0bad2db7170c7560dc",
	"embeddableReportHtmlUrl": "ui/links/application/cb748fb6ff8f4251b40b63edf1cc465c/report/affdb6b964a64f0bad2db7170c7560dc/embeddable",
	"reportPdfUrl": "ui/links/application/cb748fb6ff8f4251b40b63edf1cc465c/report/affdb6b964a64f0bad2db7170c7560dc/pdf",
	"reportDataUrl": "api/v2/applications/cb748fb6ff8f4251b40b63edf1cc465c/reports/affdb6b964a64f0bad2db7170c7560dc"
}

Finally, when the status URL indicates a completed scan promotion status, then the various reports can be viewed via the provided links.