secureCodeBox · malexmave · Nov 18, 2021 · Oct 11, 2021 · Nov 1, 2021 · Nov 1, 2021
diff --git a/docs/api/crds/scan-completion-hook.md b/docs/api/crds/scan-completion-hook.md
@@ -20,6 +20,31 @@ The `type` field can be either `ReadOnly` or `ReadAndWrite`.
 
 `ReadAndWrite` hooks have the ability to update both the findings and raw scan reports. This can be used to attach additional metadata to the findings by comparing the findings to external inventory systems or APIs of cloud providers.
 
+### Priority (Optional)
+
+The `priority` field helps determine the execution order of the hook.
+Hooks with a higher priority will be scheduled before hooks with a lower priority.
+By default, hooks are given a priority of 0.
+Hooks with equal priority are scheduled according to the default schedule:
+
+1. Run ReadAndWrite hooks one by one (undefined order).
+2. Once all ReadAndWrite hooks are completed, ReadOnly hooks are scheduled in parallel.
+
+The following diagram shows an example run:
+
+```text
+                                 Priority 2                                          Priority 1                    Priority 0
+    +-------------------------------------------------------------------+     +----------------------+      +----------------------+
+    |    +--------------+       +--------------+       +--------------+ |     |    +--------------+  |      |    +--------------+  | 
+    | -> | ReadAndWrite |------>| ReadAndWrite |------>|   ReadOnly   | |     | -> |   ReadOnly   |  | ---> | -> | ReadAndWrite |  |
+    |    +--------------+       +--------------+  |    +--------------+ |     |    +--------------+  |      |    +--------------+  |
+--> |                                             |                     | --> |                      |      +----------------------+
+    |                                             |    +--------------+ |     |    +--------------+  |
+    |                                             +--->|   ReadOnly   | |     | -> |   ReadOnly   |  |
+    |                                                  +--------------+ |     |    +--------------+  |
+    +-------------------------------------------------------------------+     +----------------------+
+```
+
 ### Image (Required)
 
 The `image` field contains a container image reference for the image supposed to run as the hook.
@@ -69,6 +94,7 @@ metadata:
   name: elastic-persistence-hook
 spec:
   type: ReadOnly
+  priority: 2
   image: docker.io/securecodebox/persistence-elastic:latest
   imagePullSecrets:
   - name: image-pull-secret

diff --git a/docs/api/crds/scan.md b/docs/api/crds/scan.md
@@ -113,15 +113,55 @@ See:
 
 The cascades config in the scans spec contains [Kubernetes Label Selectors](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#labelselector-v1-meta) which allow you to select which [CascadingRule](https://docs.securecodebox.io/docs/api/crds/cascading-rule) are allowed to be used by the cascading logic.
 
-Furthermore, in the cascade config you can specify whether cascading scan should inherit the parent's labels (`inheritLabels`) and annotations (`inheritAnnotations`). If not specified, the options will be considered as `true`.
+Furthermore, in the cascade config you can specify whether cascading scan should inherit parent fields:
 
-To use cascades you'll need to have the [CombinedScan hook](https://docs.securecodebox.io/docs/hooks/cascading-scans) installed.
+* `inheritLabels`: `true`
+* `inheritAnnotations`: `true`
+* `inheritEnv`: `false`
+* `inheritVolumes`: `false`
+* `inheritInitContainers`: `false`
+* `inheritHookSelector`: `false`
+
+These fields will merge the parent's entries with entries defined in the cascading rules.
+Entries defined in cascading rules will only apply to the current scan.
+
+:::caution
+Defining identical entries in both the Scan AND the Cascading Rule resource will lead to undefined behaviour.
+See [#789](https://github.com/secureCodeBox/secureCodeBox/issues/789) for more details.
+:::
+
+
+To use cascades you'll need to have the [CascadingScan hook](https://docs.securecodebox.io/docs/hooks/cascading-scans) installed.
 
 For an example on how they can be used see the [Scanning Networks HowTo](https://docs.securecodebox.io/docs/how-tos/scanning-networks)
 
+### HookSelector (Optional)
+
+`hookSelector` allows you to select which hooks to run using [Kubernetes Label Selectors](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#labelselector-v1-meta).
+
+You can only select hooks in the namespace in which the scan is running.
+
+Leaving this field undefined will select all available hooks in this namespace.
+
+```yaml
+hookSelector:
+  matchExpressions:
+   - key: app.kubernetes.io/instance
+     operator: In
+     values: [ "defectdojo", "cascading-scans" ]
+```
+
+:::note
+Cascading scans are currently implemented as a hook.
+To use cascading scans in combination with hookSelector, ensure that you also select the cascading scans hook.
+The cascading scan hook, as well as any future core secureCodeBox features implemented as hooks, carry the label `securecodebox.io/internal: true` to make this easier.
+:::
+
+For more examples on how this field can be used, see the [Hook HowTo](/docs/how-tos/hooks).
+
 ## Metadata
 
-Metadata is a standard field on Kubernetes resources. It contains multiple relevant fields, e.g. the name of the resource, its namespace and a `creationTimestamp` of the resource. See more on the [Kubernetes Docs]https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) and the [Kubernetes API Reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#objectmeta-v1-meta))
+Metadata is a standard field on Kubernetes resources. It contains multiple relevant fields, e.g. the name of the resource, its namespace and a `creationTimestamp` of the resource. See more on the [Kubernetes Docs](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) and the [Kubernetes API Reference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.21/#objectmeta-v1-meta).
 
 ## Status
 

diff --git a/docs/contributing/integrating-a-hook/values.yaml.md b/docs/contributing/integrating-a-hook/values.yaml.md
@@ -24,6 +24,12 @@ hook:
     # @default -- defaults to the charts version
     tag: null
 
+  # -- Add Kubernetes Labels to the hook definition
+  labels: {}
+
+  # -- Hook priority. Higher priority Hooks are guaranteed to execute before low priority Hooks.
+  priority: null
+
   # hook.ttlSecondsAfterFinished -- Seconds after which the kubernetes job for the hook will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
   ttlSecondsAfterFinished: null
 ```
@@ -34,6 +40,15 @@ The `image` field specifies the Docker image that is used for your hook.
 The `repository` specifies Registry and Namespace and `tag` defines the desired image tag.
 These are the only mandatory fields for a hook to work.
 
+## Labels
+
+Adds Kubernetes labels to the Hook definition. See the [Hooks HowTo](/docs/how-tos/hooks#hook-selector) for examples on how to use it.
+
+## Priority
+
+You can specify the priority of the hook with `hook.priorty`.
+By default, this priority should be zero since they regard deployment-specific configurations which the secureCodeBox team does not manage.
+
 ## Additional Values
 
-If your hook needs some additional information like an URL (`webhookUrl` in the example above), environment variables or volume mounts, you need to provide an option to specify them in your `values.yaml` and access them in the hook implementation (See [templates](docs/contributing/integrating-a-hook/templates-dir) for information on how to access the provided values, and [ScanCompletionHook](/docs/api/crds/scan-completion-hook) for a list of possible keys you can set in the template).
+If your hook needs some additional information like an URL (`webhookUrl` in the example above), environment variables or volume mounts, you need to provide an option to specify them in your `values.yaml` and access them in the hook implementation (See [templates](/docs/contributing/integrating-a-hook/templates-dir) for information on how to access the provided values, and [ScanCompletionHook](/docs/api/crds/scan-completion-hook) for a list of possible keys you can set in the template).