Jenkins

The Veracode Jenkins Plugin integrates with your Jenkins development pipelines to seamlessly automate the operations for building, uploading, and scanning your application code. You can run Static Analysis and Dynamic Analysis scans, and review the results from these scans and SCA scans.

Starting with version 20.6.10.0 of the Veracode Jenkins Plugin, Veracode distributes the plugin as open source under an MIT license. You can download the plugin source code from GitHub. On the Jenkins Marketplace and in the Jenkins Plugin Manager, the plugin name is Veracode Scan.

The Veracode Jenkins Plugin supports the Jenkins pipeline functionality and the ability to bind your Veracode API credentials to build environment variables.

The Veracode Jenkins Plugin contains the Java API wrapper and uses the uploadandscan composite action from the wrapper to upload your code to Veracode for scanning. By default, the uploadandscan composite action is set to autoscan, which starts the scan automatically after the prescan. However, the prescan must meet the Veracode Static Analysis scanning requirements. Before running your automation, perform a prescan verification. Since the uploadandscan composite action runs through the Java API wrapper, the wrapper returns a non-zero integer exit code when a command fails. These are the exit codes:

• 1 = Invalid input
• 2 = API internal error
• 3 = Incorrect file format of the CSV file referred to in the -inputfilepath parameter
• 4 = The scan did not pass policy compliance. This code only applies to an uploadandscan composite action that specifies the scantimeout parameter.

The Veracode API wrappers return errors for missing required parameters and unrecognized parameters. They do not return errors on defined API parameters that are not valid for use with the specified action. For example, if an API wrapper takes sandboxid as an optional parameter, and you supply sandboxname in error, the wrapper ignores sandboxname and executes. You can verify the list of valid parameters in the console.

Supported versions

Veracode has tested the following versions, but the integration might work with other versions.

Jenkins 2.440.1 - 2.504.1

Supported libraries

Veracode has tested the following version, but the integration might work with other versions.

Java 11

Prerequisites

Before you can install and use the Veracode Jenkins Plugin, you must have:

• A supported version of Jenkins. Although there are additional Veracode Jenkins plugins available from the Jenkins server list of available plugins, Veracode only supports the Veracode-developed plugin available here.
• Java 11.
• Installed any dependencies on the Jenkins server. The Veracode Jenkins Plugin has a dependency on numerous plugins including the Jenkins Structs plugin and Jenkins Symbol Annotation plugin, as do most default installations of Jenkins. Newer versions of Jenkins automatically resolve these dependencies at the time of installation. If this fails, you must manually install the dependencies.
• Ensured the Jenkins server has Internet connectivity.
• Packaged the application code you plan to upload to Veracode for scanning to include the required debug symbols, as described in the packaging requirements. If you have a .NET application, you can use the Visual Studio extension to prepare your application. You can also automate the preparation of a .NET application by precompiling it with MSBUILD.
• Generated Veracode API credentials.
• Ensured that all required Veracode IP addresses for the Veracode APIs and integrations are on the allowlist for your organization. The integration uses these addresses to authenticate with Veracode. To update your allowlist, you might need to contact your IT team.
• You have compiled and packaged your application source files according to the packaging requirements.

Starting with version 20.6.10.0 of the Veracode Jenkins Plugin, Veracode distributes the plugin as open source under an MIT license. You can download the plugin source code from GitHub. On the Jenkins Marketplace and in the Jenkins Plugin Manager, the plugin name is Veracode Scan.

Permissions

You must have one of these Veracode accounts:

• A user account with these roles:

  • Creator or Security Lead role to be able to create application profiles, and upload and scan applications
  • Submitter role to create a new scan for an existing application and upload and scan these applications
  • Reviewer role to check scan completion

• An API service account with these roles:

  • Upload API to create application profiles, create sandboxes, and upload and scan applications
  • Upload API - Submit only to submit scans
  • Results API to check scan completion

Set up the Jenkins plugin

Download and install or upgrade the Veracode Jenkins Plugin using the Plugin Manager from within Jenkins or from the Jenkins Marketplace. To protect your Veracode credentials in Jenkins, we recommend installing the Credentials Binding plugin and binding your credentials so that they aren't visible in Jenkins.

Install the Jenkins plugin

Starting with version 20.6.10.0 of the Veracode Jenkins Plugin, Veracode distributes the plugin as open source under an MIT license. You can download the plugin source code from GitHub.

note

