# PSPTool and the AMD firmware blobs that hide in UEFI padding volumes

> PSPTool parses, extracts and replaces AMD Secure Processor firmware inside UEFI images, working on the padding volume content that UEFITool cannot parse. It is aimed at firmware researchers and platform engineers who need to look inside AMD BIOS updates.

**PSPReverse/PSPTool** — Display, extract, and manipulate PSP firmware inside UEFI images

- Repository: https://github.com/PSPReverse/PSPTool
- Stars: 716 · Forks: 76
- Language: Python
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/pspreverse-psptool

## The AMD blobs that sit in padding volumes

A vendor BIOS update for an AMD machine is usually a 16MB, 8MB or 32MB UEFI firmware image. A generic tool such as UEFITool parses that image comfortably, but the README makes a narrower point that matters in practice: every binary blob AMD packs sits in a padding volume that UEFITool cannot parse. The result is that the interesting half of the image, the AMD Secure Processor content, is visible to nobody using the standard tool. PSPTool exists to close that gap. It targets the Platform Security Processor, also called the AMD Secure Processor or ASP, and its job is to parse, extract and replace the AMD firmware inside those otherwise opaque volumes.

That framing also sets the audience. The project comes out of security research at TU Berlin, and the README lists talks and papers on fault injection against AMD Secure Encrypted Virtualization, on exposing AMD fTPM secrets, and on regaining control over an AMD CPU. This is a tool for people who need to know what is inside a firmware image, not a tool for people who want a working BIOS. Nothing in the documentation describes flashing, writing a modified image back to a device, or bypassing a signature check, and the absence is worth noticing before you plan a workflow around it.

## Directory tables, magic values and the $PSP root

The mechanism is a proprietary AMD filesystem that packs firmware blobs into a firmware image, and PSPTool is built on reverse engineering efforts into how that filesystem is laid out. Concretely, the tool walks a directory structure rather than scanning for byte patterns. The listing of a ThinkPad T495 image in the README shows a top-level ROM entry with an address and size, then a directory table whose Type column carries the magic value $PSP and whose Secondary Directory column points at another table. A second directory appears below with the magic $PL2, marked as a secondary directory.

From the $PSP directory the tool enumerates entries, and each entry has its own address, size, a type name with a numeric identifier, a magic or ID field, a version, and an Info column. The type names are the payload kinds: a bootloader, a recovery bootloader, an SMU firmware entry, an off-chip firmware entry, and a run of ABL entries numbered zero through seven. An entry carrying $PS1 with an Info value of verified and encrypted is signed and encrypted at the source, and a version string such as A.2.3.27 is carried through the listing rather than inferred.

The practical takeaway is that PSPTool gives you a typed, addressed inventory of the AMD filesystem. You can point at a specific blob by address and size instead of hunting for it by pattern.

## Installing from PyPI and listing a BIOS image

The quickest start is the packaged release on PyPI, installed with pip3:

```bash
pip3 install psptool
```

If you would rather track the source tree, clone the repository and install it from the checkout:

```bash
git clone https://github.com/PSPReverse/PSPTool
cd PSPTool
pip3 install .
```

The documentation also covers the editable install, which is the one to pick if you plan to change the code and want your installation to follow the working tree:

```bash
pip3 install -e .
```

The console entry point is named psptool, and pointing it at a BIOS image lists its firmware entries. The README runs it against a ThinkPad ROM:

```bash
$ psptool Lenovo_Thinkpad_T495_r12uj35wd.iso
```

What you should see is the table structure described above: a ROM row with the image address and size and an AGESA version, a $PSP directory table, a $PL2 secondary directory, and the per-entry listing with type names, magic values, versions and the Info column. If the output is empty or shows no PSP directory, the image you supplied is not laid out the way the tool expects, which is a reasonable first thing to check before assuming the parsing is broken. No extra flags are needed for a first listing, and the README documents no configuration file or environment variable.

## Encrypted and compressed entries are listed, not opened

The listing is where this project stops short of what some readers expect. Entries marked compressed are shown as compressed, and entries marked encrypted are shown as encrypted, and the Info column of a signed entry carries a parenthetical key reference such as verified(60BB). The tool reports that state; the documentation does not claim to unwrap or decrypt those payloads.

That is a real limit for anyone hoping to read the contents of the AMD root key or an SMU firmware image directly. A researcher can enumerate what is present, note addresses and sizes, and identify which pieces are signed, but reading the bytes inside an encrypted entry is a different task that PSPTool does not document performing.

The dependency list explains part of the design. The package requires cryptography at version 38.0.0 or later and prettytable, and the latter is what produces the bordered tables seen in the output. A crypto library in the dependency set suggests signature and verification related work is in scope, but it is not evidence that encrypted firmware is decrypted. Treating the Info column as metadata about the image, rather than as a decrypted view of the payload, keeps expectations aligned with what the documentation actually shows.

