suricata
detect-template.c
Go to the documentation of this file.
1 /* Copyright (C) 2015-2020 Open Information Security Foundation
2  *
3  * You can copy, redistribute or modify this Program under the terms of
4  * the GNU General Public License version 2 as published by the Free
5  * Software Foundation.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * version 2 along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
15  * 02110-1301, USA.
16  */
17 
18 /**
19  * \file
20  *
21  * \author XXX Yourname <youremail@yourdomain>
22  *
23  * XXX Short description of the purpose of this keyword
24  */
25 
26 #include "suricata-common.h"
27 #include "util-unittest.h"
28 
29 #include "detect-parse.h"
30 #include "detect-engine.h"
31 
32 #include "detect-template.h"
33 
34 /**
35  * \brief Regex for parsing our keyword options
36  */
37 #define PARSE_REGEX "^\\s*([0-9]+)?\\s*,s*([0-9]+)?\\s*$"
38 static DetectParseRegex parse_regex;
39 
40 /* Prototypes of functions registered in DetectTemplateRegister below */
41 static int DetectTemplateMatch (DetectEngineThreadCtx *,
42  Packet *, const Signature *, const SigMatchCtx *);
43 static int DetectTemplateSetup (DetectEngineCtx *, Signature *, const char *);
44 static void DetectTemplateFree (void *);
45 #ifdef UNITTESTS
46 static void DetectTemplateRegisterTests (void);
47 #endif
48 
49 /**
50  * \brief Registration function for template: keyword
51  *
52  * This function is called once in the 'lifetime' of the engine.
53  */
55  /* keyword name: this is how the keyword is used in a rule */
56  sigmatch_table[DETECT_TEMPLATE].name = "template";
57  /* description: listed in "suricata --list-keywords=all" */
58  sigmatch_table[DETECT_TEMPLATE].desc = "give an introduction into how a detection module works";
59  /* link to further documentation of the keyword. Normally on the Suricata redmine/wiki */
60  sigmatch_table[DETECT_TEMPLATE].url = "https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_Developers_Guide";
61  /* match function is called when the signature is inspected on a packet */
62  sigmatch_table[DETECT_TEMPLATE].Match = DetectTemplateMatch;
63  /* setup function is called during signature parsing, when the template
64  * keyword is encountered in the rule */
65  sigmatch_table[DETECT_TEMPLATE].Setup = DetectTemplateSetup;
66  /* free function is called when the detect engine is freed. Normally at
67  * shutdown, but also during rule reloads. */
68  sigmatch_table[DETECT_TEMPLATE].Free = DetectTemplateFree;
69 #ifdef UNITTESTS
70  /* registers unittests into the system */
72 #endif
73  /* set up the PCRE for keyword parsing */
74  DetectSetupParseRegexes(PARSE_REGEX, &parse_regex);
75 }
76 
77 /**
78  * \brief This function is used to match TEMPLATE rule option on a packet
79  *
80  * \param t pointer to thread vars
81  * \param det_ctx pointer to the pattern matcher thread
82  * \param p pointer to the current packet
83  * \param m pointer to the sigmatch with context that we will cast into DetectTemplateData
84  *
85  * \retval 0 no match
86  * \retval 1 match
87  */
88 static int DetectTemplateMatch (DetectEngineThreadCtx *det_ctx, Packet *p,
89  const Signature *s, const SigMatchCtx *ctx)
90 {
91  int ret = 0;
92  const DetectTemplateData *templated = (const DetectTemplateData *) ctx;
93 #if 0
94  if (PKT_IS_PSEUDOPKT(p)) {
95  /* fake pkt */
96  }
97 
98  if (PKT_IS_IPV4(p)) {
99  /* ipv4 pkt */
100  } else if (PKT_IS_IPV6(p)) {
101  /* ipv6 pkt */
102  } else {
103  SCLogDebug("packet is of not IPv4 or IPv6");
104  return ret;
105  }
106 #endif
107  /* packet payload access */
108  if (p->payload != NULL && p->payload_len > 0) {
109  if (templated->arg1 == p->payload[0] &&
110  templated->arg2 == p->payload[p->payload_len - 1])
111  {
112  ret = 1;
113  }
114  }
115 
116  return ret;
117 }
118 
119 /**
120  * \brief This function is used to parse template options passed via template: keyword
121  *
122  * \param templatestr Pointer to the user provided template options
123  *
124  * \retval templated pointer to DetectTemplateData on success
125  * \retval NULL on failure
126  */
127 static DetectTemplateData *DetectTemplateParse (const char *templatestr)
128 {
129  char arg1[4] = "";
130  char arg2[4] = "";
131  int ov[MAX_SUBSTRINGS];
132 
133  int ret = DetectParsePcreExec(&parse_regex, templatestr, 0, 0, ov, MAX_SUBSTRINGS);
134  if (ret != 3) {
135  SCLogError(SC_ERR_PCRE_MATCH, "parse error, ret %" PRId32 "", ret);
136  return NULL;
137  }
138 
139  ret = pcre_copy_substring((char *) templatestr, ov, MAX_SUBSTRINGS, 1, arg1, sizeof(arg1));
140  if (ret < 0) {
141  SCLogError(SC_ERR_PCRE_GET_SUBSTRING, "pcre_copy_substring failed");
142  return NULL;
143  }
144  SCLogDebug("Arg1 \"%s\"", arg1);
145 
146  ret = pcre_copy_substring((char *) templatestr, ov, MAX_SUBSTRINGS, 2, arg2, sizeof(arg2));
147  if (ret < 0) {
148  SCLogError(SC_ERR_PCRE_GET_SUBSTRING, "pcre_copy_substring failed");
149  return NULL;
150  }
151  SCLogDebug("Arg2 \"%s\"", arg2);
152 
153  DetectTemplateData *templated = SCMalloc(sizeof (DetectTemplateData));
154  if (unlikely(templated == NULL))
155  return NULL;
156 
157  templated->arg1 = (uint8_t)atoi(arg1);
158  templated->arg2 = (uint8_t)atoi(arg2);
159 
160  return templated;
161 }
162 
163 /**
164  * \brief parse the options from the 'template' keyword in the rule into
165  * the Signature data structure.
166  *
167  * \param de_ctx pointer to the Detection Engine Context
168  * \param s pointer to the Current Signature
169  * \param templatestr pointer to the user provided template options
170  *
171  * \retval 0 on Success
172  * \retval -1 on Failure
173  */
174 static int DetectTemplateSetup (DetectEngineCtx *de_ctx, Signature *s, const char *templatestr)
175 {
176  DetectTemplateData *templated = DetectTemplateParse(templatestr);
177  if (templated == NULL)
178  return -1;
179 
180  SigMatch *sm = SigMatchAlloc();
181  if (sm == NULL) {
182  DetectTemplateFree(templated);
183  return -1;
184  }
185 
186  sm->type = DETECT_TEMPLATE;
187  sm->ctx = (void *)templated;
188 
191 
192  return 0;
193 }
194 
195 /**
196  * \brief this function will free memory associated with DetectTemplateData
197  *
198  * \param ptr pointer to DetectTemplateData
199  */
200 static void DetectTemplateFree(void *ptr)
201 {
202  DetectTemplateData *templated = (DetectTemplateData *)ptr;
203 
204  /* do more specific cleanup here, if needed */
205 
206  SCFree(templated);
207 }
208 
209 #ifdef UNITTESTS
210 #include "tests/detect-template.c"
211 #endif
SigTableElmt_::url
const char * url
Definition: detect.h:1204
DETECT_TEMPLATE
@ DETECT_TEMPLATE
Definition: detect-engine-register.h:239
DetectTemplateRegister
void DetectTemplateRegister(void)
Registration function for template: keyword.
Definition: detect-template.c:54
detect-engine.h
SigTableElmt_::desc
const char * desc
Definition: detect.h:1203
DetectTemplateData_
Definition: detect-template.h:32
SigTableElmt_::name
const char * name
Definition: detect.h:1201
PKT_IS_PSEUDOPKT
#define PKT_IS_PSEUDOPKT(p)
return 1 if the packet is a pseudo packet
Definition: decode.h:1115
PKT_IS_IPV6
#define PKT_IS_IPV6(p)
Definition: decode.h:253
MAX_SUBSTRINGS
#define MAX_SUBSTRINGS
SCFree
#define SCFree(a)
Definition: util-mem.h:322
unlikely
#define unlikely(expr)
Definition: util-optimize.h:35
SCLogDebug
#define SCLogDebug(...)
Definition: util-debug.h:335
Packet_::payload
uint8_t * payload
Definition: decode.h:541
DetectEngineCtx_
main detection engine ctx
Definition: detect.h:761
SigTableElmt_::Free
void(* Free)(void *)
Definition: detect.h:1192
SC_ERR_PCRE_GET_SUBSTRING
@ SC_ERR_PCRE_GET_SUBSTRING
Definition: util-error.h:34
SigTableElmt_::Setup
int(* Setup)(DetectEngineCtx *, Signature *, const char *)
Definition: detect.h:1187
Packet_::payload_len
uint16_t payload_len
Definition: decode.h:542
util-unittest.h
SC_ERR_PCRE_MATCH
@ SC_ERR_PCRE_MATCH
Definition: util-error.h:32
de_ctx
DetectEngineCtx * de_ctx
Definition: fuzz_siginit.c:16
DetectEngineThreadCtx_
Definition: detect.h:1004
DetectTemplateData_::arg1
uint8_t arg1
Definition: detect-template.h:33
DetectSetupParseRegexes
void DetectSetupParseRegexes(const char *parse_str, DetectParseRegex *detect_parse)
Definition: detect-parse.c:2440
DETECT_SM_LIST_MATCH
@ DETECT_SM_LIST_MATCH
Definition: detect.h:89
SigMatch_::ctx
SigMatchCtx * ctx
Definition: detect.h:321
SCMalloc
#define SCMalloc(a)
Definition: util-mem.h:222
Signature_::flags
uint32_t flags
Definition: detect.h:523
DetectParsePcreExec
int DetectParsePcreExec(DetectParseRegex *parse_regex, const char *str, int start_offset, int options, int *ovector, int ovector_size)
Definition: detect-parse.c:2372
Packet_
Definition: decode.h:408
SigTableElmt_::Match
int(* Match)(DetectEngineThreadCtx *, Packet *, const Signature *, const SigMatchCtx *)
Definition: detect.h:1171
SigMatchAlloc
SigMatch * SigMatchAlloc(void)
Definition: detect-parse.c:235
SigMatch_::type
uint8_t type
Definition: detect.h:319
SigMatchCtx_
Used to start a pointer to SigMatch context Should never be dereferenced without casting to something...
Definition: detect.h:313
detect-template.c
DetectTemplateData_::arg2
uint8_t arg2
Definition: detect-template.h:34
suricata-common.h
sigmatch_table
SigTableElmt sigmatch_table[DETECT_TBLSIZE]
Definition: detect-parse.c:73
DetectParseRegex_
Definition: detect-parse.h:42
PARSE_REGEX
#define PARSE_REGEX
Regex for parsing our keyword options.
Definition: detect-template.c:37
SCLogError
#define SCLogError(err_code,...)
Macro used to log ERROR messages.
Definition: util-debug.h:294
detect-template.h
detect-parse.h
Signature_
Signature container.
Definition: detect.h:522
SigMatch_
a single match condition for a signature
Definition: detect.h:318
DetectTemplateRegisterTests
void DetectTemplateRegisterTests(void)
this function registers unit tests for DetectTemplate
Definition: detect-template.c:58
PKT_IS_IPV4
#define PKT_IS_IPV4(p)
Definition: decode.h:252
SigMatchAppendSMToList
void SigMatchAppendSMToList(Signature *s, SigMatch *new, int list)
Append a SigMatch to the list type.
Definition: detect-parse.c:349
SigTableElmt_::RegisterTests
void(* RegisterTests)(void)
Definition: detect.h:1193
SIG_FLAG_REQUIRE_PACKET
#define SIG_FLAG_REQUIRE_PACKET
Definition: detect.h:223