Installing and using the Azure DevOps Services plugin

This task describes how to install and use the Azure DevOps Services plugin for running static or dynamic scans in your Azure DevOps Services and Team Foundation Server (TFS) pipelines. (Azure DevOps Services was previously known as Visual Studio Team Services (VSTS)).

Tutorial

Installing the Azure DevOps/TFS plugin

Note: AppScan 360° supports TFS version 2018 update 2 and newer.
To use the Azure DevOps/TFS plugin, you must first download the plugin from the Azure DevOps marketplace and install it:
  1. In Azure DevOps Services, go to Manage Extensions > Browse Marketplace..
  2. In the resulting window, search for HCL.
  3. Select and install the HCL AppScan plugin.
Note: For TFS, download the plugin from Azure DevOps marketplace as instructed. Once done, go to Manage Extensions > Browse local extensions > Upload new extension and chose the downloaded extension to install.

Setting up the Azure DevOps Environment

To configure the Azure DevOps environment for testing:

  1. Log into Azure DevOps Services.
  2. Create a new organization:
    1. Click Create new organization.
    2. Specify the organization name.
    3. Specify a project name.
    4. Indicate whether the project is public or private.
    5. Click OK.
  3. Associate a code repository with the project:
    1. Click Repos > Files.
    2. Select Import.
    3. Choose a source type for the repository.
    4. Specify a clone URL for the repository.
    5. Click Import.
  4. Create a build pipeline:
    1. Click Pipelines > Builds.
    2. Click New pipeline.
    3. Click Use the visual designer.
    4. At Select a source, click Azure Repos git, then select the repository to scan, and click Continue.
    5. Select Empty pipeline and Continue.
    6. Click + next to Agent job 1, then search for NuGet and click Add.
    7. Select NuGet restore from tasks and point it to the solution file. Under Path to solution, packages.config, or project.json, browse to the appropriate .sln file.
    8. Click + next to Agent job 1to add the first step. Click Build, then Visual Studio Build, and Add.
    9. Click Build solution **/*.sln and point it to the solution file. At the Solution field, browse to the appropriate .sln file.
    10. Click Save & Queue to test the build.

      As you make adjustments to the build, add comments to reflect those changes. Each time you click Save & Queue the build number will update.

Using the Azure DevOps/TFS plugin

Adding a security test

To add a security test to a build process in Azure DevOps/TFS:
  1. Choose one of the following:
    • For Azure DevOps Services, choose Pipelines > Builds menu from your project home page.
    • For TFS, choose Build and Release > Builds.
  2. Edit the pipeline where you want to add the security test.
  3. On the Tasks tab, click + to add a task.
  4. Locate the task as HCL AppScan on Cloud, and click Add.
  5. In your build process, click the newly added Run HCL AppScan on Cloud Security Test task.
  6. Specify Task Settings
    1. Type in a string for the Display Name.

      This becomes the task name in the build process.

    2. Select the appropriate Credentials from the list.

      If the Credentials field is empty, see Adding a new service endpoint.

    3. Select an application from the Application list.

      The Application drop-down is populated based on the selected credentials.

    4. Type in a name for the scan in then Scan Namefield. Optional.

      This will be the name of the scan in the service.

    5. Select a scan type from the Scan Type list:
      • Select Static Analyzer to run static analysis security testing.
        Table 1. Static Analyzer Scan Parameters
        Parameter Description
        Repository Subdirectory to Scan Type in a value or select the value from the repository’s file browser dialog (optional). By default, the service scans the entire repository. To limit the scan to a subdirectory, specify the relative path here.
        Additional options
        Scan Speed Specify a scan optimization level based on need and time demands:
        • Simple A simple scan performs a surface-level analysis of your files to identify the most pressing issues for remediation. It takes the least amount of time to complete.
        • Balanced: A balanced scan provides a medium level of detail on the analysis and identification of security issues, and takes a bit more time to complete than the simple scan.
        • Deep: Default. A deep scan performs a more complete analysis of your files to identify vulnerabilities, and usually takes longer to complete.
        • Thorough: A thorough scan performs a comprehensive analysis to identify the most comprehensive list of vulnerabilities and will take the longest time to complete.
        Note: Scan speed does not necessarily correlate to relative number of vulnerabilities found in the code. For example, thorough analysis may rule out false positives that might be reported in a simple scan and therefore report fewer vulnerabilities.

Advanced options

Advanced options are not required to use the Azure DevOps/TFS plugin. To set advanced properties:

  1. Click Advanced to display additional options.
  2. Select the Email Notification checkbox to receive an email when the security analysis is complete. The email will be sent to the email address associated with the selected credentials.
  3. Select Run as a personal scan to evaluate the relative security of an application in development without affecting overall application scan data, or compliance. Personal scan support is not available in the deprecated HCL AppScan task.
  4. Select Allow intervention by scan enablement team to allow our scan enablement team to step in if the scan fails, or if no issues are found, and try to fix the configuration. This may delay the scan result. This option is selected by default.
  5. Select Suspend job until security analysis completes: Select this check box if you want the Jenkins build to wait for security analysis results to be available before moving on to the next step in the pipeline.
  6. Select Fail Build Configuration to specify conditions that will cause the build to fail based on results of the security test. Fail Build Configuration will be visible only if the Suspend job until security analysis completes is selected.
    • Select For noncompliance with application policies to fail the build if any security issues are found that are out of compliance with the policies of the selected application.
    • Select When the following conditions are true to fail the build based on the specified number of non-compliant Total security issues, Critical severity security issues, High severity security issues, Medium severity security issues, or Low severity security issues. If multiple thresholds are specified, they are logically OR'd together.
  7. Once a build completes, you can view or download the scan report from the Application Security Report tab on the Build Summary page. This report includes only the non-compliant issues.
    The Application Security report and irx. generation logs (for Static scans) are also made available for download via Azure Pipeline Build logs.
    Note: Please note that scan reports are not available for download if the Suspend job until security analysis completes option is not selected. In this case, you can download the report from HCL AppScan On Cloud portal.

Adding a new service endpoint

If, in Task Settings, the Credentials field is empty, you must configure the service endpoint. To configure a service endpoint for using the Azure DevOps/TFS plugin:

  1. At Task Settings, click Manage above the empty Credentials field.
  2. In the resulting window, click New Service Endpoint.
  3. Click HCL AppScan on Cloud from the list of endpoints.
  4. Fill in the details in the resulting dialog box and click OK:
    Table 2. Service Endpoint Properties
    Property Value
    Connection Name A logical name for the connection.
    Server URL
    KeyID Refer to Preparing the configuration file.
    KeySecret

Optimizing scans and reviewing results

As for other scans, you can use a config file to optimize scans by specifying individual targets to include or exclude from the scan, and to specify additional information. The config file should be placed at the project's root directory so the plugin picks it up for scanning.

When a scan is complete, AppScan 360° generates a report of the scan. Review the information in Results to learn about how security vulnerabilities are reported and how to remediate issues.