Skip to content

Commit

Permalink
#1902 basic copy of zap scanner folder renamed to zap-automation-fram…
Browse files Browse the repository at this point in the history
…ework

Signed-off-by: Ilyes Ben Dlala <ilyes.bendlala@iteratec.com>
  • Loading branch information
Ilyesbdlala committed Mar 19, 2024
1 parent ee8a3aa commit f789735
Show file tree
Hide file tree
Showing 59 changed files with 26,849 additions and 0 deletions.
5 changes: 5 additions & 0 deletions scanners/zap-automation-framework/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

*.tar
252 changes: 252 additions & 0 deletions scanners/zap-automation-framework/.helm-docs.gotmpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,252 @@
{{- /*
SPDX-FileCopyrightText: the secureCodeBox authors

SPDX-License-Identifier: Apache-2.0
*/ -}}

{{- define "extra.docsSection" -}}
---
title: "ZAP Automation Framework"
category: "scanner"
type: "WebApplication"
state: "released"
appVersion: "{{ template "chart.appVersion" . }}"
usecase: "WebApp & OpenAPI Vulnerability Scanner"
---

![zap logo](https://raw.githubusercontent.com/wiki/zaproxy/zaproxy/images/zap32x32.png)

{{- end }}

{{- define "extra.dockerDeploymentSection" -}}
## Supported Tags
- `latest` (represents the latest stable release build)
- tagged releases, e.g. `3.0.0`, `2.9.0`, `2.8.0`, `2.7.0`
{{- end }}

{{- define "extra.chartAboutSection" -}}
## What is OWASP ZAP?

The [OWASP Zed Attack Proxy (ZAP)][zap owasp project] is one of the world’s most popular free security tools and is actively maintained by hundreds of international volunteers*. It can help you automatically find security vulnerabilities in your web applications while you are developing and testing your applications. It's also a great tool for experienced pentesters to use for manual security testing.

To learn more about the ZAP scanner itself visit [https://www.zaproxy.org/](https://www.zaproxy.org/).
To learn more about the ZAP Automation Framework itself visit [https://www.zaproxy.org/docs/desktop/addons/automation-framework/](https://www.zaproxy.org/docs/desktop/addons/automation-framework/).
{{- end }}

{{- define "extra.scannerConfigurationSection" -}}
## Scanner Configuration

The following security scan configuration example are based on the ZAP Docker Scan Scripts. By default, the secureCodeBox ZAP Helm Chart installs all four ZAP scripts: `zap-baseline`, `zap-full-scan` , `zap-api-scan` & `zap-automation-scan`. Listed below are the arguments supported by the `zap-baseline` script, which are mostly interchangeable with the other ZAP scripts (except for `zap-automation-scan`). For a more complete reference check out the [ZAP Documentation](https://www.zaproxy.org/docs/docker/) and the secureCodeBox based ZAP examples listed below.

The command line interface can be used to easily run server scans: `-t www.example.com`

```bash
Usage: zap-baseline.py -t <target> [options]
-t target target URL including the protocol, eg https://www.example.com
Options:
-h print this help message
-c config_file config file to use to INFO, IGNORE or FAIL warnings
-u config_url URL of config file to use to INFO, IGNORE or FAIL warnings
-g gen_file generate default config file (all rules set to WARN)
-m mins the number of minutes to spider for (default 1)
-r report_html file to write the full ZAP HTML report
-w report_md file to write the full ZAP Wiki (Markdown) report
-x report_xml file to write the full ZAP XML report
-J report_json file to write the full ZAP JSON document
-a include the alpha passive scan rules as well
-d show debug messages
-P specify listen port
-D delay in seconds to wait for passive scanning
-i default rules not in the config file to INFO
-I do not return failure on warning
-j use the Ajax spider in addition to the traditional one
-l level minimum level to show: PASS, IGNORE, INFO, WARN or FAIL, use with -s to hide example URLs
-n context_file context file which will be loaded prior to spidering the target
-p progress_file progress file which specifies issues that are being addressed
-s short output format - dont show PASSes or example URLs
-T max time in minutes to wait for ZAP to start and the passive scan to run
-z zap_options ZAP command line options e.g. -z "-config aaa=bbb -config ccc=ddd"
--hook path to python file that define your custom hooks
```

## ZAP Automation Scanner Configuration

The Automation Framework allows for higher flexibility in configuring ZAP scans. Its goal is the automation of the full functionality of ZAP's GUI. The configuration of the Automation Framework differs from the other three ZAP scan types. The following security scan configuration example highlights the differences for running a `zap-automation-scan`.
Of particular interest for us will be the -autorun option. `zap-automation-scan` allows for providing an automation file as a ConfigMap that defines the details of the scan. See the secureCodeBox based ZAP Automation example listed below for what such a ConfigMap would look like.

```bash
Usage: zap.sh -cmd -host <target> [options]
-t target target URL including the protocol, eg https://www.example.com
Add-on options:
-script <script> Run the specified script from commandline or load in GUI
-addoninstall <addOnId> Installs the add-on with specified ID from the ZAP Marketplace
-addoninstallall Install all available add-ons from the ZAP Marketplace
-addonuninstall <addOnId> Uninstalls the Add-on with specified ID
-addonupdate Update all changed add-ons from the ZAP Marketplace
-addonlist List all of the installed add-ons
-certload <path> Loads the Root CA certificate from the specified file name
-certpubdump <path> Dumps the Root CA public certificate into the specified file name, this is suitable for importing into browsers
-certfulldump <path> Dumps the Root CA full certificate (including the private key) into the specified file name, this is suitable for importing into ZAP
-notel Turns off telemetry calls
-hud Launches a browser configured to proxy through ZAP with the HUD enabled, for use in daemon mode
-hudurl <url> Launches a browser as per the -hud option with the specified URL
-hudbrowser <browser> Launches a browser as per the -hud option with the specified browser, supported options: Chrome, Firefox by default 'Firefox'
-openapifile <path> Imports an OpenAPI definition from the specified file name
-openapiurl <url> Imports an OpenAPI definition from the specified URL
-openapitargeturl <url> The Target URL, to override the server URL present in the OpenAPI definition. Refer to the help for supported format.
-quickurl <target url> The URL to attack, e.g. http://www.example.com
-quickout <filename> The file to write the HTML/JSON/MD/XML results to (based on the file extension)
-autorun <filename> Run the automation jobs specified in the file.
-autogenmin <filename> Generate template automation file with the key parameters.
-autogenmax <filename> Generate template automation file with all parameters.
-autogenconf <filename> Generate template automation file using the current configuration.
-graphqlfile <path> Imports a GraphQL Schema from a File
-graphqlurl <url> Imports a GraphQL Schema from a URL
-graphqlendurl <url> Sets the Endpoint URL
```

{{- end }}

{{- define "extra.chartConfigurationSection" -}}
The secureCodeBox provides two different scanner charts (`zap`, `zap-advanced`) to automate ZAP WebApplication security scans. The first one `zap` comes with four scanTypes:
- `zap-baseline-scan`
- `zap-full-scan`
- `zap-api-scan`
- `zap-automation-scan`

The scanTypes `zap-baseline-scan`, `zap-full-scan` & `zap-api-scan` can be configured via CLI arguments which are somehow a bit limited for some advanced usecases, e.g. using custom zap scripts or configuring complex authentication settings.

That's why we introduced this `zap-advanced` scanner chart, which introduces extensive YAML configuration options for ZAP. The YAML configuration can be split in multiple files and will be merged at start.
ZAP's own Automation Framework provides similar functionality to the `zap-advanced` scanner chart and is set to displace it in the future.

## ZAP Automation Configuration

The ZAP Automation Scanner supports the use of secrets, as to not have hardcoded credentials in the scan definition.
Generate secrets using the credentials that will later be used in the scan for authentication. Supported authentication methods for the ZAP Authentication scanner are Manual, HTTP / NTLM, Form-based, JSON-based, and Script-based.


```bash
kubectl create secret generic unamesecret --from-literal='username=<USERNAME>'
kubectl create secret generic pwordsecret --from-literal='password=<PASSWORD>'
```

You can now include the secrets in the scan definition and reference them in the ConfigMap that defines the scan options.
A ZAP Automation scan using JSON-based authentication may look like this:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: "zap-automation-scan-config"
data:
1-automation.yaml: |-

env: # The environment, mandatory
contexts: # List of 1 or more contexts, mandatory
- name: test-config # Name to be used to refer to this context in other jobs, mandatory
urls: ["http://juiceshop.demo-targets.svc:3000"] # A mandatory list of top level urls, everything under each url will be included
includePaths:
- "http://juiceshop.demo-targets.svc:3000/.*" # An optional list of regexes to include
excludePaths:
- ".*socket\\.io.*"
- ".*\\.png"
- ".*\\.jpeg"
- ".*\\.jpg"
- ".*\\.woff"
- ".*\\.woff2"
- ".*\\.ttf"
- ".*\\.ico"
authentication:
method: "json"
parameters:
loginPageUrl: "http://juiceshop.demo-targets.svc:3000/rest/user"
loginRequestUrl: "http://juiceshop.demo-targets.svc:3000/rest/user/login"
loginRequestBody: '{"email":"${EMAIL}","password":"${PASS}"}'
verification:
method: "response"
loggedOutRegex: '\Q{"user":{}}\E'
loggedInRegex: '\Q<a href="password.jsp">\E'
users:
- name: "juiceshop-user-1"
credentials:
username: "${EMAIL}"
password: "${PASS}"
parameters:
failOnError: true # If set exit on an error
failOnWarning: false # If set exit on a warning
progressToStdout: true # If set will write job progress to stdout

jobs:
- type: passiveScan-config # Passive scan configuration
parameters:
maxAlertsPerRule: 10 # Int: Maximum number of alerts to raise per rule
scanOnlyInScope: true # Bool: Only scan URLs in scope (recommended)
- type: spider # The traditional spider - fast but doesnt handle modern apps so well
parameters:
context: test-config # String: Name of the context to spider, default: first context
user: juiceshop-user-1 # String: An optional user to use for authentication, must be defined in the env
maxDuration: 2 # Int: The max time in minutes the spider will be allowed to run for, default: 0 unlimited
- type: spiderAjax # The ajax spider - slower than the spider but handles modern apps well
parameters:
context: test-config # String: Name of the context to spider, default: first context
maxDuration: 2 # Int: The max time in minutes the ajax spider will be allowed to run for, default: 0 unlimited
- type: passiveScan-wait # Passive scan wait for the passive scanner to finish
parameters:
maxDuration: 10 # Int: The max time to wait for the passive scanner, default: 0 unlimited
- type: report # Report generation
parameters:
template: traditional-xml # String: The template id, default : modern
reportDir: /home/securecodebox/ # String: The directory into which the report will be written
reportFile: zap-results # String: The report file name pattern, default: [[yyyy-MM-dd]]-ZAP-Report-[[site]]
risks: # List: The risks to include in this report, default all
- high
- medium
- low
---
apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
name: "zap-example-scan"
spec:
scanType: "zap-automation-scan"
parameters:
- "-autorun"
- "/home/securecodebox/scb-automation/1-automation.yaml"
volumeMounts:
- mountPath: /home/securecodebox/scb-automation/1-automation.yaml
name: zap-automation
subPath: 1-automation.yaml
volumes:
- name: zap-automation
configMap:
name: zap-automation-scan-config
env:
- name: EMAIL
valueFrom:
secretKeyRef:
name: unamesecret
key: username
- name: PASS
valueFrom:
secretKeyRef:
name: pwordsecret
key: password
```

For a complete overview of all the possible options you have for configuring a ZAP Automation scan, run
```bash
./zap.sh -cmd -autogenmax zap.yaml
```
For an overview of all required configuration options, run
```
bash ./zap.sh -cmd -autogenmin zap.yaml
```
Alternatively, have a look at the [official documentation](https://www.zaproxy.org/docs/desktop/addons/automation-framework/).
{{- end }}

{{- define "extra.scannerLinksSection" -}}
[zap owasp project]: https://owasp.org/www-project-zap/
[zap github]: https://github.com/zaproxy/zaproxy/
[zap user guide]: https://www.zaproxy.org/docs/
[zap automation framework]: https://www.zaproxy.org/docs/desktop/addons/automation-framework/
{{- end }}
40 changes: 40 additions & 0 deletions scanners/zap-automation-framework/.helmignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0
# Patterns to ignore when building packages.
# This supports shell glob matching, relative path matching, and
# negation (prefixed with !). Only one pattern per line.
.DS_Store
# Common VCS dirs
.git/
.gitignore
.bzr/
.bzrignore
.hg/
.hgignore
.svn/
# Common backup files
*.swp
*.bak
*.tmp
*~
# Various IDEs
.project
.idea/
*.tmproj
.vscode/
# Node.js files
node_modules/*
package.json
package-lock.json
src/*
config/*
Dockerfile
.dockerignore
*.tar
parser/*
scanner/*
integration-tests/*
examples/*
docs/*
Makefile
28 changes: 28 additions & 0 deletions scanners/zap-automation-framework/Chart.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

apiVersion: v2
name: zap
description: A Helm chart for the OWASP ZAP security scanner that integrates with the secureCodeBox.
type: application
# version - gets automatically set to the secureCodeBox release version when the helm charts gets published
version: v3.1.0-alpha1
appVersion: "2.14.0"
kubeVersion: ">=v1.11.0-0"
annotations:
versionApi: https://api.github.com/repos/zaproxy/zaproxy/releases/latest
supported-platforms: linux/amd64,linux/arm64
keywords:
- security
- Zap
- OWASP
- scanner
- secureCodeBox
home: https://www.securecodebox.io/docs/scanners/ZAP
icon: https://www.securecodebox.io/img/integrationIcons/ZAP.svg
sources:
- https://github.com/secureCodeBox/secureCodeBox
maintainers:
- name: iteratec GmbH
email: secureCodeBox@iteratec.com
24 changes: 24 additions & 0 deletions scanners/zap-automation-framework/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
#!/usr/bin/make -f
#
# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0
#

include_guard = set
scanner = zap-automation-framework

include ../../scanners.mk

deploy-test-deps: deploy-test-dep-juiceshop deploy-test-dep-nginx deploy-test-dep-bodgeit deploy-test-dep-petstore

#Run integration tests for the ZAP Automation Framework Scanner.
integration-tests:
@echo ".: 🩺 Starting integration test in kind namespace 'integration-tests'."
kubectl -n integration-tests delete scans --all
kubectl -n integration-tests delete configmaps --all
helm -n integration-tests upgrade --install $(scanner) ./ --wait \
--set="parser.image.repository=docker.io/$(IMG_NS)/$(parser-prefix)-zap" \
--set="parser.image.tag=$(IMG_TAG)"
kubectl apply -f ./integration-tests/automation-framework-configMap.yaml -n integration-tests
cd $(SCANNERS_DIR) && npm ci && cd $(scanner)/integration-tests && npm run test:integration -- $(scanner)/integration-tests

0 comments on commit f789735

Please sign in to comment.