Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

output/eve: add 'verdict' field to 'alert' and 'drop' events - v8 #9162

Closed
wants to merge 6 commits into from
Closed

output/eve: add 'verdict' field to 'alert' and 'drop' events - v8 #9162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
412c08c
userguide/eve: add section about drop event type
jufajardini Dec 23, 2022
a0509c0
misc: fix typos & update copyright years
jufajardini Jan 5, 2023
1fa4c22
output: add verdict as an event type
jufajardini Jun 13, 2023
6615f84
output/alert: add verdict field
jufajardini Jul 5, 2023
aa205da
outputs/drop: add verdict field
jufajardini Jul 5, 2023
24c9bf8
userguide/eve: format and reorganize alert section
jufajardini Dec 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 72 additions & 15 deletions doc/userguide/output/eve/eve-json-format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,23 +89,17 @@ generated the event.
Event type: Alert
-----------------

Field action
~~~~~~~~~~~~

Possible values: "allowed" and "blocked"

Example:

::
This field contains data about a signature that matched, such as
``signature_id`` (``sid`` in the rule) and the ``signature`` (``msg`` in the
rule).


"action":"allowed"

Action is set to "allowed" unless a rule used the "drop" action and Suricata is in IPS mode, or when the rule used the "reject" action.

It can also contain information about Source and Target of the attack in the alert.source and alert.target field if target keyword is used in
It can also contain information about Source and Target of the attack in the
``alert.source`` and ``alert.target`` field if target keyword is used in
the signature.

This event will also have the ``pcap_cnt`` field, when running in pcap mode, to
indicate which packet triggered the signature.

::

"alert": {
Expand Down Expand Up @@ -147,13 +141,76 @@ the signature.
}
},

Action field
~~~~~~~~~~~~

Possible values: "allowed" and "blocked".

Example:

::

"action":"allowed"

Action is set to "allowed" unless a rule used the "drop" action and Suricata is
in IPS mode, or when the rule used the "reject" action. It is important to note
that this does not necessarily indicate the final verdict for a given packet or
flow, since one packet may match on several rules.

Verdict Field
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not a field, but an object containing other fields, right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, I was seeing it as a field because it's part of 'alert', but... that's indeed wrong.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also: update description, there are more fields in verdict now.

~~~~~~~~~~~~~

Possible values are "accept", "drop" or "reject".

Example:

::

"verdict":"drop"

Verdict is the final action that will be applied to a given packet, based on all
the signatures triggered by it. In IPS mode, all values are possible. In IDS
mode, verdict is only present if its value is "reject".

Pcap Field
~~~~~~~~~~

If pcap log capture is active in `multi` mode, a `capture_file` key will be added to the event
with value being the full path of the pcap file where the corresponding packets
have been extracted.

Eventy type: Verdict
--------------------

The "verdict" event indicates the final decision by the engine for a given
packet that triggered alerts. This is especially useful for scenarios in which
there are several alerts with different, conflicting actions, as it will state
what was the prevailing action and whether the packet was also dropped or any
other outcomes (as it happens with the ``reject`` action, for instance).

Examples
~~~~~~~~

::

"verdict": {
"action": "alert"
"reject-target": "both"
"reject": [ "tcp-reset", "icmp-prohib", "user defined" ]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the value here should be a json array of strings

}

Fields
~~~~~~

* "action": the action associated with the alert, and performed by the engine.
Possible values: ``alert``, ``pass``, ``drop``.
* "reject-target": (optional) dependent on Engine mode (IDS or IPS) and type of reject
(cf :ref:`actions`). Possible values: ``source``, ``destination``, ``both``.
* "reject": (optional) ``["tcp-reset", "icmp-prohib", "user defined"]`` depending on
flow protocol and user settings.

.. note:: ``reject`` is only logged for ``reject`` rules.

Event type: Anomaly
-------------------

Expand Down Expand Up @@ -2532,4 +2589,4 @@ Example of DHCP log entry (extended logging enabled):
"rebinding_time":43200,
"client_id":"54:ee:75:51:e0:66",
"dns_servers":["192.168.1.50","192.168.1.49"]
}
}
13 changes: 13 additions & 0 deletions doc/userguide/output/eve/eve-json-output.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,19 @@ enabled, then the log gets more verbose.

