Skip to main content

Creating a Detection

During this tutorial I am going to create a Use Case that will send an alert when conditions are met. Through the different chapters you will be able to see the different steps that need to be taken to create and run a Use Case.

Step 1: Getting the data​

The first thing we need to create a Detection is a dataset. We will use Python importing the Pandas library to create our dataset.

import pandas as pd

df = pd.DataFrame({
    "col1": [2 * x for x in range(10)],
    "col2": [x**2 for x in range(10)],
    "col3": [x for x in range(10)]
})
df

In this code block we have three columns, col1 contains numbers, col2 gives us the squares of the col1 numbers and col3 contain the row numbers.

Step 2: Building the Detection​

Now that we have our data, let's start to create a Python class that will define our Detection.

from Usecases.Base_module.BaseUsecase import (BaseUsecase, Alert, Occurrence)
from typing import List
from stix2 import TimestampConstant, IntegerConstant
import datetime as dt
import pandas as pd
import pytz
import uuid

class TestUsecase(BaseUsecase):
    # Class attributes
    detection_id = 'b376a756-f0f1-40b0-92f3-a9cf9410cfd1'

    def __init__(self, df: pd.DataFrame, difference: int = 10, **kwargs):
        super().__init__(**kwargs)
        self.df1 = df
        self.difference = difference
        self.now = dt.datetime.now(pytz.utc)

    # More class methods

In this code block we name our class TestUsecase which will inherit it's base class from BaseUsecase which is used as a base for ALL Use Cases. Then takes our dataset and a difference value as input.

Step 2.1: Creating a Detection ID​

Every Detection has a individual detection_id which identifies for which Detection the alert was created. Here is how we obtain our own detection ID:

  1. First we need to call the uuid (Universally Unique Identifier) generator Python module
detection_id = str(uuid.uuid4())

A. This will generate a random detection_id.

B. detection_id will hold our unique identifier

  1. Associate this detection ID with your alerts. In the TestUsecase class, we set the detection_id for each alert:
alert = Alert(
    title=title,
    detection_id=self.detection_id,  # Assign the detection ID here
    alert_id=str(uuid.uuid4()),  # Generating a unique alert ID
    description=description1,
    date=str(self.now),
    occurrences=[Occurrence(self.now)],
    tactic=None,
    technique=None,
    events=df_1.to_dict("records"),
    references=references,
    severity=severity,
    observables=observables
)

Step 3: Deploying the Detection​

Finally, with our class defined we can start deploying the Detectiob. For this we need to create an instance of the TestUsecase class by providing the dataset df and specifying the difference value as "5". This will represent the difference between the two columns, and if conditions are met, will send an alert.

usecase = TestUsecase(df=df, difference=5)

Having the conditions of our Use Case we can run and generate alerts using the run_usecase() method

def get_result():
    for _ in usecase.run_usecase():
        pass
get_result()

Last, we can summarize our generated alerts by using the summarize_alerts() method which will return the title, description and the original dataset.

titles, descriptions, df = usecase.summarize_alerts()

By displaying titles and descriptions, we can review the alerts that our use case has generated.

This Detection will enable us to define conditions and generate alerts when certain criteria are met.

At the moment users are not able to add Detections to the Raven Portal, this can only be done by the DTACT team.

Step 4: Viewing Detections in the Raven Portal​

To see Detections created go to the Detections App located at the left menu of the Portal. Here you will be able to search and interact with all Detections that have been added to your team.

At the right corner of each Detection there is a three dotted button which will let you run or delete the Detection and lastly by clicking a specific Detection we will see specific information like:

  • Detection ID

  • Title

  • Description

  • Sensitivity

  • Alerts generated