rulevis 1.0.0__py3-none-any.whl

internal/analyzer.py

@@ -0,0 +1,167 @@
+import logging
+import math
+import pickle
+import json
+import os
+from networkx import MultiDiGraph, descendants, ancestors, nodes_with_selfloops, simple_cycles
+
+
+class Analyzer:
+    """
+    Analyzes a graph from a pickle file and calculates key statistics.
+    """
+    def __init__(self, graph_path: str) -> None:
+        """
+        Initializes the Analyzer with the path to the graph file.
+
+        Args:
+            graph_path (str): The path to the .gpickle file.
+
+        Raises:
+            FileNotFoundError: If the graph file does not exist.
+        """
+        if not os.path.isfile(graph_path):
+            raise FileNotFoundError(f"Graph file not found: {graph_path}")
+        self.graph_path = graph_path
+        self.G: MultiDiGraph = self._load_graph()
+
+    def _load_graph(self) -> MultiDiGraph:
+        """Loads the graph from the pickle file."""
+        with open(self.graph_path, "rb") as f:
+            return pickle.load(f)
+
+    def calculate_statistics(self) -> dict:
+        """
+        Calculates all the required statistics for the graph, ensuring no
+        duplicate cycles are reported.
+        """
+        real_nodes = [n for n in self.G.nodes() if n != '0']
+
+        # --- Calculate Top 5 Lists ---
+        real_nodes = [n for n in self.G.nodes() if n != '0']
+        out_degrees = dict(self.G.out_degree(real_nodes))
+        in_degrees = dict(self.G.in_degree(real_nodes))
+
+        top_5_direct_descendants = sorted(out_degrees, key=out_degrees.get, reverse=True)[:5]
+        indirect_descendants_counts = {n: len(descendants(self.G, n)) for n in real_nodes}
+        top_5_indirect_descendants = sorted(indirect_descendants_counts,
+                                            key=indirect_descendants_counts.get, reverse=True)[:5]
+        top_5_direct_ancestors = sorted(in_degrees,
+                                        key=in_degrees.get, reverse=True)[:5]
+        indirect_ancestors_counts = {n: len(ancestors(self.G, n)) for n in real_nodes}
+        top_5_indirect_ancestors = sorted(indirect_ancestors_counts,
+                                          key=indirect_ancestors_counts.get, reverse=True)[:5]
+
+        isolated_rules = [
+            n for n in real_nodes
+            if self.G.out_degree(n) == 0 and list(self.G.predecessors(n)) == ['0']
+        ]
+
+        # 1. Find all nodes with self-loops first. This is our definitive list.
+        logging.info("Detecting self-loops (e.g., A -> A)...")
+        self_loop_nodes = set(nodes_with_selfloops(self.G))  # Use a set for efficient lookup
+        logging.info(f"Found {len(self_loop_nodes)} nodes with self-loops: {self_loop_nodes}")
+
+        # 2. Find all other simple cycles.
+        logging.info("Detecting multi-node cycles...")
+        all_simple_cycles = list(simple_cycles(self.G))
+
+        # 3. Filter out any multi-node cycles that contain a node we've already
+        #    identified as having a self-loop. This prevents double-reporting.
+        multi_node_cycles = [
+            cycle for cycle in all_simple_cycles
+            if not self_loop_nodes.intersection(cycle)
+        ]
+
+        logging.info(f"Found {len(multi_node_cycles)} distinct multi-node cycles.")
+        if multi_node_cycles:
+            logging.info(f"Example multi-node cycle: {multi_node_cycles[0]}")
+
+        # 4. Format the multi-node cycles for display
+        for cycle in multi_node_cycles:
+            if cycle:
+                cycle.append(cycle[0])
+
+        stats = {
+            "top_direct_descendants": [{"id": n, "count": out_degrees[n]}
+                                       for n in top_5_direct_descendants],
+            "top_indirect_descendants": [{"id": n, "count": indirect_descendants_counts[n]}
+                                         for n in top_5_indirect_descendants],
+            "top_direct_ancestors": [{"id": n, "count": in_degrees[n]} for n in top_5_direct_ancestors],
+            "top_indirect_ancestors": [{"id": n, "count": indirect_ancestors_counts[n]}
+                                       for n in top_5_indirect_ancestors],
+            "isolated_rules": [{"id": n}
+                               for n in isolated_rules],
+            "self_loops": [{"id": n}
+                           for n in self_loop_nodes],
+            "cycles": multi_node_cycles
+        }
+
+        return stats
+
+    def calculate_heatmap_data(self, block_size: int = 10) -> dict:
+        """
+        Generates data for a block-based heatmap, showing rule ID occupancy.
+        The heatmap range is dynamically calculated based on the highest rule ID found.
+
+        Args:
+            block_size (int): The size of each ID range block (e.g., 10).
+
+        Returns:
+            dict: A dictionary containing the list of blocks and metadata.
+        """
+        all_rule_ids = {int(n) for n in self.G.nodes() if n.isdigit() and n != '0'}
+
+        if not all_rule_ids:
+            # Handle case where there are no integer rules
+            return {"metadata": {"block_size": block_size, "max_id": 0, "total_blocks": 0}, "blocks": []}
+
+        actual_max_id = max(all_rule_ids)
+
+        # Calculate the upper bound for the heatmap range.
+        #    We use math.ceil to round up to the next full block.
+        #    For example, if max ID is 101234 and block size is 1000, this becomes:
+        #    ceil(101234 / 1000) * 1000  =>  ceil(101.234) * 1000  =>  102 * 1000  =>  102000
+        dynamic_max_range = math.ceil(actual_max_id / block_size) * block_size
+
+        # Ensure we have at least one block even if max_id is small
+        dynamic_max_range = max(dynamic_max_range, block_size)
+
+        blocks = []
+        # Use the dynamically calculated range for the loop
+        for i in range(0, dynamic_max_range, block_size):
+            start_range = i
+            end_range = i + block_size - 1
+
+            count = sum(1 for rule_id in all_rule_ids if start_range <= rule_id <= end_range)
+
+            blocks.append({
+                "id": f"{start_range}-{end_range}",
+                "count": count
+            })
+
+        return {
+            "metadata": {
+                "block_size": block_size,
+                "max_id": dynamic_max_range,
+                "total_blocks": len(blocks)
+            },
+            "blocks": blocks
+        }
+
+    def write_to_json(self, stats_output_path: str, heatmap_output_path: str) -> None:
+        """Calculates all data and writes to respective files."""
+
+        logging.info("Calculating graph statistics...")
+        stats_data = self.calculate_statistics()
+        logging.info(f"Writing statistics to {stats_output_path}...")
+        with open(stats_output_path, "w") as f:
+            json.dump(stats_data, f, indent=4)
+
+        logging.info("Calculating heatmap data...")
+        heatmap_data = self.calculate_heatmap_data()
+        logging.info(f"Writing heatmap data to {heatmap_output_path}...")
+        with open(heatmap_output_path, "w") as f:
+            json.dump(heatmap_data, f, indent=2)
+
+        logging.info("All analysis complete.")

