recongraph 0.0.1__tar.gz → 0.0.2__tar.gz

{recongraph-0.0.1 → recongraph-0.0.2}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 forensic-timeline
-
-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.
+MIT License
+
+Copyright (c) 2025 forensic-timeline
+
+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.

{recongraph-0.0.1/recongraph.egg-info → recongraph-0.0.2}/PKG-INFO

@@ -1,166 +1,181 @@
-Metadata-Version: 2.4
-Name: recongraph
-Version: 0.0.1
-Summary: Reconstruction of Forensic Timelines Using Graph Theory
-Author: Muhammad Nur Yasir Utomo
-Project-URL: Homepage, https://github.com/forensic-timeline/recongraph
-Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: PyYAML
-Requires-Dist: networkx
-Requires-Dist: pandas
-Requires-Dist: lxml
-Dynamic: license-file
-
-# 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](#features)
-- [Prerequisites](#prerequisites)
-- [Installation](#installation)
-  - [Python Virtual Environment Setup](#python-virtual-environment-setup)
-  - [Recongraph Package Installation](#recongraph-package-installation)
-  - [Sigma Rules Setup](#sigma-rules-setup)
-- [Quick Start](#quick-start)
-- [Input Data Format](#input-data-format)
-  - [Log File](#log-file)
-  - [Event File](#event-file)
-- [Output](#output)
-- [Documentation](#documentation)
-- [License](#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:
-
-### Anaconda or Miniconda
-
-```bash
-conda create -n recongraph python
-conda activate recongraph
-```
-
-Or using venv (recommended):
-
-### Venv
-
-```bash
-python -m venv venv
-# Windows
-venv\Scripts\activate
-# Linux/Mac
-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
-
-```bash
-pip install recongraph
-```
-
-Or installing by cloning this repository:
-
-### Installing from Source
-
-1. Clone the Repository
-
-```bash
-git clone https://github.com/forensic-timeline/recongraph
-```
-
-2. Install Depedencies
-
-```bash
-cd recongraph
-pip install -e .
-```
-
-## Sigma Rules Setup
-
-THIS PART NEED IMPROVEMENT
-
-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](https://github.com/SigmaHQ/Detection-Rule-License).
-
-Using git clone, you can use the sigma rules folder:
-
-```bash
-git clone https://github.com/SigmaHQ/sigma
-```
-
-## Quick Start
-
-Here is a simple example of how to use `recongraph` to reconstruct a forensic timeline:
-
-```bash
-recongraph -f ./plaso-result.csv -r ./sigma-rules
-```
-
-## 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](https://github.com/SigmaHQ/Detection-Rule-License)
-
-## 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](https://recongraph.readthedocs.io/).
- 
-## Licenses
- 
-### ReconGraph
- 
-This project is licensed under the [MIT License](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](https://github.com/SigmaHQ/sigma) are released under the [Detection Rule License (DRL) 1.1](https://github.com/SigmaHQ/Detection-Rule-License).
+Metadata-Version: 2.4
+Name: recongraph
+Version: 0.0.2
+Summary: Reconstruction of Forensic Timelines Using Graph Theory
+Author: Muhammad Nur Yasir Utomo
+Project-URL: Homepage, https://github.com/forensic-timeline/recongraph
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML
+Requires-Dist: networkx
+Requires-Dist: pandas
+Requires-Dist: lxml
+Dynamic: license-file
+
+# 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](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+  - [Python Virtual Environment Setup](#python-virtual-environment-setup)
+  - [Recongraph Package Installation](#recongraph-package-installation)
+  - [Sigma Rules Setup](#sigma-rules-setup)
+- [Quick Start](#quick-start)
+- [Input Data Format](#input-data-format)
+  - [Log File](#log-file)
+  - [Event File](#event-file)
+- [Output](#output)
+- [Documentation](#documentation)
+- [License](#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
+
+      ```bash
+      conda create -n recongraph python
+      conda activate recongraph
+      ```
+
+Or using venv (recommended):
+
+  2. Venv
+
+      ```bash
+      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
+
+ ```bash
+pip install recongraph
+```
+
+Or installing by cloning this repository:
+
+### Installing from Source
+
+  1. **Clone the Repository**
+
+      ```bash
+      git clone https://github.com/forensic-timeline/recongraph
+      ```
+
+  2. **Install Depedencies**
+
+      ```bash
+      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](https://github.com/SigmaHQ/Detection-Rule-License).
+
+Using git clone, you can use the sigma rules folder:
+
+```bash
+git clone https://github.com/SigmaHQ/sigma
+```
+
+## Quick Start
+
+  Here is a simple example of how to use `recongraph` to reconstruct a forensic timeline:
+
+  ```bash
+  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.
+
+    ```bash
+    pip install pytest pandas pyyaml
+    ```
+
+2.  **Run Tests**:
+    Navigate to the project root directory and execute:
+
+    ```bash
+    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](https://github.com/SigmaHQ/Detection-Rule-License)
+
+## 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](https://recongraph.readthedocs.io/).
+ 
+## Licenses
+ 
+### ReconGraph
+ 
+This project is licensed under the [MIT License](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](https://github.com/SigmaHQ/sigma) are released under the [Detection Rule License (DRL) 1.1](https://github.com/SigmaHQ/Detection-Rule-License).