If you are currently running a Veracode Jenkins Plugin that is earlier than version 20.6.10.0, do not uninstall or disable the plugin before installing the new plugin. The installation imports the configuration settings from the existing plugin to the new plugin. After completing the installation and restarting Jenkins, you must uninstall the earlier plugin version and restart Jenkins a second time.

Before you begin:

Ensure you meet the prerequisites.

To complete this task:

1. Open a browser and log in to Jenkins.
2. Select Manage Jenkins > Manage Plugins > Available tab.
3. In the Filter field, enter veracode to show only the available Veracode plugins.
4. Select the Veracode Scan checkbox. On the Jenkins Marketplace and in the Jenkins Plugin Manager, the plugin name is Veracode Scan.
5. At the bottom of the page, select Download now and install after restart.
6. On the Installing Plugins/Upgrades page, select the Restart Jenkins when installation is complete and no jobs are running checkbox.
7. Select Manage Jenkins > Manage Plugins > Installed tab.
8. Confirm that the Veracode Scan plugin appears in the list of installed plugins. If a plugin earlier than version 20.6.10.0 is installed, the earlier version, which has the name Veracode Jenkins Plugin, is also listed on the Installed tab.
9. Optionally, right-click the Veracode Scan link and select to open it in a new tab or window. The Veracode website site opens in the new tab or window, which confirms that you are running the official Veracode plugin.
10. Uninstall any Veracode Jenkins Plugin earlier than version 20.6.10.0. Then, restart Jenkins.

Configure the Jenkins plugin

There are required and optional settings you can configure before using the plugin to scan your code. After installing the Veracode Jenkins Plugin, there are required and optional settings you can configure before using the plugin to scan your code.

Before you begin:

Ensure you have installed the Jenkins Plugin.

To complete this task:

1. Open a browser window and sign in to your Jenkins server.

2. Select Manage Jenkins > Configure System and scroll down to the Veracode Jenkins Plugin section.

3. In the Veracode User Credentials fields, enter your Veracode API credentials.

   If you are using credentials binding to protect your credentials, you can enter a placeholder, which the Credentials Binding plugin uses later. Configure this placeholder if you intend to use the binding plugin for freestyle, Domain Specific Language (DSL), or pipeline jobs that require credentials management. This placeholder must have a leading dollar sign and be unique. For example, Veracode recommends $veracode_id and $veracode_key.

4. To stop the build job if the Veracode task encounters a problem or the application does not pass a security policy, select Fail Job. If you select this option, you can also select the option under it to have Jenkins show the job status as Unstable.

   Several conditions could cause a scan to fail, including network timeouts, invalid credentials, or the application exceeds the maximum file size during upload. The Fail Job option allows you to stop a build if, during an upload and scan, an SCA or Static Analysis fails a specified policy evaluation. You can review the details of a failed job in Jenkins. The Fail Job option can save you time and enable you to quickly troubleshoot build issues that are related to your Veracode scan.

5. Optionally, in the Copy Output Remote Files to Controller section:

   note

   Veracode does not recommend this option.

   • If you want to build and upload code to Veracode from a remote machine, ensure the Copy Output Remote Files to Controller option is cleared. Jenkins uses the term node to refer to a remote machine. If you do not copy the files to controller, the Jenkins plugin copies the Java API wrapper JAR files to the veracode-jenkins-plugin directory in the remote root directory. The Java wrapper CLI executes from the remote machine to upload and scan the output code that a build generates.
   • If you build only on a remote machine, and copy the output files from the remote machine to the controller for uploading to Veracode, select the Copy Output Remote Files to Controller option.

6. In the Default Values field, select these Jenkins server environment-type variables to apply them to all Jenkins jobs:

   • $projectname: changes the new Veracode application name to the Jenkins server project name. You can overwrite this value within the individual Jenkins project settings page in the Veracode options section.
   • Jenkins server workspace path and IP address.
   • $buildnumber: changes to the Veracode default scan name.

7. Optionally, select the Run in debug mode option to collect detailed information about Veracode scans. The plugin stores this information in the console log of each individual Jenkins project. Veracode recommends you select this option.

8. If you intend to connect using a proxy, select the Connect using proxy option. Then, provide the specific host, port, username and password settings for global use in Jenkins.

Install the Credentials Binding plugin

Install the Credentials Binding plugin in Jenkins to store and access your Veracode API credentials securely. You use the plugin to bind your credentials to environment variables that you add to your build script. Binding prevents your credentials from appearing in the Jenkins interface.

Before you begin:

Ensure you have installed the Jenkins Plugin.

To complete this task:

