diff --git a/stat/entropy.py b/stat/entropy.py new file mode 100644 index 0000000..ac19a22 --- /dev/null +++ b/stat/entropy.py @@ -0,0 +1,180 @@ +# File: entropy.py +# Copyright (C) 2026 Erick Ahmed +# SPDX-License-Identifier: AGPL-3.0-or-later + +import argparse +from pathlib import Path + +import numpy as np +import pandas as pd +import plotly.graph_objects as go + +from utils.extractor import load_data + + +def _to_int(x): + """Convert a hex string or integer to int, returning NaN on failure.""" + if isinstance(x, (int, np.integer)): + return int(x) + if isinstance(x, str): + try: + return int(x, 16) + except ValueError: + return np.nan + return np.nan + + +def calculate_byte_entropy(df: pd.DataFrame) -> pd.DataFrame: + """Calculates Shannon entropy per byte position for each identifier.""" + byte_cols = [f"b{i}" for i in range(8)] + available_cols = [col for col in byte_cols if col in df.columns] + if not available_cols: + raise ValueError("No byte columns (b0-b7) found in the DataFrame") + + df_bytes = df[available_cols].copy() + for col in available_cols: + df_bytes[col] = df_bytes[col].apply(_to_int) + + def entropy(s: pd.Series) -> float: + s = s.dropna() + if s.empty: + return 0.0 + p = s.value_counts(normalize=True) + return -np.sum(p * np.log2(p)) + + return df.groupby("Identifier")[available_cols].agg(entropy) + + +def plot_entropy_heatmap(entropy_df: pd.DataFrame, title: str) -> go.Figure: + """Generates an interactive heatmap of byte-level Shannon entropy.""" + x = entropy_df.columns.tolist() + y = entropy_df.index.tolist() + z = entropy_df.values + + fig = go.Figure( + data=go.Heatmap( + z=z, + x=x, + y=y, + colorscale=[ + [0.0, "#ffffff"], + [0.15, "#fff7ec"], + [0.35, "#fee8c8"], + [0.55, "#fdd49e"], + [0.75, "#fdbb84"], + [1.0, "#ef6548"], + ], + xgap=3, + ygap=3, + text=np.round(z, 2), + texttemplate="%{text}", + textfont={ + "size": 11, + "color": "#2a2a2a", + "family": "Segoe UI, Arial, sans-serif", + }, + hoverongaps=False, + hovertemplate=( + "%{y}
" + "Byte %{x}: %{z:.2f} bits" + ), + colorbar=dict( + title=dict( + text="Entropy (bits)", + side="top", + font=dict(size=13, color="#1a1a1a"), + ), + orientation="h", + thickness=15, + len=0.35, + x=1.0, + xanchor="right", + y=1.02, + yanchor="bottom", + tickfont=dict(size=11, color="#2a2a2a"), + tickformat=".1f", + outlinewidth=0.5, + outlinecolor="#cccccc", + ), + ) + ) + + fig.update_layout( + title=dict( + text=title, + font=dict(size=20, color="#1a1a1a"), + x=0.5, + xanchor="center", + pad=dict(b=20), + ), + height=max(600, len(y) * 28 + 150), + autosize=True, + template="plotly_white", + xaxis=dict( + title=dict(text="Byte Position", font=dict(size=13, color="#1a1a1a")), + side="top", + dtick=1, + showgrid=False, + linecolor="#bdbdbd", + tickfont=dict(size=12, color="#2a2a2a"), + ticks="outside", + ticklen=4, + tickcolor="#cccccc", + ), + yaxis=dict( + title=dict(text="PGN or CAN ID", font=dict(size=13, color="#1a1a1a")), + autorange="reversed", + showgrid=False, + linecolor="#bdbdbd", + tickfont=dict(size=12, color="#2a2a2a"), + ticks="outside", + ticklen=4, + tickcolor="#cccccc", + automargin=True, + ), + font=dict(family="Segoe UI, Arial, sans-serif", size=12, color="#2a2a2a"), + hoverlabel=dict( + bgcolor="white", + font_size=13, + font_family="Segoe UI", + bordercolor="#cccccc", + ), + margin=dict(l=200, r=40, t=120, b=60), + ) + return fig + + +if __name__ == "__main__": + parser = argparse.ArgumentParser( + description="Analyze CAN bus byte-level entropy" + ) + parser.add_argument( + "input", type=Path, help="Path to the input CAN log file" + ) + parser.add_argument( + "output", + type=Path, + nargs="?", + default=Path("entropy_report.html"), + help="Path to the output HTML report", + ) + parser.add_argument( + "title", + nargs="?", + default="CAN Bus Byte-Level Entropy", + help="Title for the HTML report", + ) + args = parser.parse_args() + + df = load_data(args.input) + entropy_df = calculate_byte_entropy(df) + fig = plot_entropy_heatmap(entropy_df, title=args.title) + + config = { + "responsive": True, + "displaylogo": False, + "scrollZoom": True, + "modeBarButtonsToAdd": ["toggleSpikelines"], + "toImageButtonOptions": {"format": "png", "scale": 2}, + } + fig.write_html(str(args.output), include_plotlyjs="cdn", config=config)