Installing and using the Visual Studio Team Services plugin

This task describes how to install and use the Visual Studio Team Services (VSTS) plugin for scanning static, dynamic, or mobile VSTS and Team Foundation Server (TFS) projects.

Note: Please note the new URL for the AppScan on Cloud service is http://cloud.appscan.com. Migrate from the previous service location at IBM to this location, including updating Service Endpoint Properties. For additional information, see https://hclpnpsupport.hcltech.com/csm?id=kb_article&sysparm_article=KB0069537.

Installing the VSTS/TFS plugin

Note: Visual Studio Team Services (VSTS) is now known as Azure DevOps. For consistency with user interface options, we continue to refer to it as VSTS here. AppScan on Cloud supports TFS version 2018 update 2 and newer.
To use the VSTS/TFS plugin, you must first download the plugin from the VSTS marketplace and install it:
  1. In VSTS, 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 VSTS 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 VSTS Environment

To configure the VSTS environment for testing:

  1. Log into VSTS.
  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 VSTS/TFS plugin

Adding a security test

To add a security test to a build process in VSTS/TFS:
  1. Choose one of the following:
    • For VSTS, 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 plugin as installed (HCL AppScan), and click Add.
  5. In your build process, click the newly added Run HCL AppScan Security 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. Optionally, type in a name for the scan in then Scan Namefield.

      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 Optionally, type in a value or select the value from the repository’s file browser dialog. 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.
      • Select Dynamic Analyzer to perform analysis of an application that runs in a browser.
        Table 2. Dynamic Analyzer Scan Parameters
        Parameter Description
        Starting URL

        Enter the URL from which you want the scan to start exploring the site.

        If you select Additional Options, the following optional settings are available:

        Additional options
        Site Type Indicate whether your site is a Staging site (under development) or a Production site (live and in use), or choose NA.
        Test Optimization Specify an optimization level:
        • No optimization (Default): Regular in-depth scanning. Scan time is longer. Maximum vulnerability coverage.
        • Fast: Up to twice as fast. Vulnerability coverage of ~97%.
        • Faster: Up to five times as fast. Vulnerability coverage of ~85%.
        • Fastest: Up to ten times as fast. Vulnerability coverage of ~70%.

        For additional information about test optimization and relative scan depth and speed, see Test Optimization.

        Login User and Login Password If the app requires login, enter valid user credentials.
        Third Credential If your app requires a third credential, enter it in this field.
        Presence If the app is not on the internet, enter the AppScan Presence Name. For information about creating an AppScan Presence, see Creating the AppScan Presence.
        Scan File If you have an AppScan Standard scan file, enter the relative path and file name in this field. To learn more about AppScan Standard scan files, see Using AppScan Standard scans or templates.

        To learn more about dynamic analysis settings, see Run a DAST Scan.

      • Select Mobile Analyzer to run security analysis of an Android or iOS mobile application.
        Table 3. Mobile Analyzer Scan Parameters
        Parameter Description
        Application File

        Enter the relative path and file name of the. apk or .ipa file that you want to scan.

        If you select the Additional Options, below optional settings are available:

        Additional options
        Login User and Login Password If the app requires login, enter valid user credentials.
        Third Credential If your app requires a third credential, enter it in this field.
        Presence If the app is not on the internet, enter the AppScan Presence ID. For information about creating an AppScan Presence, see Creating the AppScan Presence.

        For more information about mobile analysis, see Run an Android Mobile Scan and Run an iOS Mobile Scan.

Advanced options

Advanced options are not required to use the VSTS/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 Fail Build Configuration to specify conditions that will cause the build to fail based on results of the security test:
    • 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, High severity security issues, Medium severity security issues, or Low severity security issues. If multiple thresholds are specified, they are logically OR'd together.
  4. Once a build completes, you can view or download the scan report from the Application Security Report tab on the Build Summary page.

    The Application Security report and irx.generation logs are available as part of the Build logs and can be downloaded.

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 VSTS/TFS plugin:

  1. At Task Settings, click Manage above the empty Credentials field.
  2. In the resulting window, click New Service Endpoint.
  3. Click Run HCL AppScan Security from the list of endpoints.
  4. Fill in the details in the resulting dialog box and click OK:
    Table 4. Service Endpoint Properties
    Property Value
    Connection Name A logical name for the connection.
    Server URL https://cloud.appscan.com/
    KeyID Acquire a KeyID and KeySecret at https://cloud.appscan.com/api/ideclientuilogin
    KeySecret

Optimizing scans and revewing 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.

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