1. In Jenkins, select Manage Plugins.
2. Select the Available tab.
3. Select the Credentials Binding checkbox.
4. Select Install without restart or Download now and install after restart.
5. Optionally, bind your credentials in a Jenkins pipeline.

Bind your credentials

After binding your Veracode API credentials to the environment variables, Jenkins secretly uses the credentials saved in its credentials store. Only the bound environment variables appear in the Jenkins interface and logs instead of your Veracode API credentials. You generate a script containing the bound environment variables and add this script to your Jenkins pipeline script.

Before you begin:

Ensure you have installed the Jenkins plugin and the Credentials Binding plugin from the Jenkins Plugin Index.

To complete this task:

1. In Jenkins, go to your pipeline project.

2. Select Pipeline Syntax to open the Snippet Generator.

3. From the Sample Step dropdown menu, select withCredentials: Bind credentials to variables.

4. In the Bindings section, select Add > Username and password (separated). The Username and password (separated) section opens.

5. In the Username Variable and Password Variable fields, enter username and password variables. Your Veracode API credentials bind to these variables at runtime.

6. Do one of the following:

   • If the Veracode API credentials to which you want to bind the specified username and password variables are in the Jenkins credentials store, select them from the Credentials dropdown menu. Then, continue to Step 7.

   • If the Veracode API credentials to which you want to bind the specified username and password variables are not in the Jenkins credentials store, you must add the credentials:

     a. To the right of the Credentials dropdown menu, select Add > Jenkins to open the Jenkins Credentials Provider window.

     b. In the Username field, enter your API ID. In the Password field, enter your API key.

     c. Optionally, enter values for the ID and Description fields.

     d. Select Add to add the credentials to the Jenkins credentials store.

     e. From the Credentials dropdown menu, select the credentials you added.

7. Select Generate Pipeline Script. In the generated script, which is Apache Groovy code, the withCredentials step contains the username variable, password variable, and, if specified, the credentials ID.

8. Copy the entire withCredentials step and add it to your Jenkins pipeline script for Static Analysis or Dynamic Analysis.

Add Static Analysis scanning to Jenkins

You can configure a Jenkins build job in a freestyle or pipeline project for uploading binaries to Veracode for Static Analysis. You continue to use your same build process, but you add a post-build action for the Veracode parameters.

Before you begin:

Ensure you have installed the Jenkins Plugin.

note

The Veracode Jenkins Plugin only supports freestyle and pipeline projects.

To complete this task:

1. In the Jenkins left menu, select New Item.

2. In the Enter an Item name field, enter a name for this new scan that you want to submit to Veracode.

3. Select one of these options:

   • If you want to create a new project using the standard projects types provided by Jenkins, select one of the available project types listed.
   • If you want to create a new project based on an existing project, in the Copy from input box, enter the name of an existing project you want to use as the model when you create the new item.

4. Select OK.

5. Select Advanced... to expand the Advanced Project Options.

6. In the Post-build Actions section, from the Add post-build action dropdown menu, select Upload and Scan with Veracode.

7. In the Application Name field, enter the name of the application you want Veracode to scan.

   To use the Jenkins project name as the application name, enter $projectname.

   note

   Do not wrap the application name in quotation marks.

8. If the application does not already exist in the Veracode Platform, but is a new application you want Jenkins to create, select the Create Application checkbox.

   note

   If you select this option, you must also provide the name of the team that is associated with the application.

9. From the Business Criticality dropdown menu, select the level of criticality of this application.

10. In the Sandbox Name field, enter the name of the sandbox in which you want to run the scan as a sandbox scan.

11. If the sandbox does not already exist in the Veracode Platform, but is a new sandbox you want Jenkins to create, select the Create Sandbox checkbox.

12. In the Scan Name field, enter a name for the static scan you want to submit to the Veracode Platform for this application.

    To use the Jenkins project build number as the scan name, enter $buildnumber. To use the date and time of the Jenkins build job submission as the scan name, enter $timestamp.

13. In the Upload field, you can include and exclude filepath patterns of the files you want to upload and scan.

    Use a comma-separated list of ant-style include patterns relative to the job workspace project name. The project name is the one you entered in the Project name field. For a description of the ant-style pattern format, see https://ant.apache.org/manual/dirtasks.html.

    note

    The Upload field does not accept variable names.

14. In the Scan field, you can include and exclude filename patterns of the uploaded files you want to scan as top-level modules.

    Use a comma-separated list of ant-style include patterns with only the filenames of the files you have uploaded, not the filepaths.

    note

    The Scan field does not accept variable names.

