suricata
util-plugin.c
Go to the documentation of this file.
1 /* Copyright (C) 2026 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  * Tests for plugin patterns.
22  *
23  * These tests exercise the API as it is used by plugins and by keywords
24  * implemented in Rust, which can't see Suricata internals such as the
25  * Signature and SigMatch structs. Some of these patterns are not used by
26  * Suricata itself, so these tests may be their only in-tree user.
27  *
28  * Write the tests the way a plugin would: register through the public
29  * helpers (e.g. SCDetectHelperKeywordRegister()) and only use SC-prefixed
30  * API functions for keyword and signature access, never struct fields.
31  * This file can see the internals, so nothing but this rule enforces that.
32  */
33 
34 #include "../detect-engine.h"
35 #include "../detect-engine-helper.h"
36 #include "../detect-parse.h"
37 #include "../util-byte.h"
38 #include "../util-unittest.h"
39 
40 /*
41  * Keyword setup: a packet keyword registered the way a plugin does it, whose
42  * Setup callback records what it observed through the API so the tests can
43  * check it after the rule is parsed. It is registered on first use, so it
44  * only exists while running unit tests.
45  */
46 
47 #define UTIL_PLUGIN_TEST_KW "util-plugin-test"
48 
49 typedef struct UtilPluginTestKwData_ {
50  int value;
51  /** result of SCDetectSetupSignatureIsNegated() in Setup */
52  bool negated;
53  /** value of the previous instance found in Setup, or -1 if none */
56 
57 static int g_util_plugin_test_kw_id = -1;
58 
59 static void UtilPluginTestKwFree(DetectEngineCtx *de_ctx, void *ptr)
60 {
61  SCFree(ptr);
62 }
63 
64 static int UtilPluginTestKwSetup(DetectEngineCtx *de_ctx, Signature *s, const char *arg)
65 {
66  const uint16_t id = (uint16_t)g_util_plugin_test_kw_id;
67 
68  if (arg == NULL)
69  return -1;
70  int32_t value;
71  if (StringParseInt32(&value, 10, strlen(arg), arg) <= 0)
72  return -1;
73 
74  UtilPluginTestKwData *data = SCCalloc(1, sizeof(*data));
75  if (data == NULL)
76  return -1;
77  data->value = value;
79  data->prev_value = -1;
80 
82  if (prev != NULL) {
83  data->prev_value = ((const UtilPluginTestKwData *)SCSigMatchGetCtx(prev))->value;
84  }
85 
87  NULL) {
88  SCFree(data);
89  return -1;
90  }
91  return 0;
92 }
93 
94 static uint16_t UtilPluginTestKwRegister(void)
95 {
96  if (g_util_plugin_test_kw_id < 0) {
99  .desc = "unit test keyword for plugin patterns",
100  .flags = SIGMATCH_HANDLE_NEGATION,
101  .Setup = UtilPluginTestKwSetup,
102  .Free = UtilPluginTestKwFree,
103  };
104  uint16_t id = SCDetectHelperKeywordRegister(&kw);
105  BUG_ON(id == (uint16_t)-1);
106  g_util_plugin_test_kw_id = id;
107  }
108  return (uint16_t)g_util_plugin_test_kw_id;
109 }
110 
111 static const UtilPluginTestKwData *UtilPluginTestKwGetData(const SigMatch *sm)
112 {
113  return (const UtilPluginTestKwData *)SCSigMatchGetCtx(sm);
114 }
115 
116 /**
117  * \test SCDetectSetupSignatureIsNegated() reports the '!' that the rule parser
118  * stripped from a SIGMATCH_HANDLE_NEGATION keyword option.
119  */
120 static int UtilPluginKeywordNegationTest(void)
121 {
122  const uint16_t id = UtilPluginTestKwRegister();
125 
126  Signature *s = DetectEngineAppendSig(de_ctx, "alert ip any any -> any any (" UTIL_PLUGIN_TEST_KW
127  ":1; " UTIL_PLUGIN_TEST_KW ":!2; sid:1;)");
128  FAIL_IF_NULL(s);
129 
131  FAIL_IF_NULL(sm);
132  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->value == 2);
133  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->negated);
134 
135  sm = SCSigMatchGetPrevByType(sm, id);
136  FAIL_IF_NULL(sm);
137  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->value == 1);
138  FAIL_IF(UtilPluginTestKwGetData(sm)->negated);
139 
141  PASS;
142 }
143 
144 /**
145  * \test The SigMatch lookup walks only instances of the requested keyword,
146  * newest first, and still finds them from Setup once a sticky buffer
147  * is active.
148  */
149 static int UtilPluginKeywordLookupTest(void)
150 {
151  const uint16_t id = UtilPluginTestKwRegister();
154 
156  "alert tcp any any -> any any (" UTIL_PLUGIN_TEST_KW ":1; ttl:10; " UTIL_PLUGIN_TEST_KW
157  ":2; tcp.hdr; content:\"|00|\"; " UTIL_PLUGIN_TEST_KW ":3; sid:1;)");
158  FAIL_IF_NULL(s);
159 
161  FAIL_IF_NULL(sm);
162  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->value == 3);
163  /* seen from Setup, after tcp.hdr made a sticky buffer active */
164  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->prev_value == 2);
165 
166  sm = SCSigMatchGetPrevByType(sm, id);
167  FAIL_IF_NULL(sm);
168  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->value == 2);
169  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->prev_value == 1);
170 
171  /* skips the ttl SigMatch in between */
172  sm = SCSigMatchGetPrevByType(sm, id);
173  FAIL_IF_NULL(sm);
174  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->value == 1);
175  FAIL_IF_NOT(UtilPluginTestKwGetData(sm)->prev_value == -1);
176 
178 
179  /* no instances in another static list */
181 
183  PASS;
184 }
185 
186 #ifndef DEBUG_VALIDATION
187 /**
188  * \test Lists other than the static ones from DetectSigmatchListEnum are not
189  * supported and return NULL. Debug validation builds treat this as a
190  * bug instead.
191  */
192 static int UtilPluginKeywordLookupDynamicListTest(void)
193 {
194  const uint16_t id = UtilPluginTestKwRegister();
197 
199  de_ctx, "alert tcp any any -> any any (" UTIL_PLUGIN_TEST_KW ":1; sid:1;)");
200  FAIL_IF_NULL(s);
201 
205 
207  PASS;
208 }
209 #endif
210 
212 {
213  UtRegisterTest("UtilPluginKeywordNegationTest", UtilPluginKeywordNegationTest);
214  UtRegisterTest("UtilPluginKeywordLookupTest", UtilPluginKeywordLookupTest);
215 #ifndef DEBUG_VALIDATION
217  "UtilPluginKeywordLookupDynamicListTest", UtilPluginKeywordLookupDynamicListTest);
218 #endif
219 }
FAIL_IF_NULL
#define FAIL_IF_NULL(expr)
Fail a test if expression evaluates to NULL.
Definition: util-unittest.h:89
SCSigTableAppLiteElmt::name
const char * name
keyword name
Definition: detect-engine-helper.h:53
UtilPluginRegisterTests
void UtilPluginRegisterTests(void)
Definition: util-plugin.c:211
UtilPluginTestKwData_
Definition: util-plugin.c:49
SCSigMatchGetCtx
const SigMatchCtx * SCSigMatchGetCtx(const SigMatch *sm)
Get the keyword context of sm, as passed to SCSigMatchAppendSMToList() by the keyword's Setup callbac...
Definition: detect-parse.c:786
UtRegisterTest
void UtRegisterTest(const char *name, int(*TestFn)(void))
Register unit test.
Definition: util-unittest.c:101
UTIL_PLUGIN_TEST_KW
#define UTIL_PLUGIN_TEST_KW
Definition: util-plugin.c:47
DetectEngineCtx_
main detection engine ctx
Definition: detect.h:966
DetectEngineCtxFree
void DetectEngineCtxFree(DetectEngineCtx *)
Free a DetectEngineCtx::
Definition: detect-engine.c:2913
StringParseInt32
int StringParseInt32(int32_t *res, int base, size_t len, const char *str)
Definition: util-byte.c:586
DetectEngineAppendSig
Signature * DetectEngineAppendSig(DetectEngineCtx *, const char *)
Parse and append a Signature into the Detection Engine Context signature list.
Definition: detect-parse.c:4045
UtilPluginTestKwData_::prev_value
int prev_value
Definition: util-plugin.c:54
FAIL_IF_NOT
#define FAIL_IF_NOT(expr)
Fail a test if expression evaluates to false.
Definition: util-unittest.h:82
SCSigTableAppLiteElmt
App-layer light version of SigTableElmt.
Definition: detect-engine-helper.h:51
UtilPluginTestKwData
struct UtilPluginTestKwData_ UtilPluginTestKwData
FAIL_IF_NOT_NULL
#define FAIL_IF_NOT_NULL(expr)
Fail a test if expression evaluates to non-NULL.
Definition: util-unittest.h:96
PASS
#define PASS
Pass the test.
Definition: util-unittest.h:105
de_ctx
DetectEngineCtx * de_ctx
Definition: fuzz_siginit.c:22
UtilPluginTestKwData_::negated
bool negated
Definition: util-plugin.c:52
DETECT_SM_LIST_MAX
@ DETECT_SM_LIST_MAX
Definition: detect-engine-register.h:324
SCSigMatchAppendSMToList
SigMatch * SCSigMatchAppendSMToList(DetectEngineCtx *de_ctx, Signature *s, uint16_t type, SigMatchCtx *ctx, const int list)
Append a SigMatch to the list type.
Definition: detect-parse.c:424
UtilPluginTestKwData_::value
int value
Definition: util-plugin.c:50
BUG_ON
#define BUG_ON(x)
Definition: suricata-common.h:322
SCDetectHelperKeywordRegister
uint16_t SCDetectHelperKeywordRegister(const SCSigTableAppLiteElmt *kw)
Definition: detect-engine-helper.c:184
SCDetectSetupSignatureIsNegated
bool SCDetectSetupSignatureIsNegated(const Signature *s)
Check if the keyword option being set up was negated.
Definition: detect-parse.c:2684
SigMatchCtx_
Used to start a pointer to SigMatch context Should never be dereferenced without casting to something...
Definition: detect.h:326
SCDetectSignatureGetLastSMByType
const SigMatch * SCDetectSignatureGetLastSMByType(const Signature *s, int list_id, uint16_t type)
Get the last SigMatch of keyword type in list list_id.
Definition: detect-parse.c:758
FAIL_IF
#define FAIL_IF(expr)
Fail a test if expression evaluates to true.
Definition: util-unittest.h:71
DETECT_SM_LIST_MATCH
@ DETECT_SM_LIST_MATCH
Definition: detect-engine-register.h:306
DETECT_SM_LIST_POSTMATCH
@ DETECT_SM_LIST_POSTMATCH
Definition: detect-engine-register.h:316
SCSigMatchGetPrevByType
const SigMatch * SCSigMatchGetPrevByType(const SigMatch *sm, uint16_t type)
Get the previous SigMatch of keyword type before sm.
Definition: detect-parse.c:775
SCFree
#define SCFree(p)
Definition: util-mem.h:61
Signature_
Signature container.
Definition: detect.h:663
SigMatch_
a single match condition for a signature
Definition: detect.h:331
DetectEngineCtxInit
DetectEngineCtx * DetectEngineCtxInit(void)
Definition: detect-engine.c:2874
SCCalloc
#define SCCalloc(nm, sz)
Definition: util-mem.h:53
SIGMATCH_HANDLE_NEGATION
#define SIGMATCH_HANDLE_NEGATION
Definition: detect-engine-register.h:355