Plug-in Documentation

HCL AppScan on Cloud (ASoC)

Overview

The ASoC plug-in provides steps to integrate with the ASoC server.

This plug-in includes the following steps:

Step palette

To access this plug-in in the palette, click Utilities > HCL AppScan on Cloud.

Compatibility

This plug-in requires IBM UrbanCode Deploy version 6.0 or later.

This plug-in runs on all operating systems that UrbanCode Deploy supports.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode Deploy.

History

Version 13

  • Renamed to HCL AppScan on Cloud (ASoC)
  • After one hour while waiting for scan completion, a re-authentication will occur to preserve credential set.
  • The “Scan Name” property is added to the “Start Dynamic Analyzer ASoC Scan” step.

Version 12

  • Updated to the new ASoC domain ‘cloud.appscan.com’

Version 11

  • Set high, medium, low, informational issue count output properties on dynamic scan.

Version 10

  • Complete rewrite of former plugin to fix broken scan steps.
  • Added Application ID property to scan steps.
  • Changed authentication to API tokens as opposed to IBM IDs.
  • Added support for scan templates for DAST/MAST scans.
  • Added steps for creating, deleting, starting, and stopping presences.
  • Added support for running scans on private applications using presences.
  • Added third credential for DAST/MAST scans.
  • Added support for Staging and Production DAST scans.

Version 9

  • Remove old deprecated projectLocation and workspaceScheme fields from Start iOS Scan step (ipaFileLocation already replaced them)

Version 8

  • Add testPolicy to Start Dynamic Analyzer ASoC Scan step. Migrate the Start iOS Analyzer ASoC Scan from working with IPAX generator, to working with ipa file

Version 7

  • Add step Start iOS Analyzer ASoC Scan

Version 6

  • Rename the step Start Mobile Analyzer Scan into Start Android Mobile Analyzer ASoC Scan

Version 5

  • Rename plugin from Application Security Testing (Smartcloud Exchange) to IBM Application Security on Cloud and add support for running a DAST(Domain Verification not supported) and SAST scans.

Version 4

  • Upgrade to http-builder-0.7.2-uc.jar, and change our portal domain from appscan.bluemix.net to appscan.ibmcloud.com

Version 3

  • Changing our portal domain from appscan.ibmcloud.com to appscan.bluemix.net (and adding hidden experimental feature PSS)

Version 2

  • Migrate internal logic to work with cloud V2 APIs

Version 1

  • Initial version

Usage

Usage Documentation:

ASoC UCD Demonstration

The following video demonstrates how to:

  • Create a presence
  • Start a presence
  • Delete presences
  • Run static and dynamic scans
  • Scan a private web application using a presence
  • Run a dynamic scan using a scan template file (SCANT)

Steps

Process steps in the HCL AppScan on Cloud plug-in

Create ASoC Presence

Create and start a new presence. To access a private site server you must
start the presence in an environment that has local access to the server. The PresenceId
output property generated can be used to run scans in environments that do not have
access to the private site.

Input properties for the Create ASoC Presence step
Name Type Description Required
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Start Presence Boolean Select this option to start the presence after it is created. No

Delete ASoC Presence

Delete an ASoC presence. The presence will subsequently be stopped on any
machine where it is currently running.

Input properties for the Delete ASoC Presence step
Name Type Description Required
Delete All Presences Boolean Select this box to remove all existing ASoC presences that
can be accessed with the provided login credentials.
No
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Presence ID String Specify an ID of an existing presence that is accessible using
the provided login credentials. This field will be ignored if
the Delete All Presences box is checked.
No

Start ASoC Presence

Start an existing ASoC presence. The presence will be started on the
agent machine that runs the step.

Input properties for the Start ASoC Presence step
Name Type Description Required
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Presence ID String Specify an ID of an existing presence, which allows you to run
scans on apps not connected to the internet or require a proxy server
to make a connection. The presence must be accessible to the user.
No
Renew Presence Key Boolean Select this option to renew the key before starting the presence. No

Start Android Mobile Analyzer ASoC Scan

Starts a new Android Mobile Analyzer ASoC Scan, using IBM Application
Security on Cloud. This step will generate the ScanId output property.

Input properties for the Start Android Mobile Analyzer ASoC Scan step
Name Type Description Required
APK File Location String The path to the Android package (APK) file. Yes
ASoC Application ID String The ID of the application in ASoC. Yes
Application Password Password Password for the scanned application if it contains a login. No
Application Username String Username for the scanned application if it contains a login. No
Enable Mail Notification Boolean Select this option to notify email IDs configured in ASoC. No
Fail condition threshold (H, M, L, I) String Please set the number of issues found (by severity) in a
comma-separated list. If the threshold is reached during the scan,
the scan will fail. In this field, you can specify the numbers for
these severity levels: High (H), Medium (M), Low (L), and
Informational (I). For example, a fail condition of 0,5,10,20
will cause the step to fail if the resulting scan has more than 0
High issues, 5 Medium issues, and so on. If this field is left
empty, there will be no validation of results and the scan will
not fail as a result of a fail condition.
No
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Original scan ID String If this is a rescan please enter the original scan id No
Presence ID String Specify an ID of an existing presence, which allows you to run
scans on apps not connected to the internet or require a proxy server
to make a connection. The presence must be accessible to the user.
No
Third Application Credential Password Provide this field if your application requires a third credential. No

Start Dynamic Analyzer ASoC Scan

Starts a new Dynamic Analyzer Scan, using IBM Application Security on Cloud.
This step will generate the ScanId output property.

