Skip to content

Commit

Permalink
Update detection engine depth test scripts and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@marshallmain
marshallmain committed Sep 4, 2020
1 parent 2c9d038 commit 93094ab
Show file tree
Hide file tree
Showing 4 changed files with 141 additions and 108 deletions.
239 changes: 136 additions & 103 deletions ...tection_engine/scripts/rules/test_cases/signals_on_signals/depth_test/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ which will write a single signal document into the signals index by searching fo
signal_on_signal_depth_1.json
```

which has this key part of its query: `"query": "signal.parent.depth: 1 and _id: *"` which will only create signals
which has this key part of its query: `"query": "signal.depth: 1 and _id: *"` which will only create signals
from all signals that point directly to an event (signal -> event).

Then a second rule called
Expand All @@ -34,7 +34,7 @@ signal_on_signal_depth_2.json
which will only create signals from all signals that point directly to another signal (signal -> signal) with this query

```json
"query": "signal.parent.depth: 2 and _id: *"
"query": "signal.depth: 2 and _id: *"
```

## Setup
Expand Down Expand Up @@ -90,38 +90,39 @@ And then you can query against that:
GET .siem-signals-default/_search
```

Check your parent section of the signal and you will see something like this:
Check your signal.parents section of the signal and you will see something like this:

```json
"parent" : {
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
},
"ancestors" : [
"parents" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
}
],
"ancestors" : [
{
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 0
},
]
```

The parent and ancestors structure is defined as:
The parents structure is defined as:

```
rule -> The id of the rule. You can view the rule by ./get_rule_by_rule_id.sh ded57b36-9c4e-4ee4-805d-be4e92033e41
rule -> The id of the rule, if the parent was generated by a rule. You can view the rule by ./get_rule_by_rule_id.sh ded57b36-9c4e-4ee4-805d-be4e92033e41
id -> The original _id of the document
type -> The type of the document, it will be either event or signal
index -> The original location of the index
depth -> The depth of this signal. It will be at least 1 to indicate it is a signal generated from a event. Otherwise 2 or more to indicate a signal on signal and what depth we are at
ancestors -> An array tracking all of the parents of this particular signal. As depth increases this will too.
depth -> The depth of the parent event/signal. It will be 0 if the parent is an event, or 1+ if the parent is another signal.
```

The ancestors structure has the same fields as parents, but is an array of all ancestors (parents, grandparents, etc) of the signal.

This is indicating that you have a single parent of an event from the signal (signal -> event) and this document has a single
ancestor of that event. Each 30 seconds that goes it will use de-duplication technique to ensure that this signal is not re-inserted. If after
each 30 seconds you DO SEE multiple signals then the bug is a de-duplication bug and a critical bug. If you ever see a duplicate rule in the
Expand All @@ -138,55 +139,63 @@ running in the system which are generating signals on top of signals. After 30 s
documents in the signals index. The first signal is our original (signal -> event) document with a rule id:

```json
"parent" : {
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
},
"parents" : [
{
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 0
}
],
"ancestors" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
}
]
```
],
"depth": 1,
"rule": {
"id": "74e0dd0c-4609-416f-b65e-90f8b2564612"
}

and the second document is a signal on top of a signal like so:

```json
"parent" : {
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
},
"ancestors" : [
"parents" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 1
}
]
"ancestors" : [
{
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
},
{
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
"depth" : 1
}
]
],
"depth": 2,
"rule": {
"id": "1d3b3735-66ef-4e53-b7f5-4340026cc40c"
}
```

Notice that the depth indicates it is at level 2 and its parent is that of a signal. Also notice that the ancestors is an array of size 2
indicating that this signal terminates at an event. Each and every signal ancestors array should terminate at an event and should ONLY contain 1
event and NEVER 2 or more events. After 30+ seconds you should NOT see any new documents being created and you should be stable
event and NEVER 2 or more events for KQL query based rules. EQL query based rules that use sequences may have multiple parents at the same level. After 30+ seconds you should NOT see any new documents being created and you should be stable
at 2. Otherwise we have AND/OR a de-duplication issue, signal on signal issue.

Now, post this same rule a second time as a second instance which is going to run against these two documents.
Expand All @@ -212,79 +221,93 @@ The expected behavior is that eventually you will get 3 total documents but not
The original event rule 74e0dd0c-4609-416f-b65e-90f8b2564612 (event -> signal)

