Dev (#51)

* Enhance documentation for the project (#41) Co-authored-by: Br4guette <[email protected]> * Add build docs * Add more docs (#42) * Enhance documentation for the project * Update docs --------- Co-authored-by: Br4guette <[email protected]> * Add references (#43) * Enhance documentation for the project * Update docs * add references --------- Co-authored-by: Br4guette <[email protected]> * Add references * Add title * Title 2 * add : mkdocs navigation references * document codes * fix typo * typo * fix typo * fix typo in utils * fix docs in tutorials.md * add : How to use documentation rename : tuto to installation add : documentation for windows fix : mkdocs add paths * Add other OS documentation * fix how to * fix : typo in docs * fix : typo * fix: typo in index * add : dark mode * add : colors on documentation * fix: diataxis * Fix colors * fix readme * Fix dumpfiles (#46) * fix : Dumpfile issue with parameters * test : Create test for dumpfiles * fix context builder * fix dumpfiles : dumpfiles can now be passed with arguments * tests: add tests for each parameters of dumpfiles fix: add markers on tests to easily execute a bunch of test instead of the complete file * fix : kwargs value in set_arguments was setted to int directly * add : Add test fonctions to test dumpfiles with a virtaddr but not able to test locally * add : add pytest decorator markers to pslist_pid --------- Co-authored-by: Br4guette <[email protected]> * fix: fix error, function without parameter return an error * sorry * fix typing information (#47) * Fix/get plugins (#48) * fix : bad import on v3_plugins_mod fix : poetry lock modfied due to update dependacies fix : windows setargs * remover useless info --------- Co-authored-by: Br4guette <[email protected]> * Fix: Correct dict.get() usage in TreeGrid_to_json renderer and remove debug print - Corrected the usage of dict.get() method by removing keyword arguments and using positional arguments instead. - Ensured the render method returns a dictionary as expected. - Updated the to_list method to properly call the render method and handle exceptions. - Improved the docstrings to reflect the correct return types and behaviors of the methods. - Removed a debug print statement introduced in a previous commit. This fixes the TypeError and ensures the TreeGrid is properly rendered to JSON format. * oops * fix to dataframe * add test for volatility (#49) Co-authored-by: Br4guette <[email protected]> --------- Co-authored-by: Br4guette <[email protected]> Co-authored-by: St0n14 <[email protected]> Co-authored-by: Yann MAGNIN <[email protected]>
PyDFIR · Jul 25, 2024 · 5e53bcf · 5e53bcf
1 parent c6665c7
commit 5e53bcf
Show file tree

Hide file tree

Showing 30 changed files with 1,300 additions and 338 deletions.
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - main
+      - dev
 jobs:
   deploy:
     runs-on: ubuntu-latest

diff --git a/README.md b/README.md
@@ -76,7 +76,7 @@ print(output.to_df())
 print(win.pslist().to_json())
 ```
 
-All supported features are documented, check it out on [our documentation](https://pydfir.github.io/pyDFIRRam/) !
+All supported features are documented, check it out on [our documentation](https://pydfir.github.io/pyDFIRRam) !
 
 ## Objectives
 

diff --git a/docs/tutorials.md → docs/Usage/installation.md b/docs/tutorials.md → docs/Usage/installation.md
@@ -3,10 +3,9 @@
 ## Quick installation
 
 ### Prerequisites 
-Install python3.10
-TODO
-Install : poetry 
-TODO
+- Python
+- Poetry (for dev)
+- pip
 
 ### From source
 On a standard Linux distribution :
@@ -15,8 +14,14 @@ git clone https://github.com/pydfir/pydfirram
 poetry shell
 poetry install
 ```
-### From pip
+### From pip stable
 
 ```shell
 pip install pydfirram
 ```
+### From pip dev
+
+```bash
+pip install -i https://test.pypi.org/simple/ pydfirram
+```
+
diff --git a/docs/Usage/linux.md b/docs/Usage/linux.md
@@ -0,0 +1,58 @@
+## Using pyDFIRRam for Linux or macOS
+
+### Introduction
+
+`pyDFIRRam` is a tool under development aimed at utilizing Volatility plugins for memory forensics on Linux and macOS systems.
+
+### Initial Setup
+
+1. **Installation**:
+   - Ensure Python 3.10 (or compatible version) is installed.
+   - Install `pyDFIRRam` using Poetry or manually. Example:
+     ```
+     pip install pydfirram
+     ```
+
+2. **Setting up a Profile**:
+   - Currently, there's no direct method via Python interface to add a profile. If you have a profile, place it in the Volatility symbols directory:
+     - For Linux/macOS:
+       ```
+       $HOME/.local/lib/python3.10/site-packages/volatility3/symbols/
+       ```
+     - For Poetry virtual environments:
+       ```
+       $HOME/.cache/pypoetry/virtualenvs/pydfirram-qv9SWnlF-py3.10/lib/python3.10/site-packages/volatility3/symbols/
+       ```
+
+### Using pyDFIRRam
+
+3. **Creating an Object**:
+   - Import necessary modules and create an object for your memory dump:
+     ```python
+     from pydfirram.core.base import Generic, OperatingSystem
+     from pathlib import Path
+     
+     os = OperatingSystem.LINUX  # Set to OperatingSystem.MACOS for macOS
+     dumpfile = Path("dump.raw")  # Replace with your actual memory dump path
+     generic = Generic(os, dumpfile)
+     ```
+
+4. **Listing Available Functions**:
+   - To list all available Volatility plugins:
+     ```python
+     generic.get_all_plugins()
+     ```
+
+5. **Using Plugins**:
+   - Refer to Volatility plugin documentation for parameters. Example using `pslist` plugin:
+     ```python
+     generic.pslist(pid=[4]).to_list()
+     ```
+
+6. **Formatting Output**:
+   - The return from Volatility functions provides a `Rendering` class, allowing customization of output format.
+
+### Notes
+
+- Ensure your memory dump file (`dump.raw` in the example) is correctly specified.
+- Adjust paths and settings based on your specific environment and Python setup.
diff --git a/docs/Usage/usage.md b/docs/Usage/usage.md
diff --git a/docs/Usage/windows.md b/docs/Usage/windows.md
@@ -0,0 +1,45 @@
+# How to Use pyDFIRRam for Windows
+
+This guide provides a brief and concise demonstration of how to use the pyDFIRRam tool for Windows.
+
+## Introduction
+
+Currently, the project is under development. To use the Volatility-related functions for Windows, follow these steps:
+
+### Initial Setup
+
+First, create an object for your memory dump:
+
+```python
+from pydfirram.modules.windows import Windows
+from pathlib import Path
+
+dump = Path("/home/dev/image.dump")
+win = Windows(dump)
+```
+
+### Listing Available Functions
+
+The available functions are all the Volatility plugins (located in the Volatility plugin path).
+
+To list all available functions:
+
+```python
+win.get_all_plugins()
+```
+
+You can use this function to retrieve all the plugins.
+
+### Using Parameters
+
+If you want to use Volatility parameters, refer to the plugin documentation. The parameters expected are generally the same with the same names.
+
+For example, to use the `pslist` plugin with a parameter:
+
+```python
+win.pslist(pid=4).to_list()
+```
+
+### Note
+
+On the return of the Volatility functions, a `Rendering` class is retrieved. This allows us to format our output as desired.
diff --git a/docs/how-to-guides.md b/docs/how-to-guides.md
diff --git a/docs/index.md b/docs/index.md
@@ -8,11 +8,10 @@ project documentation as described by Daniele Procida
 in the [Diátaxis documentation framework](https://diataxis.fr/)
 and consists of four separate parts:
 
-1. [Tutorials](tutorials.md)
-2. [How-To Guides](how-to-guides.md)
+1. [Tutorials](./Usage/installation.md)
+2. [How-To Guides](./Usage/usage.md)
 3. [Reference](reference/reference.md)
 4. [Explanation](explanation.md)
-5. [Test](test.md)
 
 Quickly find what you're looking for depending on
 your use case by looking at the different pages.
diff --git a/docs/reference/base.md b/docs/reference/base.md
@@ -0,0 +1,3 @@
+## Base
+
+::: pydfirram.core.base
diff --git a/docs/reference/handler.md b/docs/reference/handler.md
@@ -0,0 +1,3 @@
+## Handler
+
+::: pydfirram.core.handler
diff --git a/docs/reference/reference.md b/docs/reference/reference.md
@@ -1,5 +1,4 @@
-<!-- This part of the project documentation focuses on
-an **information-oriented** approach. Use it as a
-reference for the technical implementation of the
-`calculator` project code. -->
-
+<!-- This part of the project documentation focuses on
+an **information-oriented** approach. Use it as a
+reference for the technical implementation of the
+`calculator` project code. -->
diff --git a/docs/reference/renderer.md b/docs/reference/renderer.md
@@ -0,0 +1,3 @@
+## Renderer
+
+::: pydfirram.core.renderer
diff --git a/docs/reference/test.md b/docs/reference/test.md
@@ -0,0 +1,53 @@
+# Test Documentation
+
+## Project Structure
+The project is organized as follows:
+```bash
+.
+├── __init__.py
+├── config.py
+├── data
+│   └── dump.raw
+├── test_core_base.py
+├── test_core_rendering.py
+└── test_volatility_windows_function.py
+```
+
+### Files Description
+
+- **config.py**
+  This file contains configuration settings. You need to set the path of your dump file here before running the tests.
+
+- **test_core_base.py**
+  This script tests the core functionalities used in `pydfirram/core/base.py`.
+
+- **test_core_rendering.py**
+  This script tests the core functionalities used in `pydfirram/core/renderer.py`.
+
+- **test_volatility_windows_function.py**
+  This script tests all(Not All configuration an plugins for the moment) plugins of Volatility.
+
+### Test Data
+- **data/dump.raw**
+  This is where your test dump file should be located.
+
+## Running the Tests
+
+### Prerequisites
+1. Download the Windows XP image from the Volatility Foundation:
+   [Win XP Image](https://downloads.volatilityfoundation.org/volatility3/images/win-xp-laptop-2005-06-25.img.gz).
+
+2. Extract the downloaded image and place it in the `data` directory. Rename it to `dump.raw`.
+
+### Configuration
+1. Open `config.py`.
+2. Set the path of your dump file in the configuration.
+
+### Running the Tests
+To run the tests, use the following command:
+```bash
+pytest
+```
+
+## Notes
+- The current tests only support Windows architectures. Linux architectures are not supported yet.
diff --git a/docs/reference/utils.md b/docs/reference/utils.md
@@ -0,0 +1,3 @@
+## Utils
+
+::: pydfirram.core.utils
diff --git a/docs/reference/windows.md b/docs/reference/windows.md
@@ -0,0 +1,3 @@
+## Windows
+
+::: pydfirram.modules.windows
diff --git a/docs/test.md b/docs/test.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,7 +8,22 @@ repo_url: https://github.com/PyDFIR/PyDFIRRam
 edit_uri: edit/main/docs/
 
 theme:
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
   name: material
+  color_mode: auto
+  user_color_mode_toggle: true
+  locale: en
   features:
     - search.suggest
     - search.highlight
@@ -39,11 +54,19 @@ markdown_extensions:
 
 nav:
   - index.md
-  - tutorials.md
-  - how-to-guides.md
+  - explanation.md
+  - Usage:
+    - Installation : Usage/installation.md
+    - Windows : Usage/windows.md
+    - Linux/Mac : Usage/linux.md
   - Reference:
       - Index: reference/reference.md
-  - explanation.md
+      - Base: reference/base.md
+      - Handler: reference/handler.md
+      - Renderer: reference/renderer.md
+      - Utils: reference/utils.md
+      - Windows : reference/windows.md
+      - Testing : reference/test.md
 
 extra:
   version:
@@ -53,4 +76,4 @@ extra:
       link: https://github.com/PyDFIR/pyDFIRRam
       name: Github
     - icon: material/email
-      link: "mailto:[email protected]"
+      link: "mailto:[email protected]"
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,7 @@ on: @@
       push:
         branches:
           - main
+          - dev
     jobs:
       deploy:
         runs-on: ubuntu-latest
@@ Expand Down @@