Feature : Hibernation Layer and plugins.

.github/workflows/build-pypi.yml

@@ -5,39 +5,38 @@ on:
     branches:
       - stable
       - develop
-      - 'release/**'
+      - "release/**"
 
   pull_request:
     branches:
       - stable
-      - 'release/**'
+      - "release/**"
 
 jobs:
-
   build:
     runs-on: ubuntu-22.04
     strategy:
       matrix:
         python-version: ["3.8"]
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
 
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
 
-    - name: Build PyPi packages
-      run: |
-        python -m build
+      - name: Build PyPi packages
+        run: |
+          python -m build
 
-    - name: Archive dist
-      uses: actions/upload-artifact@v4
-      with:
-        name: volatility3-pypi
-        path: |
-          dist/
+      - name: Archive dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: volatility3-pypi
+          path: |
+            dist/

.github/workflows/install.yml

@@ -1,7 +1,6 @@
 name: Install Volatility3 test
 on: [push, pull_request]
 jobs:
-
   install_test:
     runs-on: ${{ matrix.host }}
     strategy:
@@ -10,15 +9,15 @@ jobs:
         host: [ ubuntu-latest, windows-latest ]
         python-version: [ "3.10", "3.11", "3.12", "3.13" ]
     steps:
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ matrix.python-version }}
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
 
-    - name: Setup python-pip
-      run: python -m pip install --upgrade pip
+      - name: Setup python-pip
+        run: python -m pip install --upgrade pip
 
     - name: Install volatility3
       run: pip install .

contrib/hibernation_checks/README.md

@@ -0,0 +1,23 @@
+# Checks for the hibernation layer (Windows 11 24H2+ support, Huffman set size)
+
+Plain Python 3 scripts, no Volatility needed for the first three. They print counters only (no path,
+no hash, no exact file size, no section offset by default). For the decompression checks and the
+layer tests: `pip install xpress-lz77`.
+
+| file | what it does |
+|---|---|
+| `hib_check.py` | Walks the chain of compression sets of the boot and of the kernel section of a `hiberfil.sys` with three layouts: `23h2` (size = bits 8-29, bits 30-31 = algorithm, `KernelPagesProcessed` at `0x230`), `24h2-early` (size = bits 8-28, bit 30 = LZ77+Huffman, counter at `0x238`) and `24h2` (same rules, counter at `0x250`). A layout matches a section when the chain reaches exactly the page count of the header with no invalid set header. It also walks the kernel chain until it ends by itself and prints which header qwords hold its page count and byte length (to find the counter of an unknown build), the set kinds and header bits 25-31 of each section, the Huffman sets that do not cover 16 pages, and with `--decompress` decompresses every compressed set and checks the output size. `--show-offsets` adds identifying values (local debugging only). |
+| `compare_outputs.py` | Compares two `windows.hibernation.Dump` outputs of the same file page by page, for the pages of the boot section and of the kernel section (`--outside` also counts the pages outside both). |
+| `count_nonzero_pages.py` | Counts the 4 KiB pages of a raw image that contain a non-zero byte (needs numpy). |
+| `test_hib_layout.py` | 16 synthetic unit tests of the tools, on hibernation files generated in memory. No sample data. |
+| `test_hib_layer.py` | 3 tests of the real `HibernationLayer` on the same synthetic files, for the three layouts: every page reads back; a LZ77+Huffman set of 4 pages converts (with the decoder asked for a fixed 65536 bytes it fails with `EOF Error`); a `--version 4` file whose counter matches no known offset is refused. Needs `xpress-lz77` and runs from this directory with the repository root on `sys.path` (done by the test itself). |
+| `campaign_2026-10/` | Logs of the test campaign on Windows 11 21H2, 22H2, 23H2, 24H2, 25H2 and 26H1 lab VMs: `SUMMARY.md` (tables), `campaign.log` (one line per step), and per build and round the `hib_check.py --decompress` output and the `windows.hibernation.Dump` runs (this branch, second run, original code, wrong `--version`), the unit-test and ruff runs. Nothing from a real case is included. |
+
+```
+python3 hib_check.py hiberfil.sys --decompress
+python3 compare_outputs.py hiberfil.sys out_a/memory_layer.raw out_b/memory_layer.raw
+cd contrib/hibernation_checks && python3 -m unittest -v test_hib_layout test_hib_layer
+```
+
+The two tools mirror the parsing rules of the layer, they are not Volatility itself; `test_hib_layer.py`
+exercises the layer.

