beginscan.do

APIs

The beginscan.do call runs the full scan of the application.

Before using this API, Veracode strongly recommends that you read API Usage and Access Guidelines.

Resource URL

https://analysiscenter.veracode.com/api/5.0/beginscan.do

Parameters

app_id Integer. Required.
modules

String. A comma-separated list of top-level module IDs. The module IDs for a specific scan are available from the results of getprescanresults.do. In those results, each module is associated with an is_dependency boolean that indicates whether the module is a top-level module is_dependency=false or a dependency module is_dependency=true. You can use this parameter or, alternatively you can set the scan_all_top_level_modules, scan_selected_modules or scan_previously_selected_modules parameter to true.

scan_all_top_level_modules Boolean. Requires:
  • This parameter to be set to true, or either the scan_selected_modules or scan_previously_selected_modules to be set to true
  • Or the modules parameter to be set to a list of valid module IDs with the app_id parameter.

Veracode recommends that you use the scan_all_top_level_modules parameter if you want to ensure the scan completes even though there are non-fatal errors, such as unsupported frameworks.

The top-level modules are the binaries that are the non-third party entrypoints to the application, and all the other binaries are either third-party or the dependents of these top-level modules. In Java, the uploaded JARs, WARs, and EARs are almost always the top-level modules. In .NET and C++, the uploaded EXEs and DLLs are almost always the top-level modules, and in iOS, Ruby, PHP, and most other languages, the top-level modules are the uploaded files.

scan_selected_modules
Boolean. Requires:
  • This parameter to be set to true
  • Or either the scan_all_top_level_modules or the scan_previously_selected_modules parameter to be set to true
  • Or the modules parameter to be set to a list of valid module IDs with the app_id parameter.
When this parameter is set to true, only the modules that are selected in the Veracode Platform UI are scanned. This selection may or may not be the same as scan_all_top_level_modules, depending on whether or not any third-party modules are selected and/or any top-level modules are deselected.

scan_previously_selected_modules

Boolean.
Requires:
  • This parameter, the scan_all_top_level_modules parameter, or the scan_selected_modules parameter to be set to true
  • Or the modules parameter with the app_id parameter.
When the scan_previously_selected_modules parameter is set to true, only the modules which were selected in the previous scan are scanned. The outcome may or may not be the same as using just scan_all_top_level_modules, depending on the previous scan module selections.
sandbox_id Integer. Optional. Enter the ID of the sandbox for which you want to begin a scan.

cURL Examples

curl --compressed -u <VeracodeUsername>:<VeracodePassword>
          "https://analysiscenter.veracode.com/api/5.0/beginscan.do" -F "app_id=10886" -F
          "modules=284642,284653,284654"
curl --compressed -u <VeracodeUsername>:<VeracodePassword>
          "https://analysiscenter.veracode.com/api/5.0/beginscan.do" -F "app_id=10886" -F
          "scan_all_top_level_modules=true"
curl --compressed -u <VeracodeUsername>:<VeracodePassword>
          "https://analysiscenter.veracode.com/api/5.0/beginscan.do" -F "app_id=10886" -F
          "scan_selected_modules=true"
curl --compressed -u <VeracodeUsername>:<VeracodePassword> "https://analysiscenter.veracode.com/api/5.0/beginscan.do" -F "app_id=10886" -F "scan_previously_selected_modules=true"

cURL Results

The beginscan.do call returns the buildinfo XML document, which references the buildinfo.xsd. Additional buildinfo.xsd schema documentation is available. Use the XSD file to validate the XML data.

If no modules have been selected in the Veracode Platform and you use this API with "scan_selected_modules=true", the following is the response:

<?xml version="1.0" encoding="UTF-8"?>
<error>No modules parameter specified</error>

Java Examples

This example uses the Veracode username and password.

java -jar vosp-api-wrappers-java-<version #>.jar -vuser <VeracodeUsername> -vpassword <VeracodePassword> -action beginprescan -appid <app id> -toplevel true

This example uses the Veracode API ID and key credentials.

java -jar vosp-api-wrappers-java-<version #>.jar -vid <VeracodeApiId> -vkey <VeracodeApiKey> -action beginscan -appid <app id> -toplevel true
    

Java Results

The beginscan.do call returns the buildinfo XML document, which references the buildinfo.xsd. Additional buildinfo.xsd schema documentation is available. Use the XSD file to validate the XML data.The following is an example of the returned XML when the Veracode API ID and key credentials are supplied:

<buildinfo xmlns="https://analysiscenter.veracode.com/schema/4.0/buildinfo" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" account_id="12345" 
        app_id=<app id> build_id=<build id> buildinfo_version="1.4" xsi:schemaLocation="https://analysiscenter.veracode.com/schema/4.0/buildinfo https://analysiscenter.veracode.com/resource/4.0/buildinfo.xsd">
        
<build build_id=<build id> grace_period_expired="false" legacy_scan_engine="false" lifecycle_stage="Not Specified" platform="Not Specified" policy_compliance_status="Not Assessed" policy_name="Veracode Recommended Very High" policy_version="1" 
        results_ready="false" rules_status="Not Assessed" scan_overdue="false" submitter="JoeUser" version="4 Dec 2018 Static">
        
<analysis_unit analysis_type="Static" engine_version="131771" status="Submitted to Engine"/>
        
</build>
        
</buildinfo>