mirror of https://github.com/OISF/suricata
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
81 lines
2.8 KiB
ReStructuredText
81 lines
2.8 KiB
ReStructuredText
2 weeks ago
|
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.
|