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 #include "util-byte.h"
29 
30 #include "detect-parse.h"
31 #include "detect-engine.h"
32 
33 #include "detect-template.h"
34 
35 /**
36  * \brief Regex for parsing our keyword options
37  */
38 #define PARSE_REGEX "^\\s*([0-9]+)?\\s*,s*([0-9]+)?\\s*$"
39 static DetectParseRegex parse_regex;
40 
41 /* Prototypes of functions registered in DetectTemplateRegister below */
42 static int DetectTemplateMatch (DetectEngineThreadCtx *,
43  Packet *, const Signature *, const SigMatchCtx *);
44 static int DetectTemplateSetup (DetectEngineCtx *, Signature *, const char *);
45 static void DetectTemplateFree (DetectEngineCtx *, void *);
46 #ifdef UNITTESTS
47 static void DetectTemplateRegisterTests (void);
48 #endif
49 
50 /**
51  * \brief Registration function for template: keyword
52  *
53  * This function is called once in the 'lifetime' of the engine.
54  */
56  /* keyword name: this is how the keyword is used in a rule */
57  sigmatch_table[DETECT_TEMPLATE].name = "template";
58  /* description: listed in "suricata --list-keywords=all" */
59  sigmatch_table[DETECT_TEMPLATE].desc = "give an introduction into how a detection module works";
60  /* link to further documentation of the keyword. Normally on the Suricata redmine/wiki */
61  sigmatch_table[DETECT_TEMPLATE].url = "https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_Developers_Guide";
62  /* match function is called when the signature is inspected on a packet */
63  sigmatch_table[DETECT_TEMPLATE].Match = DetectTemplateMatch;
64  /* setup function is called during signature parsing, when the template
65  * keyword is encountered in the rule */
66  sigmatch_table[DETECT_TEMPLATE].Setup = DetectTemplateSetup;
67  /* free function is called when the detect engine is freed. Normally at
68  * shutdown, but also during rule reloads. */
69  sigmatch_table[DETECT_TEMPLATE].Free = DetectTemplateFree;
70 #ifdef UNITTESTS
71  /* registers unittests into the system */
73 #endif
74  /* set up the PCRE for keyword parsing */
75  DetectSetupParseRegexes(PARSE_REGEX, &parse_regex);
76 }
77 
78 /**
79  * \brief This function is used to match TEMPLATE rule option on a packet
80  *
81  * \param t pointer to thread vars
82  * \param det_ctx pointer to the pattern matcher thread
83  * \param p pointer to the current packet
84  * \param m pointer to the sigmatch with context that we will cast into DetectTemplateData
85  *
86  * \retval 0 no match
87  * \retval 1 match
88  */
89 static int DetectTemplateMatch (DetectEngineThreadCtx *det_ctx, Packet *p,
90  const Signature *s, const SigMatchCtx *ctx)
91 {
92  int ret = 0;
93  const DetectTemplateData *templated = (const DetectTemplateData *) ctx;
94 #if 0
95  if (PKT_IS_PSEUDOPKT(p)) {
96  /* fake pkt */
97  }
98 
99  if (PacketIsIPv4(p)) {
100  /* ipv4 pkt */
101  } else if (PacketIsIPv6(p)) {
102  /* ipv6 pkt */
103  } else {
104  SCLogDebug("packet is of not IPv4 or IPv6");
105  return ret;
106  }
107 #endif
108  /* packet payload access */
109  if (p->payload != NULL && p->payload_len > 0) {
110  if (templated->arg1 == p->payload[0] &&
111  templated->arg2 == p->payload[p->payload_len - 1])
112  {
113  ret = 1;
114  }
115  }
116 
117  return ret;
118 }
119 
120 /**
121  * \brief This function is used to parse template options passed via template: keyword
122  *
123  * \param templatestr Pointer to the user provided template options
124  *
125  * \retval templated pointer to DetectTemplateData on success
126  * \retval NULL on failure
127  */
128 static DetectTemplateData *DetectTemplateParse (const char *templatestr)
129 {
130  char arg1[4] = "";
131  char arg2[4] = "";
132 
133  pcre2_match_data *match = NULL;
134  int ret = DetectParsePcreExec(&parse_regex, &match, templatestr, 0, 0);
135  if (ret != 3) {
136  SCLogError("parse error, ret %" PRId32 "", ret);
137  goto error;
138  }
139 
140  size_t pcre2len = sizeof(arg1);
141  ret = pcre2_substring_copy_bynumber(match, 1, (PCRE2_UCHAR8 *)arg1, &pcre2len);
142  if (ret < 0) {
143  SCLogError("pcre2_substring_copy_bynumber failed");
144  goto error;
145  }
146  SCLogDebug("Arg1 \"%s\"", arg1);
147 
148  pcre2len = sizeof(arg2);
149  ret = pcre2_substring_copy_bynumber(match, 2, (PCRE2_UCHAR8 *)arg2, &pcre2len);
150  if (ret < 0) {
151  SCLogError("pcre2_substring_copy_bynumber failed");
152  goto error;
153  }
154  SCLogDebug("Arg2 \"%s\"", arg2);
155 
156  DetectTemplateData *templated = SCMalloc(sizeof (DetectTemplateData));
157  if (unlikely(templated == NULL))
158  goto error;
159 
160  if (ByteExtractStringUint8(&templated->arg1, 10, 0, (const char *)arg1) < 0) {
161  SCFree(templated);
162  goto error;
163  }
164  if (ByteExtractStringUint8(&templated->arg2, 10, 0, (const char *)arg2) < 0) {
165  SCFree(templated);
166  goto error;
167  }
168  pcre2_match_data_free(match);
169  return templated;
170 
171 error:
172  if (match) {
173  pcre2_match_data_free(match);
174  }
175  return NULL;
176 }
177 
178 /**
179  * \brief parse the options from the 'template' keyword in the rule into
180  * the Signature data structure.
181  *
182  * \param de_ctx pointer to the Detection Engine Context
183  * \param s pointer to the Current Signature
184  * \param templatestr pointer to the user provided template options
185  *
186  * \retval 0 on Success
187  * \retval -1 on Failure
188  */
189 static int DetectTemplateSetup (DetectEngineCtx *de_ctx, Signature *s, const char *templatestr)
190 {
191  DetectTemplateData *templated = DetectTemplateParse(templatestr);
192  if (templated == NULL)
193  return -1;
194 
196  DETECT_SM_LIST_MATCH) == NULL) {
197  DetectTemplateFree(de_ctx, templated);
198  return -1;
199  }
201 
202  return 0;
203 }
204 
205 /**
206  * \brief this function will free memory associated with DetectTemplateData
207  *
208  * \param ptr pointer to DetectTemplateData
209  */
210 static void DetectTemplateFree(DetectEngineCtx *de_ctx, void *ptr)
211 {
212  DetectTemplateData *templated = (DetectTemplateData *)ptr;
213 
214  /* do more specific cleanup here, if needed */
215 
216  SCFree(templated);
217 }
218 
219 #ifdef UNITTESTS
220 #include "tests/detect-template.c"
221 #endif
util-byte.h
SigTableElmt_::url
const char * url
Definition: detect.h:1311
DETECT_TEMPLATE
@ DETECT_TEMPLATE
Definition: detect-engine-register.h:282
DetectTemplateRegister
void DetectTemplateRegister(void)
Registration function for template: keyword.
Definition: detect-template.c:55
detect-engine.h
SigTableElmt_::desc
const char * desc
Definition: detect.h:1310
DetectTemplateData_
Definition: detect-template.h:32
SigTableElmt_::Free
void(* Free)(DetectEngineCtx *, void *)
Definition: detect.h:1298
DetectParseRegex
Definition: detect-parse.h:62
SigTableElmt_::name
const char * name
Definition: detect.h:1308
PKT_IS_PSEUDOPKT
#define PKT_IS_PSEUDOPKT(p)
return 1 if the packet is a pseudo packet
Definition: decode.h:1330
unlikely
#define unlikely(expr)
Definition: util-optimize.h:35
SCLogDebug
#define SCLogDebug(...)
Definition: util-debug.h:269
Packet_::payload
uint8_t * payload
Definition: decode.h:588
DetectEngineCtx_
main detection engine ctx
Definition: detect.h:848
DetectParsePcreExec
int DetectParsePcreExec(DetectParseRegex *parse_regex, pcre2_match_data **match, const char *str, int start_offset, int options)
Definition: detect-parse.c:2663
SigTableElmt_::Setup
int(* Setup)(DetectEngineCtx *, Signature *, const char *)
Definition: detect.h:1293
Packet_::payload_len
uint16_t payload_len
Definition: decode.h:589
util-unittest.h
de_ctx
DetectEngineCtx * de_ctx
Definition: fuzz_siginit.c:17
DetectEngineThreadCtx_
Definition: detect.h:1104
DetectTemplateData_::arg1
uint8_t arg1
Definition: detect-template.h:33
DetectSetupParseRegexes
void DetectSetupParseRegexes(const char *parse_str, DetectParseRegex *detect_parse)
Definition: detect-parse.c:2789
DETECT_SM_LIST_MATCH
@ DETECT_SM_LIST_MATCH
Definition: detect.h:114
Signature_::flags
uint32_t flags
Definition: detect.h:603
Packet_
Definition: decode.h:482
SigTableElmt_::Match
int(* Match)(DetectEngineThreadCtx *, Packet *, const Signature *, const SigMatchCtx *)
Definition: detect.h:1276
SigMatchCtx_
Used to start a pointer to SigMatch context Should never be dereferenced without casting to something...
Definition: detect.h:345
detect-template.c
ByteExtractStringUint8
int ByteExtractStringUint8(uint8_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:285
DetectTemplateData_::arg2
uint8_t arg2
Definition: detect-template.h:34
suricata-common.h
sigmatch_table
SigTableElmt sigmatch_table[DETECT_TBLSIZE]
Definition: detect-parse.c:127
PARSE_REGEX
#define PARSE_REGEX
Regex for parsing our keyword options.
Definition: detect-template.c:38
detect-template.h
SCMalloc
#define SCMalloc(sz)
Definition: util-mem.h:47
SCLogError
#define SCLogError(...)
Macro used to log ERROR messages.
Definition: util-debug.h:261
SCFree
#define SCFree(p)
Definition: util-mem.h:61
detect-parse.h
Signature_
Signature container.
Definition: detect.h:602
SigMatchAppendSMToList
SigMatch * SigMatchAppendSMToList(DetectEngineCtx *de_ctx, Signature *s, uint16_t type, SigMatchCtx *ctx, const int list)
Append a SigMatch to the list type.
Definition: detect-parse.c:436
DetectTemplateRegisterTests
void DetectTemplateRegisterTests(void)
this function registers unit tests for DetectTemplate
Definition: detect-template.c:58
SigTableElmt_::RegisterTests
void(* RegisterTests)(void)
Definition: detect.h:1300
SIG_FLAG_REQUIRE_PACKET
#define SIG_FLAG_REQUIRE_PACKET
Definition: detect.h:249