By using ``custom`` it is possible to select which TLS fields to log.

Drops
~~~~~

Drops are event types logged when the engine drops a packet.

Config::

- drop:
alerts: yes # log alerts that caused drops
flows: all # start or all: 'start' logs only a single drop
# per flow direction. All logs each dropped pkt.


Date modifiers in filename
~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down
25 changes: 25 additions & 0 deletions etc/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,11 @@
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d+[+\\-]\\d+$"
},
"verdict": {
"type": "object",
"additionalProperties": true,
"$ref": "#/$defs/verdict_type"
},
"direction": {
"type": "string"
},
Expand Down Expand Up @@ -262,6 +267,9 @@
"items": {
"type": "string"
}
},
"verdict": {
"$ref": "#/$defs/verdict_type"
}
},
"additionalProperties": true
Expand Down Expand Up @@ -1289,6 +1297,9 @@
},
"reason": {
"type": "string"
},
"verdict": {
"$ref": "#/$defs/verdict_type"
}
},
"additionalProperties": false
Expand Down Expand Up @@ -5482,6 +5493,20 @@
"$comment": "Definition for TLS date formats",
"type": "string",
"pattern": "^[1-2]\\d{3}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$"
},
"verdict_type": {
"type": "object",
"properties": {
"action": {
"type": "string"
},
"reject": {
"type": "string"
},
"reject-target": {
"type": "string"
}
}
}
}
}
2 changes: 2 additions & 0 deletions src/Makefile.am
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,6 +427,7 @@ noinst_HEADERS = \
output-json-template.h \
output-json-tftp.h \
output-json-tls.h \
output-json-verdict.h \
output-eve-syslog.h \
output-lua.h \
output-packet.h \
Expand Down Expand Up @@ -1036,6 +1037,7 @@ libsuricata_c_a_SOURCES = \
output-json-template.c \
output-json-tftp.c \
output-json-tls.c \
output-json-verdict.c \
output-eve-syslog.c \
output-lua.c \
output-packet.c \
Expand Down
2 changes: 1 addition & 1 deletion src/decode.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* Copyright (C) 2007-2022 Open Information Security Foundation
/* Copyright (C) 2007-2023 Open Information Security Foundation
*
* You can copy, redistribute or modify this Program under the terms of
* the GNU General Public License version 2 as published by the Free
Expand Down
9 changes: 8 additions & 1 deletion src/output-json-alert.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* Copyright (C) 2013-2022 Open Information Security Foundation
/* Copyright (C) 2013-2023 Open Information Security Foundation
*
* You can copy, redistribute or modify this Program under the terms of
* the GNU General Public License version 2 as published by the Free
Expand Down Expand Up @@ -78,6 +78,7 @@
#include "output-json-modbus.h"
#include "output-json-frame.h"
#include "output-json-quic.h"
#include "output-json-verdict.h"

#include "util-byte.h"
#include "util-privs.h"
Expand All @@ -101,6 +102,7 @@
#define LOG_JSON_HTTP_BODY_BASE64 BIT_U16(7)
#define LOG_JSON_RULE_METADATA BIT_U16(8)
#define LOG_JSON_RULE BIT_U16(9)
#define LOG_JSON_VERDICT BIT_U16(10)

#define METADATA_DEFAULTS ( LOG_JSON_FLOW | \
LOG_JSON_APP_LAYER | \
Expand Down Expand Up @@ -828,6 +830,10 @@ static int AlertJson(ThreadVars *tv, JsonAlertLogThread *aft, const Packet *p)
jb_set_string(jb, "capture_file", pcap_filename);
}

if (json_output_ctx->flags & LOG_JSON_VERDICT) {
GetVerdictJsonInfo(jb, p);
}

OutputJsonBuilderBuffer(jb, aft->ctx);
jb_free(jb);
}
Expand Down Expand Up @@ -1016,6 +1022,7 @@ static void JsonAlertLogSetupMetadata(AlertJsonOutputCtx *json_output_ctx,
SetFlag(conf, "payload-printable", LOG_JSON_PAYLOAD, &flags);
SetFlag(conf, "http-body-printable", LOG_JSON_HTTP_BODY, &flags);
SetFlag(conf, "http-body", LOG_JSON_HTTP_BODY_BASE64, &flags);
SetFlag(conf, "verdict", LOG_JSON_VERDICT, &flags);

/* Check for obsolete flags and warn that they have no effect. */
static const char *deprecated_flags[] = { "http", "tls", "ssh", "smtp", "dnp3", "app-layer",
Expand Down
2 changes: 1 addition & 1 deletion src/output-json-alert.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* Copyright (C) 2013-2014 Open Information Security Foundation
/* Copyright (C) 2013-2023 Open Information Security Foundation
*
* You can copy, redistribute or modify this Program under the terms of
* the GNU General Public License version 2 as published by the Free
Expand Down
22 changes: 17 additions & 5 deletions src/output-json-drop.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* Copyright (C) 2007-2021 Open Information Security Foundation
/* Copyright (C) 2007-2023 Open Information Security Foundation
*
* You can copy, redistribute or modify this Program under the terms of
* the GNU General Public License version 2 as published by the Free
Expand Down Expand Up @@ -45,6 +45,7 @@
#include "output-json.h"
#include "output-json-alert.h"
#include "output-json-drop.h"
#include "output-json-verdict.h"

#include "util-unittest.h"
#include "util-unittest-helper.h"
Expand All @@ -60,7 +61,8 @@

#define MODULE_NAME "JsonDropLog"

#define LOG_DROP_ALERTS 1
#define LOG_DROP_ALERTS BIT_U8(1)
#define LOG_DROP_VERDICT BIT_U8(2)

Comment on lines -63 to +65
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed this, tried adding the flows start/all option here, but led to failures. Can make this a TODO.

typedef struct JsonDropOutputCtx_ {
uint8_t flags;
Expand All @@ -82,7 +84,7 @@ static int g_droplog_flows_start = 1;
* \param tv Pointer the current thread variables
* \param p Pointer the packet which is being logged
*
* \return return TM_EODE_OK on success
* \return return TM_ECODE_OK on success
*/
static int DropLogJSON (JsonDropLogThread *aft, const Packet *p)
{
Expand Down Expand Up @@ -158,6 +160,10 @@ static int DropLogJSON (JsonDropLogThread *aft, const Packet *p)
/* Close drop. */
jb_close(js);

if (aft->drop_ctx->flags & LOG_DROP_VERDICT) {
GetVerdictJsonInfo(js, p);
}

if (aft->drop_ctx->flags & LOG_DROP_ALERTS) {
int logged = 0;
int i;
Expand Down Expand Up @@ -273,7 +279,7 @@ static OutputInitResult JsonDropLogInitCtxSub(ConfNode *conf, OutputCtx *parent_
const char *extended = ConfNodeLookupChildValue(conf, "alerts");
if (extended != NULL) {
if (ConfValIsTrue(extended)) {
drop_ctx->flags = LOG_DROP_ALERTS;
drop_ctx->flags |= LOG_DROP_ALERTS;
}
}
extended = ConfNodeLookupChildValue(conf, "flows");
Expand All @@ -287,6 +293,12 @@ static OutputInitResult JsonDropLogInitCtxSub(ConfNode *conf, OutputCtx *parent_
"'flow' are 'start' and 'all'");
}
}
extended = ConfNodeLookupChildValue(conf, "verdict");
if (extended != NULL) {
if (ConfValIsTrue(extended)) {
drop_ctx->flags |= LOG_DROP_VERDICT;
}
}
}

drop_ctx->eve_ctx = ajt;
Expand All @@ -306,7 +318,7 @@ static OutputInitResult JsonDropLogInitCtxSub(ConfNode *conf, OutputCtx *parent_
* \param data Pointer to the droplog struct
* \param p Pointer the packet which is being logged
*
* \retval 0 on succes
* \retval 0 on success
*/
static int JsonDropLogger(ThreadVars *tv, void *thread_data, const Packet *p)
{
Expand Down
Loading
Loading