contrib/hibernation_checks/TEST_hib_check_lab_vms.txt

@@ -0,0 +1,149 @@
+##### lab VM file: win10 (Fast Startup: Windows 10 22H2 / Windows 11 24H2 build 26100.1742)
+signature            : b'HIBR'
+file size            : about 4 GiB
+NumPagesForLoader    : 18919
+
+=== layout 23h2 (KernelPagesProcessed @ 0x230) ===
+KernelPagesProcessed : 222203
+boot section         : 1183 sets, 18919/18919 pages, ok, MATCH
+kernel section       : 13888 sets, 222203/222203 pages, ok, MATCH
+
+=== layout 24h2 (KernelPagesProcessed @ 0x250) ===
+KernelPagesProcessed : 75013
+boot section         : 1183 sets, 18919/18919 pages, ok, MATCH
+kernel section       : 4689 sets, 75024/75013 pages, ok, MISMATCH
+
+=== layout 24h2-early (KernelPagesProcessed @ 0x238) ===
+KernelPagesProcessed : 17612265
+boot section         : 1183 sets, 18919/18919 pages, ok, MATCH
+kernel section       : 13888 sets, 222203/17612265 pages, INVALID SET HEADER, MISMATCH
+
+=== header bits, 24h2 rules ===
+  boot: set kinds (kind, bit29, bit30):
+     plain-lz77  bit29=0 bit30=0 : 1183
+  boot: largest set size 53665 bytes (16 bits), header bits set:
+     bit 25 : 0 sets
+     bit 26 : 0 sets
+     bit 27 : 0 sets
+     bit 28 : 0 sets
+     bit 29 : 0 sets
+     bit 30 : 0 sets
+     bit 31 : 0 sets
+  boot: sets larger than 64 KiB : 0
+  boot: huffman sets with pages != 16 : 0
+  boot: compressed sets classified differently by the 23h2 rules : 0
+  boot: compressed sets sized differently by the 23h2 rules : 0
+
+=== kernel chain walked to its natural end, 23h2 set rules ===
+13888 sets, 222203 pages | header qwords equal to that page count: 0x230 | equal to its length in bytes: 0x240
+
+=== kernel chain walked to its natural end, 24h2 set rules ===
+13888 sets, 222203 pages | header qwords equal to that page count: 0x230 | equal to its length in bytes: 0x240
+
+=== decompression (algorithm selected by each layout; output size checked) ===
+23h2 layout, boot section: 1183 compressed sets | plain LZ77 ok=1183 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+23h2 layout, kernel section: 13850 compressed sets | plain LZ77 ok=13572 failed=0 | Huffman ok=278 failed=0 (ok only with the exact size argument: 0)
+24h2 layout, boot section: 1183 compressed sets | plain LZ77 ok=1183 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+24h2 layout, kernel section: not walked (section skipped or chain does not match)
+24h2-early layout, boot section: 1183 compressed sets | plain LZ77 ok=1183 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+24h2-early layout, kernel section: not walked (section skipped or chain does not match)
+
+##### lab VM file: w11fs (Fast Startup: Windows 10 22H2 / Windows 11 24H2 build 26100.1742)
+signature            : b'HIBR'
+file size            : about 6 GiB
+NumPagesForLoader    : 30093
+
+=== layout 23h2 (KernelPagesProcessed @ 0x230) ===
+KernelPagesProcessed : 30093
+boot section         : 1881 sets, 30093/30093 pages, ok, MATCH
+kernel section       : 25 sets, 400/30093 pages, INVALID SET HEADER, MISMATCH
+
+=== layout 24h2 (KernelPagesProcessed @ 0x250) ===
+KernelPagesProcessed : 10338
+boot section         : 1881 sets, 30093/30093 pages, ok, MATCH
+kernel section       : 647 sets, 10352/10338 pages, ok, MISMATCH
+
+=== layout 24h2-early (KernelPagesProcessed @ 0x238) ===
+KernelPagesProcessed : 322278
+boot section         : 1881 sets, 30093/30093 pages, ok, MATCH
+kernel section       : 20143 sets, 322278/322278 pages, ok, MATCH
+
+=== header bits, 24h2 rules ===
+  boot: set kinds (kind, bit29, bit30):
+     plain-lz77  bit29=0 bit30=0 : 1881
+  boot: largest set size 55327 bytes (16 bits), header bits set:
+     bit 25 : 0 sets
+     bit 26 : 0 sets
+     bit 27 : 0 sets
+     bit 28 : 0 sets
+     bit 29 : 0 sets
+     bit 30 : 0 sets
+     bit 31 : 0 sets
+  boot: sets larger than 64 KiB : 0
+  boot: huffman sets with pages != 16 : 0
+  boot: compressed sets classified differently by the 23h2 rules : 0
+  boot: compressed sets sized differently by the 23h2 rules : 0
+
+=== kernel chain walked to its natural end, 23h2 set rules ===
+25 sets, 400 pages | header qwords equal to that page count: none | equal to its length in bytes: none
+
+=== kernel chain walked to its natural end, 24h2 set rules ===
+20143 sets, 322278 pages | header qwords equal to that page count: 0x238 | equal to its length in bytes: 0x248
+
+=== decompression (algorithm selected by each layout; output size checked) ===
+23h2 layout, boot section: 1881 compressed sets | plain LZ77 ok=1881 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+23h2 layout, kernel section: not walked (section skipped or chain does not match)
+24h2 layout, boot section: 1881 compressed sets | plain LZ77 ok=1881 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+24h2 layout, kernel section: not walked (section skipped or chain does not match)
+24h2-early layout, boot section: 1881 compressed sets | plain LZ77 ok=1881 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+24h2-early layout, kernel section: 19579 compressed sets | plain LZ77 ok=19174 failed=0 | Huffman ok=405 failed=0 (ok only with the exact size argument: 0)
+
+##### lab VM file: Windows 10 22H2 full hibernation (shutdown /h)
+signature            : b'HIBR'
+file size            : about 4 GiB
+NumPagesForLoader    : 19211
+
+=== layout 23h2 (KernelPagesProcessed @ 0x230) ===
+KernelPagesProcessed : 291139
+boot section         : 1201 sets, 19211/19211 pages, ok, MATCH
+kernel section       : 18197 sets, 291139/291139 pages, ok, MATCH
+
+=== layout 24h2 (KernelPagesProcessed @ 0x250) ===
+KernelPagesProcessed : 89229
+boot section         : 1201 sets, 19211/19211 pages, ok, MATCH
+kernel section       : 5577 sets, 89232/89229 pages, ok, MISMATCH
+
+=== layout 24h2-early (KernelPagesProcessed @ 0x238) ===
+KernelPagesProcessed : 17850400
+boot section         : 1201 sets, 19211/19211 pages, ok, MATCH
+kernel section       : 18197 sets, 291139/17850400 pages, INVALID SET HEADER, MISMATCH
+
+=== header bits, 24h2 rules ===
+  boot: set kinds (kind, bit29, bit30):
+     plain-lz77  bit29=0 bit30=0 : 1201
+  boot: largest set size 54147 bytes (16 bits), header bits set:
+     bit 25 : 0 sets
+     bit 26 : 0 sets
+     bit 27 : 0 sets
+     bit 28 : 0 sets
+     bit 29 : 0 sets
+     bit 30 : 0 sets
+     bit 31 : 0 sets
+  boot: sets larger than 64 KiB : 0
+  boot: huffman sets with pages != 16 : 0
+  boot: compressed sets classified differently by the 23h2 rules : 0
+  boot: compressed sets sized differently by the 23h2 rules : 0
+
+=== kernel chain walked to its natural end, 23h2 set rules ===
+18197 sets, 291139 pages | header qwords equal to that page count: 0x230 | equal to its length in bytes: 0x240
+
+=== kernel chain walked to its natural end, 24h2 set rules ===
+18197 sets, 291139 pages | header qwords equal to that page count: 0x230 | equal to its length in bytes: 0x240
+
+=== decompression (algorithm selected by each layout; output size checked) ===
+23h2 layout, boot section: 1201 compressed sets | plain LZ77 ok=1201 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+23h2 layout, kernel section: 18175 compressed sets | plain LZ77 ok=24 failed=0 | Huffman ok=18150 failed=1 (ok only with the exact size argument: 1)
+24h2 layout, boot section: 1201 compressed sets | plain LZ77 ok=1201 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+24h2 layout, kernel section: not walked (section skipped or chain does not match)
+24h2-early layout, boot section: 1201 compressed sets | plain LZ77 ok=1201 failed=0 | Huffman ok=0 failed=0 (ok only with the exact size argument: 0)
+24h2-early layout, kernel section: not walked (section skipped or chain does not match)