Skip to content

Commit 295d7d2

Browse files
J12934J12934
committed
Regenerate readmes
Signed-off-by: Jannik Hollenbach <jannik.hollenbach@owasp.org>
1 parent bc65847 commit 295d7d2

3 files changed

Lines changed: 118 additions & 162 deletions

File tree

‎hooks/persistence-defectdojo/README.md‎

Lines changed: 59 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -56,27 +56,6 @@ This hook reads only from _raw findings_ and **not** from _secureCodeBox finding
5656

5757
For scan types which are not supported by _DefectDojo_, the generic importer is used, which will result in a less sophisticated display of the results and fewer features inside _DefectDojo_. In the worst case, it can lead to some findings being lost - see the note below.
5858

59-
:::note
60-
A big amount of findings may require higher resource limits. Changing them may be required to avoid OOM errors. The default values are:
61-
62-
```yaml
63-
requests: {
64-
cpu: "200m",
65-
memory: "100Mi"
66-
},
67-
limits: {
68-
cpu: "400m",
69-
memory: "200Mi"
70-
}
71-
```
72-
73-
For example, to set the memory limit to 512Mi, we run the following command:
74-
75-
```bash
76-
helm upgrade --namespace NAMESPACE --install persistence-defectdojo oci://ghcr.io/securecodebox/helm/persistence-defectdojo --set="hook.resources.limits.memory=512Mi"
77-
```
78-
:::
79-
8059
:::caution
8160
Be careful when using the _DefectDojo Hook_ in combination with other _ReadAndWrite Hooks_. By default, the _secureCodeBox_ makes no guarantees about the execution order of multiple ReadAndWrite hooks, they can be executed in any order. This can lead to "lost update" problems as the _DefectDojo_ hook will overwrite all findings, which disregards the results of previously run ReadAndWrite hooks. ReadOnly hooks work fine with the _DefectDojo_ hook as they are always executed after ReadAndWrite Hooks. If you want to control the order of execution of the different hooks, take a look at the [hook priority documentation](https://www.securecodebox.io/docs/how-tos/hooks#hook-order) (supported with secureCodeBox 3.4.0 and later).
8261
:::
@@ -85,29 +64,6 @@ Be careful when using the _DefectDojo Hook_ in combination with other _ReadAndWr
8564
The _DefectDojo_ hook will send all scan results to _DefectDojo_, including those for which _DefectDojo_ does not have native support. In this case, _DefectDojo_ may incorrectly deduplicate findings, which can in some cases [lead to incomplete imports and even data loss](https://github.com/DefectDojo/django-DefectDojo/issues/5312). You can set the hook to read-only mode, which will prevent it from writing the results back to _secureCodeBox_ (`--set defectdojo.syncFindingsBack=false` during installation of the hook) if you want to rule out any data loss inside _secureCodeBox_, but this will not prevent the incorrect deduplication from affecting the data you see inside _DefectDojo_ (for this, you will need to [contribute a parser to DefectDojo](https://defectdojo.github.io/django-DefectDojo/contributing/how-to-write-a-parser/)). You can also selectively disable the _DefectDojo_ hook for certain scans using the [hook selector feature](https://www.securecodebox.io/docs/how-tos/hooks#hook-selector) (supported with _secureCodeBox_ 3.4.0 and later).
8665
:::
8766

88-
### Running _Persistence DefectDojo Hook_ Locally from Source
89-
90-
For development purposes, it can be useful to run this hook locally. You can do so by following these steps:
91-
92-
1. Make sure you have access to a running [DefectDojo](https://github.com/DefectDojo/django-DefectDojo) instance.
93-
2. [Run a Scan](https://www.securecodebox.io/docs/getting-started/first-scans) of your choice.
94-
3. Supply Download Links for the Scan Results (Raw Result and Findings.json). You can access them from the
95-
included [Minio Instance](https://www.securecodebox.io/docs/getting-started/installation/#accessing-the-included-minio-instance)
96-
and upload them to a GitHub Gist.
97-
4. Set the following environment variables:
98-
- `DEFECTDOJO_URL`: URL to your DefectDojo server, e.g `DEFECTDOJO_URL="http://192.168.0.1:8080"`. (Required by _defectdojo-client-java_ lib.)
99-
- `DEFECTDOJO_USERNAME`: User you want to use to import findings, e.g `DEFECTDOJO_USERNAME="admin"`. (Required by _defectdojo-client-java_ lib.)
100-
- `DEFECTDOJO_APIKEY`: API key, e.g. `DEFECTDOJO_APIKEY="..."` (Can be fetched from the _DefectDojo_ API information page). (Required by _defectdojo-client-java_ lib.)
101-
- `DEFECTDOJO_IS_DEV`: To enable dev mode, which loads a k8s config from `~/.kube/config`, e.g. `DEFECTDOJO_IS_DEV="true"`.
102-
- `SCAN_NAME`: (optional) For mocking purpose when debugging locally, e.g `SCAN_NAME="nmap-scanme.nmap.org"`. Must be set exactly to the name of the scan used in step 2. Typically, this is set automatically by _secureCodeBox_.
103-
- `NAMESPACE`: (optional) For mocking purpose when debugging locally, e.g `NAMESPACE=my-namespace`. Typically, this is set automatically by _secureCodeBox_.
104-
5. Build the jar with gradle and run it with the following CLI arguments: \{Raw Result Download URL\} \{Findings Download URL\} \{Raw Result Upload URL\} \{Findings Upload URL\}. See the code snippet below. You have to adjust the filename of the jar. Also, you will need to change the download URLs for the Raw Result and Findings to the ones from Step 3.
105-
106-
```bash
107-
./gradlew build
108-
java -jar build/libs/defectdojo-persistenceprovider-<VERSION>>.jar https://gist.githubusercontent.com/.../scanme-nmap-org.xml https://gist.githubusercontent.com/.../nmap-findings.json https://httpbin.org/put https://httpbin.org/put
109-
```
110-
11167
## Deployment
11268
The persistence-defectdojo chart can be deployed via helm:
11369

@@ -125,24 +81,15 @@ Kubernetes: `>=v1.11.0-0`
12581
Installing the _DefectDojo_ persistenceProvider hook will add a _ReadAndWrite Hook_ to your namespace.
12682

12783
```bash
128-
kubectl create secret generic defectdojo-credentials --from-literal="username=admin" --from-literal="apikey=08b7..."
84+
kubectl create secret generic defectdojo-credentials --from-literal="apikey=08b7..."
12985

13086
helm upgrade --install dd oci://ghcr.io/securecodebox/helm/persistence-defectdojo \
13187
--set="defectdojo.url=https://defectdojo-django.default.svc"
13288
```
13389

134-
The hook will automatically import the scan results into an engagement in _DefectDojo_. If the engagement doesn't exist the hook will create the engagement (CI/CD engagement) and all objects required for it (product & product type). The hook will then pull the imported information from _DefectDojo_ and use them to replace the findings inside _secureCodeBox_.
135-
136-
In case you use a _DefectDojo_ instance with a self-signed root CA, upgrade the hook with:
90+
### Configuring Where In DefectDojo Results Are Ingested To
13791

138-
```bash
139-
helm upgrade --install dd oci://ghcr.io/securecodebox/helm/persistence-defectdojo \
140-
--set="defectdojo.url=https://defectdojo-django.default.svc" \
141-
--set-json 'hook.extraVolumes=[{"name": "ca-dojo", "configMap": {"name": "ca-dojo"}}]' \
142-
--set-json 'hook.extraVolumeMounts=[{"name": "ca-dojo", "mountPath": "/etc/ssl/certs/java/cacerts", "subPath": "cacerts", "readOnly": false}]'
143-
```
144-
145-
After, you can update `/etc/ssl/certs/java/cacerts` with your certificate.
92+
The hook will automatically import the scan results into an engagement in _DefectDojo_. If the engagement doesn't exist the hook will create the engagement (CI/CD engagement) and all objects required for it (product & product type). The hook will then pull the imported information from _DefectDojo_ and use them to replace the findings inside _secureCodeBox_.
14693

14794
You don't need any configuration for that to work, the hook will infer engagement & product names from the scan name. If you want more control over the names or add additional meta information like the version of the tested software you can add these via annotation to the scan. See examples below.
14895

@@ -228,7 +175,6 @@ _DefectDojo_ >2.0.0 refined their user access rights, allowing you to restrict t
228175

229176
#### Limitations of the Low Privileged Mode
230177

231-
- Instead of the username, the userId **must** be configured as the low privileged can't use the users list api to look up its own userId.
232178
- The configured product type must exist beforehand as the low privileged user isn't permitted to create a new one
233179
- The hook will not create / link the engagement to the _secureCodeBox_ orchestration engine tool type.
234180
- The low privileged user must have at least the `Maintainer` role in the configured product type.
@@ -240,8 +186,7 @@ kubectl create secret generic defectdojo-credentials --from-literal="apikey=08b7
240186

241187
helm upgrade --install dd oci://ghcr.io/securecodebox/helm/persistence-defectdojo \
242188
--set="defectdojo.url=http://defectdojo-django.default.svc" \
243-
--set="defectdojo.lowPrivilegedMode=true" \
244-
--set="defectdojo.authentication.userId=42"
189+
--set="defectdojo.lowPrivilegedMode=true"
245190
```
246191

247192
### DefectDojo minimum severity
@@ -314,6 +259,61 @@ spec:
314259
- "http://juice-shop.demo-targets.svc:3000"
315260
```
316261
262+
## Assinging more resources (CPU/Memory) to the Hook
263+
264+
:::note
265+
When ingesting a large amount of findings into DefectDojo, you may require higher resource limits. Changing them may be required to avoid OOM errors. The default values are:
266+
:::
267+
```yaml
268+
requests:
269+
cpu: "200m"
270+
memory: "100Mi"
271+
limits:
272+
cpu: "400m"
273+
memory: "200Mi"
274+
```
275+
276+
For example, to set the memory limit to 512Mi, we run the following command:
277+
278+
```bash
279+
helm upgrade --namespace NAMESPACE --install persistence-defectdojo oci://ghcr.io/securecodebox/helm/persistence-defectdojo --set="hook.resources.limits.memory=512Mi"
280+
```
281+
282+
### Connecting to DefectDojo Instances usign a custom Certificate Authority
283+
284+
In case you use a _DefectDojo_ instance with a self-signed root CA, upgrade the hook with:
285+
286+
```bash
287+
helm upgrade --install dd oci://ghcr.io/securecodebox/helm/persistence-defectdojo \
288+
--set="defectdojo.url=https://defectdojo-django.default.svc" \
289+
--set-json 'hook.extraVolumes=[{"name": "ca-dojo", "configMap": {"name": "ca-dojo"}}]' \
290+
--set-json 'hook.extraVolumeMounts=[{"name": "ca-dojo", "mountPath": "/etc/ssl/certs/java/cacerts", "subPath": "cacerts", "readOnly": false}]'
291+
```
292+
293+
After, you can update `/etc/ssl/certs/java/cacerts` with your certificate.
294+
295+
## Running _Persistence DefectDojo Hook_ Locally from Source
296+
297+
For development purposes, it can be useful to run this hook locally. You can do so by following these steps:
298+
299+
1. Make sure you have access to a running [DefectDojo](https://github.com/DefectDojo/django-DefectDojo) instance.
300+
2. [Run a Scan](https://www.securecodebox.io/docs/getting-started/first-scans) of your choice.
301+
3. Supply Download Links for the Scan Results (Raw Result and Findings.json). You can access them from the
302+
included [Minio Instance](https://www.securecodebox.io/docs/getting-started/installation/#accessing-the-included-minio-instance)
303+
and upload them to a GitHub Gist.
304+
4. Set the following environment variables:
305+
- `DEFECTDOJO_URL`: URL to your DefectDojo server, e.g `DEFECTDOJO_URL="http://192.168.0.1:8080"`. (Required by _defectdojo-client-java_ lib.)
306+
- `DEFECTDOJO_APIKEY`: API key, e.g. `DEFECTDOJO_APIKEY="..."` (Can be fetched from the _DefectDojo_ API information page). (Required by _defectdojo-client-java_ lib.)
307+
- `DEFECTDOJO_IS_DEV`: To enable dev mode, which loads a k8s config from `~/.kube/config`, e.g. `DEFECTDOJO_IS_DEV="true"`.
308+
- `SCAN_NAME`: (optional) For mocking purpose when debugging locally, e.g `SCAN_NAME="nmap-scanme.nmap.org"`. Must be set exactly to the name of the scan used in step 2. Typically, this is set automatically by _secureCodeBox_.
309+
- `NAMESPACE`: (optional) For mocking purpose when debugging locally, e.g `NAMESPACE=my-namespace`. Typically, this is set automatically by _secureCodeBox_.
310+
5. Build the jar with gradle and run it with the following CLI arguments: \{Raw Result Download URL\} \{Findings Download URL\} \{Raw Result Upload URL\} \{Findings Upload URL\}. See the code snippet below. You have to adjust the filename of the jar. Also, you will need to change the download URLs for the Raw Result and Findings to the ones from Step 3.
311+
312+
```bash
313+
./gradlew build
314+
java -jar build/libs/defectdojo-persistenceprovider-<VERSION>>.jar https://gist.githubusercontent.com/.../scanme-nmap-org.xml https://gist.githubusercontent.com/.../nmap-findings.json https://httpbin.org/put https://httpbin.org/put
315+
```
316+
317317
## Values
318318

319319
| Key | Type | Default | Description |

0 commit comments

Comments
 (0)