Skip to content
Back to search

bitlocker-dbx-rollback

MarketplaceWorks with Claude CodeGitHub

Unlock BitLocker again after a Secure Boot dbx change, without the recovery key.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jpsanders/bitlocker-dbx-rollback with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jpsanders/bitlocker-dbx-rollback'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jpsanders--bitlocker-dbx-rollback/badge.svg)](/listings/jpsanders--bitlocker-dbx-rollback)

HTML

<a href="/listings/jpsanders--bitlocker-dbx-rollback"><img src="/api/listings/jpsanders--bitlocker-dbx-rollback/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Python 3.14 or later. `uv tool install bitlocker-dbx-rollback` or `pipx install bitlocker-dbx-rollback`. `fetch --lvfs` needs `zstd`; the Windows update steps need `wine` and `cabextract`.

`dbx-rollback man --install` makes `man dbx-rollback` work. The source is [`docs/MANUAL.md`](https://github.com/jpsanders/bitlocker-dbx-rollback/blob/main/docs/MANUAL.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "bitlocker-dbx-rollback",
  4. "description": "Unlock BitLocker again after a Secure Boot dbx change, without the recovery key.",
  5. "owner": {
  6. "name": "James Phillip Sanders",
  7. "email": "hello@jamesphillipsanders.com"
  8. },
  9. "plugins": [
  10. {
  11. "name": "bitlocker-dbx-rollback",
  12. "description": "A skill that drives dbx-rollback safely: analyze, plan, kit, and the firmware steps one at a time.",
  13. "version": "1.0.0",
  14. "source": "./",
  15. "category": "development",
  16. "homepage": "https://github.com/jpsanders/bitlocker-dbx-rollback"
  17. }
  18. ]
  19. }
