SecureCodeBox tools for Command Line Interface

This directory contains tools for executing SCB functions inside a Bash shell.

run_scanner.sh

Syntax: ./run_scanner.sh [options] scanner target Runs a scanner and stores findings on disk. Helpful for use in combination with Continuous integration software like Jenkins, Bamboo, etc. The following scanners (scanner parameter) and variants are currently supported:

Arachni (arachni)
Nikto (nikto)
NMAP (nmap)
Combined NMAP, Nikto (nmap-nikto)
SSLyze (sslyze)
Zed Attack Proxy (zap)

Simple example

A simple call looks like this: ./run_scanner.sh sslyze example.com:443

This call queries the local SCB instance (expected to run on http://localhost:8080) to start the SSLyze securityTest for the host example.com on port 443. Afterwards it repeatedly polls the status of the started securityTest via the secureCodeBox Engine API untill the securityTest is finished. It performs a maximum of 180 api calls where it waits for 5 seconds between each call.

Complex example

A more elaborate call could look like this: ./run_scanner.sh --backend http://scb_engine:8080 --auth kermit:myPassword --max_iter 10 --wait 20 --context feature-team-3 zap http://www.example.com/shop

This call executes the remote SCB instance on http://scb_engine:8080 to start the OWASP Zed Attack Proxy for the URL http://www.example.com/shop. For all with the secureCodeBox Engine the HTTP Basic authentication credentials "kermit:myPassword" are used. It performs a maximum of 10 api calls and waits for 20 seconds between each call. Depending on the configured persistence provider of the secureCodeBox Engine instance the context will be used to isolate the results so that they are only accessible by members of feature-team-3.

Mandatory parameters

./run_scanner.sh scanner target The script expects to receive at least two arguments scanner and target,

scanner: SCB scan engine to run the test on
target: Target hostname / IP address / URI to scan

While some scanners require the scan target to have a specific format (URI, hostname, hostname and port, etc.) the run_scanner.sh script is able to automatically transform the given argument to match the required format. Thus, it is safe to always pass a target URI, like for example http://www.example:8080/some/path, regardless of the scanner to use.

Optional parameters

The following optional parameters may be passed:

--help: Displays a help page
--auth: HTTP Basic authentication string
--max-iter: Maximum number of api call to perform while polling
--wait: Number of seconds to wait between api calls
--context: SCB context to use
--name: Target name, to identify the target later. This can be helpfull when the url is temporary and cant later be traced to a specific service / team.

In Depth Configuration of securityTests

More involved security Tests require tweaking of the target attributes to configure the security scanner correctly. To give you full controll over the securityTest configuration you can use the --payload argument to provide a link to a custom json payload. For examples check out the usage examples in out user-guide.

Data files

During execution the script generates some files that are all stored in the working directory. When called it renames old data files from the previous run that facilitated the same tenant and scanner: The file extension .last is appended to each filename. The script then creates the following data files:

job_[SCANNER]_payload.json is the JSON payload which is sent to the SCB engine in order to start the scan.
job_[SCANNER]_result.json contains JSON data of all findings returned by Elasticsearch.
job_[SCANNER].log contains the console output of the script

Filenames consist of the following dynamic parts:

[SCANNER] corresponds to the scanner used.

Template files

The file job_[SCANNER]_payload.json is generated by replacing the following variables in the corresponding the template file [SCANNER].template.json:

%TENANT%: Tenant, as given; e.g. mytenant
%TARGET%: Scan target, as given; e.g. http://www.example.com:8080/shop
%HOST_PORT% Scan target, hostname and port number; e.g. www.example.com:8080
%HOST%: Scan target, hostname; e.g. www.example.com
%PORT%: Scan target, port number: e.g. 8080