Analysis commands (Windows™)

Analysis commands are used for submitting scan requests for analysis - or for working with scan requests that are already submitted. Using the commands, you can also receive information about scans. This information can be useful for automation scripts.

Before you use these commands, ensure that you log in to the analysis service (see Authentication commands).

appscan status

Syntax:

appscan status -i <job_id>

Description:

Return one of these status codes for an analysis job:

0 = Pending
1 = Starting
2 = Running
3 = FinishedRunning
4 = FinishedRunningWithErrors
5 = PendingSupport
6 = Ready
7 = ReadyIncomplete
8 = FailedToScan
9 = ManuallyStopped
10 = None
11 = Initiating
12 = MissingConfiguration
13 = PossibleMissingConfiguration

Required options:

  • -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
Tip: For all commands, options can be used in any order.

Examples:

To see the status of job ID 12345, specify this:

appscan status -i 12345

If the return code is 0, the job is pending. If the return code is 1, the job is starting, and so on.

appscan list

Syntax:

appscan list

Description:

List all analysis jobs, including those jobs that are queued, running, and completed. The ID for every job is returned so that you can use the ID for other commands. For example, the ID can be used with the info command in the command prompt or in scripts.

Note: This command returns a maximum of 2000 scans.

appscan list_apps

Syntax:

appscan list_apps

Description:

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.

This command allows you to see the AppScan on Cloud applications that you have access to. To use the command, you must be authenticated to the service. After issuing the command, a list of AppScan on Cloud applications displays with application names followed by their IDs in parentheses. Use the ID values in this list when using the -a option of the queue_analysis command.

appscan cancel

Syntax:

appscan cancel -i <job_id>

Description:

Cancel an analysis job that is running or queued.

Required options:

  • -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
Tip: For all commands, options can be used in any order.

Examples:

To cancel job ID 12345, specify this:

appscan cancel -i 12345

appscan queue_analysis

Syntax:

appscan queue_analysis -a <app_id> -f <file> -di -n <scan_name> -nen -oso -ps -sao

Description:

Submit a file for analysis (IRX or non-IRX archive). When the scan is complete, you receive an email notification (at the email address that is associated with the account that was used to log in to the analysis service). The email includes a link so that you can log in to download your scan.
Note: When you scan code or generate an IRX file, you might receive a message about updating to the latest Static Analyzer Command Line Utility. See Command Line Utility (CLI) support.

Required options:

  • -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.
  • -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.
Optional flags/settings:
  • -di: Disable intervention. If your scan fails for any reason, the scan enablement team will not intervene to try to improve the configuration. By default, when a scan fails, it enters Under review status to await intervention from the scan enablement team. Specify -di to disable this intervention; the scan simply fails.
  • -n: Specify -n <scan_name>, where <scan_name> is the name of the submitted scan.
  • -nen: Disable email notification on analysis completion. If this flag is not specified, email notification occurs by default.
    Note: The -e flag has been deprecated and replaced by -nen.
  • -oso: Specify -oso to look only for known vulnerabilities in SCA packages. When -oso is specified, AppScan on Cloud does not perform static analysis on the package.
    Note: When a user has an Open Source license, SCA analysis is part of a static scan by default. This option limits analysis to SCA vulnerabilities. Users must have an Open Source license to take advantage of SCA-only analysis.
  • -ps: Run the scan as a personal scan. If this flag is not specified, a regular scan occurs by default.
  • -sao: Specify -sao to perform static analysis only. When -sao is specified, AppScan on Cloud does not perform open source analysis on the package.
Tip: For all commands, options can be used in any order.

Examples:

appscan queue_analysis -f my_irx.irx 12345 -n my_scan
To submit my_irx.irx, which is in the current directory, for scanning, use 
appscan queue_analysis -f my_irx.irx -a 12345 -n my_scan
Where 12345 is the ID of the application to associate the scan with (the application ID can be determined using the list_apps command). When you use the user interface or the list command to see all current scans, my_scan appears in the list.
When the IRX is created without specifying either open source only (SCA) or static analysis only, those options can be applied at the time of analysis using the -oso or -sao options with appscan queue_analysis. In this example the following command sends the file for both open source and static analysis:
appscan queue_analysis -a <application> -f my_irx.irx
The following sends the file for static analysis only:
appscan queue_analysis -a <application> -f <file> -sao
The following sends the file for open source analysis (SCA) only:
appscan queue_analysis -a <application> -f <file> -os
Conversely, if a file is created and open source (SCA) or static analysis only is specified with appscan prepare, the basic command
appscan queue_analysis -a <application> -f my_irx.irx
sends the file for only the type of analysis specified with the appscan prepare command.

appscan info

Syntax:

appscan info -i <job_id>

Description:

Display the information for a specified analysis job.

The information that is provided can be used for automation scripts.

Required options:

  • -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
Tip: For all commands, options can be used in any order.

Examples:

To receive information about job ID 12345, specify this:

appscan info -i 12345

An example of the information that is returned is:

NLowIssues=0
ReadStatus=2
NHighIssues=0
Name=appscan.zip
ScanEndTime=2014-11-20T13:56:04.497Z
Progress=0
RemainingFreeRescanMinutes=0
ParentJobId=00000000-0000-0000-0000-000000000000
EnableMailNotifications=false
JobStatus=6
NInfoIssues=0
JobId=9b344fc7-bc70-e411-b922-005056924f9b
NIssuesFound=0
CreatedAt=2014-11-20T13:54:49.597Z
UserMessage=Scan completed successfully. The report is ready.
NMediumIssues=0
Result=1