README.md · README · 148 lines
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jpsanders/bitlocker-dbx-rollback/main/docs/images/banner-dark.png">
  4. <img alt="bitlocker-dbx-rollback: unlock BitLocker again after a Secure Boot dbx change, without the recovery key" src="https://raw.githubusercontent.com/jpsanders/bitlocker-dbx-rollback/main/docs/images/banner-light.png" width="100%">
  5. </picture>
  6. </p>
  7. <p align="center">
  8. <a href="https://github.com/jpsanders/bitlocker-dbx-rollback/actions/workflows/dev.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/jpsanders/bitlocker-dbx-rollback/dev.yml?branch=main&label=CI&logo=github"></a>
  9. <a href="https://github.com/jpsanders/bitlocker-dbx-rollback/releases/latest"><img alt="Release 1.0.0" src="https://img.shields.io/badge/release-1.0.0-a95719"></a>
  10. <a href="https://pypi.org/project/bitlocker-dbx-rollback/"><img alt="PyPI bitlocker-dbx-rollback" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fbitlocker-dbx-rollback%2Fjson&query=%24.info.version&label=pypi&logo=pypi&logoColor=white&color=a95719"></a>
  11. <a href="https://www.python.org/downloads/"><img alt="Python 3.14 and 3.15" src="https://img.shields.io/badge/python-3.14%20%7C%203.15-3776AB?logo=python&logoColor=white"></a>
  12. <img alt="BitLocker TPM only, PCR 7 and 11" src="https://img.shields.io/badge/bitlocker-TPM%20%C2%B7%20PCR%207%2B11-0078D4?logo=windows&logoColor=white">
  13. <img alt="No Microsoft binaries redistributed" src="https://img.shields.io/badge/Microsoft%20binaries-never%20bundled-2ea44f">
  14. <a href="https://github.com/jpsanders/bitlocker-dbx-rollback#with-an-ai-agent"><img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude%20Code-plugin-a95719"></a>
  15. <a href="https://mypy-lang.org/"><img alt="mypy strict" src="https://img.shields.io/badge/mypy-strict-2a6db2"></a>
  16. <a href="https://github.com/jpsanders/bitlocker-dbx-rollback/blob/main/LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-blue"></a>
  17. <a href="https://github.com/jpsanders/bitlocker-dbx-rollback/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/jpsanders/bitlocker-dbx-rollback?style=flat&logo=github&color=a95719"></a>
  18. </p>
  19. Your Windows laptop suddenly says **"BitLocker needs your recovery key to unlock your drive because Secure Boot
  20. policy has unexpectedly changed"**, and you do not have the key. If the change was to the Secure Boot revocation list
  21. (dbx), this tool can get the TPM to unlock the drive by itself again. It works out exactly which dbx the TPM is
  22. waiting for, proves which Microsoft signed updates rebuild it byte for byte, and writes a guarded script that puts
  23. it back.
  24. It was built to recover a real laptop, and it did: Windows started again with the TPM alone, and the recovery key was
  25. read out and saved.
  26. ```sh
  27. uv tool install bitlocker-dbx-rollback
  28. dbx-rollback analyze --efivars efivars/ --dislocker-log bitlocker-info.log --out target-dbx.bin
  29. dbx-rollback plan --factory-dbx factory-dbx.bin --target target-dbx.bin --payloads payloads/
  30. ```
  31. ## Is this your problem?
  32. It fits when all of these hold:
  33. - The blue BitLocker screen gives the reason **Secure Boot policy has unexpectedly changed**.
  34. - The drive's only protectors are **TPM** and **Numerical Password** (TPM only BitLocker, the Windows default),
  35. sealed to **PCRs 7 and 11**.
  36. - Something wrote to the firmware's **dbx** from outside Windows. The classic case: an Ubuntu USB stick whose
  37. `secureboot-db.service` appends Microsoft's revocation list to every PC it boots. `fwupd` dbx updates and BIOS
  38. updates can do the same.
  39. - The firmware can load its **factory Secure Boot keys**, and its PK, KEK and db are still the factory ones.
  40. If you have the 48 digit recovery key, type it in instead. This tool is for when you cannot.
  41. ## How it works
  42. 1. **The sealed state.** A TPM only protector seals the volume key to `PolicyAuthValue` then `PolicyPCR(7, 11)`.
  43. The protector stores the PCR digest the TPM will accept. `analyze` reads it from `dislocker-metadata` output and
  44. checks the policy really is that shape.
  45. 2. **PCR 7 from variables.** Firmware measures SecureBoot, PK, KEK, db and dbx, a separator, then the db entry
  46. that verified each image. `analyze` replays that for every list boundary of today's dbx and every db entry. Firmware
  47. only ever appends to dbx, so the sealed dbx is a prefix of today's. One prefix matches.
  48. 3. **Rebuild by signed appends.** dbx only accepts additions signed by a KEK. So the firmware's factory keys go back
  49. first (dbx becomes the factory list), then Microsoft's own signed updates are appended in the order Windows once
  50. applied them. Firmware drops entries it already has and adds the rest as one new list, so the structure comes back
  51. exactly. `plan` simulates that and searches for the order that rebuilds the target byte for byte.
  52. 4. **Find the missing updates.** `fetch` downloads every uefi.org release from LVFS and every version in
  53. `microsoft/secureboot_objects`, and collects the files a Windows install kept in `SecureBootUpdates` and `WinSxS`.
  54. Some updates only ever shipped inside Windows updates; `psf` pulls their patches out of an express package from
  55. the Microsoft Update Catalog, and `apply-delta` applies them with `msdelta.dll` from a Windows install you own,
  56. under Wine.
  57. 5. **A guarded kit.** `kit` refuses to write anything unless the sequence rebuilds the target in simulation. Its
  58. `rebuild.sh` runs on the locked machine from a Linux stick, writes only dbx, checks PK, KEK and db first, checks
  59. every step's size and content, stops at the first difference, can be rerun, logs everything, and has a read only
  60. `verify` mode for after a reboot.
  61. ## Recover a machine
  62. The full walkthrough, with the firmware steps, is in the [manual](https://github.com/jpsanders/bitlocker-dbx-rollback/blob/main/docs/MANUAL.md).
  63. In short:
  64. ```sh
  65. # On the locked PC, booted from a Linux stick whose secureboot-db.service is MASKED:
  66. sudo dislocker-metadata -V /dev/nvme0n1p3 > bitlocker-info.log
  67. mkdir efivars && cp /sys/firmware/efi/efivars/{SecureBoot,SetupMode,PK,KEK,db,dbx,dbxDefault}-* efivars/
  68. # Anywhere:
  69. dbx-rollback analyze --efivars efivars/ --dislocker-log bitlocker-info.log --out target-dbx.bin
  70. tail -c +5 efivars/dbxDefault-* > factory-dbx.bin
  71. dbx-rollback fetch --out payloads/ --lvfs --secureboot-objects
  72. dbx-rollback plan --factory-dbx factory-dbx.bin --target target-dbx.bin --payloads payloads/
  73. dbx-rollback kit --efivars efivars/ --factory-dbx factory-dbx.bin --target target-dbx.bin \
  74. --sequence payloads/A payloads/B ... --out kit/
  75. # On the locked PC: firmware setup, Secure Boot off, clear the Secure Boot keys, load the factory keys,
  76. # Secure Boot on. Then from the stick:
  77. sudo bash kit/rebuild.sh
  78. sudo bash kit/rebuild.sh verify # after one more reboot
  79. ```
  80. When `verify` prints **VERIFIED**, unplug the stick and start Windows. Then save the recovery key:
  81. `manage-bde -protectors -get C:` in an administrator prompt.
  82. ## Safety
  83. - Nothing here writes to the encrypted drive or the TPM. The kit writes one firmware variable, dbx.
  84. - Never use **Clear TPM** or a firmware option that resets security settings (on HP: *Restore Security settings to
  85. Factory Defaults*). That destroys the TPM protector, and with it this route.
  86. - Clearing the Secure Boot keys is only safe when the firmware can load its factory keys afterwards. On the HP
  87. this was built on, *Load HP Factory Default Keys* becomes selectable only after *Clear All Secure Boot Keys*.
  88. - The recovery key always still works. Nothing in this process can stop it from working.
  89. ## No Microsoft binaries
  90. This repository ships code only. Signed dbx updates are downloaded by `fetch` from their public homes (LVFS,
  91. `microsoft/secureboot_objects`, the Microsoft Update Catalog), and `msdelta.dll` comes from a Windows installation you
  92. own. Tests use synthetic data.
  93. ## With an AI agent
  94. The repository is a Claude Code plugin: `claude plugin install` it from this repository, and its skill walks an
  95. agent through the analysis with the same stop rules. `dbx-rollback guide` prints the full manual for any agent.
  96. ## Install
  97. Python 3.14 or later. `uv tool install bitlocker-dbx-rollback` or `pipx install bitlocker-dbx-rollback`. `fetch
  98. --lvfs` needs `zstd`; the Windows update steps need `wine` and `cabextract`.
  99. `dbx-rollback man --install` makes `man dbx-rollback` work. The source is [`docs/MANUAL.md`](https://github.com/jpsanders/bitlocker-dbx-rollback/blob/main/docs/MANUAL.md).
  100. ## Develop
  101. ```sh
  102. make init-dev
  103. make checks
  104. ```
  105. `make checks` runs isort, black, editorconfig-checker, darglint, flake8, mypy in strict mode, bandit, the man page
  106. check and pytest, the same as CI. See [CONTRIBUTING.md](https://github.com/jpsanders/bitlocker-dbx-rollback/blob/main/CONTRIBUTING.md)
  107. and [AGENTS.md](https://github.com/jpsanders/bitlocker-dbx-rollback/blob/main/AGENTS.md).
  108. ## Star history
  109. <a href="https://star-history.com/#jpsanders/bitlocker-dbx-rollback&Date">
  110. <picture>
  111. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=jpsanders/bitlocker-dbx-rollback&type=Date&theme=dark">
  112. <img alt="Star history of jpsanders/bitlocker-dbx-rollback" src="https://api.star-history.com/svg?repos=jpsanders/bitlocker-dbx-rollback&type=Date">
  113. </picture>
  114. </a>
  115. ## Licence
  116. MIT. Made by [James Phillip Sanders](https://jamesphillipsanders.com).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.