# RuleVis: Interactive Wazuh Rule Graph Explorer
RuleVis is a powerful analysis tool that transforms your Wazuh ruleset into a dynamic, interactive force-directed graph. It helps you visualize the complex relationships between rules, identify critical dependencies, discover structural issues, and analyze the distribution of your rule IDs.
This tool is designed for security engineers, SOC analysts, and Wazuh administrators who need to understand, maintain, and develop complex custom rulesets.
## Features
* **Interactive Graph Visualization:** Renders your entire ruleset as a graph using D3.js and HTML Canvas for high performance.
* **Dependency Analysis:** Clearly shows parent-child relationships (`if_sid`, `if_group`, etc.) with directed edges.
* **Node Expansion:** Interactively expand nodes to reveal their parent or child dependencies on demand.
* **Detailed Rule Information:** Click on any rule to see its full description, groups, and a complete list of its parents and children.
* **Powerful Search:** Instantly find and focus on any rule by its ID.
* **Graph Statistics Panel:** Get at-a-glance insights into your ruleset with statistics like:
* Top 5 rules with the most direct children (foundational rules).
* Top 5 rules with the highest impact (most total descendants).
* Top 5 rules with the most complex dependencies.
* A list of isolated rules.
* Cycles in the rules
* **Rule ID Heatmap:** Visualize the entire rule ID space from 0 to 100,000+ to see which ID ranges are heavily used and which are available for custom rules.
* **Keyboard Shortcuts:** Pause the simulation (`Space`), close panels (`Esc`), and more for an efficient workflow.
* **Focus:** By default, when a node is highlighted, any node except for the selected node and its neighbords are dimmed. That allows better focus minimizing visual complexity.
## The Problem It Solves
Wazuh's rule engine builds a complex, tree-like structure in memory. While powerful, this structure is invisible to the user. It can be difficult to:
* Understand the full impact of changing a single rule.
* Find redundant rules or overly complex dependency chains.
* Identify structural issues like circular dependencies, which can impact performance.
* Know which ID ranges are safe to use for new custom rules.
RuleVis makes these invisible structures visible, turning abstract XML files into a tangible, explorable map.
## Installation
### Using pipx (recommended)
`pipx install rulevis`
### Using pip (for testing)
`pip install rulevis`
### Using source
1. **Clone the repository:**
```shell
git clone https://github.com/zbalkan/rulevis.git
cd rulevis
```
2. **Create and activate a Python virtual environment:**
```shell
python -m venv .venv
source .venv/bin/activate
```
Or for Windows
```shell
python -m venv .venv
source .venv\Scripts\activate.ps1
```
3. **Install dependencies:**
```shell
pip install -r requirements.txt
```
## Usage
The tool is run from the command line. You must provide the path to the directory (or directories) containing your Wazuh rule XML files.
```shell
python src/rulevis.py --path /var/ossec/ruleset/rules,/var/ossec/etc/rules
```
**Arguments:**
* `--path, -p`: **(Required)** A comma-separated list of paths to your Wazuh rule directories. This should include both the default rules and your custom rules.
* `-h, --help`: Show the help message.
Once executed, the script will:
1. Parse all `.xml` files in the specified paths.
2. Build a graph model of the rule relationships.
3. Pre-calculate statistics and heatmap data.
4. Start a local web server.
5. Automatically open the tool in your default web browser.
## Key Features in Action
### Graph Statistics
Quickly identify the most important and complex rules in your entire ruleset. Click on any rule in the list to instantly navigate to it in the main graph.
### Rule ID Heatmap
Get a bird's-eye view of your rule ID landscape. Dark gray blocks are unused and available for your custom rules, while brighter red blocks indicate heavily populated ranges. This is invaluable for planning and organizing a large custom ruleset.
## Technical Overview
The project is composed of three main Python modules and a JavaScript frontend:
1. **`generator.py`:** Parses the Wazuh XML rule files and uses the `networkx` library to build a `MultiDiGraph` object representing the rule relationships. It saves this graph to a temporary file.
2. **`analyzer.py`:** Loads the graph file and uses `networkx` to perform complex calculations (descendants, ancestors, etc.). It pre-calculates the data needed for the Statistics Panel and the Rule ID Heatmap and saves them to temporary JSON files.
3. **`visualizer.py`:** A Flask web application that serves the frontend and provides a clean API for the visualization to fetch graph, stats, and heatmap data.
4. **`graph.js`:** The core frontend logic. It uses **D3.js** for the force simulation and user interactions, and renders the main graph to an **HTML Canvas** for high performance. The interactive heatmap is rendered using **SVG** for its superior event handling and styling capabilities.
Here’s a **ready-to-paste README subsection** that explains `rulevis` logging clearly and professionally for your users. It assumes the per-user setup you’ve implemented.
---
## Logging
`rulevis` automatically writes diagnostic and operational logs to a user-specific location. Logs are plain text encoded in UTF-8 and include timestamps, module names, and severity levels. The application creates its log directory if it does not exist.
| Platform | Log file location | Example path |
| --------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Windows | `%LocalAppData%\rulevis\Logs\rulevis.log` | `C:\Users\<user>\AppData\Local\rulevis\Logs\rulevis.log` |
| macOS | `~/Library/Logs/rulevis/rulevis.log` | `/Users/<user>/Library/Logs/rulevis/rulevis.log` |
| Linux / BSD | `$XDG_STATE_HOME/rulevis/rulevis.log` or fallback `~/.local/share/rulevis/logs/rulevis.log` | `/home/<user>/.local/state/rulevis/rulevis.log` |
`rulevis` follows the [XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/latest/) on Unix-like systems and Windows conventions under `%LocalAppData%`.
The log file records informational messages, warnings, and errors emitted during execution. You can safely delete it; a new one will be created automatically on the next run.
## Notes
While the documentation defines <if_level> as another condition creating a parent-child relationship, it has not been used in any built-in rules. And as a personal choicem I decided to omit that deliberately.
There is another `if`, called `<if_fts>`, that is used for *first time seen* events, not creating a parent-child relationship. Theefore it is not mentioned.
Raw data
{
"_id": null,
"home_page": null,
"name": "rulevis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "wazuh, detection, security, monitoring, logging, siem",
"author": null,
"author_email": "Zafer Balkan <zafer@zaferbalkan.com>",
"download_url": null,
"platform": null,
"description": "# RuleVis: Interactive Wazuh Rule Graph Explorer\r\n\r\nRuleVis is a powerful analysis tool that transforms your Wazuh ruleset into a dynamic, interactive force-directed graph. It helps you visualize the complex relationships between rules, identify critical dependencies, discover structural issues, and analyze the distribution of your rule IDs.\r\n\r\nThis tool is designed for security engineers, SOC analysts, and Wazuh administrators who need to understand, maintain, and develop complex custom rulesets.\r\n\r\n\r\n\r\n## Features\r\n\r\n* **Interactive Graph Visualization:** Renders your entire ruleset as a graph using D3.js and HTML Canvas for high performance.\r\n* **Dependency Analysis:** Clearly shows parent-child relationships (`if_sid`, `if_group`, etc.) with directed edges.\r\n* **Node Expansion:** Interactively expand nodes to reveal their parent or child dependencies on demand.\r\n* **Detailed Rule Information:** Click on any rule to see its full description, groups, and a complete list of its parents and children.\r\n* **Powerful Search:** Instantly find and focus on any rule by its ID.\r\n* **Graph Statistics Panel:** Get at-a-glance insights into your ruleset with statistics like:\r\n * Top 5 rules with the most direct children (foundational rules).\r\n * Top 5 rules with the highest impact (most total descendants).\r\n * Top 5 rules with the most complex dependencies.\r\n * A list of isolated rules.\r\n * Cycles in the rules\r\n* **Rule ID Heatmap:** Visualize the entire rule ID space from 0 to 100,000+ to see which ID ranges are heavily used and which are available for custom rules.\r\n* **Keyboard Shortcuts:** Pause the simulation (`Space`), close panels (`Esc`), and more for an efficient workflow.\r\n* **Focus:** By default, when a node is highlighted, any node except for the selected node and its neighbords are dimmed. That allows better focus minimizing visual complexity.\r\n\r\n## The Problem It Solves\r\n\r\nWazuh's rule engine builds a complex, tree-like structure in memory. While powerful, this structure is invisible to the user. It can be difficult to:\r\n\r\n* Understand the full impact of changing a single rule.\r\n* Find redundant rules or overly complex dependency chains.\r\n* Identify structural issues like circular dependencies, which can impact performance.\r\n* Know which ID ranges are safe to use for new custom rules.\r\n\r\nRuleVis makes these invisible structures visible, turning abstract XML files into a tangible, explorable map.\r\n\r\n## Installation\r\n\r\n### Using pipx (recommended)\r\n\r\n`pipx install rulevis`\r\n\r\n### Using pip (for testing)\r\n\r\n`pip install rulevis`\r\n\r\n### Using source\r\n\r\n1. **Clone the repository:**\r\n\r\n ```shell\r\n git clone https://github.com/zbalkan/rulevis.git\r\n cd rulevis\r\n ```\r\n\r\n2. **Create and activate a Python virtual environment:**\r\n\r\n ```shell\r\n python -m venv .venv\r\n source .venv/bin/activate\r\n ```\r\n\r\n Or for Windows\r\n\r\n ```shell\r\n python -m venv .venv\r\n source .venv\\Scripts\\activate.ps1\r\n ```\r\n\r\n3. **Install dependencies:**\r\n\r\n ```shell\r\n pip install -r requirements.txt\r\n ```\r\n\r\n## Usage\r\n\r\nThe tool is run from the command line. You must provide the path to the directory (or directories) containing your Wazuh rule XML files.\r\n\r\n```shell\r\npython src/rulevis.py --path /var/ossec/ruleset/rules,/var/ossec/etc/rules\r\n```\r\n\r\n**Arguments:**\r\n\r\n* `--path, -p`: **(Required)** A comma-separated list of paths to your Wazuh rule directories. This should include both the default rules and your custom rules.\r\n* `-h, --help`: Show the help message.\r\n\r\nOnce executed, the script will:\r\n\r\n1. Parse all `.xml` files in the specified paths.\r\n2. Build a graph model of the rule relationships.\r\n3. Pre-calculate statistics and heatmap data.\r\n4. Start a local web server.\r\n5. Automatically open the tool in your default web browser.\r\n\r\n## Key Features in Action\r\n\r\n### Graph Statistics\r\n\r\nQuickly identify the most important and complex rules in your entire ruleset. Click on any rule in the list to instantly navigate to it in the main graph.\r\n\r\n\r\n\r\n### Rule ID Heatmap\r\n\r\nGet a bird's-eye view of your rule ID landscape. Dark gray blocks are unused and available for your custom rules, while brighter red blocks indicate heavily populated ranges. This is invaluable for planning and organizing a large custom ruleset.\r\n\r\n\r\n\r\n## Technical Overview\r\n\r\nThe project is composed of three main Python modules and a JavaScript frontend:\r\n\r\n1. **`generator.py`:** Parses the Wazuh XML rule files and uses the `networkx` library to build a `MultiDiGraph` object representing the rule relationships. It saves this graph to a temporary file.\r\n2. **`analyzer.py`:** Loads the graph file and uses `networkx` to perform complex calculations (descendants, ancestors, etc.). It pre-calculates the data needed for the Statistics Panel and the Rule ID Heatmap and saves them to temporary JSON files.\r\n3. **`visualizer.py`:** A Flask web application that serves the frontend and provides a clean API for the visualization to fetch graph, stats, and heatmap data.\r\n4. **`graph.js`:** The core frontend logic. It uses **D3.js** for the force simulation and user interactions, and renders the main graph to an **HTML Canvas** for high performance. The interactive heatmap is rendered using **SVG** for its superior event handling and styling capabilities.\r\n\r\nHere\u2019s a **ready-to-paste README subsection** that explains `rulevis` logging clearly and professionally for your users. It assumes the per-user setup you\u2019ve implemented.\r\n\r\n---\r\n\r\n## Logging\r\n\r\n`rulevis` automatically writes diagnostic and operational logs to a user-specific location. Logs are plain text encoded in UTF-8 and include timestamps, module names, and severity levels. The application creates its log directory if it does not exist.\r\n\r\n| Platform | Log file location | Example path |\r\n| --------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------- |\r\n| Windows | `%LocalAppData%\\rulevis\\Logs\\rulevis.log` | `C:\\Users\\<user>\\AppData\\Local\\rulevis\\Logs\\rulevis.log` |\r\n| macOS | `~/Library/Logs/rulevis/rulevis.log` | `/Users/<user>/Library/Logs/rulevis/rulevis.log` |\r\n| Linux / BSD | `$XDG_STATE_HOME/rulevis/rulevis.log` or fallback `~/.local/share/rulevis/logs/rulevis.log` | `/home/<user>/.local/state/rulevis/rulevis.log` |\r\n\r\n`rulevis` follows the [XDG Base Directory specification](https://specifications.freedesktop.org/basedir-spec/latest/) on Unix-like systems and Windows conventions under `%LocalAppData%`.\r\n\r\nThe log file records informational messages, warnings, and errors emitted during execution. You can safely delete it; a new one will be created automatically on the next run.\r\n\r\n## Notes\r\n\r\nWhile the documentation defines <if_level> as another condition creating a parent-child relationship, it has not been used in any built-in rules. And as a personal choicem I decided to omit that deliberately.\r\n\r\nThere is another `if`, called `<if_fts>`, that is used for *first time seen* events, not creating a parent-child relationship. Theefore it is not mentioned.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Interactive Wazuh Rule Graph Explorer",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/zbalkan/rulevis",
"Issues": "https://github.com/zbalkan/rulevis/issues",
"Repository": "https://github.com/zbalkan/rulevis"
},
"split_keywords": [
"wazuh",
" detection",
" security",
" monitoring",
" logging",
" siem"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9b6c526ff0712b9e0f541a062690f5fd2009fccba56fcf766fe2bb1935ba6b2a",
"md5": "e3e294238431a8c9b4898cbdb2239848",
"sha256": "ca91b9627cd82eebeed21dffd8e96e2cf8a38376070ec8d6e2551d431b926233"
},
"downloads": -1,
"filename": "rulevis-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3e294238431a8c9b4898cbdb2239848",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17238,
"upload_time": "2025-10-28T16:53:42",
"upload_time_iso_8601": "2025-10-28T16:53:42.086931Z",
"url": "https://files.pythonhosted.org/packages/9b/6c/526ff0712b9e0f541a062690f5fd2009fccba56fcf766fe2bb1935ba6b2a/rulevis-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 16:53:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zbalkan",
"github_project": "rulevis",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Flask",
"specs": [
[
">=",
"3.1.2"
]
]
},
{
"name": "networkx",
"specs": [
[
">=",
"3.5"
]
]
}
],
"lcname": "rulevis"
}
JSON