15. You can rename the files you are uploading by entering the filename pattern of the uploaded files that you want to rename and clicking Save As. You must also enter the replacement filename pattern that represents the groups that the filename pattern captured.

16. Select the Wait for scan to complete checkbox if you want the Jenkins job to wait for the Veracode scan to complete.

    Enter the maximum time in minutes that you want the Jenkins job to wait before skipping the Upload and Scan with Veracode action. Allow enough time for a typical scan of your application to complete. A Veracode policy scan fails, regardless of whether it completes or not, if it does not meet the requirements of the associated policy.

17. For Delete Incomplete Scan, select an option for automatically deleting an incomplete scan, based on its status, to allow the uploadandscan action to continue processing. Default is 0, which specifies to not delete an incomplete scan.

    To delete scans, you must have a user account with the Delete Scans role or an API service account with the Upload and Scan role.

18. If you provided Veracode credentials on the Manage Jenkins page and want to use them for this project, select the Use global Veracode API ID and key checkbox.

19. In the Veracode Credentials section, enter your Veracode API credentials. If your credentials are bound to environment variables, enter the environment variables for the API ID and key.

20. Select Apply and Save.

21. Go to the Jenkins project and select Build Now from the left menu.

Next steps:

You can monitor the progress of the Veracode job by selecting the build from the Jenkins left menu and clicking Console Output.

Add a job for Static Analysis scanning

You can add the Veracode Jenkins Plugin to a pipeline job to include Static Analysis in your build pipeline.

Before you begin:

• Ensure you have installed the Jenkins plugin.
• If you bound your Veracode API credentials using the Jenkins Credentials Binding plugin, ensure you have generated the script containing the environment variables for your credentials.

To complete this task:

1. In Jenkins, select Pipeline Syntax to display the Snippet Generator page.

2. From the Sample Step dropdown menu, select veracode: Upload and Scan with Veracode Pipeline.

3. In the Application Name field, enter the name of the Veracode application profile that you want to scan. If you want to create a new application profile using the provided application name, select the Create Application checkbox.

   note

   The name of the application profile must not contain quotation marks.

4. In the Team Name field, enter a comma-separated list of team names to which to assign the application.

5. From the Business Criticality dropdown menu, select the level of criticality of this application.

6. If you want to run the scan from a development sandbox, in the Sandbox Name field, enter the sandbox name. If the sandbox does not already exist, select the Create Sandbox checkbox to create a sandbox using the name you entered.

7. In the Scan Name field, enter a name for the scan.

8. In the Upload section, enter filepath patterns to specify which files to include or exclude for uploading to Veracode for scanning. Use a comma-separated list of ant-style include patterns relative to the job workspace directory.

9. In the Scan section, enter filename patterns of the uploaded files you want to scan as top-level modules. Use a comma-separated list to specify the filenames in ant-style format. As this is a flat file structure, you do not need to specify folder paths.

10. Optionally, in the Save As section, enter the filename pattern of the files for upload and the replacement filename patterns to which to rename the uploaded files. You can leave these fields blank to not rename the files.

11. Optionally, select the Wait for scan to complete checkbox to open the Maximum Wait Time field. Enter the number of minutes that you want the Jenkins job to wait for the scan to complete and pass policy. If the scan does not complete or pass policy within the specified time, the scan continues in the Veracode Platform, but the Jenkins build fails. The default timeout is 60 minutes.

12. For Delete Incomplete Scan, select an option for automatically deleting an incomplete scan, based on its status, to allow the uploadandscan action to continue processing. Default is 0, which specifies to not delete an incomplete scan.

13. Enter your Veracode API credentials. If your credentials are bound to environment variables using the Credentials Binding plugin, enter the username variable and password variable.

14. If you want the entire Jenkins job to fail if the Upload and Scan with Veracode action fails, select the Fail Build checkbox.

note

If you do not select the Fail Build checkbox, Jenkins does not notify you if the action fails but the job completes.

15. Optionally, if you are using a remote build machine, called a node, and need to copy your binaries to a Jenkins controller server before uploading to Veracode for scanning, select the Copy Output Remote Files to Controller checkbox.

    If you do not select this checkbox, the plugin uploads your binaries directly from the remote machine to Veracode. On the remote machine, the plugin first copies the Veracode Java API wrapper JAR files to the temporary directory {root}/veracode-jenkins-plugin. Then, the Java API wrapper CLI executes on the remote machine to upload the binaries to Veracode.

16. Select the Debug checkbox to display troubleshooting information in the console output window.

