Submitting HCL AppScan Source assessments to the Cloud for analysis

If you have a subscription to HCL AppScan on Cloud, you can submit AppScan Source assessments for analysis there. Assessments from AppScan Source Versions 9.0 or higher are supported. The number of scans you can submit depends on your ASoC subscription.

About this task

When you use the static analysis functionality of the AppScan on Cloud service, you can generate security analysis reports that make use of Intelligent Finding Analytics (IFA). IFA is a powerful machine-learning technology that does much of the triage work for you by, among other things, filtering out false positives and by grouping findings that can be remedied by a fix in one code point. To learn more about IFA, see this article.

If you are using AppScan Source Version 9.0 or higher and have an AppScan on Cloud subscription, you can benefit from this technology by uploading your AppScan Source assessment to AppScan on Cloud. In return, you will receive a new assessment that has been automatically triaged by IFA. This assessment can be in the form of an HTML report or an assessment that can be opened in your AppScan Source product.

If you have a paid AppScan on Cloud subscription, you can scan 10 additional AppScan Source assessments. For example, if your subscription includes 20 AppScan on Cloud scans, you can scan another 10 AppScan Source assessments - for a total of 30 scans. Concurrent scan limits, as outlined in your subscription, include scans of AppScan Source assessments. For example, if your subscription allows you 2 scans at the same time, scans of AppScan Source assessments would be included.
If you have a trial AppScan on Cloud subscription, scans of AppScan Source assessments count toward your total number of allowed scans.

Note: If you are scanning an AppScan Source assessment with a free trial of AppScan on Cloud, you can download a full HTML report, in addition to the AppScan Source assessment file that has been triaged by IFA. For all other scan types, you can only download a summary report when you have a free trial.

Procedure

Perform one of the following steps (skip this step if you are already using AppScan on Cloud for static analysis):
1. If you do not have an AppScan on Cloud subscription, go to https://cloud.appscan.com/AsoCUI/serviceui/home and sign in. If you do not have a subscription, use the link for creating an HCL ID. Then sign up for a free trial or paid subscription using the links at the service.
2. In the AppScan on Cloud service, create an application and then click Create Scan.
3. In the What type of app are you scanning today? screen, select Desktop or Web > Static.
4. If you have not previously downloaded and set up the Static Analyzer Command Line Utility, do so now. See Setting up the Static Analyzer Command Line Utility for more information.
Generate an assessment (.ozasmt file) in the AppScan Source product or tool of your choice. Versions 9.0 or higher are supported.
Use the Static Analyzer Command Line Utility command line interface (CLI) to generate an Intermediate Representation (IRX or .irx) file for the assessment (.ozasmt file):
1. After extracting the Static Analyzer Command Line Utility to a local drive, add the location of its \bin directory to your PATH environment variable. If you do not do this, all Static Analyzer Command Line Utility CLI commands will need to be qualified by using the \bin directory each time the command is issued. See Generating an IRX file by using the command line interface (CLI) for more information.
2. Issue this command on Windows™:
```
appscan package -d <save_path> -f <assessment_file> -n <file_name>
```
  or this command on Linux™ and macOS:
```
appscan.sh package -d <save_path> -f <assessment_file> -n <file_name>
```
  The command arguments are optional:
  - -d: Specify -d <save_path>, where <save_path> is the directory that you want to save the IRX file to.
  - -f: Specify -f <assessment_file>, where <assessment_file> is the .ozasmt file that you want to package for scanning. If the <assessment_file> file is not in the current directory, use this option to specify the assessment file path and file name.
    Note: This option is only required if one or both of these statements are true:
    
    You are issuing the command from a directory that contains more than one assessment file. If the directory contains only one assessment file, that file is packaged if the -f option is not used.
    
    You are issuing the command from a directory that contains no assessment files. In this case, the -f option must be used to specify the path and file name of the assessment file to package.
  - -n: Specify -n <file_name>, where <file_name> is the IRX file name. You can specify the file name with or without the .irx file extension. If you specify it without the extension, it is automatically added for you when the file is generated.
  Additional information about this command, including usage examples, can be found at Configuration commands (Windows™) or Configuration commands (Linux™ and macOS).
Use the CLI appscan queue_analysis (Windows™) or appscan.sh queue_analysis (Linux™ and macOS) command to upload the IRX file:
1. Log in to the service from the CLI. The method for doing this is different at HCL Cloud Marketplace. Detailed information about authenticating to the service in the CLI can be found at Authentication commands (Windows™) or Authentication commands (Linux™ and macOS).
  - HCL Cloud Marketplace:
    Issue this command on Windows™:
    appscan api_login -P <password> -u <user_name> -persist
    or this command on Linux™ and macOS:
    appscan.sh api_login -P <password> -u <user_name> -persist
    These arguments are required:
    - -P: Specify -P <password>, where <password> is the password that you specified when you registered for the ASoC service.
    - -u: Specify -u <user_name>, where <user_name> is the email address that you specified when you registered for the ASoC service.
    This argument is optional:
    - -persist: Automatically attempt to reauthenticate to the service when the login token file expires.
