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
- In Azure DevOps Services, go to .
- In the resulting window, search for HCL.
- Select and install the HCL AppScan plugin.
Setting up the Azure DevOps Environment
To configure the Azure DevOps environment for testing:
- Log into Azure DevOps Services.
- Create a new organization:
- Click Create new organization.
- Specify the organization name.
- Specify a project name.
- Indicate whether the project is public or private.
- Click OK.
- Associate a code repository with the project:
- Click .
- Select Import.
- Choose a source type for the repository.
- Specify a clone URL for the repository.
- Click Import.
- Create a build pipeline:
- Click .
- Click New pipeline.
- Click Use the visual designer.
- At Select a source, click Azure Repos git, then select the repository to scan, and click Continue.
- Select Empty pipeline and Continue.
- Click + next to Agent job 1, then search for NuGet and click Add.
- 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.
- Click + next to Agent job 1to add the first step. Click Build, then Visual Studio Build, and Add.
- Click Build solution **/*.sln and point it to the solution file. At the Solution field, browse to the appropriate .sln file.
- 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
- Choose one of the following:
- For Azure DevOps Services, choose menu from your project home page.
- For TFS, choose .
- Edit the pipeline where you want to add the security test.
- On the Tasks tab, click + to add a task.
- Locate the task as HCL AppScan on Cloud, and click Add.
- In your build process, click the newly added Run HCL AppScan on Cloud Security Test task.
- Specify Task Settings
- Type in a string for the Display Name.
This becomes the task name in the build process.
- Select the appropriate Credentials from the
list.
If the Credentials field is empty, see Adding a new service endpoint.
- Select an application from the Application
list.
The Application drop-down is populated based on the selected credentials.
- Type in a name for the scan in then Scan
Namefield. Optional.
This will be the name of the scan in the service.
- 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 thesimple
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 asimple
scan and therefore report fewer vulnerabilities. - Simple A
- 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 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 Creating a web application scan (full configuration).
- Select Static Analyzer to run static
analysis security testing.
- Type in a string for the Display Name.
Advanced options
Advanced options are not required to use the Azure DevOps/TFS plugin. To set advanced properties:
- Click Advanced to display additional options.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- At Task Settings, click Manage above the empty Credentials field.
- In the resulting window, click New Service Endpoint.
- Click HCL AppScan on Cloud from the list of endpoints.
- Fill in the details in the resulting dialog box and click
OK:
Table 3. Service Endpoint Properties Property Value Connection Name A logical name for the connection. Server URL -
AppScan on Cloud United States Data Center: http://cloud.appscan.com/
-
AppScan on Cloud European Union Data Center: http://eu.cloud.appscan.com/
KeyID Acquire a KeyID and KeySecret at the AppScan on Cloud service for the datacenter you are using: - US datacenter API key page
- EU datacenter API key page
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 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.