17. Select the Connect using proxy checkbox, if connecting to Veracode through a proxy host. Then, enter the proxy host information.

18. Select Generate Pipeline Script.

    The generated script, which is Apache Groovy code, contains the veracode step. This step contains details about your application and the Veracode scan settings.

19. Copy the entire veracode script step and add it to your pipeline job.

    You are done. You can now run your pipeline build. If you are using bound credentials, continue to the next step.

20. Add the entire withCredentials script step to the beginning of your pipeline script.

21. Replace the value for the vid parameter with the value from the usernameVariable parameter.

22. Place the veracode step inside the withCredentials step.

23. Replace the value for the vkey parameter with the value from the passwordVariable parameter.

    This code example shows two complete pipeline scripts with bound Veracode API credentials. The veracode step is inside the withCredentials step. The second, commented-out example includes the optional timeout parameter. For parameter descriptions, see plugin script parameters

echo 'Veracode scanning'
    withCredentials([ usernamePassword (
        credentialsId: 'veracode_login', usernameVariable: 'VERACODE_API_ID', passwordVariable: 'VERACODE_API_KEY') ]) {
            // fire-and-forget
            veracode applicationName: "${VERACODE_APP_NAME}", criticality: 'VeryHigh', debug: true, fileNamePattern: '', pHost: '', pPassword: '', pUser: '', replacementPattern: '', sandboxName: '', scanExcludesPattern: '', scanIncludesPattern: '', scanName: "${BUILD_TAG}", uploadExcludesPattern: '', uploadIncludesPattern: 'target/verademo.war', vid: VERACODE_API_ID, vkey: VERACODE_API_KEY
 
           // wait for scan to complete (includes timeout parameter)
           // veracode applicationName: "${VERACODE_APP_NAME}", criticality: 'VeryHigh', debug: true, timeout: 20, fileNamePattern: '', pHost: '', pPassword: '', pUser: '', replacementPattern: '', sandboxName: '', scanExcludesPattern: '', scanIncludesPattern: '', scanName: "${BUILD_TAG}", uploadExcludesPattern: '', uploadIncludesPattern: 'target/verademo.war', vid: VERACODE_API_ID, vkey: VERACODE_API_KEY
 }

You are done. You can now run your pipeline build using bound Veracode API credentials.

Review Static Analysis and SCA results

You can choose to display the results of a Veracode Static Analysis and SCA scan in Jenkins for freestyle or pipeline jobs.

If scans do not complete due to errors, the Jenkins build summary states that results are unavailable. The console output lists more information, including the cause of the error.

Before you begin:

• Ensure you have installed the Jenkins Plugin.
• You have configured a Jenkins job for Static Analysis with the Wait for scan to complete checkbox selected and run a Veracode scan. If you configure the Jenkins job to scan with Veracode and wait for the results, the results display on the build summary page and indicate the policy compliance status of the scan.
• In controller/agent Jenkins environments, the controller returns the Veracode scan results, so you must ensure your controller can access Veracode. If there is no access to Veracode, the Jenkins build status is not affected.
• For Software Composition Analysis (SCA) results, you have configured the organization associated with the Veracode Platform account to provide SCA results to Jenkins.

To complete this task:

1. Sign in to your Jenkins freestyle or pipeline project.

2. Select the Veracode link at the left or in the main summary to see the results:

   Static Analysis results:

   • Overall policy compliance status
     • Policy name
     • Policy rules:
       • Veracode Level
       • Static Scan Requirement
       • Static Score
     • Link to the Executive Summary page in the Veracode Platform
     • Flaw count table: derived from the Veracode Detailed Report
     • Flaw trend chart: only against successful Jenkins builds

   SCA results:

   • Number of blocklisted SCA components
   • Highest found Common Vulnerability Scoring System (CVSS) score
   • SCA vulnerability count table
   • List of components added since the previous build

Add Dynamic Analysis scanning to Jenkins

You can configure post-build actions, or steps, to have the Veracode Jenkins Plugin perform a Dynamic Analysis of your application and generate a report of the analysis results.

You configure Dynamic Analysis to run as a post-build action in freestyle builds and as a build step in pipeline builds. The post-build actions and steps require your Veracode API credentials.

note

The Veracode Jenkins Plugin only supports freestyle and pipeline projects.

Freestyle and pipeline builds

For freestyle builds, complete the following tasks:

• Configure global credentials for freestyle builds
• Configure a post-build action to resubmit scans in freestyle builds
• Configure a post-build action to review scan results in freestyle builds

For pipeline builds, complete the following tasks:

