secureCodeBox · J12934 · Nov 27, 2018 · Nov 15, 2018 · Nov 15, 2018 · Nov 15, 2018
diff --git a/cli/.gitignore b/cli/.gitignore
@@ -0,0 +1,5 @@
+*
+!*.template.json
+!README.html
+!run_scanner.sh
+!.gitignore
diff --git a/cli/README.md b/cli/README.md
@@ -3,60 +3,74 @@
 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`)
-* NMAP, raw results (`nmap-raw`)
-* Combined NMAP, Nikto (`nmap-nikto`)
-* SSLyze (`sslyze`)
-* Zed Attack Proxy (`zap`)
+
+- 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 scanner for the host `example.com` on port `443`. Afterwards it repeatedly queries the local Elasticsearch engine (expected to run on `http://localhost:9200`) until scan results (findings) have been received and their number has been verified. It performs a maximum of `30` queries to Elasticsearch where it waits for `60` seconds between each query operation.
+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 http://es_engine:9200 --auth a2VybWl0OmE= --max_iter 10 --wait 20 --tenant mytenant zap http://www.example.com/shop`
+`./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`. An HTTP Basic authentication is performed with header value `a2VybWl0OmE=`. Afterwards it queries the Elasticsearch engine on `http://es_engine:9200` for findings. It performs a maximum of `10` queries to Elasticsearch and waits for `20` seconds between each query operation. All operations are performed on the `mytenant` tenant.
+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
+
+- `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 Elasticsearch queries to perform
-* `--tenant`: SCB/Elasticsearch tenant to address
-* `--wait`: Number of seconds to wait between Elasticsearch queries
+
+- `--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](https://github.com/secureCodeBox/secureCodeBox/blob/master/docs/user-guide/README.md#in-depth-scan-examples).
 
 ### 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_[TENANT]_[SCANNER]_payload.json` is the JSON payload which is sent to the SCB engine in order to start the scan.
-* `job_[TENANT]_[SCANNER]_result.json` contains JSON data of all findings returned by Elasticsearch.
-* `job_[TENANT]_[SCANNER]_result.readable` contains all findings returned by Elasticsearch. The contents are said to be somewhat more readable than their JSON counterpart.
-* `job_[TENANT]_[SCANNER].log` contains the console output of the script
+
+- `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:
-* `[TENANT]` corresponds to the value passed to the `--tenant` parameter and
-* `[SCANNER]` corresponds to the scanner used.
+
+- `[SCANNER]` corresponds to the scanner used.
 
 ### Template files
-The file `job_[TENANT]_[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`
 
+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`
diff --git a/cli/arachni.template.json b/cli/arachni.template.json
@@ -1,7 +1,10 @@
 [
-	{
-		"name" : "Target",
-		"location" : "%TARGET%"
-	}
+  {
+    "context": "%CONTEXT%",
+    "name": "arachni",
+    "target": {
+      "location": "%HOST%",
+      "name": "%TARGET_NAME%"
+    }
+  }
 ]
-
diff --git a/cli/nikto.template.json b/cli/nikto.template.json
@@ -1,10 +1,10 @@
 [
-	{
-		"name" : "Target",
-    	"location" : "%HOST%",
-        "attributes" : {
-            "NIKTO_PORTS" : "%PORT%"
-        }
-	}
+  {
+    "context": "%CONTEXT%",
+    "name": "nikto",
+    "target": {
+      "location": "%HOST%",
+      "name": "%TARGET_NAME%"
+    }
+  }
 ]
-
diff --git a/cli/nmap-nikto.template.json b/cli/nmap-nikto.template.json
@@ -1,7 +1,10 @@
 [
-	{
-		"name" : "Target",
-    	"location" : "%HOST%"
-	}
+  {
+    "context": "%CONTEXT%",
+    "name": "nmap-nikto",
+    "target": {
+      "location": "%HOST%",
+      "name": "%TARGET_NAME%"
+    }
+  }
 ]
-
diff --git a/cli/nmap-raw.template.json b/cli/nmap-raw.template.json
diff --git a/cli/nmap.template.json b/cli/nmap.template.json
@@ -1,7 +1,10 @@
 [
-	{
-		"name" : "Target",
-    	"location" : "%HOST%"
-	}
+  {
+    "context": "%CONTEXT%",
+    "name": "nmap",
+    "target": {
+      "location": "%HOST%",
+      "name": "%TARGET_NAME%"
+    }
+  }
 ]
-