Input properties for the Start Dynamic Analyzer ASoC Scan step
Name Type Description Required
ASoC Application ID String The ID of the application in ASoC. Yes
Application Password Password Password for the scanned application if it contains a login. No
Application Username String Username for the scanned application if it contains a login. No
Enable Mail Notification Boolean Select this option to notify email IDs configured in ASoC. No
Fail condition threshold (H, M, L, I) String Please set the number of issues found (by severity) in a
comma-separated list. If the threshold is reached during the scan,
the scan will fail. In this field, you can specify the numbers for
these severity levels: High (H), Medium (M), Low (L), and
Informational (I). For example, a fail condition of 0,5,10,20
will cause the step to fail if the resulting scan has more than 0
High issues, 5 Medium issues, and so on. If this field is left
empty, there will be no validation of results and the scan will
not fail as a result of a fail condition.
No
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Original scan ID String If this is a rescan please enter the original scan id No
Presence ID String Specify an ID of an existing presence, which allows you to run
scans on apps not connected to the internet or require a proxy server
to make a connection. The presence must be accessible to the user.
No
Scan Name String Scan Name of the running scan. No
Scan Type Enumeration:

  • Production
  • Staging
Select the type of scan. Staging scans are more comprehensive
and designed to scan sites before production. Production scans are
designed to scan live sites.
No
Scan/Template File String The path to a configuration (SCAN or SCANT) file. Use this
field if you have specific configuration requirements. The
Starting URL that you enter above must be identical to the
Starting URL in the file.
No
Starting url String Please enter a url to scan. (You must complete Domain Verification through the UI,
as it is not currently supported by this plugin.)
Yes
Test Policy Enumeration:

  • Default
  • Application-Only
  • The Vital Few
A predefined set of tests for AppScan to use. Here is a short description for each
option: Comprehensive (Default) -> This is the most thorough Test Set and is used
by default. Application-Only -> This Test Set includes all application level tests
except invasive and port listener tests. The Vital Few -> This Test Set includes a
selection of tests that have a high probability of success. This can be useful for
evaluating a site when time is limited.
No
Third Application Credential Password Provide this field if your application requires a third credential. No

Start Static Analyzer ASoC Scan

Starts a new Static Analyzer ASoC Scan, using IBM Application Security
on Cloud. This step will generate the ScanId output property.

Input properties for the Start Static Analyzer ASoC Scan step
Name Type Description Required
ASoC Application ID String The ID of the application in ASoC. Yes
Enable Mail Notification Boolean Select this option to notify email IDs configured in ASoC. No
Fail condition threshold (H, M, L, I) String Please set the number of issues found (by severity) in a
comma-separated list. If the threshold is reached during the scan,
the scan will fail. In this field, you can specify the numbers for
these severity levels: High (H), Medium (M), Low (L), and
Informational (I). For example, a fail condition of 0,5,10,20
will cause the step to fail if the resulting scan has more than 0
High issues, 5 Medium issues, and so on. If this field is left
empty, there will be no validation of results and the scan will
not fail as a result of a fail condition.
No
IRX file/Scan directory String Please point to the IRX file to be uploaded for scanning,
or the directory that contains the files or other locations to scan.
The files and locations that can be specified in this field include:
.jar files, .war files, .ear files, Eclipse workspaces, and
scan configuration files. For example, c:\build_output\testapp.irx
or c:\build_output.
Yes
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Original scan ID String If you have previously scanned the application, please enter
the original scan ID here if you want to rescan it.
No
Scan configuration file String Please point to the path and file name of a scan configuration
file. This overrides any scan configuration files which may
exist in the scan directory. For example, c:\build_output\appscan-config.xml.
No
Static Analyzer Client Tool location String Please point to the directory that the client tool was unzipped
to. For example, C:\SAClientUtil. This property must be supplied
if you need to generate the IRX file.
No

Start iOS Analyzer ASoC Scan

Starts a new iOS Analyzer ASoC Scan, using IBM Application Security on
Cloud. This step will generate the ScanId output property.

Input properties for the Start iOS Analyzer ASoC Scan step
Name Type Description Required
ASoC Application ID String The ID of the application in ASoC. Yes
Application Password Password Password for the scanned application if it contains a login. No
Application Username String Username for the scanned application if it contains a login. No
Enable Mail Notification Boolean Select this option to notify email IDs configured in ASoC. No
Fail condition threshold (H, M, L, I) String Please set the number of issues found (by severity) in a
comma-separated list. If the threshold is reached during the scan,
the scan will fail. In this field, you can specify the numbers
for these severity levels: High (H), Medium (M), Low (L), and
Informational (I). For example, a fail condition of 0,5,10,20
will cause the step to fail if the resulting scan has more than 0
High issues, 5 Medium issues, and so on. If this field is left
empty, there will be no validation of results and the scan will
not fail as a result of a fail condition.
No
IPA file location String The path to the ipa file. Yes
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Original scan ID String If this is a rescan please enter the original scan id No
Presence ID String Specify an ID of an existing presence, which allows you to run
scans on apps not connected to the internet or require a proxy server
to make a connection. The presence must be accessible to the user.
No
Third Application Credential Password Provide this field if your application requires a third credential. No

Stop ASoC Presence

Stop a running ASoC presence. This step must be run on the
agent machine on which the presence was originally started.

Input properties for the Stop ASoC Presence step
Name Type Description Required
Login Key ID String The API key ID to authenticate with ASoC. Yes
Login Key Secret Password The API key secret to authenticate with ASoC. Yes
Presence ID String Specify an ID of an existing presence, which allows you to run
scans on apps not connected to the internet or require a proxy server
to make a connection. The presence must be accessible to the user.
No