Cascading Scans

What is "Cascading Scans" Hook about?#

The Cascading Scans Hook can be used to orchestrate security scanners based on defined rule sets. The so called CascadingRules consist of a matches section which contains one or multiple rules which are compared against findings. When a finding matches a rule the scanSpec section will then be used to create a new scan. To customize the scan to match the finding, the mustache templating language can be used to reference fields of the finding.

This Hook is based on the ADR https://docs.securecodebox.io/docs/architecture/adr/adr_0003

More information about how to use cascading scans can be found here:

Custom Resource Definition: https://docs.securecodebox.io/docs/api/crds/cascading-rule/
How-To Network Scanning: https://docs.securecodebox.io/docs/how-tos/scanning-networks/

Deployment#

The cascading-scans chart can be deployed via helm:

# Install HelmChart (use -n to configure another namespace)helm upgrade --install cascading-scans secureCodeBox/cascading-scans

Requirements#

Kubernetes: >=v1.11.0-0

Additional Chart Configurations#

Installing the Cascading Scans hook will add a ReadOnly Hook to your namespace which looks for matching CascadingRules in the namespace and start the according scans.

Verification#

kubectl get ScanCompletionHooksNAME   TYPE       IMAGEdssh   ReadOnly   docker.io/securecodebox/hook-cascading-scans:latest

CascadingScan Rules#

The CascadingRules are included directly in each helm chart of the individual scanners. There is a configuration option cascadingRules.enabled for each scanner to prevent this inclusion.

# Check your CascadingRuleskubectl get CascadingRulesNAME             STARTS              INVASIVENESS   INTENSIVENESShttps-tls-scan   sslyze              non-invasive   lightimaps-tls-scan   sslyze              non-invasive   lightnikto-http       nikto               non-invasive   mediumnmap-smb         nmap                non-invasive   lightpop3s-tls-scan   sslyze              non-invasive   lightsmtps-tls-scan   sslyze              non-invasive   lightssh-scan         ssh-scan            non-invasive   lightzap-http         zap-baseline-scan   non-invasive   medium

Starting a cascading Scan#

When you start a normal Scan, no CascadingRule will be applied. To use a CascadingRule the scan must be marked to allow cascading rules. This is implemented using kubernetes label selectors, meaning that scans mark the classes of scans which are allowed to be cascaded by the current one.

Example#

cat <<EOF | kubectl apply -f -apiVersion: "execution.securecodebox.io/v1"kind: Scanmetadata:  name: "example.com"spec:  scanType: nmap  parameters:    - -p22,80,443    - example.com  cascades:    matchLabels:      securecodebox.io/intensive: lightEOF

This Scan will use all CascadingRules which are labeled with a "light" intensity. You can lookup which CascadingRules this selects by running:

kubectl get CascadingRules -l "securecodebox.io/intensive=light"NAME             STARTS     INVASIVENESS   INTENSIVENESShttps-tls-scan   sslyze     non-invasive   lightimaps-tls-scan   sslyze     non-invasive   lightnmap-smb         nmap       non-invasive   lightpop3s-tls-scan   sslyze     non-invasive   lightsmtps-tls-scan   sslyze     non-invasive   lightssh-scan         ssh-scan   non-invasive   light

The label selectors also allow the more powerful matchExpressions selectors:

cat <<EOF | kubectl apply -f -apiVersion: "execution.securecodebox.io/v1"kind: Scanmetadata:  name: "example.com"spec:  scanType: nmap  parameters:    - -p22,80,443    - example.com  cascades:    # Using matchExpressions instead of matchLabels    matchExpressions:    - key: "securecodebox.io/intensive"      operator: In      # This select both light and medium intensity rules      values: [light, medium]EOF

This selection can be replicated in kubectl using:

kubectl get CascadingRules -l "securecodebox.io/intensive in (light,medium)"NAME             STARTS              INVASIVENESS   INTENSIVENESShttps-tls-scan   sslyze              non-invasive   lightimaps-tls-scan   sslyze              non-invasive   lightnikto-http       nikto               non-invasive   mediumnmap-smb         nmap                non-invasive   lightpop3s-tls-scan   sslyze              non-invasive   lightsmtps-tls-scan   sslyze              non-invasive   lightssh-scan         ssh-scan            non-invasive   lightzap-http         zap-baseline-scan   non-invasive   medium

Values#

Key	Type	Default	Description
hook.affinity	object	`{}`	Optional affinity settings that control how the hook job is scheduled (see: https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/)
hook.image.repository	string	`"docker.io/securecodebox/hook-cascading-scans"`	Hook image repository
hook.image.tag	string	defaults to the charts version	The image Tag defaults to the charts version if not defined.
hook.labels	object	`{}`	Add Kubernetes Labels to the hook definition
hook.priority	int	`0`	Hook priority. Higher priority Hooks are guaranteed to execute before low priority Hooks.
hook.tolerations	list	`[]`	Optional tolerations settings that control how the hook job is scheduled (see: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
hook.ttlSecondsAfterFinished	string	`nil`	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/

License#

Code of secureCodeBox is licensed under the Apache License 2.0.