internal/generator.py

@@ -0,0 +1,176 @@
+import logging
+import os
+import pickle
+import xml.etree.ElementTree as ET
+from collections import defaultdict
+from typing import Any, Final, Optional
+
+import networkx as nx
+
+ENCODING: Final[str] = "utf-8"
+
+
+class GraphGenerator:
+    def __init__(self, paths: list[str], graph_file: str) -> None:
+        self.paths = paths
+        self.group_membership: dict[str, list[str]] = defaultdict(list)
+        self.G: nx.MultiDiGraph[Any] = nx.MultiDiGraph()
+        self.graph_file: str = graph_file
+
+    def get_all_xml_files(self) -> list[str]:
+        xml_files: list[str] = []
+        for path in self.paths:
+            for root, _, files in os.walk(path):
+                for file in files:
+                    if file.lower().endswith('.xml'):
+                        abs = os.path.abspath(os.path.join(root, file))
+                        xml_files.append(abs)
+
+        print(f'Found {len(xml_files)} XML files in the given paths')
+        logging.info(f'Found {len(xml_files)} XML files in the given paths')
+        logging.info('Processing all files...')
+        return xml_files
+
+    def add_edge_with_type(self, source: str, target: str, relation_type: str) -> None:
+        if logging.getLogger().getEffectiveLevel() <= logging.DEBUG:
+            logging.debug(
+                f"Adding edge from {source} to {target} with type {relation_type}")
+        self.G.add_edge(source, target, relation_type=relation_type)
+
+    def add_relationship_edges(self, rule_id: str,
+                               if_sid: Optional[str], if_matched_sid: Optional[str],
+                               if_group: Optional[str], if_matched_group: Optional[str]) -> None:
+        if if_sid:
+            for sid in if_sid.split(','):
+                self.add_edge_with_type(sid.strip(), rule_id, 'if_sid')
+
+        if if_matched_sid:
+            for sid in if_matched_sid.split(','):
+                self.add_edge_with_type(sid.strip(), rule_id, 'if_matched_sid')
+
+        if if_group:
+            for group in if_group.split(','):
+                for parent_rule in self.group_membership.get(group.strip(), []):
+                    self.add_edge_with_type(parent_rule, rule_id, 'if_group')
+
+        if if_matched_group:
+            for group in if_matched_group.split(','):
+                for parent_rule in self.group_membership.get(group.strip(), []):
+                    self.add_edge_with_type(
+                        parent_rule, rule_id, 'if_matched_group')
+
+    def parse_groups_and_rules(self, element: ET.Element, inherited_groups: list[str], xml_file: str) -> None:
+        if element.tag == 'rule':
+            rule_id = element.get('id', '0')
+            rule_level = element.get('level')
+            if_sid = element.findtext('if_sid', None)
+            if_matched_sid = element.findtext('if_matched_sid', None)
+            if_group = element.findtext('if_group', None)
+            if_matched_group = element.findtext('if_matched_group', None)
+
+            attributes = [(i.tag, i.text) for i in element]
+            rule_description = self.extract_rule_description(attributes)
+            all_groups = self.extract_rule_groups(inherited_groups, attributes)
+
+            if self.G.nodes.get(rule_id) is not None:
+                logging.debug(
+                    f"Duplicate rule ID found: {rule_id}. Skipping this rule.")
+
+            else:
+                self.G.add_node(rule_id,
+                                groups=all_groups,
+                                description=rule_description,
+                                level=rule_level,
+                                file=os.path.basename(xml_file))
+                for group in all_groups:
+                    self.group_membership[group].append(rule_id)
+
+                self.add_relationship_edges(
+                    rule_id, if_sid, if_matched_sid, if_group, if_matched_group)
+
+        elif element.tag == 'group':
+            group_attribute = element.get('name', '')
+            internal_groups = [
+                gr for gr in group_attribute.split(',') if gr != '']
+            new_inherited_groups = inherited_groups + internal_groups
+
+            for child in element:
+                self.parse_groups_and_rules(child, new_inherited_groups, xml_file)
+
+    def extract_rule_groups(self, inherited_groups: list[str], children: list[tuple[str, Optional[str]]]) -> list[str]:
+        all_groups = list(inherited_groups)
+        for child in children:
+            if child[0] == 'group' and child[1]:
+                all_groups.extend([g for g in child[1].split(',') if g])
+        return all_groups
+
+    def extract_rule_description(self, attributes: list[tuple[str, Optional[str]]]) -> Optional[str]:
+        description: list[str] = []
+        for attr in attributes:
+            if attr[0] == 'description':
+                d = attr[1]
+                if d:
+                    description.append(d)
+        if len(description) > 0:
+            return ' '.join(description)
+        return None
+
+    def wrap_with_root(self, xml_content: str) -> str:
+        return f"<root>{xml_content}</root>"
+
+    def build_graph_from_xml(self) -> None:
+        xml_files = self.get_all_xml_files()
+
+        for xml_file in xml_files:
+            logging.info(f'Processing file: {xml_file}')
+            try:
+                with open(xml_file, 'r', encoding=ENCODING) as f:
+                    xml_content = f.read()
+            except OSError as e:
+                logging.error(
+                    f"Error reading file {xml_file}: {e}", exc_info=True)
+                continue
+
+            wrapped_content: str = self.wrap_with_root(xml_content)
+
+            try:
+                parsed_xml = ET.fromstring(wrapped_content)
+                root = parsed_xml
+                for child in root:
+                    self.parse_groups_and_rules(child, [], xml_file)
+            except Exception as e:
+                logging.error(f"Error parsing {xml_file}: {e}", exc_info=True)
+
+        first_level_rules = [
+            node for node in self.G.nodes if self.G.in_degree(node) == 0]
+
+        # Add synthetic root and connect to top-level rules
+        synthetic_root = '0'  # Root has ID of 0
+        self.G.add_node(
+            synthetic_root, description="Synthetic root node", groups=["__meta__"])
+
+        for node in first_level_rules:
+            self.add_edge_with_type(synthetic_root, node, "root")
+
+        # Pre-calculate and store all children for every node.
+        # This is crucial for the frontend to know if a node is fully expanded.
+        print("Pre-calculating child relationships...")
+        for node_id in list(self.G.nodes):
+            # G.successors(node_id) returns an iterator of all direct children
+            children_ids = list(self.G.successors(node_id))
+            # Store this list as a new attribute on the node itself.
+            self.G.nodes[node_id]['children_ids'] = children_ids
+        print("Child relationship calculation complete.")
+
+        print("Total nodes:", self.G.number_of_nodes())
+        print("First-level children (connected to root):",
+              len(list(self.G.successors("0"))))
+
+    def save_graph(self) -> None:
+        try:
+            output_path = self.graph_file
+            os.makedirs(os.path.dirname(output_path), exist_ok=True)
+            pickle.dump(self.G, open(output_path, 'wb'))
+            logging.info(f"Graph saved to {output_path}")
+        except Exception as e:
+            logging.error(f"Error saving graph: {e}", exc_info=True)

