diff --git a/doc/userguide/rules/meta.rst b/doc/userguide/rules/meta.rst index 849a9542cd..bdcf733ea6 100644 --- a/doc/userguide/rules/meta.rst +++ b/doc/userguide/rules/meta.rst @@ -1,4 +1,4 @@ -Meta-settings +Meta Keywords ============= .. role:: example-rule-emphasis @@ -7,32 +7,28 @@ Meta-settings have no effect on Suricata's inspection; they do have an effect on msg (message) ------------- +The keyword msg gives textual information about the signature and the possible alert. -The keyword msg gives more information about the signature and the possible alert. The first part shows the class of the signature. It is a convention that part is written in uppercase -characters. - -The format of msg is: - -:: +The format of msg is:: msg: "some description"; -Examples: - -:: +Examples:: msg:"ATTACK-RESPONSES 403 Forbidden"; msg:"ET EXPLOIT SMB-DS DCERPC PnP bind attempt"; -It is a convention that msg is always the first keyword of a signature. - -Another example of msg in a signature: +To continue the example of the previous chapter, this is the keyword in action in an actual rule: .. container:: example-rule drop tcp $HOME_NET any -> $EXTERNAL_NET any (:example-rule-emphasis:`msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)";` flow:established,to_server; flowbits:isset,is_proto_irc; content:"NICK "; pcre:"/NICK .*USA.*[0-9]{3,}/i"; reference:url,doc.emergingthreats.net/2008124; classtype:trojan-activity; sid:2008124; rev:2;) -In this example the red, bold-faced part is the msg. +.. tip:: + + It is convention to make the first part of the signature uppercase and show the class of the signature. + + It is also convention that ``msg`` is made the first keyword in the signature. .. note:: The following characters must be escaped inside the msg: ``;`` ``\`` ``"`` @@ -40,11 +36,7 @@ In this example the red, bold-faced part is the msg. sid (signature ID) ------------------ -The keyword sid gives every signature its own id. This id is stated with a number. - -The format of sid is: - -:: +The keyword sid gives every signature its own id. This id is stated with a number. The format of sid is:: sid:123; @@ -54,22 +46,19 @@ Example of sid in a signature: drop tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)"; flow:established,to_server; flowbits:isset,is_proto_irc; content:"NICK "; pcre:"/NICK .*USA.*[0-9]{3,}/i"; reference:url,doc.emergingthreats.net/2008124; classtype:trojan-activity; :example-rule-emphasis:`sid:2008124;` rev:2;) -In this example the red, bold-faced part is the sid. +.. tip:: -rev (Revision) --------------- + It is convention that the signature ``sid`` is provided as the last keyword (or second-to-last if there is a ``rev``) of the signature. +rev (revision) +-------------- The sid keyword is almost every time accompanied by rev. Rev represents the version of the signature. If a signature is modified, the number of rev will be incremented by the signature writers. The -format of rev is: - -:: +format of rev is:: rev:123; -*It is a convention that sid comes before rev, and both are the last -of all keywords.* Example of rev in a signature: @@ -77,44 +66,44 @@ Example of rev in a signature: drop tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)"; flow:established,to_server; flowbits:isset,is_proto_irc; content:"NICK "; pcre:"/NICK .*USA.*[0-9]{3,}/i"; reference:url,doc.emergingthreats.net/2008124; classtype:trojan-activity; sid:2008124; :example-rule-emphasis:`rev:2;`) -In this example the red, bold-faced part is the rev. +.. tip:: + + It is a convention that sid comes before rev, and both are the last + of all keywords. gid (group ID) -------------- - The gid keyword can be used to give different groups of signatures another id value (like in sid). Suricata uses by default gid 1. It is possible to modify this. It is not usual that it will be changed, and changing it has no technical implications. You can only notice it in the alert. -Example of gid in a signature: +Example of gid in an alert of fast.log. In the part [1:2008124:2], 1 is the gid (2008124 is the the sid and 2 the rev). .. container:: example-rule 10/15/09-03:30:10.219671 [**] [:example-rule-emphasis:`1`:2008124:2] ET TROJAN Likely Bot Nick in IRC (USA +..) [**] [Classification: A Network Trojan was Detected] [Priority: 3] {TCP} 192.168.1.42:1028 -> 72.184.196.31:6667 -This is an example from the fast.log. -In the part [1:2008124:2], 1 is the gid (2008124 is the the sid and 2 the rev). classtype --------- - The classtype keyword gives information about the classification of rules and alerts. It consists of a short name, a long name and a priority. It can tell for example whether a rule is just informational or is about a hack etcetera. For each classtype, the classification.config has a priority which will be used in the rule. -*It is a convention that classtype comes before sid and rev and after -the rest of the keywords.* - -Example classtype:: +Example classtype definition:: config classification: web-application-attack,Web Application Attack,1 config classification: not-suspicious,Not Suspicious Traffic,3 +Now when we have defined this in the configuration, we can use the classtypes +in our rules. A rule with classtype web-application-attack will be assigned +a priority of 1 and the alert will contain 'Web Application Attack': + ======================= ====================== =========== classtype Alert Priority ======================= ====================== =========== @@ -122,16 +111,17 @@ web-application-attack Web Application Attack 1 not-suspicious Not Suspicious Traffic 3 ======================= ====================== =========== -In this example you see how classtype appears in signatures, the -classification.config and the alert. - -Another example of classtype in a signature: +Our continuing example has also a classtype, this one of trojan-activity: .. container:: example-rule drop tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)"; flow:established,to_server; flowbits:isset,is_proto_irc; content:"NICK "; pcre:"/NICK .*USA.*[0-9]{3,}/i"; reference:url,doc.emergingthreats.net/2008124; :example-rule-emphasis:`classtype:trojan-activity;` sid:2008124; rev:2;) -In this example the red, bold-faced part is the classtype. + +.. tip:: + + It is a convention that classtype comes before sid and rev and after + the rest of the keywords. reference --------- @@ -140,80 +130,58 @@ The reference keywords direct to places where information about the signature and about the problem the signature tries to address, can be found. The reference keyword can appear multiple times in a signature. This keyword is meant for signature-writers and analysts who -investigate why a signature has matched. It has the following format: - -:: - - reference: url, www.info.nl - -In this example url is the type of reference. After that comes the -actual reference (notice here you can not use http before the url). +investigate why a signature has matched. It has the following format:: -There are different types of references: + reference: type, reference -type: +A typical reference to www.info.com would be:: -:: + reference: url, www.info.com - system URL Prefix - bugtraq http://www.securityfocus.com/bid - cve http://cve.mitre.org/cgi-bin/cvename.cgi?name= - nessus http://cgi.nessus.org/plugins/dump.php3?id= - arachnids (No longer available but you might still encounter this in signatures.) - http://www.whitehats.com/info/IDS - mcafee http://vil.nai.com/vil/dispVirus.asp?virus_k= - url http:// +However, there are also several systems that can be used as a reference. A +commonly known example is the CVE-database, that assigns numbers to +vulnerabilities. To prevent you from typing the same URL over and over +again, you can use something like this:: -For example bugtraq will be replaced by the full url: + reference: cve, CVE-2014-1234 -:: +This would make a reference to http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-1234. +All reference types are defined in the reference.config configuration file. - reference: bugtraq, 123; http://www.securityfocus.com/bid - -Example of reference in a signature: +Our continuing example also has a reference: .. container:: example-rule drop tcp $HOME_NET any -> $EXTERNAL_NET any (msg:"ET TROJAN Likely Bot Nick in IRC (USA +..)"; flow:established,to_server; flowbits:isset,is_proto_irc; content:"NICK "; pcre:"/NICK .*USA.*[0-9]{3,}/i"; :example-rule-emphasis:`reference:url,doc.emergingthreats.net/2008124;` classtype:trojan-activity; sid:2008124; rev:2;) -In this example the red, bold-faced part is the action. priority -------- - The priority keyword comes with a mandatory numeric value which can range from 1 till 255. The numbers 1 to 4 are most often used. Signatures with a higher priority will be examined first. The highest priority is 1. Normally signatures have already a priority through -class type. This can be overruled with the keyword priority. The -format of priority is: - -:: +classtype. This can be overruled with the keyword priority. The +format of priority is:: priority:1; metadata -------- - Suricata ignores the words behind meta data. Suricata supports this -keyword because it is part of the signature language. The format is: - -:: +keyword because it is part of the signature language. The format is:: metadata:......; target ------ - The target keyword allows the rules writer to specify which side of the alert is the target of the attack. If specified, the alert event is enhanced to contain information about source and target. -The format is: - -:: +The format is:: - target: [src_ip|dest_ip] + target:[src_ip|dest_ip] If the value is src_ip then the source IP in the generated event (src_ip field in JSON) is the target of the attack. If target is set to dest_ip