```json
"parent" : {
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
},
"parents" : [
{
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 0
}
],
"ancestors" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
}
]
],
"depth": 1,
"rule": {
"id": "74e0dd0c-4609-416f-b65e-90f8b2564612"
}
```

The first signal to signal rule 1d3b3735-66ef-4e53-b7f5-4340026cc40c (signal -> event)

```json
"parent" : {
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
},
"ancestors" : [
"parents" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 1
}
]
"ancestors" : [
{
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
},
{
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
"depth" : 1
}
]
],
"depth": 2,
"rule": {
"id": "1d3b3735-66ef-4e53-b7f5-4340026cc40c"
}
```

Then our second signal to signal rule c93ddb57-e7e9-4973-9886-72ddefb4d22e (signal -> event) which finds the same thing as the first
signal to signal

```json
"parent" : {
"rule" : "c93ddb57-e7e9-4973-9886-72ddefb4d22e",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
},
"ancestors" : [
"parents" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 1
}
],
"ancestors" : [
{
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
},
{
"rule" : "c93ddb57-e7e9-4973-9886-72ddefb4d22e",
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
"depth" : 1
}
]
],
"depth": 2,
"rule": {
"id": "c93ddb57-e7e9-4973-9886-72ddefb4d22e"
}
```

We should be able to post this depth level as many times as we want and get only 1 new document each time. If we decide though to
Expand All @@ -298,69 +321,79 @@ The expectation is that a document for each of the previous depth 1 documents wo
depth 1 rules running then the signals at depth 2 will produce two new ones and those two will look like so:

```json
"parent" : {
"rule" : "a1f7b520-5bfd-451d-af59-428f60753fee",
"id" : "365236ce5e77770508152403b4e16613f407ae4b1a135a450dcfec427f2a3231",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 3
},
"parents" : [
{
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"id" : "365236ce5e77770508152403b4e16613f407ae4b1a135a450dcfec427f2a3231",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
}
],
"ancestors" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
},
{
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
"depth" : 1
},
{
"rule" : "a1f7b520-5bfd-451d-af59-428f60753fee",
"rule" : "1d3b3735-66ef-4e53-b7f5-4340026cc40c",
"id" : "365236ce5e77770508152403b4e16613f407ae4b1a135a450dcfec427f2a3231",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 3
"depth" : 2
}
]
],
"depth": 3,
"rule": {
"id": "a1f7b520-5bfd-451d-af59-428f60753fee"
}
```

```json
"parent" : {
"rule" : "a1f7b520-5bfd-451d-af59-428f60753fee",
"id" : "e8b1f1adb40fd642fa524dea89ef94232e67b05e99fb0b2683f1e47e90b759fb",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 3
},
"parents" : [
{
"rule" : "c93ddb57-e7e9-4973-9886-72ddefb4d22e",
"id" : "e8b1f1adb40fd642fa524dea89ef94232e67b05e99fb0b2683f1e47e90b759fb",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
}
],
"ancestors" : [
{
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "o8G7vm8BvLT8jmu5B1-M",
"type" : "event",
"index" : "filebeat-8.0.0-2019.12.18-000001",
"depth" : 1
"depth" : 0
},
{
"rule" : "c93ddb57-e7e9-4973-9886-72ddefb4d22e",
"rule" : "74e0dd0c-4609-416f-b65e-90f8b2564612",
"id" : "4cc69c1cbecdd2ace4075fd1d8a5c28e7d46e4bf31aecc8d2da39252c50c96b4",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 2
"depth" : 1
},
{
"rule" : "a1f7b520-5bfd-451d-af59-428f60753fee",
"rule" : "c93ddb57-e7e9-4973-9886-72ddefb4d22e",
"id" : "e8b1f1adb40fd642fa524dea89ef94232e67b05e99fb0b2683f1e47e90b759fb",
"type" : "signal",
"index" : ".siem-signals-default-000001",
"depth" : 3
"depth" : 2
}
]
],
"depth": 3,
"rule": {
"id": "a1f7b520-5bfd-451d-af59-428f60753fee"
}
```

The total number of documents should be 5 at this point. If you were to post this same rule a second time to get a second instance
Expand Down
Loading

0 comments on commit 93094ab

Please sign in to comment.