Dev (#51)

* Enhance documentation for the project (#41) Co-authored-by: Br4guette <Br4guette@pm.me> * Add build docs * Add more docs (#42) * Enhance documentation for the project * Update docs --------- Co-authored-by: Br4guette <Br4guette@pm.me> * Add references (#43) * Enhance documentation for the project * Update docs * add references --------- Co-authored-by: Br4guette <Br4guette@pm.me> * 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 <Br4guette@pm.me> * 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 <Br4guette@pm.me> * 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 <Br4guette@pm.me> --------- Co-authored-by: Br4guette <Br4guette@pm.me> Co-authored-by: St0n14 <alexis.debrito@lgm.fr> Co-authored-by: Yann MAGNIN <42215723+YannMagnin@users.noreply.github.com>
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:alexis.debrito@ecole2600.com"
+ link: "mailto:alexis.debrito@ecole2600.com"