recongraph 0.0.2

Reconstruction of Forensic Timelines Using Graph Theory

ReconGraph

Reconstruction of Forensic Timelines Using Graph Theory

recongraph is a Python library designed to reconstruct and visualize system behaviors and activities based on logs from various devices, such as Windows and Linux systems. It converts Plaso log2timeline CSV files into a forensic graph timeline. By parsing sequential log data and mapping them to defined events, recongraph builds a MultiDiGraph (Multi-Directed Graph) that represents the state transitions and operational flow of the target system. This graph-based approach aids in forensic analysis, anomaly detection, and understanding complex system behaviors across diverse platforms.

Table of Contents

• Features
• Prerequisites
• Installation
  • Python Virtual Environment Setup
  • Recongraph Package Installation
  • Sigma Rules Setup
• Quick Start
• Input Data Format
  • Log File
  • Event File
• Output
• Documentation
• License

Features

• Sigma Rule-Based Pattern Matching: Leverages standardized Sigma rules to identify and label security-relevant events in raw logs.
• Forensic Graph Construction: Transforms sequential log entries from Plaso (log2timeline) into a directed graph, where nodes represent detected events and edges represent temporal transitions.
• Intelligent Log Detection: Automatically identifies various log formats (e.g., Apache, Linux auth, Syslog) and extracts relevant metadata like HTTP methods, URIs, and status codes.
• Weighted Behavioral Mapping: Edges are weighted by transition frequency, helping to distinguish common flows from rare or suspicious sequences.
• Anomaly-Focused Reconstruction: Specifically isolates and maps behaviors based on rule severity levels (Critical, High, Medium, Low).
• Multi-Format Export: Exports graphs to GraphML for visualization (Gephi, Cytoscape) and detailed forensic timelines to CSV.

Prerequisites

• Python 3.13 or higher
• Git
• Python virtual environment (venv or conda)

Python Virtual Environment Setup

Recongraph uses several Python packages to function properly. It is recommended to install the package in a virtual environment to avoid dependency conflicts. Here is a simple example of how to create and activate a virtual environment:

1. Anaconda or Miniconda

   conda create -n recongraph python
   conda activate recongraph
   

Or using venv (recommended):

2. Venv

   python -m venv venv
   source venv/bin/activate
   

Recongraph Package Installation

Recongraph package installation can be done directly from PyPI using pip or by cloning this repository

Installing via Pip

pip install recongraph

Or installing by cloning this repository:

Installing from Source

1. Clone the Repository

   git clone https://github.com/forensic-timeline/recongraph
   

2. Install Depedencies

   cd recongraph
   pip install -e .
   

Sigma Rules Setup

To use the recongraph tools, sigma rules are needed to label and detect events in the log files. Sigma rules can be downloaded from https://github.com/SigmaHQ/sigma. The sigma rules are released under the Detection Rule License (DRL) 1.1.

Using git clone, you can use the sigma rules folder:

git clone https://github.com/SigmaHQ/sigma

Quick Start

Here is a simple example of how to use recongraph to reconstruct a forensic timeline:

recongraph -f /path/to/your/plaso-file.csv -r /path/to/your/sigma-rules-folder -o output-filename.graphml

How to Test

To ensure that the installation is correct and the code is functioning as expected, you can run the test suite provided in the tests/ directory.

1. Install Test Dependencies: Ensure you have pytest installed.

   pip install pytest pandas pyyaml
   

2. Run Tests: Navigate to the project root directory and execute:

   pytest -v
   

   You should see output indicating that all tests have passed.

Input Data Format

recongraph processes raw log data and applies Sigma rules to identify significant security events.

Log File (<filename>.csv)

A sequential log file containing system activities. The tool supports supports CSV format from Plaso (log2timeline).

Sigma Rules (rules/ directory)

A directory containing standardized Sigma rules in .yml format. These rules define the logic used to detect and label events within the logs.

Sigma rules are downloaded from https://github.com/SigmaHQ/sigma.

The content of that repository is released under the following licenses:

• The Sigma specification (https://github.com/SigmaHQ/sigma-specification) and the Sigma logo are public domain
• The rules contained in the SigmaHQ repository (https://github.com/SigmaHQ) are released under the Detection Rule License (DRL) 1.1

Output

The tool generates several files to aid in analysis:

• GraphML File (reconstruction_edge_graph.graphml): A directed graph where nodes are detected events and edges represent the flow between them. Suitable for visualization in Gephi or Cytoscape.
• Event Logs CSV (reconstruction_event_logs.csv): A detailed breakdown of every log entry associated with a graph node, including timestamps and raw message content.
• Sigma Labeled CSV (<filename>_sigma_labeled.csv): The input log file augmented with matching Sigma rule titles and severity levels.

Documentation

Full documentation is available at ReadTheDocs.

Licenses

ReconGraph

This project is licensed under the MIT License.

Third-Party Licenses

This project uses Sigma Rules for event detection.

• The Sigma specification and logo are public domain.
• The detection rules from the SigmaHQ repository are released under the Detection Rule License (DRL) 1.1.