adding a handy example showing how to automate the pentest within the…

… CI pipeline

This uses docker and docker-compose to run sandbox with sonarqube, zap tool and zap-sonar-plugin altogether in 3 steps :

1. run a sonarqube instance using docker with zap-sonar-plugin installed
2. generate a zapproxy.html report
3. publish the zapproxy.html report to sonarqube

README.md

@@ -40,6 +40,28 @@ sonar.zaproxy.htmlReportPath=${WORKSPACE}/zaproxy-htmlReport.html
 sonar.zaproxy.rulesFilePath=${WORKSPACE}/myrules.xml
 ```
 
+## Example of automation with a CI toolchain
+
+```sh
+cd example
+
+docker-compose up -d sonarqube
+sleep 120
+# wait 2 minute for sonarqbue to start
+
+export PLUGIN_VERSION=2.2.0
+wget https://github.com/Coveros/zap-sonar-plugin/releases/download/sonar-zap-plugin-${PLUGIN_VERSION}/sonar-zap-plugin-${PLUGIN_VERSION}.jar -O ./plugin/sonar-zap-plugin-${PLUGIN_VERSION}.jar
+
+export APP_URL_UNDER_TEST='your-url-under-test'
+docker-compose up owasp-zap
+docker-compose up sonar-scanner
+```
+
+  * If you wish to run the zap tool within the CI pipeline:
+  ** you may refet to the [example](example)
+  ** You need to have docker and docker-compose installed
+  ** You may refer to [.gitlab-ci.yml](example/.gitlab-ci.yml) if you wish to run on Gitlab CI
+
 ## History
 
 The ZAP SonarQube Plugin is derived from the

example/.gitignore

@@ -0,0 +1,32 @@
+.scannerwork
+
+### IntelliJ IDEA ###
+.idea
+*.iws
+*.iml
+*.ipr
+
+### VS Code ###
+.vscode/
+
+### Eclipse ###
+.classpath
+.factorypath
+.project
+.settings
+.metadata
+.springBeans
+.sts4-cache
+bin/
+tmp/
+*.tmp
+*.bak
+*.swp
+*.launch
+
+### Vim ###
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-v][a-z]
+[._]sw[a-p]
+Session.vim

example/.gitlab-ci.yml

@@ -0,0 +1,33 @@
+image: openjdk:13-slim
+
+stages:
+  - pentest
+
+# please make sure to install the zap-sonar-plugin on sonarqube
+
+owasp-zap:
+  image: docker:19.03.12
+  stage: pentest
+  services:
+    - name: docker:19.03.12-dind
+      command: ["--insecure-registry=registry.gitlab.com"]
+  variables:
+    DOCKER_DRIVER: overlay2
+    APP_URL_UNDER_TEST: https://oneprofile.io/auth
+    PLUGIN_VERSION: 2.2.0
+  before_script:
+    - apk add --no-cache make git wget
+    - apk add --no-cache docker-compose
+    - docker info
+  script:
+    - wget https://github.com/Coveros/zap-sonar-plugin/releases/download/sonar-zap-plugin-${PLUGIN_VERSION}/sonar-zap-plugin-${PLUGIN_VERSION}.jar -O ./plugin/sonar-zap-plugin-${PLUGIN_VERSION}.jar
+    - docker-compose up -d sonarqube
+    - sleep 75
+    - docker-compose up owasp-zap
+    - docker-compose up sonar-scanner
+  only:
+    - master
+    - develop
+
+after_script:
+  - echo "End CI"

example/Makefile

@@ -0,0 +1,34 @@
+#!make
+
+# Makefile for Demo Auth Serve
+SHELL := /bin/sh
+
+export APP_URL_UNDER_TEST ?= 'https://oneprofile.io/auth'
+export PLUGIN_VERSION ?= 2.2.0
+
+$(info URL of the application under test = $(APP_URL_UNDER_TEST))
+
+#build:
+#	@docker-compose build sonarqube-build
+
+sonarqube:
+	@wget https://github.com/Coveros/zap-sonar-plugin/releases/download/sonar-zap-plugin-${PLUGIN_VERSION}/sonar-zap-plugin-${PLUGIN_VERSION}.jar -O ./plugin/sonar-zap-plugin-${PLUGIN_VERSION}.jar
+	@docker-compose up -d sonarqube
+
+zap:
+	@docker-compose up owasp-zap
+
+sonar-scan:
+	@docker-compose up sonar-scanner
+
+zap-scan: zap sonar-scan
+
+run:
+	@wget https://github.com/Coveros/zap-sonar-plugin/releases/download/sonar-zap-plugin-${PLUGIN_VERSION}/sonar-zap-plugin-${PLUGIN_VERSION}.jar -O ./plugin/sonar-zap-plugin-${PLUGIN_VERSION}.jar
+	@docker-compose up -d sonarqube
+	@sleep 75
+	@docker-compose up owasp-zap
+	@docker-compose up sonar-scanner
+
+down:
+	@docker-compose down

example/README.md

@@ -0,0 +1,58 @@
+# zap-sonar-plugin-example
+
+## Prerequisites
+
+* [Git](https://git-scm.com/downloads)
+* [Make](https://www.gnu.org/software/make/)
+* [Docker](https://docs.docker.com/install/) and [docker-compose](https://docs.docker.com/compose/install/)
+
+## Scan the vulnerabilitis with owasp-zap tool
+
+```sh
+export PLUGIN_VERSION=2.2.0
+export APP_URL_UNDER_TEST='your-url-under-test'
+make run
+```
+
+or
+
+```sh
+docker-compose up -d sonarqube
+sleep 120
+# wait 2 minute for sonarqbue to start
+
+export PLUGIN_VERSION=2.2.0
+wget https://github.com/Coveros/zap-sonar-plugin/releases/download/sonar-zap-plugin-${PLUGIN_VERSION}/sonar-zap-plugin-${PLUGIN_VERSION}.jar -O ./plugin/sonar-zap-plugin-${PLUGIN_VERSION}.jar
+
+export APP_URL_UNDER_TEST='your-url-under-test'
+docker-compose up owasp-zap
+docker-compose up sonar-scanner
+```
+
+Then go to [sonarqube](http://localhost:9000)
+
+Please have a look on `.gitlab-ci.yml` if you wish to run the scan wihtin the Gitlab CI pipeline.
+
+## Vulnerabilities Scan
+
+The Open Web Application Security Project (OWASP) team recommends many [tools](https://www.owasp.org/index.php/Appendix_A:_Testing_Tools) to address security matters, allowing to scan the vulnerabilities of Web Applications.One of the most popular is OWASP `Zed Attack Proxy` (**ZAP**).
+
+## OWASP Zap Tool
+
+The Open Web Application Security Project (OWASP) provides a security tool, called `Zed Attack Proxy` (**ZAP**) to scan the vulnerabilities.
+
+![Alt Text](assets/owasp-zap-2.8.0.png)
+
+You may download the standalone application [here](https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project) or use it with CLI.Using the CLI is interesting as in the software industry, we may want to automate to this inside the Continuous Integration (**CI**) toolchain.
+
+OWASP ZAP is one of the most popular security tools and is actively maintained. It comes with a UI and it allows to launch an automated scan against a URL of a web application. It then generate a report.
+
+![Alt Text](assets/zaproxy-report.html)
+
+The generated report is then published to Sonarqube by this hereby plugin. As a result, all metrics related to a software are gathered at one place.
+
+## Quality Metrics
+
+Once this is done, we can see the [vulnerabilities](http://127.0.0.1:9000) metrics on SonarQube.
+
+![Alt Text](assets/sonarqube-vulnerabilities.png)