veracode-gradle-plugin

Table of Contents

• Pre-Requisites
• Getting Started
  • Apply the plugin into your project
  • veracodeSetup extension
  • Work flow tasks (CI environment)
  • Additional Task Documentation
• Compatibility
• Contributing
  • Building Using a local Java API Wrapper
• LICENSE

Veracode Gradle Plugin that automates Veracode application security scanning activities.

As a set of Gradle tasks, it is meant to be usable either as a command line submission tool or integrated as part of a continuous integration build process.

It helps perform the following tasks:

• Perform Veracode submissions for applications.

• Retrieve Scan reports.

Pre-Requisites

• Veracode account & application to perform scanning.

• JDK 7+ is a requirement for the Veracode Java API.

Getting Started

The plugin is published as a gradle plugin: https://plugins.gradle.org/plugin/com.calgaryscientific.gradle.veracode

Apply the plugin into your project

1. Create a new Gradle project.

2. Copy the VeracodeJavaAPI.jar (from Veracode) to a newly created lib directory within your project.

3. Apply the plugin with a minimal setup:

   apply plugin: 'groovy'
   apply plugin: 'com.calgaryscientific.gradle.veracode'
   
   buildscript {
       repositories {
           maven {
             url "https://plugins.gradle.org/m2/"
           }
       }
       dependencies {
           classpath 'gradle.plugin.com.calgaryscientific.gradle:veracodePlugin:0.6.0'
       }
   }
   
   veracodeSetup {
       // Authentication
       username = project.findProperty("veracodeUsername") (1)
       password = project.findProperty("veracodePassword")
       id = project.findProperty("veracodeID") (1)
       key = project.findProperty("veracodeKey")
   
       // App info
       app_id = project.findProperty("veracodeAppID")
   
       // Upload Config
       filesToUpload = fileTree(dir: "upload/", include: "*").getFiles()
       sandboxFilesToUpload = fileTree(dir: "upload/", include: "*").getFiles()
   
       // Scan Config
       moduleWhitelist = ['class1.jar', 'class2.jar']
   }

   1. You are only required to use either username and password combination or API id and key.

4. Rename the sample-gradle.properties file to gradle.properties within your project and edit its contents to setup Veracode credentials. Optionally, the Veracode credentials properties can be placed in the ~/.gradle/gradle.properties file.

5. Execute gradle tasks to see available tasks.

veracodeSetup extension

The veracodeSetup extension is used to configure the Plugin and to pass details to the tasks.

A minimal setup is shown above, a full description of all fields is shown below:

veracodeSetup configuration

// Authentication
String username
String password
String id
String key

// Output location
String outputDir = "${project.buildDir}/veracode"

// App and Sandbox
String app_id
String sandbox_id
String sandbox_name

// Build Info
String build_id
String build_version

// Flaw Info
String flaw_id
String flaw_id_list
String action
String comment
String cweid

// File Info
String file_id

// Upload Config
Boolean deleteUploadedArtifacts = false
Integer maxUploadAttempts = 10
Integer waitTimeBetweenAttempts = 5000
Set<File> filesToUpload
Set<File> sandboxFilesToUpload

// Scan Config
Set<String> moduleWhitelist

// Error Management
Boolean ignoreFailure = false

// Workflow reports
Boolean failWorkflowTasksOnNewFlaws = false

To pass these fields to the Plugin as properties, set the field on veracodeSetup to read the desired property, for example:

veracodeSetup {
    ...
    build_id = project.findProperty("build_id")
}

Then:

./gradlew veracodeDetailedReport -P build_id=xxx

Work flow tasks (CI environment)

The full work flow tasks are meant to be used in a CI environment.

A single task will do the following:

• Query the status of the latest build:

  • If the latest build Scan is complete:

    1. Get latest build’s Detailed Report and print flaw summary.

    2. Creates a new build.

    3. Uploads the given files to the Veracode platform.

    4. Begins a Pre-Scan of the uploaded files.

    5. Optionally fail the build if there were new flaws from the Detailed Report on step 1.

  • If the latest build has a completed Pre-scan:

    • Begins the Scan of the application selecting the given white list modules.

  • If the Pre-scan or Scan is in progress:

    • Doesn’t run any steps.

A sample configuration looks like this:

task veracodeBuildWorkflow(type: com.calgaryscientific.gradle.VeracodeWorkflowTask) {
    dependsOn buildMyApplication
    doFirst {
        veracodeSetup {
            build_version =  "build-name-if-creating-a-new-build"
            ignoreFailure =  true (1)
            filesToUpload = fileTree(dir: "upload/", include: "*").getFiles() (2)
            failWorkflowTasksOnNewFlaws = true (3)
        }
    }
}

1. Optionally ignore failures to avoid stopping the build process if there is a problem with the Veracode calls.

2. Setup veracodeSetup filesToUpload again to ensure it is evaluated after the buildMyApplication task.

3. Optionally fail the task if there are new flaws introduced in the latest build. The failure will be triggered after a new build creation, file upload and pre-scan submission.

This task can be triggered by every commit and will only create a new build, upload files, begin pre-scans or begin scans when the Veracode platform is ready for it.

The Sandbox counterpart can be used as:

task veracodeBuildWorkflow(type: com.calgaryscientific.gradle.VeracodeWorkflowSandboxTask) {
    dependsOn buildMyApplication
    doFirst {
        veracodeSetup {
            build_version =  "build-name-if-creating-a-new-sandbox-build"
            ignoreFailure =  true
            sandboxFilesToUpload = fileTree(dir: "upload/", include: "*").getFiles()
            failWorkflowTasksOnNewFlaws = true
        }
    }
}

Additional Task Documentation

For additional documentation please review the veracode-gradle-plugin Documentation.

Compatibility

Tested with the Java API version: VeracodeJavaAPI v17.6.4.4 c201706231537

Tested with the following XML file versions:

• appinfo: appinfo_version="1.1"

• applist: applist_version="1.2"

• buildinfo: buildinfo_version="1.4"

• detailedreport: report_format_version="1.5"

• buildlist: buildlist_version="1.3"

• filelist: filelist_version="1.1"

• prescanresults: prescanresults_version="1.4"

• sandboxlist: sandboxlist_version="1.0"

• sandboxinfo: sandboxinfo_version="1.2"

Contributing

• Clone the project.

• Run the tests:

  gradle test

• Make your changes.

• Build and publish to mavenLocal by running:

  gradle publish

• Create a PR after you have verified things are working as expected.

Building Using a local Java API Wrapper

Gradle doesn’t support verifying PGP keys. If you want to use a local Java API Wrapper instead of the Maven provided one, follow these steps:

1. Uncomment the local dependency code on build.gradle and comment out the Maven Central one.

2. Copy the Veracode Java API JAR file to a newly created lib directory. The zip file is found in the documentation from Veracode’s website.

LICENSE

MIT License

Copyright (c) 2017-2018 Calgary Scientific Incorporated

Copyright (c) 2013-2014 kctang

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.