| Name | SuricataLog JSON |
| Version |
1.1.4
JSON |
| download |
| home_page | None |
| Summary | Scripts to display contents of Suricata eve.json log |
| upload_time | 2025-07-19 16:48:44 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
suricata
log
eve
json
cybersecurity
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SuricataLog
[](https://pepy.tech/project/suricatalog)
When I started learning how to use [Suricata](https://suricata.io/) quickly found that I needed a tool to inspect the eve.json file; Most of the tutorials
and documentation out there suggested installing a stack to do the following tasks:
1. Store the logs in a central location
2. Normalize and enrich the events, specially alerts
3. Use a frontend to dive into the data
Which is very useful, but what if I just needed to do a quick inspection of the events?
Sooner or later you will get [bored to death](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) doing this:
```shell
cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode
```
SuricataLog is a set of tools/ scripts to parse and display Suricata log files (like /var/log/suricata/eve.json)
The [Eve JSON format](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) is not very complex,
so I wrote few scripts with the features I tough would be more useful for my home network analysis.
As a bonus, I wrote my learning experience as a [tutorial](TUTORIAL.md) that you can use to learn about Suricata and also how to test it.
## Installing from PIP
Before you do anything else, make sure your environment is good to go:
```shell
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
python3 -m pip install --upgrade pip setuptools wheel
```
### Installing from Pypi.org
```shell
pip3 install --upgrade SuricataLog
```
### Installing from source
```shell
git clone git@github.com:josevnz/SuricataLog.git
cd SuricataLog
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
python3 -m pip install --upgrade build
python3 -m build
pip3 install dist/SuricataLog-X.Y.Z-py3-none-any.whl
```
### Developer installation
So you want to contribute? Or found a bug and think you can submit a patch? Nice! Here is what you can dd to run on development mode:
```shell
git clone git@github.com:josevnz/SuricataLog.git
cd SuricataLog
python3 -m venv ~/virtualenv/suricatalog
. ~/virtualenv/suricatalog/bin/activate
pip install --upgrade pip
python -m pip install --upgrade build
pip install textual-dev
pip install --editable .
```
Running unit tests is very easy after that:
```shell
(SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py
.........
----------------------------------------------------------------------
Ran 9 tests in 0.334s
OK
```
If the unit tests fails, then this is most likely the first place to fix a problem.
I do recommend also running the textualize console and watch for the console messages:
```shell
# textual console
textual console --exclude SYSTEM --exclude EVENT
```
Then on another terminal:
```shell
textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json
```
That will print even debug messages on the console (you can exclude these if you restart the console with '--exclude DEBUG')
### Creating a Docker image
Please check [DOCKER.md](DOCKER.md) for more details.
## Running the scripts
Once everything is installed in your virtual environment you should be able to call the scripts
You can find out what applications got installed by using auto complete, after activating your virtual environment:
```shell
eve_[tab][tab]
```
And if you install the Bash auto complete extension you will also get some suggestions for the flags.
### Simple EVE log parser
Better see it by yourself (remember, use --help to learn what options are supported)
#### Table format:
````shell
eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json
````
### Canned reports with eve_json.py
```shell
(suricatalog) [josevnz@dmaf5 SuricataLog]$ eve_json --help
usage: eve_json [-h] [--nxdomain | --payload | --flow | --netflow NETFLOW | --useragent] eve [eve ...]
This script is inspired by the examples provided on [15.1.3. Eve JSON ‘jq’ Examples](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-
examplesjq.html) A few things: * The output uses colorized JSON
positional arguments:
eve Path to one or more /var/log/suricata/eve.json file to parse.
optional arguments:
-h, --help show this help message and exit
--nxdomain Show DNS records with NXDOMAIN
--payload Show alerts with a printable payload
--flow Aggregated flow report per protocol and destination port
--netflow NETFLOW Get the netflow for a given IP address
--useragent Top user agent in HTTP traffic
```
Take a look at some examples below:
#### NXDOMAIN
```shell
eve_json --nxdomain test/eve.json
```
#### PAYLOAD
```shell
eve_json --payload ~/Downloads/eve.json
```
#### FLOW
```shell
eve_json --flow test/eve_udp_flow.json
```
#### NETFLOW
```shell
eve_json --netflow 224.0.0.251 test/eve_udp_flow.json
```
#### USERAGENT
```shell
eve_json --useragent test/eve.json
```
### Running eve_* applications on a browser
You can run Suricata Log applications on a browser by using the `eve_server` wrapper:
```shell
# Show the flow report on a eve.json file
eve_server --application eve_json -- --flow ~/eve.json
# Show NX domain report
eve_server --application eve_json -- --nxdomain ~/eve.json
# Inspect the eve.json records
eve_server --applications eve_log -- ~/eve.json
```
You need to pass the '--' to tell the server than this options belong to the underlying eve_* you want to call.
## Running from Docker
It is also possible to run SuricataLog from a Docker container. Please see the [DOCKER.md](DOCKER.md) for more details
## Running with uv
If you have uv, you can just do this:
```shell
uvx --from SuricataLog eve_log /var/log/suricata/eve.json
uvx --from SuricataLog eve_json --useragent /var/log/suricata/eve.json
uvx --from SuricataLog eve_server --application eve_json -- --flow /var/log/suricata/eve.json
```
You get the idea.
## Bash Auto complete
I tried my best to follow [8.6 Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion)
I provided auto complete for the most common flags. You can figure out all the flags by passing '--help' to any of the scripts.
### Installation of auto complete commands
You can install Bash autocomplete for all the SuricataLog scripts. Just run the 'eve_autocomplete' and follow directions:
```shell
eve_autocomplete --help
```
## Supported versions
I work on this project on **my spare time** and I cannot support every version of Linux/ Python combination out there.
This is my current test bed, and it may change without further notice
| SuricataLog | Supported | OS | Python | Suricata |
|-------------|-----------|----------------------------------|-----------|----------|
| <= 0.8 | NO | NA | < 3.8 | 6.04 |
| 0.9+ | NO | fedora 37 | => 3.11.4 | 6.04 |
| 0.9+ | NO | Armbian 23.02.2 Jammy | => 3.10.6 | 6.04 |
| 0.9+ | NO | Ubuntu 20.04.4 LTS (Focal Fossa) | => 3.8.10 | 6.04 |
| 1.0.3+ | YES | fedora 40 | => 3.11.4 | 7.0.6 |
*You are more than welcome to*:
* Submit patches with new features and bug-fixes.
* Open bug reports. Be as detailed as possible, otherwise I will have no choice but to close it.
## Tutorials
* [Suricata, RaspberryPI4 and Python to secure your home network](TUTORIAL.md)
* [Using SuricataLog to analyze your events](Using_SuricataLog_to_analyze_your_events.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "SuricataLog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Jose Vicente Nunez <kodegeek.com@protonmail.com>",
"keywords": "suricata, log, eve, json, cybersecurity",
"author": null,
"author_email": "Jose Vicente Nunez <kodegeek.com@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3f/68/c7c5fb13aaa4256cabcbacc87d4da98695f9609d4026f7208b649c7061d1/suricatalog-1.1.4.tar.gz",
"platform": null,
"description": "# SuricataLog\n\n[](https://pepy.tech/project/suricatalog)\n\nWhen I started learning how to use [Suricata](https://suricata.io/) quickly found that I needed a tool to inspect the eve.json file; Most of the tutorials \nand documentation out there suggested installing a stack to do the following tasks:\n1. Store the logs in a central location\n2. Normalize and enrich the events, specially alerts\n3. Use a frontend to dive into the data\n\nWhich is very useful, but what if I just needed to do a quick inspection of the events?\n\nSooner or later you will get [bored to death](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-examplesjq.html) doing this:\n\n```shell\ncat eve.json | jq -r -c 'select(.event_type==\"alert\")|.payload'| base64 --decode\n```\n\nSuricataLog is a set of tools/ scripts to parse and display Suricata log files (like /var/log/suricata/eve.json)\n\nThe [Eve JSON format](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-format.html) is not very complex, \nso I wrote few scripts with the features I tough would be more useful for my home network analysis.\n\nAs a bonus, I wrote my learning experience as a [tutorial](TUTORIAL.md) that you can use to learn about Suricata and also how to test it.\n\n## Installing from PIP\n\nBefore you do anything else, make sure your environment is good to go:\n\n```shell\npython3 -m venv ~/virtualenv/suricatalog\n. ~/virtualenv/suricatalog/bin/activate\npython3 -m pip install --upgrade pip setuptools wheel\n```\n\n### Installing from Pypi.org\n\n```shell\npip3 install --upgrade SuricataLog\n```\n\n### Installing from source\n\n```shell\ngit clone git@github.com:josevnz/SuricataLog.git\ncd SuricataLog\npython3 -m venv ~/virtualenv/suricatalog\n. ~/virtualenv/suricatalog/bin/activate\npython3 -m pip install --upgrade build\npython3 -m build\npip3 install dist/SuricataLog-X.Y.Z-py3-none-any.whl\n```\n\n### Developer installation\n\nSo you want to contribute? Or found a bug and think you can submit a patch? Nice! Here is what you can dd to run on development mode:\n\n```shell\ngit clone git@github.com:josevnz/SuricataLog.git\ncd SuricataLog\npython3 -m venv ~/virtualenv/suricatalog\n. ~/virtualenv/suricatalog/bin/activate\npip install --upgrade pip\npython -m pip install --upgrade build\npip install textual-dev\npip install --editable .\n```\n\nRunning unit tests is very easy after that:\n```shell\n(SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py\n.........\n----------------------------------------------------------------------\nRan 9 tests in 0.334s\n\nOK\n```\n\nIf the unit tests fails, then this is most likely the first place to fix a problem.\n\nI do recommend also running the textualize console and watch for the console messages:\n\n```shell\n# textual console\ntextual console --exclude SYSTEM --exclude EVENT\n```\n\nThen on another terminal:\n\n```shell\ntextual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json\n```\nThat will print even debug messages on the console (you can exclude these if you restart the console with '--exclude DEBUG')\n\n### Creating a Docker image\n\nPlease check [DOCKER.md](DOCKER.md) for more details.\n\n## Running the scripts\n\nOnce everything is installed in your virtual environment you should be able to call the scripts\n\nYou can find out what applications got installed by using auto complete, after activating your virtual environment:\n\n```shell\neve_[tab][tab]\n```\n\nAnd if you install the Bash auto complete extension you will also get some suggestions for the flags.\n\n\n### Simple EVE log parser\n\nBetter see it by yourself (remember, use --help to learn what options are supported)\n\n#### Table format:\n\n\n\n````shell\neve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json\n````\n\n### Canned reports with eve_json.py\n\n```shell\n(suricatalog) [josevnz@dmaf5 SuricataLog]$ eve_json --help\nusage: eve_json [-h] [--nxdomain | --payload | --flow | --netflow NETFLOW | --useragent] eve [eve ...]\n\nThis script is inspired by the examples provided on [15.1.3. Eve JSON \u2018jq\u2019 Examples](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-\nexamplesjq.html) A few things: * The output uses colorized JSON\n\npositional arguments:\n eve Path to one or more /var/log/suricata/eve.json file to parse.\n\noptional arguments:\n -h, --help show this help message and exit\n --nxdomain Show DNS records with NXDOMAIN\n --payload Show alerts with a printable payload\n --flow Aggregated flow report per protocol and destination port\n --netflow NETFLOW Get the netflow for a given IP address\n --useragent Top user agent in HTTP traffic\n```\n\nTake a look at some examples below:\n\n#### NXDOMAIN\n\n\n\n```shell\neve_json --nxdomain test/eve.json\n```\n\n#### PAYLOAD\n\n\n\n```shell\neve_json --payload ~/Downloads/eve.json\n```\n\n#### FLOW\n\n\n\n```shell\neve_json --flow test/eve_udp_flow.json\n```\n\n#### NETFLOW\n\n\n\n```shell\neve_json --netflow 224.0.0.251 test/eve_udp_flow.json\n```\n\n#### USERAGENT\n\n\n\n```shell\neve_json --useragent test/eve.json\n```\n\n### Running eve_* applications on a browser\n\n\n\nYou can run Suricata Log applications on a browser by using the `eve_server` wrapper:\n\n```shell\n# Show the flow report on a eve.json file\neve_server --application eve_json -- --flow ~/eve.json\n\n# Show NX domain report\neve_server --application eve_json -- --nxdomain ~/eve.json\n\n# Inspect the eve.json records\neve_server --applications eve_log -- ~/eve.json\n```\n\nYou need to pass the '--' to tell the server than this options belong to the underlying eve_* you want to call.\n\n## Running from Docker\n\nIt is also possible to run SuricataLog from a Docker container. Please see the [DOCKER.md](DOCKER.md) for more details\n\n## Running with uv\n\nIf you have uv, you can just do this:\n\n```shell\nuvx --from SuricataLog eve_log /var/log/suricata/eve.json\nuvx --from SuricataLog eve_json --useragent /var/log/suricata/eve.json\nuvx --from SuricataLog eve_server --application eve_json -- --flow /var/log/suricata/eve.json\n```\n\nYou get the idea.\n\n## Bash Auto complete\n\nI tried my best to follow [8.6 Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html#Programmable-Completion)\n\nI provided auto complete for the most common flags. You can figure out all the flags by passing '--help' to any of the scripts.\n\n### Installation of auto complete commands\nYou can install Bash autocomplete for all the SuricataLog scripts. Just run the 'eve_autocomplete' and follow directions:\n\n```shell\neve_autocomplete --help\n```\n\n## Supported versions\n\nI work on this project on **my spare time** and I cannot support every version of Linux/ Python combination out there.\nThis is my current test bed, and it may change without further notice\n\n| SuricataLog | Supported | OS | Python | Suricata |\n|-------------|-----------|----------------------------------|-----------|----------|\n| <= 0.8 | NO | NA | < 3.8 | 6.04 |\n| 0.9+ | NO | fedora 37 | => 3.11.4 | 6.04 |\n| 0.9+ | NO | Armbian 23.02.2 Jammy | => 3.10.6 | 6.04 |\n| 0.9+ | NO | Ubuntu 20.04.4 LTS (Focal Fossa) | => 3.8.10 | 6.04 |\n| 1.0.3+ | YES | fedora 40 | => 3.11.4 | 7.0.6 |\n\n*You are more than welcome to*:\n* Submit patches with new features and bug-fixes.\n* Open bug reports. Be as detailed as possible, otherwise I will have no choice but to close it.\n\n## Tutorials\n* [Suricata, RaspberryPI4 and Python to secure your home network](TUTORIAL.md)\n* [Using SuricataLog to analyze your events](Using_SuricataLog_to_analyze_your_events.md)\n",
"bugtrack_url": null,
"license": null,
"summary": "Scripts to display contents of Suricata eve.json log",
"version": "1.1.4",
"project_urls": {
"Repository": "https://github.com/josevnz/SuricataLog"
},
"split_keywords": [
"suricata",
" log",
" eve",
" json",
" cybersecurity"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8793ce7799b40cf3895afb968e250f9a1a0e282264d90685c8a2da57b12989a6",
"md5": "f1326855763323536cbaa6f6b6fe818f",
"sha256": "314d86ad052692aded64794b76930979d994141a7586c10192230f6cbf0a0841"
},
"downloads": -1,
"filename": "suricatalog-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f1326855763323536cbaa6f6b6fe818f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 37196,
"upload_time": "2025-07-19T16:48:43",
"upload_time_iso_8601": "2025-07-19T16:48:43.285397Z",
"url": "https://files.pythonhosted.org/packages/87/93/ce7799b40cf3895afb968e250f9a1a0e282264d90685c8a2da57b12989a6/suricatalog-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3f68c7c5fb13aaa4256cabcbacc87d4da98695f9609d4026f7208b649c7061d1",
"md5": "52766f42c23c8da14ab0db22ad36c24a",
"sha256": "1f51e51741dfac418fbc032d607a9f004b1a88e3cb8d581164f947dd49a1cfa8"
},
"downloads": -1,
"filename": "suricatalog-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "52766f42c23c8da14ab0db22ad36c24a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 32382,
"upload_time": "2025-07-19T16:48:44",
"upload_time_iso_8601": "2025-07-19T16:48:44.500698Z",
"url": "https://files.pythonhosted.org/packages/3f/68/c7c5fb13aaa4256cabcbacc87d4da98695f9609d4026f7208b649c7061d1/suricatalog-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-19 16:48:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "josevnz",
"github_project": "SuricataLog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "suricatalog"
}
