Skip to main content

beginscan.do

The beginscan.do call runs a full scan of the application. Specify the application ID and one of the four scan-type parameters.

Before using this API, Veracode strongly recommends that you read API usage and access guidelines. Ensure you access the APIs with the domain for your region.

Resource URL

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

Parameters

NameTypeDescription
app_id
Required
IntegerApplication ID.
modules
Required
StringUse either this parameter or one of: scan_all_top_level_modules, scan_selected_modules, scan_previously_selected_modules
Comma-separated list of top-level module IDs. Find the module IDs for a specific scan in the results of getprescanresults.do. In those results, each module is associated with an is_dependency Boolean, where false indicates a top-level module.
scan_all_top_level_modules
Required
BooleanUse either this parameter or one of:
  • modules
  • scan_selected_modules
  • scan_previously_selected_modules
Veracode recommends that you use the scan_all_top_level_modules parameter if you want to ensure the scan completes even if 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. 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. In iOS, Ruby, PHP, and most other languages, the top-level modules are the uploaded files.
scan_selected_modules
Required
BooleanUse either this parameter or one of:
  • modules
  • scan_all_top_level_modules
  • scan_previously_selected_modules
When this parameter is true, only the modules selected in the Veracode Platform are scanned. This selection may or may not be the same as scan_all_top_level_modules, depending on whether any third-party modules are selected and any top-level modules are deselected.
scan_previously_selected_modules
Required
BooleanUse either this parameter or one of:
  • modules
  • scan_all_top_level_modules
  • scan_selected_modules
If true, only the modules selected in the previous scan are scanned. The outcome may or may not be the same as using scan_all_top_level_modules, depending on the previous scan module selections.
sandbox_idIntegerTarget sandbox ID.

HTTPie examples

Examples use the HTTPie command-line tool.

http --auth-type=veracode_hmac "https://analysiscenter.veracode.com/api/5.0/beginscan.do" "app_id==<app id>" "scan_all_top_level_modules==true"

http --auth-type=veracode_hmac "https://analysiscenter.veracode.com/api/5.0/beginscan.do" "app_id==<app id>" "modules==<module id>,<module id>"

HTTPie results

The beginscan.do call responds with the buildinfo XML document, which references the buildinfo.xsd schema file. You can use the XSD schema file to validate the XML data.

Response for the scan_all_top_level_modules example:

<?xml version="1.0" encoding="UTF-8"?>

<buildinfo xmlns:xsi="http&#x3a;&#x2f;&#x2f;www.w3.org&#x2f;2001&#x2f;XMLSchema-instance"
xmlns="https&#x3a;&#x2f;&#x2f;analysiscenter.veracode.com&#x2f;
schema&#x2f;4.0&#x2f;buildinfo"xsi:schemaLocation="https&#x3a;&#x2f;&#x2f;
analysiscenter.veracode.com&#x2f;schema&#x2f;4.0&#x2f;buildinfo https&#x3a;&#x2f;
&#x2f;analysiscenter.veracode.com&#x2f;resource&#x2f;4.0&#x2f;buildinfo.xsd"
buildinfo_version="1.5" account_id="<account id>" app_id="<app id>" build_id="<build id">
<build version="<build name>"
build_id="<build id>" submitter="<VeracodeUsername>" platform="Not Specified" lifecycle_stage="Not Specified"
results_ready="false" policy_name="Veracode Recommended Very High" policy_version="1"
policy_compliance_status="Not Assessed" rules_status="Not Assessed" grace_period_expired="false"
scan_overdue="false" legacy_scan_engine="false" launch_date="2019-08-22T14&#x3a;27&#x3a;59-04&#x3a;00">
<analysis_unit analysis_type="Static" status="Submitted to Engine" engine_version="20190805180615"/>
</build>
</buildinfo>

Response for the modules example:

<?xml version="1.0" encoding="UTF-8"?>

<buildinfo xmlns:xsi="http&#x3a;&#x2f;&#x2f;www.w3.org&#x2f;2001&#x2f;XMLSchema-instance"
xmlns="https&#x3a;&#x2f;&#x2f;analysiscenter.veracode.com&#x2f;schema&#x2f;
4.0&#x2f;buildinfo"xsi:schemaLocation="https&#x3a;&#x2f;&#x2f;
analysiscenter.veracode.com&#x2f;schema&#x2f;4.0&#x2f;buildinfo https&#x3a;
&#x2f;&#x2f;analysiscenter.veracode.com&#x2f;resource&#x2f;4.0&#x2f;buildinfo.xsd"
buildinfo_version="1.5" account_id="<account id>" app_id="<app id>" build_id="<build id>">
<build version="22 Aug 2019 Static" build_id="build id" submitter="<VeracodeUsername>" platform="Not Specified"
lifecycle_stage="Not Specified" results_ready="false" policy_name="Veracode Recommended Very High"
policy_version="1" policy_compliance_status="Conditional Pass"
policy_updated_date="2019-08-22T14&#x3a;42&#x3a;38-04&#x3a;00" rules_status="Pass" grace_period_expired="false"
scan_overdue="false" legacy_scan_engine="false" launch_date="2019-08-22T14&#x3a;27&#x3a;59-04&#x3a;00">
<analysis_unit analysis_type="Static" status="Submitted to Engine" engine_version="20190805180615"/>
</build>
</buildinfo>

If no selected modules exist in the Veracode Platform and the call uses the scan_selected_modules parameter, the return contains:

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

Java example

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 responds with the buildinfo XML document, which references the buildinfo.xsd schema file. You can use the XSD schema file to validate the XML data.

<?xml version="1.0" encoding="UTF-8"?>

<buildinfo xmlns="https://analysiscenter.veracode.com/schema/4.0/buildinfo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
account_id="<account id>" app_id=<app id> build_id=<build id> buildinfo_version="1.5"
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>