1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
EVE JSON Schema
###############
The Suricata source distribution contains a JSON schema for the EVE
log files. This schema follows the `JSON Schema
<https://json-schema.org/>`_ specification and can be found in
``etc/schema.json``. If your distribution does not contain this file,
it can be viewed online at
https://github.com/OISF/suricata/blob/master/etc/schema.json, but note
that it is version-specific and may change between major versions of
Suricata.
This schema attempts to log all possible fields that may be seen in
Suricata's **EVE** output, including their datatype. It also includes
extensions to help map log fields to related detection keywords.
Suricata Schema Extensions
^^^^^^^^^^^^^^^^^^^^^^^^^^
We have extended JSON schema with a ``suricata`` object to add extra
Suricata context such as detection keywords related to a log field,
for example:
.. code-block:: json
"rrname": {
"type": "string",
"suricata": {
"keywords": [
"dns.answers.rrname",
"dns.response.rrname"
]
}
}
The above shows that a field named ``rrname`` has 2 keywords that are
related. Please refer to the keyword documentation to see precisely
how they are used and related to the field being logged.
Extension Reference
===================
The ``suricata`` extension object is valid on objects inside the
``properties`` object. The ``suricata`` object may accept the
following fields:
``keywords``
------------
**Type:** ``array`` or ``boolean``
* **When an array:** Contains keyword names that are related to this
JSON property. Each keyword in the array represents a detection rule
keyword that can be used to match against the corresponding field
value.
* **When ``false``:** Indicates that this JSON property has no
applicable keyword. This is used for metadata fields that don't
correspond to actual network data. For example, the ``version``
field inside a DNS object denotes the version of the log format and
is unrelated to any aspect of a DNS message, therefore no keyword is
applicable.
.. note:: As of Suricata 8.0, mapping log fields to detection keywords
is a work in progress. Any field that does not have a
``suricata.keywords`` value still needs to be evaluated.
Schema Tooling
^^^^^^^^^^^^^^
* `Suricata-Verify <https://github.com/OISF/suricata-verify>`_: Our
own tool for verifying every Suricata pull request, validates all
EVE logs generated against the schema.
* ``./scripts/eve-parity.py``: Found inside the Suricata source code
when checked out with ``git``, is a tool to provide information on
how log fields map to keywords, or how keywords map to log entries.
* ``./scripts/evedoc.py``: Generate documentation from the schema,
such as the :doc:`eve-index` included in this documentation.
|