2. Upload the IRX file with the appscan queue_analysis (Windows™) or appscan.sh queue_analysis (Linux™ and macOS) command:
  - Issue this command on Windows™:
```
appscan queue_analysis -a <app_id> -f <file> -n <scan_name>
```
    or this command on Linux™ and macOS:
```
appscan.sh queue_analysis -a <app_id> -f <file> -n <scan_name>
```
    These arguments are required:
    - -f: Specify -f <file>, where <file> is the IRX file or non-IRX archive that you want to submit for scanning. If the file is not in the current directory, use this option to specify the file path and file name.
      Note: This option is only required if one or both of these statements are true:
      
      You are issuing the command from a directory that contains more than one target file. If the directory contains only one target file, that file is submitted if the -f option is not used.
      
      You are issuing the command from a directory that contains no target files. In this case, the -f option must be used to specify the path and file name of the file to submit.
    - -a : Files that you submit to the for analysis (IRX file or non-IRX archive) must be associated with an existing AppScan on Cloud application. With this option, specify -a <app_id>, where <app_id> is the ID of the application to associate with. To determine the ID, use the list_apps command.
  - When the command completes, an ID for the analysis job displays. If you want to receive the AppScan on Cloud analysis report by using the CLI, you will need to include this job ID in the appscan get_result (Windows™) or appscan.sh get_result (Linux™ and macOS) command - and you should make note of the ID. If you use the CLI to receive the analysis report, you will have the option of receiving an archive (.zip) file that includes a .ozasmt file so that the analysis report can be opened in AppScan Source. If you are only interested in seeing an HTML report, you can use the CLI or the AppScan on Cloud web client to download the report.
  Details about using this command can be found at Analysis commands (Windows™) or Analysis commands (Linux™ and macOS).
When analysis is complete, you will receive an email if you uploaded the IRX using the CLI - or if you selected the Email me when the scan is complete check box in the AppScan on Cloud web client.
Choose a method for retrieving the analysis report. You can use the CLI appscan get_result (Windows™) or appscan.sh get_result (Linux™ and macOS) command - or you can use the AppScan on Cloud web client. If you use the CLI to receive the analysis report, you will have the option of receiving an archive (.zip) file that includes a .ozasmt file so that the analysis report can be opened in AppScan Source. If you are only interested in seeing an HTML report, you can use the CLI or the AppScan on Cloud web client to download the report.
Complete this step if you want to use the CLI appscan get_result (Windows™) or appscan.sh get_result (Linux™ and macOS) command to retrieve the analysis report:
1. Ensure that you are logged in to the service from the CLI.
2. Issue this command on Windows™:
```
appscan get_result -d <file_path> -i <job_id> -t <type>
```
  or this command on Linux™ and macOS:
```
appscan.sh get_result -d <file_path> -i <job_id> -t <type>
```
  This argument is required:
  - -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
  Note: If you did not make note of the ID when issuing the appscan queue_analysis (Windows™) or appscan.sh queue_analysis (Linux™ and macOS) command, you can use the appscan list (Windows™) or appscan.sh list (Linux™ and macOS) command to see a list of all analysis jobs. See Analysis commands (Windows™) or Analysis commands (Linux™ and macOS) for more information.
  
  These arguments are optional:
  - -d: Specify -d <file_path>, where <file_path> is the fully qualified path for the destination file and/or the file name of the destination file. If a file name is not specified, the file name is based on the scan job name. If a path is not specified, the file is saved to the current directory. If this option is not included, the file is saved to the current directory with a file name that is based on the scan job name.
  - -t: Specify -t <type>, where <type> is either html or zip. The results are saved as an HTML file or as a .zip file that contains the HTML results. If this option is not included, the results are saved as an HTML file.
    If the scan results are for an IRX file that was generated by the package command, specifying -t zip saves results that contain a new .ozasmt file that can be loaded into your AppScan Version 9.0 or higher product.
  Details about using this command can be found at Results commands (Windows™) or Results commands (Linux™ and macOS).
If you are only interested in seeing an HTML report, you can use the AppScan on Cloud web client to download the report. Complete this step if you want to use the web client to retrieve the analysis report.

When you log in to the service, you should automatically see a list of your scans (if you have navigated to another section of the service, click the X icon at the top right to return to the list of scan). In the scan list, locate the scan and select the Download icon and then choose XML or HTML format.

To learn more about AppScan on Cloud scan results at HCL Cloud Marketplace, see Results.