• Configure a step to resubmit scans during in pipeline builds
• Configure a step to review scan results in pipeline builds

Create global credentials for freestyle builds

You can configure the Veracode Jenkins Plugin to use global Veracode API credentials when running a Dynamic Analysis as a post-build action in freestyle builds.

Before you begin:

If you are not using global credentials, continue to Add a post-build action to resubmit scans in freestyle builds and enter your credentials in the post-build action.

To complete this task:

1. In Jenkins, select Manage Jenkins > Configure System.
2. Scroll down to the Veracode Jenkins Plugin section.
3. Enter your Veracode API credentials.
4. If you are using a proxy host to connect to the Veracode Platform, select Connect using proxy and enter the proxy host information.
5. Select Run in debug mode to collect detailed information about the analysis. The plugin stores the information in the console log of each Jenkins project.
6. Select Apply to save your changes.

Add a post-build action to resubmit Dynamic Analysis scans in freestyle builds

You can add a post-build action to your Jenkins freestyle project that submits your application for Dynamic Analysis.

To complete this task:

1. In your Jenkins freestyle project, go to the Post-build Actions section.

2. From the Add post-build action dropdown menu, select Resubmit Veracode Dynamic Analysis.

3. In the Analysis Name field enter the name of a Dynamic Analysis that already exists in the Veracode Platform.

4. Enter the maximum duration, in hours, that you want the analysis to run.

5. Select whether to fail the Jenkins build if the analysis fails.

6. Select whether to use global credentials using your Veracode API credentials. If you select to use global credentials, continue to step 8.

   note

   If you select to use global credentials, but have not configured them using the API service account credentials, the build fails.

7. In the Veracode Credentials section, enter your Veracode API credentials.

8. Select Apply to save your changes.

Add a post-build action to review Dynamic Analysis scan results in freestyle builds

You can add a post-build action to your Jenkins freestyle project to get scan results from a Dynamic Analysis of your application.

Before you begin:

Ensure you have linked an existing Dynamic Analysis to an application profile with a Veracode policy. If the Dynamic Analysis is linked to multiple URLs, you cannot view the analysis results in Jenkins. Therefore, you can either unlink URLs until there is only one linked to the Dynamic Analysis, or you can view the results in the Veracode Platform.

To complete this task:

1. In your Jenkins freestyle project, go to the Post-build Actions section.

2. From the Add post-build action dropdown menu, select Review Veracode Dynamic Analysis Results.

3. Enter the number of hours to wait for analysis results to be available.

4. Select whether to fail the Jenkins build if the analysis violates a Veracode policy.

5. Select whether to use global Veracode API credentials. If you select to use global credentials, continue to step 7.

   note

   If you select to use global credentials, but have not configured them using the API service account credentials, the build fails.

6. In the Veracode Credentials section, enter your Veracode API credentials.

7. Select Apply to save your changes.

8. Go back to the main page of your freestyle project.

9. Select Build Now and wait for the build and analysis to complete successfully.

10. Under Build History, select a build number.

11. Select Veracode Dynamic Analysis to review the results of the analysis.

In the results, you can select the View Executive Summary link to view additional information in the Veracode Platform.

Add a step to resubmit a Dynamic Analysis scan in pipeline builds

You can add a step to your Jenkins pipeline project for performing a Dynamic Analysis of your application.

Before you begin:

For added security, we recommend using the Credentials Binding plugin to manage your credentials.

Veracode recommends using a snippet generator to create code snippets for routinely repeated steps in your build/test/deploy pipeline.

To complete this task:

1. In your Jenkins pipeline project, select Configure.

2. Scroll down to the Pipeline section.

3. Select Pipeline Syntax to display the Snippet Generator page.

4. From the Sample Step dropdown menu, select veracodeDynamicAnalysisResubmit: Resubmit Veracode Dynamic Analysis.

5. In the Analysis Name field, enter the name of a Dynamic Analysis that already exists in the Veracode Platform.

6. Enter the maximum duration, in hours, that you want the analysis to run.

7. Select whether to fail the Jenkins build if the analysis fails.

8. Enter your Veracode API credentials. If your Veracode API credentials are bound to environment variables, enter the environment variables for the API ID and API key.

9. Select Run in debug mode to collect detailed information about the analysis. The plugin stores the information in the console log of each Jenkins project.

10. If you are using a proxy host to connect to the Veracode Platform, select Connect using proxy and enter the proxy host information.

