Skip to content

Commit ce23fbd

Browse files
J12934J12934
committed
Update Scan documentation documenting missing fields and improving on
writing and grammar Closes #1923 Signed-off-by: Jannik Hollenbach <jannik.hollenbach@owasp.org>
1 parent f23a431 commit ce23fbd

File tree

1 file changed

+71
-49
lines changed

1 file changed

+71
-49
lines changed

‎documentation/docs/api/crds/scan.md‎

Lines changed: 71 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ sidebar_position: 2
88
---
99

1010
The Scan Custom Resource Definition (CRD) lets you define how a specific scan should be configured.
11-
The secureCodeBox Operator will then use this specification to execute the scan.
11+
The secureCodeBox Operator uses this specification to execute the scan.
1212

1313
## Specification (Spec)
1414

@@ -18,16 +18,16 @@ The `scanType` references the **name** of a [ScanType Custom Resource](/docs/api
1818

1919
### Parameters (Required)
2020

21-
`parameters` is a string array of command line flags which are passed to the scanner.
21+
`parameters` is a string array of command line flags that are passed to the scanner.
2222

23-
These usually contain scanner specific configurations and target specification.
23+
These typically contain scanner-specific configurations and target specifications.
2424

2525
### Env (Optional)
2626

27-
`env` lets you pass in custom environment variables to the scan container.
28-
This can be useful to pass in secret values like login credentials scanner require without having to define them in plain text.
27+
`env` lets you pass custom environment variables to the scan container.
28+
This can be useful for passing secret values like login credentials that scanners require without defining them in plain text.
2929

30-
Env has the same API as "env" property on Kubernetes Pods.
30+
The `env` field has the same API as the "env" property on Kubernetes Pods.
3131

3232
See:
3333

@@ -36,9 +36,9 @@ See:
3636

3737
### Volumes (Optional)
3838

39-
`volumes` lets you specify Kubernetes volumes that you want to use and make available to the scan container.
40-
Similarly to `env`, it can be used to pass data into a container.
41-
It has to be combined with [`volumeMounts`](#volumemounts-optional) to be useful (see below).
39+
`volumes` lets you specify Kubernetes volumes to make available to the scan container.
40+
Similar to `env`, it can be used to pass data into a container.
41+
It must be combined with [`volumeMounts`](#volumemounts-optional) to be useful (see below).
4242
It can also be used in combination with `initContainers` to provision files, VCS repositories, or other content into a scanner - see [`initContainers`](#initcontainers-optional) for an example.
4343

4444
`volumes` has the same API as the `volumes` property on Kubernetes pods.
@@ -50,7 +50,7 @@ See:
5050

5151
### VolumeMounts (Optional)
5252

53-
`volumeMounts` let you specify where you want the previously-created volumes to be mounted inside the container.
53+
`volumeMounts` lets you specify where previously-created volumes should be mounted inside the container.
5454
It is used in combination with [`volumes`](#volumes-optional) (see above).
5555

5656
`volumeMounts` has the same API as the `volumeMounts` property on Kubernetes pods.
@@ -62,10 +62,10 @@ See:
6262

6363
### InitContainers (Optional)
6464

65-
`initContainers` lets you specify a (set of) container(s) that are run before the scan itself.
66-
You can specify arbitrary containers with any command that you desire.
67-
By default, init containers do not share a file system with the scan job.
68-
If you want to use init containers to provision files or directories for the scan job, you need to explicitly create a volume and mount it to both the init container and the scan job itself (using the [`volumeMounts`](#volumemounts-optional) discussed above).
65+
`initContainers` lets you specify one or more containers that run before the scan itself.
66+
You can specify arbitrary containers with any commands you need.
67+
By default, init containers do not share a filesystem with the scan job.
68+
To use init containers for provisioning files or directories for the scan job, you must explicitly create a volume and mount it to both the init container and the scan job using [`volumeMounts`](#volumemounts-optional).
6969
For example, if you want to download a file that contains a list of scan targets for nmap, you could configure the scan like this:
7070

7171
```yaml
@@ -112,17 +112,34 @@ See:
112112
- [Documentation](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)
113113
- [API Reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#containers)
114114

115-
### Affinity and Tolerations (optional)
115+
### ResourceMode (Optional)
116116

117-
[`affinity`](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/) and [`tolerations`](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) can be used to control which nodes the parser is executed on.
117+
The `resourceMode` specifies whether the scan should use namespace-local or cluster-wide resources (ScanType vs. ClusterScanType). Valid values are:
118+
119+
- `"namespaceLocal"` (default): Uses ScanType resources from the same namespace
120+
- `"clusterWide"`: Uses ClusterScanType resources available cluster-wide
121+
122+
### NodeSelector (Optional)
123+
124+
[`nodeSelector`](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/) allows you to specify a simple node selection constraint to control which nodes the scan can be scheduled on.
125+
126+
```yaml
127+
nodeSelector:
128+
kubernetes.io/arch: amd64
129+
node-type: scanner
130+
```
131+
132+
### Affinity and Tolerations (Optional)
133+
134+
[`affinity`](https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/) and [`tolerations`](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) can be used to control which nodes the scan is executed on with more advanced rules than nodeSelector.
118135

119136
### Cascades (Optional)
120137

121138
`cascades` let you start new scans based on the results of the current scan.
122139

123140
The cascades config in the scans spec contains [Kubernetes Label Selectors](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/label-selector/) which allow you to select which [CascadingRule](https://www.securecodebox.io/docs/api/crds/cascading-rule) are allowed to be used by the cascading logic.
124141

125-
Furthermore, in the cascade config you can specify whether cascading scan should inherit parent fields:
142+
Furthermore, in the cascade config you can specify whether cascading scans should inherit fields from the parent scan:
126143

127144
- `inheritLabels`: `true`
128145
- `inheritAnnotations`: `true`
@@ -134,8 +151,8 @@ Furthermore, in the cascade config you can specify whether cascading scan should
134151
- `inheritTolerations`: `true`
135152

136153
These fields will merge the parent's entries with entries defined in the cascading rules.
137-
Entries defined in cascading rules will only apply to the current scan.
138-
There are two exceptions to this rule: in the case of Affinity and Tolerations, entries will be replaced instead of merged, and will be used for all following scans.
154+
Entries defined in cascading rules apply only to the current scan.
155+
There are two exceptions: for Affinity and Tolerations, entries are replaced rather than merged and apply to all subsequent scans.
139156

140157
:::caution
141158
Defining identical entries in both the Scan AND the Cascading Rule resource will lead to undefined behaviour.
@@ -147,9 +164,9 @@ For an example on how they can be used see the [Scanning Networks HowTo](https:/
147164

148165
#### ScopeLimiter (Optional)
149166

150-
`scopeLimiter` allows you to define certain rules to which cascading scans must comply before they may cascade.
151-
For example, you can define that you can only trigger a follow-up scan against a host if its IP address is within your predefined IP range.
152-
You can use Mustache templating in order to select certain properties from findings.
167+
`scopeLimiter` allows you to define rules that cascading scans must comply with before they may cascade.
168+
For example, you can define that follow-up scans against a host are only allowed if its IP address is within a predefined IP range.
169+
You can use Mustache templating to select specific properties from findings.
153170

154171
Under `scopeLimiter`, you may specify `anyOf`, `noneOf`, and `allOf` with a selector to limit your scope.
155172
If you specify multiple fields, all the rules must pass.
@@ -171,16 +188,18 @@ These annotations can only be added on the initial scan (i.e., they cannot be mo
171188

172189
`values` is a list of values for which the selector should pass.
173190

191+
The `validOnMissingRender` field in scopeLimiter defines whether a condition should match when a templating variable is not present in the finding. Defaults to `false`.
192+
174193
##### Selecting lists
175194

176195
A custom rendering function has been provided to select attributes in findings that are in a list. An example finding:
177196

178197
```json title="Finding"
179198
{
180-
name: "Subdomains found",
181-
category: "Subdomain"
182-
attributes: {
183-
domains: ["example.com", "subdomain.example.com"],
199+
"name": "Subdomains found",
200+
"category": "Subdomain",
201+
"attributes": {
202+
"domains": ["example.com", "subdomain.example.com"]
184203
}
185204
}
186205
```
@@ -202,17 +221,17 @@ Some findings have data in lists of objects, such as the following:
202221

203222
```json title="Finding"
204223
{
205-
name: "Subdomains found",
206-
category: "Subdomain"
207-
attributes: {
208-
addresses: [
224+
"name": "Subdomains found",
225+
"category": "Subdomain",
226+
"attributes": {
227+
"addresses": [
209228
{
210-
domain: "example.com",
211-
ip: "127.0.0.1",
229+
"domain": "example.com",
230+
"ip": "127.0.0.1"
212231
},
213232
{
214-
domain: "subdomain.example.com",
215-
ip: "127.0.0.2",
233+
"domain": "subdomain.example.com",
234+
"ip": "127.0.0.2"
216235
}
217236
]
218237
}
@@ -235,10 +254,10 @@ You can also manually split values from findings if your finding is like so:
235254

236255
```json title="Finding"
237256
{
238-
name: "Subdomains found",
239-
category: "Subdomain"
240-
attributes: {
241-
domains: "example.com,subdomain.example.com",
257+
"name": "Subdomains found",
258+
"category": "Subdomain",
259+
"attributes": {
260+
"domains": "example.com,subdomain.example.com"
242261
}
243262
}
244263
```
@@ -306,9 +325,9 @@ See the [Scope HowTo](/docs/how-tos/scope) for more information.
306325

307326
`hookSelector` allows you to select which hooks to run using [Kubernetes Label Selectors](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/label-selector/).
308327

309-
You can only select hooks in the namespace in which the scan is running.
328+
You can only select hooks within the namespace where the scan is running.
310329

311-
Leaving this field undefined will select all available hooks in this namespace.
330+
Leaving this field undefined selects all available hooks in the namespace.
312331

313332
```yaml
314333
hookSelector:
@@ -328,7 +347,7 @@ For more examples on how this field can be used, see the [Hook HowTo](/docs/how-
328347

329348
### Resources (Optional)
330349

331-
`resources` lets you overwrite the resource limits and requests for the primary scanner container from the values defined in the [ScanType](./scan-type). See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
350+
`resources` lets you override the resource limits and requests for the primary scanner container from the values defined in the [ScanType](./scan-type). See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
332351

333352
```yaml
334353
resources:
@@ -348,7 +367,7 @@ ttlSecondsAfterFinished: 30 #deletes the scan after 30 seconds after completion
348367
```
349368

350369
:::note
351-
ttlSecondsAfterFinished can also be set for the scan (as part of the [jobTemplate](https://www.securecodebox.io/docs/api/crds/scan-type#jobtemplate-required)), [parser](https://www.securecodebox.io/docs/api/crds/parse-definition) and [hook](https://www.securecodebox.io/docs/api/crds/scan-completion-hook#ttlsecondsafterfinished-optional) jobs individually. Setting these will only deleted the jobs not the entire scan.
370+
ttlSecondsAfterFinished can also be set for the scan (as part of the [jobTemplate](https://www.securecodebox.io/docs/api/crds/scan-type#jobtemplate-required)), [parser](https://www.securecodebox.io/docs/api/crds/parse-definition) and [hook](https://www.securecodebox.io/docs/api/crds/scan-completion-hook#ttlsecondsafterfinished-optional) jobs individually. Setting these will only delete the jobs, not the entire scan.
352371
:::
353372

354373
## Metadata
@@ -358,7 +377,7 @@ Metadata is a standard field on Kubernetes resources. It contains multiple relev
358377
## Status
359378

360379
Defines the observed state of a Scan. This will be filled by Kubernetes.
361-
It contains (see: [Go Type ScanStatus](https://github.com/secureCodeBox/secureCodeBox/blob/main/operator/apis/execution/v1/scan_types.go#L49))
380+
It contains (see: [Go Type ScanStatus](https://github.com/secureCodeBox/secureCodeBox/blob/main/operator/apis/execution/v1/scan_types.go#L169))
362381

363382
- `State`: State of the scan (See: [secureCodeBox | ScanControler](https://github.com/secureCodeBox/secureCodeBox/blob/main/operator/controllers/execution/scans/scan_controller.go#L105))
364383
- `FinishedAt`: Time when scan, parsers and hooks for this scan are marked as 'Done'
@@ -367,22 +386,22 @@ It contains (see: [Go Type ScanStatus](https://github.com/secureCodeBox/secureCo
367386
- `RawResultFile`: Filename of the result file of the scanner. e.g. `nmap-result.xml`
368387
- `FindingDownloadLink`: Link to download the finding json file from. Valid for 7 days
369388
- `RawResultDownloadLink`: RawResultDownloadLink link to download the raw result file from. Valid for 7 days
370-
- `Findings`: FindingStats (See [Go Type FindingStats](https://github.com/secureCodeBox/secureCodeBox/blob/main/operator/apis/execution/v1/scan_types.go#L89))
389+
- `Findings`: FindingStats (See [Go Type FindingStats](https://github.com/secureCodeBox/secureCodeBox/blob/main/operator/apis/execution/v1/scan_types.go#L218))
371390
- `ReadAndWriteHookStatus`: Status of the Read and Write Hooks
372391

373392
## Example
374393

375394
```yaml
376395
apiVersion: "execution.securecodebox.io/v1"
377396
kind: Scan
378-
status: # Set during runtime. Do not edit via values.yaml etc.
379397
metadata:
380398
name: "nmap-scanme.nmap.org"
381399
annotations:
382400
scope.cascading.securecodebox.io/cidr: "10.10.0.0/16"
383401
scope.cascading.securecodebox.io/domain: "example.com"
384402
spec:
385403
scanType: "nmap"
404+
resourceMode: "namespaceLocal"
386405
parameters:
387406
# Use nmap's service detection feature
388407
- "-sV"
@@ -395,15 +414,17 @@ spec:
395414
name: zap-customer-credentials
396415
- name: GREETING
397416
value: "Hello from the secureCodeBox :D"
417+
nodeSelector:
418+
kubernetes.io/arch: amd64
398419
cascades:
399420
inheritLabels: false
400421
inheritAnnotations: true
401422
matchLabels:
402423
securecodebox.io/intensive: light
403-
matchExpression:
404-
key: "securecodebox.io/invasive"
405-
operator: In
406-
values: [non-invasive, invasive]
424+
matchExpressions:
425+
- key: "securecodebox.io/invasive"
426+
operator: In
427+
values: [non-invasive, invasive]
407428
scopeLimiter:
408429
validOnMissingRender: true
409430
allOf:
@@ -421,4 +442,5 @@ spec:
421442
limits:
422443
cpu: 4
423444
memory: 4Gi
445+
ttlSecondsAfterFinished: 300
424446
```

0 commit comments

Comments
 (0)