Consolidate examples and tidy docs (#307)

* consolidate examples and workflow_examples dirs

* markdown lint readme

* Move defectdojo docs to separate file

* update examples

docs/DEFECT_DOJO.md

@@ -0,0 +1,77 @@
+# Exporting to DefectDojo
+
+RapiDAST supports integration with OWASP DefectDojo which is an open source vulnerability management tool.
+
+## Preamble: creating DefectDojo user
+
+RapiDAST needs to be able to authenticate to your DefectDojo instance. However, ideally, it should have the minimum set of permissions, such that it will not be allowed to modify products other than the one(s) it is supposed to.
+
+In order to do that:
+
+- create a user without any global role
+- add that user as a "writer" for the product(s) it is supposed to scan
+
+Then the product, as well as an engagement for that product, must be created in your DefectDojo instance. It would not be advised to give the RapiDAST user an "admin" role and simply set `auto_create_context` to True, as it would be both insecure and accident prone (a typo in the product name would let RapiDAST create a new product)
+
+## Exporting to Defect Dojo
+
+RapiDAST will send the results directly to a DefectDojo service. This is a typical configuration:
+
+```yaml
+config:
+  # Defect dojo configuration
+  defectDojo:
+    url: "https://mydefectdojo.example.com/"
+    ssl: [True | False | "/path/to/CA"]
+    authorization:
+      username: "rapidast_productname"
+      password: "password"
+      # alternatively, a `token` entry can be set in place of username/password
+```
+
+The `ssl` parameter is provided as the Python Requests module's `verify` parameter. It can be either:
+
+- True: SSL verification is mandatory, against the default CA bundle
+- False: SSL verification is not mandatory (but prints a warning if it fails)
+- /path/to/CA: a bundle of CAs to verify from
+
+Alternatively, the `REQUESTS_CA_BUNDLE` environment variable can be used to select a CA bundle file. If nothing is provided, the default value will be `True`
+
+You can either authenticate using a username/password combination, or a token (make sure it is not expired). In either case, you can use the `_from_var` method described in the previous chapter to avoid hardcoding the value in the configuration.
+
+## Configuration of exported data
+
+The data exported follows the Defectdojo methodology of "Product → Engagement → Test" : a test, such as a ZAP scan, belongs to an engagement for a product.
+Its configuration is made under the `scanners.<scanner>.defectDojoExport.parameters` configuration entries. As a baseline, parameters from the Defectdojo `import-scan` and `reimport-scan` are accepted.
+
+For each scan, the logic applied is the following, in order:
+
+- If a test ID is provided (parameter `test`), this scan will replace the previous one (a "reimport" in Defectdojo)
+- If an engagement ID is provided (parameter `engagement`), this scan will be added as a new test in that existing engagement
+- If an engagement and a product are given by name (`engagement_name` and `product_name` parameters), this scan will be added for that given engagement for the given product
+
+In each `defectDojoExport.parameters`, some defaults parameters are applied:
+
+- `product_name`, in order (the first non empty value found):
+  - `application.productName`
+  - `application.shortName` (this name should not contain non-printable characters, such as spaces)
+- `engagement_name` defaults to `RapiDAST-<product name>-<date>`
+- `scan_type` : filled by the scanner
+- `active`: `True`
+- `verified`: `False`
+
+As a reminder: values from `general` are applied to each scanner.
+
+Here is an example:
+
+```yaml
+scanners:
+  zap:
+    defectDojoExport:
+      parameters:
+        product_name: "My Product"
+        engagement_name: "RapiDAST" # or engagement: <engagement_id>
+        #test: <test_id>
+```
+
+See <https://documentation.defectdojo.com/integrations/importing/#api> for more information.

examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+The code examples in this directory show how RapiDAST can be run in various CI/CD pipelines. For RapiDAST configuration templates, see [here](../config).
+
+## Recommendations
+
+The recommended strategy for integrating RapiDAST in CI/CD pipelines is to build the target application as a container image, deploy it in the pipeline, then pull down the RapiDAST container image and launch a RapiDAST scan.
+
+Running both the target application and RapiDAST in containers simplifies the work needed to bootstrap both (e.g. skipping dependency installation) and provides strong guarantees on stability and reproducibility.

examples/github/README.md

@@ -0,0 +1,8 @@
+# RapiDAST in GitHub
+
+See the sample [workflow.yml](./workflow.yml) file for details.
+
+## Notes
+
+- The example [workflow.yml](./workflow.yml) file can be included in a github source repository in a path like `.github/workflows/rapidast.yml`
+- The "rapidast-config.yml" file is expected to be in the source repository already. See [here](../config) for config templates.

examples/github/workflow.yml

@@ -0,0 +1,38 @@
+# place in a location like .github/workflows/rapidast.yml
+name: rapidast-report
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  rapidast:
+    runs-on: ubuntu-latest
+    container:
+      image: quay.io/redhatproductsecurity/rapidast:latest
+      options: --user root # default rapidast user not compatible with github runners
+
+    # Target application to scan goes here. This contains a stub example for httpd.
+    # A more realistic example would target a custom container image built
+    # and pushed to a public container registry in an earlier build step.
+    #
+    # In the rapidast config file, for this example "http://httpd" would be the target URL.
+    #
+    services:
+      httpd:
+        image: docker.io/httpd:latest
+
+    # Scan target app with rapidast and upload results
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: run rapidast
+        run: |
+          rapidast.py --config rapidast-config.yml
+          # Display ZAP scan results in logs
+          cat results/*/*/zap/zap-report.json
+
+      - name: Upload rapidast results
+        uses: actions/upload-artifact@v4
+        with:
+          path: 'results/*/*/*'

examples/gitlab/.gitlab-ci.yml

@@ -3,11 +3,18 @@ default:
   - shared # use shared gitlab runners
 
 job:
+  # Target application to scan goes here. This contains a stub example for httpd.
+  # A more realistic example would target a custom container image built
+  # and pushed to a public container registry in an earlier build step.
+  #
+  # In the rapidast config file, for this example "http://httpd" would be the target URL.
+  services:
+    - name: registry.redhat.io/rhel9/httpd-24:latest
   image:
-    name: quay.io/redhatproductsecurity/rapidast:development
-    entrypoint: [""] # setting entrypoint is required after rapidast v2.9.1
+    name: quay.io/redhatproductsecurity/rapidast:latest
+    entrypoint: [""] # overwriting the entrypoint is required after rapidast v2.9.1
   script:
-  - rapidast.py --config custom-config.yaml
+  - rapidast.py --config rapidast-config.yml
   artifacts:
     paths:
     - ./results/

examples/gitlab/README.md

@@ -0,0 +1,8 @@
+# RapiDAST in Gitlab
+
+See the sample [.gitlab-ci.yml](.gitlab-ci.yml) file for details.
+
+## Notes
+
+- The example [.gitlab-ci.yml](.gitlab-ci.yml) file can be included in a gitlab source repository
+- The "rapidast-config.yaml" file is expected to be in the source repository already. See [here](../config) for config templates.

examples/jenkins/README.md

@@ -0,0 +1,3 @@
+# RapiDAST in Jenkins
+
+This directory contains multiple examples for running RapiDAST in Jenkins.

workflow_examples/jenkins/oauth-rtoken/rapidast-job-definition-oauth-rtoken.groovy → examples/jenkins/oauth-rtoken/rapidast-job-definition-oauth-rtoken.groovy

@@ -22,7 +22,7 @@ pipelineJob('rapidast-scan-job') {
     }
     definition {
         cps {
-            script(readFileFromWorkspace('workflow_examples/jenkins/rapidastscan.groovy'))
+            script(readFileFromWorkspace('examples/jenkins/rapidastscan.groovy'))
             sandbox()
         }
     }

workflow_examples/jenkins/simple-openapi-authorization-token/rapidast-job-definition.groovy → examples/jenkins/simple-openapi-authorization-token/rapidast-job-definition.groovy

@@ -18,7 +18,7 @@ pipelineJob('rapidast-simple-openapi-scan-job') {
     }
     definition {
         cps {
-            script(readFileFromWorkspace('/path/to/workflow_examples/jenkins/simple/rapidastscan.groovy'))
+            script(readFileFromWorkspace('/path/to/examples/jenkins/simple/rapidastscan.groovy'))
             sandbox()
         }
     }