11. Select Generate Pipeline Script to generate a script using the selected settings.

    This example shows a script using bound credentials. The values for the Veracode API user ID (vid) and API key (vkey) are the environment variables that map to the actual credentials in the Jenkins credential store.

    veracodeDynamicAnalysisResubmit analysisName: 'Dynamic Analysis Test 2', debug: true, failBuildAsScanFailed: true, maximumDuration: 72, vid: 'VERACODE_API_ID', vkey: 'VERACODE_API_KEY'

12. Copy the pipeline script, which you then add to your pipeline project.

13. Go back to the main page of your pipeline project.

14. Select Configure > Pipeline.

15. In the Pipeline section, paste the generated script into the Script field.

16. Delete the quotes from around the values for vid and vkey.

17. Select Save.

Add a step to review scan results in pipeline builds

You can add a step to your Jenkins pipeline project to get scan results from a Dynamic Analysis of your application.

Before you begin:

• For added security, we highly recommend using the Credentials Binding plugin to manage your credentials. You use the plugin to bind your credentials to environment variables, which prevents your credentials from appearing in the Jenkins interface.
• You must have already linked an existing Dynamic Analysis to an application profile with a Veracode policy. See Manually link Dynamic Analysis results to an application profile. If the Dynamic Analysis is linked to multiple URLs, you cannot view the analysis results in Jenkins. Therefore, you can either unlink URLs until there is only one linked to the Dynamic Analysis, or you can view the results in the Veracode Platform.

Veracode recommends using a snippet generator to create code snippets for routinely repeated steps in your build/test/deploy pipeline.

To complete this task:

1. In your Jenkins pipeline project, select Configure > Pipeline.

2. Select Pipeline Syntax to display the Snippet Generator page.

3. From the Sample Step dropdown menu, select veracodeDynamicAnalysisReview: Review Veracode Dynamic Analysis Results.

4. Enter the number of hours to wait for analysis results to be available.

5. Select whether to fail the Jenkins build if the analysis violates a linked Veracode policy.

6. Enter your API credentials. If your Veracode API credentials are bound to environment variables, enter the environment variables for the API ID and API key.

7. Select Run in debug mode to collect detailed information about the analysis. The plugin stores the information in the console log of each Jenkins project.

8. If you are using a proxy host to connect to the Veracode Platform, select Connect using proxy and enter the proxy host information.

9. Select Generate Pipeline Script to generate a script using the selected settings.

   This example shows a script using bound credentials. The values for the Veracode API user ID (vid) and API key (vkey) are the environment variables which map to the actual credentials in the Jenkins credential store.

   veracodeDynamicAnalysisReview debug: true, failBuildForPolicyViolation: true, vid: 'VERACODE_API_ID', vkey: 'VERACODE_API_KEY' waitForResultsDuration: 1

10. Copy the pipeline script, which you add to your pipeline project.

11. Go back to the main page for your pipeline project.

12. Select Configure > Pipeline.

13. In the Pipeline section, paste the script into the Script field.

14. Delete the quotes from around the values for vid and vkey.

15. Select Apply to save your changes.

16. Go back to the main page for your pipeline project.

17. Select Build Now and wait for the build and analysis to complete successfully.

18. Under Build History, select a build number.

19. To review the results, select Veracode Dynamic Analysis. For additional information in the Veracode Platform, select the View Executive Summary link.

Veracode Jenkins Plugin script parameters

This table describes the parameters and their values for using the Jenkins plugin in a build script. The script is Apache Groovy.

