The HCL
AppScan Jenkins plug-in allows you to add security
scan support to your Jenkins projects. The plug-in allows you to connect to HCL AppScan on Cloud on HCL AppScan on Cloud.
Procedure
-
In Jenkins, install the HCL
AppScan plug-in:
-
Select Manage Jenkins and then Manage
Plugins.
-
Select the Available tab and then select the
check box next to HCL
AppScan.
-
Click one of the installation buttons at the bottom of the page. After
installing the HCL
AppScan plug-in, you must
restart Jenkins before using it. However, you may want to install it and
then restart Jenkins later (for example, if you have running
jobs).
Note: Depending on the version of Jenkins that you are running, these steps may
vary slightly.
-
After restarting Jenkins, add credentials so that your build project can
connect to AppScan on Cloud:
-
In the Jenkins dashboard, select
Credentials.
-
In the Credentials page, add new global credentials. To do this, select
the arrow icon next to the (global) link and then
select Add credentials.
-
In the credentials page, select HCL AppScan on Cloud Credentials
in the Kind list.
-
Specify an AppScan on Cloud server URL for the connection. By
default, the URL is
https://cloud.appscan.com
.
-
When you generate an API key in the AppScan on Cloud service,
you receive a Key Id and Key
Secret. Enter these values in the
ID and Secret fields.
If you have not yet generated an API key, follow the link for creating
one.
-
Optional: Use the Label field to add an
identifier for the credentials.
-
In the Jenkins dashboard, select your Jenkins project to edit it and then click
Configure. Complete these steps in the project's General tab:
-
In the Build section, select the arrow icon next to the action for adding a build step. The
label on this action will vary depending on the type of project. Examples include Add
Build Step and Add Post-Build Step.
-
Select Run AppScan on Cloud/AppScan 360° Security
Test.
-
In the Credentials list, select the credentials that you added in the
above step. If you added a label identifier for the credentials, it will appear in the list. If you
did not add a label, your Key Id and hidden Key Secret will display.
-
Security scans must be associated with an existing AppScan on Cloud
application. Select the application in the Application list.
Note: The Application list is populated based on your credentials. The
application must already exist in the AppScan on Cloud service. The list
will be empty if no applications have been created in the service.
-
Optional: In the Test Name field, enter a name
for the scan. If you complete this field, the scan will have that name
(with timestamp appended) in the AppScan on Cloud service. In
addition, the name will be used to differentiate results in various
Jenkins views.
-
In the Test Type section:
- Select Dynamic Analysis (DAST) to
perform analysis of an application that runs in a browser. If
this test type is selected, use the required Starting
URL field to enter the URL from where you want
the scan to start exploring the site. If you select the Additional
Options check box, these optional settings
also are available:
- Scan Type: Select whether your
site is a Staging site (under
development) or a Production site
(live and in use).
- Optimization: Specify whether to scan with No
Optimization (regular in-depth scan with longer
scan time and maximum vulnerability coverage, the
default), Fast (up to twice as fast, ~97%
vulnerability coverage), Faster (up to five times
as fast, ~85% vulnerability coverage), or Fastest
(up to ten times as fast, ~70% vulnerability
coverage).
- Presence ID:
If your app is not on the internet, enter your AppScan
Presence ID. Information about
creating an AppScan Presence is available here.
- Scan File: If you have an AppScan
Standard scan file, enter its full path and file name in
this field. To learn more about
AppScan
Standard scan files, see this topic.
- Application login:Specify login
information that will allow AppScan on Cloud to
scan pages that require authentication:
- Select Login not required
if additional authentication is unnecessary.
- Select Login required: Username and
Password to provide valid user
credentials for the page:
- Login User: A valid
user name.
- Login Password: A valid
password.
- Extra Credential: A
third login credential, if required by the
site.
- Select Login required: Record
login to provide a recorded login
sequence for the page. Detail the path of the
login sequence data file in Login
Sequence File. AppScan
supports the dast.config file
type for such files.
To learn more about these settings,
see this topic. Dynamic analysis (DAST) is available
in AppScan on Cloud only.
- Select Software Composition
Analysis (SCA) to scan open source libraries. If this
test type is selected, use the required Target Directory
field to enter the full path to the directory that contains the
files or an IRX file that you want to scan.
Note: AppScan on Cloud now performs static analysis (SAST) and open source
analysis (SCA) analysis as separate scans. To run an open
source-only scan, use the Software Composition Analysis
(SCA) scan type. The open source-only option will be removed
from SAST scans in a future release.
- Select Software
Composition Analysis (SCA) to run analysis on
open source packages.
For information on open source testing,
see, About Software Composition Analysis (SCA).
- Select Static Analysis (SAST) to run static analysis security testing against your build
artifacts. If this test type is selected, use the required
Target Directory field to enter the
full path to the directory that contains the files that you want
to scan. For supported file types, see Static analysis language support.
- Scan method:
- Generate IRX: Generate an IRX archive
locally from the specified files and folders. If you select the Additional
Options check box, these optional settings
also are available:
- Source Code Only: Select whether if you
want to analyze the source code only.
- Include SCA: Include
analysis of open source packages. Include
SCA creates an SCA scan in addition to a SAST scan.
- Scan Speed: Optimize scan speed and
results according to development stage. Choose
faster scans early in the development lifecycle to
identify basic security issues; choose thorough
scans later in the cycle to ensure complete
coverage for your application.
- Normal: Performs a complete analysis of
the code, identifying vulnerabilities in detail
and differentiating issues that could be reported
as false positives. This scan takes the longest to
complete.
- Fast: Performs a comprehensive analysis
of your files to identify vulnerabilities, taking
longer to complete than “Faster” or “Fastest”
scans.
- Faster: Provides a medium level of
detail of analysis and identification of security
issues. This scan takes more time to complete than
the “Fastest” option.
- Fastest: Performs a surface-level
analysis of your files to identify the most
pressing issues for remediation, taking the least
amount of time to complete.
- Upload files and folders: Upload files
and folders directly to AppScan for
immediate scanning preparation, and faster
processing. If you select the
Additional Options check
box, this optional setting also is
available:
- Include SCA: Include
analysis of open source packages. Include
SCA creates an SCA scan in addition to a SAST scan.
-
Optional: Email Notification: Select this check box if you want to receive an
email when analysis is complete.
-
Optional: Allow intervention by scan enablement
team: When selected, our scan enablement team will step
in if the scan fails, or if no issues are found, and try to fix the
configuration. This may delay the scan result. This option is selected
by default.
-
Optional: Suspend job until security analysis completes: Select this check box if
you want the Jenkins build to wait for security analysis results to be available before moving on to
the next step in the project.
-
Optional: Select the Fail build if check box to enable build failure criteria.
Once selected, add at least one build failure condition. To do this, select Add
Condition and then complete its criteria. You can set the build to fail if:
- the Total number of security issues is greater than the number that you
specify in the field.
- the total number of Critical severity
security issues is greater than the number that you specify in
the field.
- the total number of High severity security issues is greater than the
number that you specify in the field.
- the total number of Medium severity security issues is greater than the
number that you specify in the field.
- the total number of Low severity security issues is greater than the
number that you specify in the field.
Note:
- If multiple conditions are added, they will be treated as though they are separated by a logical
OR
.
- If Fail build if is selected, the Suspend job until security
analysis completes option will automatically become selected and required.
- If the Fail build if check box is deselected, any conditions that you
have added will persist but not be in effect. Conditions are only removed if you manually delete
them.
-
Click Save to add the build step and to stop configuring your Jenkins
project. Click Apply to add the build step but continue configuring the
project.
After adding a build step, you can add more Run Security Test build
steps to your project.
-
After you run your Jenkins project, if you open the build, you will see a
snapshot of security findings. In addition, Results links
for the security tests will be available. Clicking on these will open the
non-compliant security report. In the project's main status page, you will see a
trending graph of security analysis results when you have more than one set of
results.