Analysis commands (Linux™ and macOS)
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 are logged in to the analysis service (see Authentication commands).
appscan.sh
status
Syntax:
appscan.sh 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.
Examples:
To see the status of job ID 12345, specify this:
appscan.sh 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.sh
list
Syntax:
appscan.sh 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.
appscan.sh
list_apps
Syntax:
appscan.sh 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.sh
cancel
Syntax:
appscan.sh 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.
Examples:
To cancel job ID 12345, specify this:
appscan.sh cancel -i 12345
appscan.sh
queue_analysis
Syntax:
appscan.sh queue_analysis -a <app_id> -f <file> -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.
Required options:
-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.
- 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
-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 thelist_apps
command.
-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.
Examples:
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.-oso
or -sao
options with appscan queue_analysis
. In this example the following
command sends the file for both open source and static
anlysis: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
commandappscan queue_analysis -a <application> -f my_irx.irx
sends
the file for only the type of analysis specified with the appscan
prepare
command.appscan.sh
info
Syntax:
appscan.sh 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.
Examples:
To receive information about job ID 12345, specify this:
appscan.sh 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