internal/visualizer.py

@@ -0,0 +1,336 @@
+import json
+import os
+import pickle
+from typing import Any, Union
+
+from flask import Flask, jsonify, render_template_string, request
+from flask.wrappers import Response
+from networkx import MultiDiGraph
+
+PRECOMPUTED_BLOCK_SIZES: list[int] = [1, 10, 50, 100, 250, 500]
+PRECOMPUTED_HEATMAPS: dict[int, Any] = {}
+
+
+def parse_start(idstr: str) -> int:
+    if not idstr:
+        return 0
+    s = str(idstr).strip()
+    for sep in ("-", "–"):
+        if sep in s:
+            s = s.split(sep, 1)[0]
+            break
+    try:
+        return int(s)
+    except Exception:
+        return 0
+
+
+def precompute_heatmaps(base_blocks: list[dict[str, Any]]) -> None:
+    # Use both start and count!
+    starts_and_counts = [(parse_start(b.get("id")), int(  # type: ignore
+        b.get("count", 0))) for b in base_blocks]
+    max_start = max((start for start, _ in starts_and_counts), default=0)
+    for bs in PRECOMPUTED_BLOCK_SIZES:
+        if bs == 1:
+            ids = sorted(str(start) for start, _ in starts_and_counts)
+            PRECOMPUTED_HEATMAPS[bs] = {
+                "block_size": 1,
+                "ids": ids
+            }
+        else:
+            acc: dict[str, Any] = {}
+            for start, count in starts_and_counts:
+                bucket = (start // bs) * bs
+                key = f"{bucket}-{bucket + bs - 1}"
+                acc[key] = acc.get(key, 0) + count  # Use the original count!
+            blocks = [{"id": k, "count": v} for k, v in acc.items()]
+            blocks.sort(key=lambda block: int(block["id"].split("-")[0]))
+            PRECOMPUTED_HEATMAPS[bs] = {
+                "metadata": {"block_size": bs, "max_id": max_start, "total_blocks": len(blocks)},
+                "blocks": blocks
+            }
+
+
+def create_app(graph_path: str, stats_path: str, heatmap_path: str) -> Flask:
+    if not os.path.isfile(graph_path):
+        raise FileNotFoundError(f"Graph file not found: {graph_path}")
+
+    if not os.path.isfile(stats_path):
+        raise FileNotFoundError(f"Stats file not found: {stats_path}")
+
+    with open(graph_path, "rb") as bf:
+        G: MultiDiGraph = pickle.load(bf)
+
+    with open(stats_path, "r", encoding='utf-8') as f:
+        try:
+            # Validate that the stats file is valid JSON
+            STATS_DATA = json.load(f)
+            # Simple validation to ensure keys exist
+            required_keys = [
+                "cycles", "top_direct_descendants", "top_indirect_descendants",
+                "top_direct_ancestors", "top_indirect_ancestors", "isolated_rules"
+            ]
+            if not all(key in STATS_DATA for key in required_keys):
+                raise ValueError("Stats file is missing required keys.")
+        except (json.JSONDecodeError, ValueError) as e:
+            raise RuntimeError(f"Stats file '{stats_path}' is corrupted or invalid: {e}")
+
+    if not os.path.isfile(heatmap_path):
+        raise FileNotFoundError(f"Heatmap file not found: {heatmap_path}")
+
+    with open(heatmap_path, "r") as f:
+        try:
+            HEATMAP_DATA = json.load(f)
+        except json.JSONDecodeError:
+            raise RuntimeError(f"Heatmap file '{heatmap_path}' is corrupted.")
+
+    # Precompute heatmaps for all sizes on app startup
+    base_blocks = HEATMAP_DATA.get("blocks", [])
+    precompute_heatmaps(base_blocks)
+
+    app = Flask(__name__)
+
+    # ---------- shared helpers ----------
+    def serialize_node(nid: str, displayed: set[str] | None = None) -> dict[str, Any]:
+        attrs = G.nodes[nid]
+        if displayed is None:
+            # caller doesn't care about expandable computation
+            return {"id": nid, **{k: v for k, v in attrs.items() if k != "expandable"}}
+        expandable = any(child not in displayed for child in G.successors(nid))
+        return {
+            "id": nid,
+            **{k: v for k, v in attrs.items() if k != "expandable"},
+            "expandable": expandable,
+        }
+
+    def relation_type(u: str, v: str) -> str:
+        data = G.get_edge_data(u, v)
+        if not data:
+            return "unknown"
+        return next(iter(data.values()), {}).get("relation_type", "unknown")  # type: ignore
+
+    def make_edge(u: str, v: str) -> dict[str, Any]:
+        return {"source": u, "target": v, "relation_type": relation_type(u, v)}
+
+    def error(message: str, code: int = 400) -> tuple[Response, int]:
+        return jsonify({"error": message}), code
+
+    def _handle_root(displayed: set[str]) -> Union[Response, tuple[Response, int]]:
+        root = "0"
+        if root not in G:
+            return error("Root node not found", 404)
+        children = list(G.successors(root))
+        nodes = [serialize_node(root, displayed)] + [serialize_node(c, displayed) for c in children]
+        edges = [{"source": root, "target": c, "relation_type": "no_parent"} for c in children]
+        return jsonify({"nodes": nodes, "edges": edges})
+
+    def _handle_batch(ids_param: str, displayed: set[str]) -> Union[Response, tuple[Response, int]]:
+        node_ids = [nid for nid in ids_param.split(",") if nid]
+        if not node_ids:
+            return jsonify({"nodes": [], "edges": []})
+        nodes = [serialize_node(nid, displayed) for nid in node_ids if nid in G]
+        all_relevant = set(node_ids) | displayed
+        sub_edges = [
+            make_edge(u, v)
+            for u, v in G.subgraph(all_relevant).edges()
+            if u in node_ids or v in node_ids
+        ]
+        return jsonify({"nodes": nodes, "edges": sub_edges})
+
+    def _handle_search(node_id: str, displayed: set[str]) -> Union[Response, tuple[Response, int]]:
+        if node_id not in G:
+            return error(f"Node '{node_id}' not found", 404)
+
+        node_obj = serialize_node(node_id, displayed)
+        edges = []
+        for p in G.predecessors(node_id):
+            if p in displayed:
+                edges.append(make_edge(p, node_id))
+        for c in G.successors(node_id):
+            if c in displayed:
+                edges.append(make_edge(node_id, c))
+        return jsonify({"nodes": [node_obj], "edges": edges})
+
+    def _handle_single_node(node_id: str, neighbor_mode: str,
+                            include_details: bool, displayed: set[str]) -> Union[Response, tuple[Response, int]]:
+
+        if node_id not in G:
+            return error(f"Node '{node_id}' not found", 404)
+
+        if include_details:
+            node_data = G.nodes[node_id]
+            parents = [
+                {"id": p, "relation_type": make_edge(p, node_id)["relation_type"]} for p in G.predecessors(node_id)
+                ]
+            children = [
+                {"id": c, "relation_type": make_edge(node_id, c)["relation_type"]} for c in G.successors(node_id)
+                ]
+            return jsonify({
+                "id": node_id,
+                "description": node_data.get("description"),
+                "groups": node_data.get("groups", []),
+                "level": node_data.get("level"),
+                "file": node_data.get("file"),
+                "parents": parents,
+                "children": children
+            })
+
+        nodes = [serialize_node(node_id, displayed)]
+        edges = []
+        if neighbor_mode in {"parents", "both"}:
+            for p in G.predecessors(node_id):
+                nodes.append(serialize_node(p, displayed))
+                edges.append(make_edge(p, node_id))
+        if neighbor_mode in {"children", "both"}:
+            for c in G.successors(node_id):
+                nodes.append(serialize_node(c, displayed))
+                edges.append(make_edge(node_id, c))
+        return jsonify({"nodes": nodes, "edges": edges})
+
+    # ---------- UI ----------
+    @app.route("/")
+    def index() -> str:
+        return render_template_string("""
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+            <meta charset="UTF-8">
+            <title>Rule Graph Explorer</title>
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <script src="https://d3js.org/d3.v7.min.js"></script>
+            <link rel="stylesheet" href="static/styles.css">
+        </head>
+        <body>
+        <div class="navbar">
+            <div class="navbar-left">
+                <div class="navbar-title">Interactive Rule Graph Explorer</div>
+            </div>
+            <div class="navbar-links">
+                <button id="showHeatmapBtn">Show Heatmap</button>
+                <button id="showStatsBtn">Show Stats</button>
+                <button id="resetZoom">Reset Zoom</button>
+                <button id="resetGraph">Reset Graph</button>
+                <button id="toggleFocusBtn">Toggle focus off</button>
+                <input type="text" id="searchBox" placeholder="Search Rule ID">
+                <button id="searchBtn">Search</button>
+            </div>
+        </div>
+
+        <div class="content">
+            <canvas></canvas>
+        </div>
+
+        <div id="detailsPanel" class="side-panel">
+            <button id="detailsCloseBtn" class="panel-close-btn">×</button>
+            <div id="detailsContent" class="panel-content">
+                <p>Click on a node to see its details.</p>
+            </div>
+        </div>
+
+        <div id="statsPanel" class="side-panel">
+            <button id="statsCloseBtn" class="panel-close-btn">×</button>
+            <div id="statsContent" class="panel-content">
+                <p>Statistics loading...</p>
+            </div>
+        </div>
+
+        <div id="heatmapModal" class="modal-overlay">
+            <div id="heatmapContent">
+            </div>
+        </div>
+
+        <div class="footer">
+            <p>Visit official Wazuh documentation for
+               <a href="https://documentation.wazuh.com/current/user-manual/ruleset/ruleset-xml-syntax/rules.html" target="_blank">
+               Wazuh Rule Syntax</a>.
+            </p>
+            <p>&copy; 2025 <a href="https://zaferbalkan.com" target="_blank">Zafer Balkan</a></p>
+            <p>The brand <a href="https://wazuh.com/" target="_blank">Wazuh</a> and related marks,
+               emblems and images are registered trademarks of their respective owners.
+            </p>
+        </div>
+
+        <script src="static/tutorial.js" defer></script>
+        <script src="static/graph.js" defer></script>
+        </body>
+        </html>
+""")
+
+    # ---------- Consolidated APIs ----------
+    @app.route("/api/nodes", methods=["GET"])
+    def nodes() -> Union[Response, tuple[Response, int]]:
+        """
+        Dispatches requests to the appropriate handler based on query params.
+        """
+        mode = request.args.get("mode", "").strip().lower()
+        node_id = request.args.get("id", "").strip()
+        ids_param = request.args.get("ids", "").strip()
+        neighbor_mode = request.args.get("neighbors", "").strip().lower() or ("children" if node_id else "none")
+        include_details = request.args.get("include", "").strip().lower() == "details"
+        displayed: set[str] = set(filter(None, request.args.get("displayed", "").split(",")))
+
+        if mode == "root":
+            return _handle_root(displayed)
+
+        if ids_param:
+            return _handle_batch(ids_param, displayed)
+
+        if mode == "search":
+            if not node_id:
+                return error("mode=search requires an 'id' parameter", 400)
+            return _handle_search(node_id, displayed)
+
+        if node_id:
+            return _handle_single_node(node_id, neighbor_mode, include_details, displayed)
+
+        return error("Specify one of: mode=root | mode=search&id=... | id=... | ids=...", 400)
+
+    @app.route("/api/edges", methods=["POST"])
+    def edges() -> Response:
+        """
+        Unifies: /api/connections
+        Body: { "ids": ["a","b","c"] }
+        Returns all edges among provided ids.
+        """
+        payload = request.get_json(silent=True) or {}
+        node_ids = payload.get("ids", [])
+        if not node_ids:
+            return jsonify({"nodes": [], "edges": []})
+        edges_list = [make_edge(u, v) for u, v in G.subgraph(node_ids).edges()]
+        return jsonify({"nodes": [], "edges": edges_list})
+
+    @app.route("/api/stats", methods=["GET"])
+    def stats() -> Response:
+        """Serves the pre-calculated graph statistics."""
+        return jsonify(STATS_DATA)
+
+    @app.route("/api/heatmap", methods=["GET"])
+    def heatmap() -> Union[Response, tuple[Response, int]]:
+        bs = request.args.get("block_size", type=int)
+        if not bs or bs < 1:
+            bs = 1
+
+        if bs in PRECOMPUTED_HEATMAPS:
+            return jsonify(PRECOMPUTED_HEATMAPS[bs])
+
+        # Fallback for non-precomputed block sizes
+        starts_and_counts = [(parse_start(b.get("id")), int(
+            b.get("count", 0))) for b in base_blocks]
+        if bs == 1:
+            ids = sorted(str(start) for start, _ in starts_and_counts)
+            return jsonify({"block_size": 1, "ids": ids})
+        acc: dict[str, Any] = {}
+        for start, count in starts_and_counts:
+            bucket = (start // bs) * bs
+            key = f"{bucket}-{bucket + bs - 1}"
+            acc[key] = acc.get(key, 0) + count  # Use the original count!
+        blocks = [{"id": k, "count": v} for k, v in acc.items()]
+        blocks.sort(key=lambda block: int(block["id"].split("-")[0]))
+        meta = {
+            "block_size": bs,
+            "max_id": max((start for start, _ in starts_and_counts), default=0),
+            "total_blocks": len(blocks)
+        }
+        return jsonify({"metadata": meta, "blocks": blocks})
+
+    return app

rulevis-1.0.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: rulevis
+Version: 1.0.0
+Summary: Interactive Wazuh Rule Graph Explorer
+Author-email: Zafer Balkan <zafer@zaferbalkan.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zbalkan/rulevis
+Project-URL: Repository, https://github.com/zbalkan/rulevis
+Project-URL: Issues, https://github.com/zbalkan/rulevis/issues
+Keywords: wazuh,detection,security,monitoring,logging,siem
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask>=3.1.2
+Requires-Dist: networkx>=3.5
+Dynamic: license-file
+
+# 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.
+
+![General View of RuleVis](https://github.com/zbalkan/rulevis/raw/master/assets/general-view.gif)
+
+## 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 pipx (for testing)
+
+`pipx 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.
+
+![Statistics Panel](https://github.com/zbalkan/rulevis/raw/master/assets/stats-panel.gif)
+
+### 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.
+
+![Heatmap View](https://github.com/zbalkan/rulevis/raw/master/assets/heatmap-view.gif)
+
+## 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.

rulevis-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rulevis.py,sha256=EaXrzPmJcXXPTN8BG7hozkL9aVlN8hoPGf47J_9dNwY,7147
+internal/analyzer.py,sha256=Cuz6TrKJ3EfJcwHzF5NeGidUqEoMNQ53HPmYmVFo5pg,7161
+internal/generator.py,sha256=sZu54uF9tdJq3VR8tjsuyZk1nN6SkLTjFXdH_8rbwSo,7659
+internal/visualizer.py,sha256=Fy32UtUDddZJa18rjYA9XSMcpZ1aIK5B52FvZMH4hKY,13822
+rulevis-1.0.0.dist-info/licenses/LICENSE,sha256=ztkkhuJWbd7G1tZrFebtUecU8LbQzI6Pm9wRc69eXu8,1088
+rulevis-1.0.0.dist-info/METADATA,sha256=gMf172IcL6xMeYiDme7x2Ew40Gf4EXTFO4Kuau2tJfk,8733
+rulevis-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rulevis-1.0.0.dist-info/entry_points.txt,sha256=2_1Zn-V0eVSIqleW3izMY0mp4iidkD8Rb0-WrGLxSwM,41
+rulevis-1.0.0.dist-info/top_level.txt,sha256=9ttBbMPxCJIx9wv_G5oYERYLOuOHIaq_f6-Afqk8kMM,26
+rulevis-1.0.0.dist-info/RECORD,,

rulevis-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rulevis-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rulevis = rulevis:main

rulevis-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zafer Balkan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rulevis-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+__init__
+internal
+rulevis

rulevis.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+
+import argparse
+import logging
+import os
+import re
+import sys
+import tempfile
+import webbrowser
+from threading import Timer
+from typing import Final
+
+from internal.analyzer import Analyzer
+from internal.generator import GraphGenerator
+from internal.visualizer import create_app
+
+APP_NAME: Final[str] = 'rulevis'
+DESCRIPTION: Final[str] = f"{APP_NAME} is a Wazuh rule visualization tool."
+ENCODING: Final[str] = "utf-8"
+
+# Precompiled regex to remove ANSI color/control sequences
+ANSI_ESCAPE_RE: re.Pattern[str] = re.compile(
+    r"""
+    (?:                           # Non-capturing group for all patterns
+      \x1B\[                      # ESC [ (CSI)
+      [0-?]*[ -/]*[@-~]           # Parameter bytes + intermediate + final byte
+     |                            # OR
+      \x1B[@-Z\\-_]               # 2-byte sequences
+     |                            # OR
+      \x1B\][^\x07]*(?:\x07|\x1B\\) # OSC sequences
+     |                            # OR literal representations (\x1b, <0x1b>)
+      (?:\\x1[bB]|\<0x1[bB]\>)(?:\[[0-?]*[ -/]*[@-~])?
+    )
+    """,
+    re.VERBOSE,
+)
+
+
+class CustomFileHandler(logging.FileHandler):
+    """FileHandler that strips all escape sequences and representations."""
+
+    def emit(self, record) -> None:
+        # Escape ANSI Color Sequences
+        record.msg = ANSI_ESCAPE_RE.sub('', str(record.msg))
+
+        # Rename source
+        record.name = APP_NAME
+
+        super().emit(record)
+
+
+class Rulevis():
+
+    def __init__(self, paths: list[str]) -> None:
+        self.graph_path: str = tempfile.NamedTemporaryFile(delete=False).name
+        logging.info(f"Temporary graph file created at {self.graph_path}")
+
+        self.stats_path: str = tempfile.NamedTemporaryFile(delete=False).name
+        logging.info(f"Temporary stats file created at {self.stats_path}")
+
+        self.heatmap_path: str = tempfile.NamedTemporaryFile(delete=False).name
+        logging.info(f"Temporary heatmap file created at {self.heatmap_path}")
+
+        self.__validate_paths(paths)
+        self.__paths: list[str] = paths
+
+    def __del__(self) -> None:
+        try:
+            if hasattr(self, 'graph_path') and os.path.exists(self.graph_path):
+                os.remove(self.graph_path)
+                logging.info(
+                    f"Temporary graph file {self.graph_path} deleted.")
+        except Exception as e:
+            logging.error(f"Error deleting temporary graph file: {e}")
+
+        try:
+            if hasattr(self, 'stats_path') and os.path.exists(self.stats_path):
+                os.remove(self.stats_path)
+                logging.info(
+                    f"Temporary stats file {self.stats_path} deleted.")
+        except Exception as e:
+            logging.error(f"Error deleting temporary stats file: {e}")
+
+        try:
+            if hasattr(self, 'heatmap_path') and os.path.exists(self.heatmap_path):
+                os.remove(self.heatmap_path)
+                logging.info(
+                    f"Temporary heatmap file {self.heatmap_path} deleted.")
+        except Exception as e:
+            logging.error(f"Error deleting temporary heatmap file: {e}")
+
+    def run(self) -> None:
+        self.__generate_graph()
+        self.__generate_stats()
+        self.__run_flask_app()
+
+    def __validate_paths(self, paths: list[str]) -> None:
+        for path in paths:
+            if not os.path:
+                logging.error(f"Invalid directory path: {path}", exc_info=True)
+                print(f"Error: Invalid directory path: {path}")
+                sys.exit(1)
+
+    def __generate_graph(self) -> None:
+        logging.info("Generating rule graph...")
+        generator = GraphGenerator(paths=self.__paths, graph_file=self.graph_path)
+        generator.build_graph_from_xml()
+        generator.save_graph()
+        logging.info("Graph generation complete.")
+
+    def __generate_stats(self) -> None:
+        logging.info("Generating rule stats...")
+        analyzer = Analyzer(self.graph_path)
+        analyzer.write_to_json(self.stats_path, self.heatmap_path)
+        logging.info("Stats generation complete.")
+
+    def __run_flask_app(self) -> None:
+        app = create_app(self.graph_path, self.stats_path, self.heatmap_path)
+        logging.info("Starting Flask app...")
+        Timer(1, self.__open_browser).start()
+        app.run(debug=True, use_reloader=False)
+
+    def __open_browser(self, ) -> None:
+        new_url = 'http://localhost:5000/'
+
+        if (webbrowser.get().name != 'gio'):
+            webbrowser.open_new(new_url)
+
+        print(f"Access the app over {new_url}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog=APP_NAME, description=DESCRIPTION)
+    if len(sys.argv) == 1:
+        parser.print_help()
+        sys.exit(1)
+
+    parser.add_argument("--path", "-p", dest="path", required=True, type=str,
+                        help="Path to the Wazuh rule directories. Comma-separated multiple paths are accepted.")
+
+    args: argparse.Namespace = parser.parse_args()
+    paths: list[str] = [p for p in str(args.path).split(',') if p != '']
+    logging.info(f"Paths: {paths}")
+
+    rulevis = Rulevis(paths)
+    rulevis.run()
+
+
+def _get_log_path() -> str:
+    """
+    Return a per-user log file path appropriate for Windows, Linux, and macOS.
+    Uses only os and sys modules.
+    """
+    # Determine base OS type
+    if os.name == "nt":  # Windows
+        base_dir = os.getenv(
+            "LOCALAPPDATA", os.path.expanduser("~\\AppData\\Local"))
+        log_dir = os.path.join(base_dir, APP_NAME, "Logs")
+
+    elif sys.platform == "darwin":  # macOS
+        log_dir = os.path.expanduser(f"~/Library/Logs/{APP_NAME}")
+
+    else:  # Linux / other Unix-like
+        xdg_state_home = os.getenv(
+            "XDG_STATE_HOME", os.path.expanduser("~/.local/state"))
+        log_dir = os.path.join(xdg_state_home, APP_NAME)
+        if not os.access(os.path.dirname(log_dir), os.W_OK):
+            log_dir = os.path.expanduser(f"~/.local/share/{APP_NAME}/logs")
+
+    os.makedirs(log_dir, exist_ok=True)
+    return os.path.abspath(os.path.join(log_dir, f"{APP_NAME}.log"))
+
+
+if __name__ == "__main__":
+    try:
+        handler = CustomFileHandler(_get_log_path(), encoding=ENCODING)
+
+        logging.basicConfig(handlers=[handler],
+                            format='%(asctime)s:%(name)s:%(levelname)s:%(message)s',
+                            datefmt="%Y-%m-%dT%H:%M:%S%z",
+                            level=logging.INFO)
+
+        excepthook = logging.error
+        logging.info('Starting')
+        main()
+        logging.info('Exiting.')
+    except KeyboardInterrupt:
+        print('Cancelled by user.')
+        logging.info('Cancelled by user.')
+        try:
+            sys.exit(0)
+        except SystemExit:
+            os._exit(0)
+    except Exception as ex:
+        print('ERROR: ' + str(ex))
+        logging.error(str(ex), exc_info=True)
+        try:
+            sys.exit(1)
+        except SystemExit:
+            os._exit(1)