writer

Signatures for Suricata are also referred to as rules. They are used to detect specific patterns in network traffic and generate alerts when those patterns are found.

Signature anatomy

A typical signature rule looks like:

alert <proto> <src> <sport> -> <dst> <dport> ( msg:"..."; flow:...; <sticky buffer setting buffer to match on (like tls.sni)>; content:"..."; sid:1000001; rev:1;)

Key ideas:

• proto is application layer (e.g., http, tls, smb) or is transport layer (e.g., tcp, udp). Always set application layer in second position of the signature when possible.
• sid is a unique rule id.
• rev is the rule revision.
• Use flow:established,to_server (or similar) to constrain direction/state.

Best practices

When writing signatures for Suricata, always check the result of the signatures with suricata-language-server --batch-file <file> to check for syntax errors and warnings.

List the available keywords with suricata-language-server --list-keywords. You can follow the links to the documentation in the output to get more information about each keyword.

List the available application layer with suricata-language-server --list-app-layer-protos.

Set of rules when writing signature for Suricata:

• A signature is not correct if it has any warning or errors when checked with suricata-language-server --batch-file <file>.
• Signatures should not use content modifiers keywords as they are deprecated.
• Signatures should include a readable message (msg) that describes the purpose of the rule that should not exceed 100 characters. The message should be concise and informative, providing a clear understanding of the rule's intent.
• Signatures should include metadata created_at and updated_at with the date of creation and last update of the rule in ISO 8601 format (YYYY-MM-DD).
• Signatures are mostly about detecting risk or threat happening on the assets of the organization represented by $HOME_NET in the signature.
• Signatures should have a metadata field written_by with the name of the author of the signature.
• Comment explaining the signature should be added in the signature file before the signature, and should be concise and informative, providing a clear understanding of the rule's intent. Comment are added with ## at the beginning of the line.
• When a signature is likely to trigger a lot because of repeated actions (e.g., a policy violation signature for a specific domain), consider adding a threshold to limit the number of alerts generated by that signature.
• When a threshold is setup, it needs to avoid missing any asset exhibiting the behavior, for example with threshold:type limit, track by_src, count 1, seconds 60; to limit to 5 alerts per minute per source IP when source IP is in the HOME_NET.
• Do not use a threshold to limit the number of alerts generated by a signature when the signature detect a behavior where the protocol metadata attached to alert can be interesting (e.g., no threshold if a signature detect data exfiltration or any sequantial attacks).
• Sticky buffer are setting a context so multiple match conditions can be applied after using a sticky buffer.
• Ask the user about its identity if needed to be able to add the written_by metadata field in the signature.
• Always set the application protocol in the signature as the second parameter of the rule (e.g., http, tls, smb) if possible. Avoid usage of app-layer-protocol keyword.
• Whatever the concept, always check if there is a keyword that can be used to write the signature in a more efficient way.
• Content match should have more than one character.

Additional rules for specific types of signatures:

• Signature matching on a domain name should use the domain transform to ensure proper matching of the domain name in the traffic. Don't do that for the hostname.
• When signature match on something on the internet, use $EXTERNAL_NET and $HOME_NET variables in the signature for or .
• A policy violation signature can be outbound if it is from $HOME_NET to $EXTERNAL_NET, but it can also be inbound if it is from $EXTERNAL_NET to $HOME_NET. In that case, the signature should be written in both directions.
• You can use flowbits in a set of signatures to create a condition that can be used in another signature.
• Always prefer match that are not user input when possible (e.g. match on file content instead of file name)

Tools

To install suricata-language-server, you can use pip in a virtual environment:

pip install suricata-language-server

If suricata binary is not available on the system uses --container option to run the language server in a container with Suricata installed:

suricata-language-server --container --batch-file <file>

Interaction with PCAP trace

You can ask to the user if a pcap file is available to test the signature on and then inject the path to the pcap file with the following comment (at beginning of the signature file):

## SLS pcap-file: <path to pcap file>

Then suricata-language-server will automatically test the signature on the pcap file and provide the result of the test in the output of the command.