## Getting the ROM before you parse it

PSPTool works with UEFI images as they come out of BIOS updates, so obtaining the image is the first practical obstacle. The README notes that when an update is distributed only as a Windows executable, a tool such as innoextract can help pull the image out. That workflow has a clear order: acquire the vendor update, extract the UEFI image if it is wrapped in an installer, then run psptool against that image.

The size expectations are specific enough to be worth stating: these images are usually 16MB, 8MB or 32MB. If what you have in hand is a different shape, the parsing output is not a reliable signal about the tool. The same caution applies to the model and platform in the sample listing. The example is a Lenovo ThinkPad T495 image, and the AGESA version shown there belongs to that platform, so it should not be read as the expected value for any other machine.

## Integration tests need a private submodule of ROM files

One line in the installation section is easy to skim and then important later. The integration tests require ROM files from a private submodule located at tests/integration/fixtures, and the documentation says to contact the maintainers to get access. In other words, cloning the repository does not give you a self-contained test suite, and the repository does contain a .gitmodules entry alongside a tests directory.

This has a direct effect on how you evaluate the project. You can install the tool and exercise it against images you already have, but you cannot reproduce the maintainers' integration coverage without that fixture set. If a change you make touches parsing behaviour, your feedback loop is your own set of images, and the confidence that comes from the original fixtures is unavailable to you until access is granted.

The distinction between unit-level confidence and fixture-backed confidence also applies to reverse engineering work in general. A parser that handles a known image is evidence about that image, and the fixtures are precisely what would tell you how it behaves across a wider range.

## Packaging, versioning and the cost of tracking the tool

The build system is Hatchling with Hatch VCS for version derivation, and the package targets Python 3.8 and later. The console script maps to psptool.__main__:main, and the package name on PyPI is psptool while the project name is PSPTool. Two dependencies and a light build configuration keep the upgrade surface small, which matters for a tool that has to keep pace with a vendor format that AMD is free to change.

Version numbers come from the VCS tags rather than a hardcoded field, and the recent release list shows version 3.7 dated 2026-10-02, with the last push recorded on 2026-10-09. The repository is not archived, so the project is being worked on and the release is recent rather than historical.

Licensing is GPL-3.0. That is a permissive-enough licence for reading, modification and redistribution of derived work, with the usual copyleft obligations attached to distributing the code itself. Anyone embedding PSPTool in a larger pipeline should read the licence text and check how that fits their own distribution. The repository lists a LICENSE file, so the terms are available in full at the checkout.

## Conclusion

Adopt PSPTool if your work touches AMD platform firmware and you need to read the PSP directory tree inside a vendor BIOS image; it is a research tool, not a flashing utility, and it does not decrypt signed or encrypted blobs. Skip it if you only need a general UEFI volume dump, where UEFITool already does the job, or if you need to install ROM fixture files for the integration tests without contacting the maintainers. Before relying on a modified image, check the dependency list in pyproject.toml against your Python version, confirm the magic values and directory addresses in a listing against the vendor image, and treat every entry marked verified as evidence about the image, not proof that a payload you extract will boot.

## FAQ

### What does PSPTool do that UEFITool cannot?

UEFITool can parse UEFI firmware images generally, but the README states that all binary blobs packed by AMD are located in padding volumes that UEFITool cannot parse. PSPTool parses, extracts and replaces the AMD PSP firmware inside those volumes.

### How do I install PSPTool and run it against a BIOS image?

Install the packaged release with pip3 install psptool, or clone the repository and run pip3 install . from the checkout, then point the psptool command at an image. The README example runs psptool against Lenovo_Thinkpad_T495_r12uj35wd.iso and prints the ROM, directory and entry tables.

### Can PSPTool decrypt the encrypted PSP firmware entries it lists?

The listing reports entries as compressed or encrypted and carries version and key reference information such as verified(60BB), but the documentation does not describe decrypting those payloads. It presents the state of each blob rather than its unwrapped contents.

### Why are the PSPTool integration tests not runnable after cloning?

The integration tests require ROM files from a private submodule at tests/integration/fixtures, and the README says to contact the maintainers to get access. A fresh clone therefore gives you the tool but not the fixture set the original test suite relies on.

### How do I extract a UEFI image from a vendor BIOS update that ships as a Windows executable?

The README notes that when BIOS updates are only available through Windows executables, tools such as innoextract can help. The expected images are usually 16MB, 8MB or 32MB UEFI firmware images.

## Sources

- [Issues](https://github.com/PSPReverse/PSPTool/issues)
- [License: GPL-3.0](https://github.com/PSPReverse/PSPTool/blob/master/LICENSE)
- [PSPReverse/PSPTool on GitHub](https://github.com/PSPReverse/PSPTool)
- [README](https://github.com/PSPReverse/PSPTool/blob/master/README.md)
- [Releases](https://github.com/PSPReverse/PSPTool/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pspreverse-psptool