API Reference

class recongraph.recongraph.ReconGraph(input_file, rules_dir=None, flexible_mode=True)

Bases: object

Unified facade for the complete forensic reconstruction pipeline.

This class serves as the main entry point for the ReconGraph library, coordinating the transition from raw logs to labeled data and finally to a behavioral graph. It simplifies complex operations into a single automated workflow.

run_all(graph_output='reconstruction_edge_graph.graphml', csv_output=None, sigma_output=None)

Executes the full pipeline.

This function will run the full execution pipeline which consists of 3 phases: 1. Sigma Labeling 2. Edge Graph Construction 3. Export

Component Classes

class recongraph.recongraph.SigmaLabel(input_file, rules_dir=None, flexible_mode=True)

Bases: object

Orchestrates the log labeling process using Sigma rules.

This class is responsible for reading input log files (CSV or TXT), identifying the appropriate log type and source, and applying the loaded Sigma rules to each entry to generate a labeled dataset.

count_lines()

Counts the number of lines in the input file.

This function reads the input file to count the total number of lines, which is useful for progress tracking.

detect_log_type(desc: str, filename: str) → Dict[str, Any]

Detects the type of log entry based on its description and filename.

This function analyzes the log description and filename to categorize the log (e.g., ‘webserver’, ‘linux’, ‘windows’) and extracts relevant fields like HTTP methods or status codes.

run()

Processes the input file and returns a labeled DataFrame.

This function orchestrates the loading of data, detection of log types, matching against Sigma rules, and generation of a labeled DataFrame.

class recongraph.recongraph.EdgeGraph(df: DataFrame)

Bases: object

Constructs a directed graph from sigma-labeled logs to visualize system behavior.

This class transforms a sequential list of security events into a MultiDiGraph where nodes represent unique event types and edges represent temporal transitions between them. It captures event frequency and associated log metadata to facilitate forensic analysis.

add_edges_to_graph()

Add weighted edges to the graph.

This function incorporates the calculated weighted edges into the graph structure.

add_node_attributes()

Enrich nodes with attributes.

This function adds metadata to each node in the graph, such as the first log snippet, timestamp, and the count of logs associated with that event.

create_edges()

Calculate edges based on event transitions.

This function iterates through the sequence of event IDs and creates edges between consecutive events, counting their occurrences to determine weights.

create_graph()

Initialize the graph with nodes.

This function creates a new networkx MultiDiGraph and adds the identified events as nodes.

create_weighted_edges()

Format edges with weights for the graph.

This function prepares the list of weighted edges to be added to the networkx graph.

define_events()

Identify unique security events from the labeled dataset.

This function iterates through the ‘sigma’ column to find all unique rule matches. These matches define the nodes of the graph. Each unique Sigma label becomes a distinct node in the resulting behavioral map.

export_event_logs(output_filename='reconstruction_event_logs.csv')

Exports detailed event logs to a separate CSV file.

This function creates a detailed CSV report containing every log entry that contributed to the identified events.

get_list_event_id()

Map log entries to event IDs.

This function processes the DataFrame rows, identifying which event ID corresponds to each log entry based on its Sigma label, and stores this mapping.

run_all(graph_output='reconstruction_edge_graph.graphml', csv_output=None)

Execute the full graph construction pipeline.

This function will run the full graph construction pipeline which consists of 6 phases: 1. Defining Events 2. Creating Graph Nodes 3. Processing Log Events 4. Adding Node Attributes 5. Creating Edges 6. Writing Output

write_to_graphml(output_filename='reconstruction_edge_graph.graphml')

Save the graph to a GraphML file.

This function exports the constructed graph to a file in GraphML format.