As part of our belief in the power of open source, Elastic has open sourced all our detection
rules to work alongside the security community to stop threats at a greater scale and arm
every analyst.
In this video, we will walk through how you can contribute by creating a new rule and
getting credit for it in the Elastic contributor program.
Let’s take a look at how to jump into the detection rules in the repository and become
part of the community.
The first step is to create a Github issue.
This kicks off the initial discussion for a new rule or proposed changes.
This is done to learn from each other and share ideas, and this is a separate thread
from the actual code changes.
To start working on the project from your own account, you will then fork and clone
the repository locally.
Once you’ve moved in the project directory, you can begin working with the ‘detection-rules’
CLI to begin creating rules or by editing the .toml file.
Once you’ve written your rule, you can run local tests found in the project (this is
an optional step, as tests will run on PRs upon submission).
Now that we’ve covered the general workflow, let’s create an example rule using the interactive
command line tool.
For this demo, the repository has already been cloned locally.
First, start by validating that your environment is configured correctly by running the detection_rules
module with the --help argument.
This will also show all of the sub-commands available.
Rules are separated by major category within the rules/ directory.
Let’s use the view-rule command to take a look at a simple rule to see the overall structure.
Running this command will show the options for that sub-command.
Now it’s time to use the create-rule command to create a new file to match a behavior.
This is done by using the create-rule sub-command, followed by a path-to-the-new-rule file
You will be prompted with a series of entries to build the content of your new rule.
For the purpose of this demo, we’ll focus on the fields labeled “required.”
The rule we will be building today is to detect telnet traffic in your environment.
Since this protocol can store sensitive information like passwords and usernames in clear-text,
administrators and analysts typically monitor for this protocol within their network.
Once the rule has been created, open up the new file in a text editor.
Our entries have been converted into a toml formatted file.
From here, you have the ability to make changes manually.
This is a good time to highlight fields within the file including.
Indices this rule matches on.
In this case filebeat, packetbeat, and logs-endpoint.events.
The language this query is written in along with the query itself.
The query in this example will match on the category of network traffic, TCP, and a destination
port of 23.
In this example, we’re adding a more detailed description, false positive information, tags,
and additional Mitre Attack tactics and techniques.
Next, import this rule into the repo with the command.
This will copy the new rule into the rules/ directory.
Additionally, this is a good time to check the syntax of the rule, which is easy with
the linting option.
The CLI will highlight syntax issues.
After the rule’s syntax is checked, validate the rule by running the validate-rule command,
with the path to the rule, followed by the rule id.
Once all of these steps are complete, you can then upload your rule to a Kibana instance.
Once you are confident that your rules are complete, and the previously mentioned separate
issue is properly closed, the next step would be to submit a pull request as outlined in
the contribution guide within the repo.
Thanks for watching this video on contributing detection rules in Elastic Security.
By contributing to the detection rules repo, you are eligible for rewards under the Elastic Contributor Program.
Be sure to select “code” as the contribution type.
If you’re ready to dive deeper into how to create new rules, take a look at the Public
Repository for Detection Rules Workshop, Rule creation documentation, and the Elastic Community
Slack and the detection rules channel.