Submitting AppScan Source assessments to the Cloud for analysis

If you have a subscription to HCL AppScan on Cloud at HCL Cloud Marketplace, you can submit AppScan® Source assessments for analysis there. Assessments from AppScan Source Versions 9.0 or higher are supported - and the number of scans that you can submit depends on your AppScan on Cloud subscription.

About this task

When you use the static analysis feature 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 this technology. 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 AppScan on Cloud subscription, you may have a limited number of scans per month. See https://help.hcl-software.com/appscan/ASoC/src_managing_assessments_cloud.html for more information about scan and concurrent scan entitlement.

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

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 with your HCL ID. If you do not have an HCL ID, use the link for creating one. Then sign up for a free trial or paid subscription using the links at the service.
2. HCL Cloud Marketplace only: In the AppScan on Cloud service, create an app (see https://help.hcl-software.com/appscan/ASoC/ent_create_application.html) 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 Client Utility, do so now. See https://help.hcl-software.com/appscan/ASoC/src_utility_install.html 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 Client Utility command line interface (CLI) to generate an Intermediate Representation (IRX or .irx) file for the assessment (.ozasmt file):
1. After extracting the Client Utility to a local drive, add the location of its \bin directory to your PATH environment variable. If you do not do this, all Client Utility CLI commands will need to be qualified by using the \bin directory each time the command is issued. See https://help.hcl-software.com/appscan/ASoC/src_irx_gen_cli.html 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:
```
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 the package command, including usage examples, can be found at Configuration commands (Windows) or Configuration commands (Linux).
Use the CLI queue_analysis command to upload the IRX file:
1. Log in to the service from the CLI. Detailed information about authenticating to the service in the CLI can be found at Authentication commands (Windows) or Authentication commands (Linux).
  - HCL Cloud Marketplace:
    Issue this command on Windows:
```
appscan scx_login -P <password> -u <user_name> -persist
```
    or this command on Linux:
```
appscan.sh scx_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 AppScan on Cloud service.
    - -u: Specify -u <user_name>, where <user_name> is the email address that you specified when you registered for the AppScan on Cloud service.
    This argument is optional:
    - -persist: Automatically attempt to reauthenticate to the service when the login token file expires.
2. Upload the IRX file using the queue_analysis command:
  - Issue this command on Windows:
```
appscan queue_analysis -a <app_id> -f <irx_file> -n <scan_name>
```
    or this command on Linux:
```
appscan.sh queue_analysis -a <app_id> -f <irx_file> -n <scan_name>
```
    These arguments are required:
    - -f: Specify -f <irx_file>, where <irx_file> is the IRX file that you want to submit for scanning. If the IRX file is not in the current directory, use this option to specify the IRX 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 IRX file. If the directory contains only one IRX file, that file is submitted if the -f option is not used.
      
      You are issuing the command from a directory that contains no IRX files. In this case, the -f option must be used to specify the path and file name of the IRX file to submit.
    - -n: Specify -n <scan_name>, where <scan_name> is the name of the scan that takes place on the cloud.
    - -a (HCL Cloud Marketplace only): If you are connected to the AppScan on Cloud service at HCL Cloud Marketplace, IRX files that you submit to the cloud 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 queue_analysis 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 get_result 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 the queue_analysis command can be found at Analysis commands (Windows) or Analysis commands (Linux).
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 get_result 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 get_result 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:
```
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 queue_analysis command, you can use the appscan list or appscan.sh list command to see a list of all analysis jobs. See Analysis commands (Windows) or Analysis commands (Linux) 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 Source Version 9.0 or higher product.
  Details about using the get_result command can be found at Results commands (Windows) or Results commands (Linux).
Complete this step if you want to use the web client to retrieve the analysis report: If you are only interested in seeing an HTML report, you can use the AppScan on Cloud web client to download the 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 https://help.hcl-software.com/appscan/ASoC/appseccloud_results_dashboard_cm.html.