Parameter	Type	Description
applicationName Required	String	Name of the application profile.
scanName Required	String	Name of the scan. You can enter the $buildnumber or $projectname variables to dynamically bind the build number or project name to the scan name, instead of using a fixed scan name.
uploadIncludesPattern Required	String	Include filepath patterns of the files you want to upload and scan. Use a comma-separated list of Ant-style include patterns relative to the job workspace directory.
vid Required	String	Veracode API ID. If your credentials are bound to environment variables, the environment variable is bound to the API ID.
vkey Required	String	Veracode API key. If you bound your credentials, the environment variable bound to the API key.
canFailJob	Boolean	Set to true if you want the entire Jenkins job to fail if the upload and scan with Veracode action fails. If set to false and the upload and scan with Veracode action fails, Jenkins completes the job, logs the failure, but does not notify you about the failure.
copyRemoteFiles	Boolean	If set to false (default), the plugin uploads the output files to Veracode from the remote workspace. If set to true, the plugin copies the output files from the remote machine to a local, temporary directory on the controller server and uploads to Veracode. NOTE: Veracode does not recommend enabling this option as it can increase the load on your Jenkins controller server.
createProfile	Boolean	Create a Veracode application profile, if one does not exist, for the specified application profile name. Set to true to create a profile. Set to false to not create a profile.
createSandbox	Boolean	For development sandbox scans, create a sandbox for the specified Veracode application. Set to true to create a sandbox. Set to false to not create a sandbox.
criticality	String	Required if you include the createProfile parameter. Criticality level of the scan: VeryHigh, High, Medium, Low, VeryLow
deleteIncompleteScanLevel	String	Automatically delete an incomplete scan based on its status to allow the uploadandscan action to continue processing. You can review the status of a scan in the Jenkins logs. To delete scans, you must have a user account with the Delete Scans role or an API service account with the Upload and Scan role. One of these values: 0: do not delete an incomplete scan when running the uploadandscan action. The default. If set, you must delete an incomplete scan manually to proceed with the uploadandscan action. 1: delete a scan with a status of incomplete, no modules defined, failed, or canceled to proceed with the uploadandscan action. If errors occur when running this action, the Jenkins plugin automatically deletes the incomplete scan. 2: delete a scan of any status except Results Ready to proceed with the uploadandscan action. If errors occur when running this action, the Jenkins plugin automatically deletes the incomplete scan.
debug	Boolean	Set to true to include detailed build information in the Jenkins console logs for debugging. Set to false to not include detailed build information in the logs.
fileNamePattern	String	Case-sensitive filename pattern that represents the names of uploaded files to save with a different name. The * wildcard matches 0 or more characters. The ? wildcard matches exactly one character. Each wildcard corresponds to a numbered group that you can reference in the replacement pattern.
pHost	String	Required if you include the useProxy parameter. Hostname of your proxy host.
pPassword	String	Required if you include the useProxy parameter. Password for the proxy host.
pPort	Integer	Required if you include the useProxy parameter. Port number for the proxy host.
pUser	String	Required if you include the useProxy parameter. Username for the proxy host.
replacementPattern	String	Replacement pattern that references groups captured by the filename pattern. For example, if the filename pattern is --SNAPSHOT.war and the replacement pattern is $1-master-SNAPSHOT.war, an uploaded file named app-branch-SNAPSHOT.war is saved as app-master-SNAPSHOT.war.
sandboxName	String	For development sandbox scans, the name of the sandbox in which to run the scan. If the sandbox does not exist, include createSandbox to create it with the specified name.
scanExcludesPattern	String	Case-sensitive, comma-separated list of module name patterns that represent the names of modules to not scan as top-level modules. The * wildcard matches 0 or more characters. The ? wildcard matches exactly one character.
scanIncludesPattern	String	Case-sensitive, comma-separated list of module name patterns that represent the names of modules to scan as top-level modules. The * wildcard matches 0 or more characters. The ? wildcard matches exactly one character.
teams	String	Comma-separated list of team names associated with the specified application. Validates against the names of existing teams for this account.
timeout	Integer	Number of minutes to wait for the scan to complete and pass policy. If the scan does not complete or fails policy, the build fails. Default is 60 minutes.
uploadExcludesPattern	String	Exclude filepath patterns of the files you do not want to upload and scan. Use a comma-separated list of Ant-style include patterns relative to the job workspace directory.
useProxy	Boolean	Set to true if using a proxy to access Veracode. If set to true, these parameters are required: pHost, pPassword, pPort, pUser
waitForScan	Boolean	Set to true to submit the scan and have the Jenkins job wait for the amount of time, in minutes, specified for the timeout parameter. If the scan does not complete and pass policy compliance within the specified time, the build fails.
ScanAllNonFatalTopLevelModules	Boolean	If fatal errors do not exist in the selected modules, this parameter does not have any effect. If set to true and fatal errors exist in any of the selected modules, this parameter removes the errors and continues the scan of the nonfatal selected modules. If set to false and fatal errors exist in any of the selected modules, this parameter stops the scan.
IncludeNewModules	Boolean	If ScanAllNonFatalTopLevelModules is set to true, set this parameter to true to include all the new top-level modules in the scan. The scan also includes previously selected modules by default. Note: If ScanAllNonFatalTopLevelModules is set to false, this parameter is set to false by default.

Uninstall the Jenkins plugin

You can uninstall the Veracode Jenkins Plugin the same as any other Jenkins plugin.

To complete this task:

1. Go to Manage Jenkins > Manage Plugins.
2. Select the Installed tab.
3. Select the plugin you want to uninstall and select Uninstall.