Skip to content
This repository was archived by the owner on Oct 14, 2020. It is now read-only.

Commit 49c91af

Browse files
J12934J12934
authored
Merge pull request #78 from secureCodeBox/adr/cascading-scans
Add ADR for CascadingRules
2 parents 56515c7 + 8b708dc commit 49c91af

File tree

1 file changed

+182
-0
lines changed

1 file changed

+182
-0
lines changed

‎docs/adr/adr_0002.adoc‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
[[ADR-0002]]
2+
= ADR-0002: How can we introduce a mechanism to start specialized scans on the results of previous scans?
3+
4+
[cols="h,d",grid=rows,frame=none,stripes=none,caption="Status",%autowidth]
5+
|====
6+
7+
| Status
8+
| ACCEPTED
9+
10+
| Date
11+
| 2020-05-20
12+
13+
| Author(s)
14+
| Jannik Hollenbach <Jannik.Hollenbach@iteratec.com>,
15+
Robert Seedorff <Robert.Seedorff@iteratec.com>,
16+
Sven Strittmatter <Sven.Strittmatter@iteratec.com>
17+
|====
18+
19+
== Context
20+
21+
=== Status Quo
22+
23+
Currently scans by the secureCodeBox are single focused on a specific tool.
24+
Combining multiple scans requires manual or scripting by the user to use the results of a scan (e.g. Nmap) as a input for another scanner (e.g. SSLyze)
25+
26+
=== Problem and Question
27+
28+
How can the results of a scan be used to automatically configure subsequent specialized scans for identified targets.
29+
30+
In general we want to describe cascading scans like:
31+
32+
```
33+
+--------+ +--------+ +--------+
34+
| scan 1 |-- result -->| scan 2 |-- result -->| scan 3 |
35+
+--------+ +--------+ | +--------+
36+
|
37+
| +--------+
38+
+---->| scan 4 |
39+
+--------+
40+
````
41+
42+
A concrete example:
43+
44+
```
45+
+----------------+ +-----------------+ +-----------+
46+
| <<nmap>> | | <<nmap>> | | <<SSL>> |
47+
| find all hosts |-- IP -->| find open ports |-- port 443 -->| check TLS |
48+
+----------------+ +-----------------+ | +-----------+
49+
|
50+
| +-------------+
51+
| | <<nikto>> |
52+
+------->| check HTTPd |
53+
+-------------+
54+
```
55+
56+
The solution should fulfill the following criteria:
57+
58+
- The "rules" used to describe which subsequent scans can be executed should be modular, so that they can be packaged together with the scan types.
59+
- It should be possible for a user to select which scan rules should be applied
60+
- Protections should be in place to ensure that the clusters are not completely overwhelmed by these automatically created scans. Especially circular structures which create a infinite number of scans should be prevented.
61+
62+
== Decision
63+
64+
It was decided to implement these rules as Custom Resource Definitions (CRDs) in Kubernetes.
65+
This allows the Helm Charts of the scanners to package related rules for the scanner together with their ScanTypes.
66+
67+
=== Defining CascadingRule
68+
69+
The so called "CascadingRules" consist of a "matches" section which contains one or multiple rules which are compared against findings.
70+
When a finding matches a rule the "scanSpec" section will then be used to create a new scan.
71+
To customize the scan to match the finding, the [mustache](https://github.com/janl/mustache.js) templating language can be used to reference fields of the finding.
72+
73+
```yaml
74+
apiVersion: "cascading.experimental.securecodebox.io/v1"
75+
kind: CascadingRule
76+
metadata:
77+
name: "tls-scans"
78+
labels:
79+
# Described how "invasive" the scan is.
80+
# Possible values: "invasive" or "non-invasive"
81+
# CascadingRules are considered "invasive" when the Scan they start actively sends out packages with attack payloads.
82+
securecodebox.io/invasive: non-invasive
83+
# Described the intensiveness level on a scanning and computational resource level.
84+
# Possible values: "ligh", "medium", "intense"
85+
# CascadingRules are considered more "intensive" when the Scan they start consumes lots of computational resources like RAM, CPU, or Network
86+
securecodebox.io/intensive: light
87+
spec:
88+
matches:
89+
# CascadingRule triggers if a finding matches at least one of the anyOf matchers
90+
# With the first version of this implementation only anyOf would be supported.
91+
# If this turns out to be lacking and other operators (like `allOf` can be introduced without breaking changes)
92+
anyOf:
93+
# define an explicit "port" as finding and a given port number
94+
- category: "Open Port"
95+
attributes:
96+
port: 443
97+
service: "https"
98+
# define an "port service" finding (any port)
99+
- category: "Open Port"
100+
attributes:
101+
service: "https"
102+
scanSpec:
103+
name: "sslyze"
104+
parameters: ["--regular", "{{attributes.hostname}}"]
105+
```
106+
107+
=== Using CascadingRules
108+
109+
By default no cascading Rules will be used.
110+
111+
```yaml
112+
# Nmap Scan without cascading rules
113+
apiVersion: "execution.experimental.securecodebox.io/v1"
114+
kind: Scan
115+
metadata:
116+
name: "portscan-berlin-wifi"
117+
label:
118+
office: berlin
119+
vlan: wifi
120+
spec:
121+
name: "nmap"
122+
parameters: ["-sV", "10.42.0.0/16"]
123+
```
124+
125+
To enable cascading rules you need to specify a label selector to select the cascading rules you'd like
126+
127+
```yaml
128+
apiVersion: "execution.experimental.securecodebox.io/v1"
129+
kind: Scan
130+
metadata:
131+
name: "portscan-berlin-wifi"
132+
label:
133+
office: berlin
134+
vlan: wifi
135+
spec:
136+
cascades:
137+
matchLabels:
138+
# Uses all CascadingRules in the namespace which are labelled as "non-invasive" and a intensiveness level of "light"
139+
securecodebox.io/invasive: non-invasive
140+
securecodebox.io/intensive: light
141+
name: "nmap"
142+
parameters: ["-sV", "10.42.0.0/16"]
143+
```
144+
145+
To implicitly enable all cascading rules (not-recommended) a empty label selector can be used
146+
147+
```yaml
148+
apiVersion: "execution.experimental.securecodebox.io/v1"
149+
kind: Scan
150+
metadata:
151+
name: "portscan-berlin-wifi"
152+
label:
153+
office: berlin
154+
vlan: wifi
155+
spec:
156+
cascades:
157+
# Uses all `CascadingRules` in the namespace
158+
matchLabels: {}
159+
name: "nmap"
160+
parameters: ["-sV", "10.42.0.0/16"]
161+
```
162+
163+
The label selectors also allow the more powerful [matchExpression](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement) selectors:
164+
165+
```yaml
166+
apiVersion: "execution.experimental.securecodebox.io/v1"
167+
kind: Scan
168+
metadata:
169+
name: "example.com"
170+
spec:
171+
scanType: nmap
172+
parameters:
173+
- -p22,80,443
174+
- example.com
175+
cascades:
176+
# Using matchExpression instead of matchLabels
177+
matchExpression:
178+
key: "securecodebox.io/intensive"
179+
operator: In
180+
# This select both light and medium intensity rules
181+
values: [light, medium]
182+
```

0 commit comments

Comments
 (0)