Security Skills Atlas
hardware firmware security

Auditing UEFI Firmware with CHIPSEC

Use Intel CHIPSEC to assess platform firmware configuration, SPI flash write protection, BIOS lock, SMM/SMRR, and Secure Boot variable state, dump SPI flash, and triage UEFI variables for firmware-level threats.

bios-write-protectionchipsecfirmware-assessmenthardware-firmware-securityplatform-securitysecure-bootspi-flashuefi
Install this skill
npx skills add mukul975/Anthropic-Cybersecurity-Skills
Framework mappings

MITRE ATT&CK

T1542.001 on the official MITRE ATT&CK site

NIST CSF 2.0

ID.AM-02 on the official NIST CSF 2.0 site

Authorized Use Only: CHIPSEC loads a kernel driver and reads/writes low-level hardware registers, SPI flash, and SMM. Run it only on systems you own or are explicitly authorized to assess, ideally on dedicated test hardware. Misuse (especially write/modify modules) can brick a machine. Never run write-capable modules on production systems.

Overview

CHIPSEC is the open-source Platform Security Assessment Framework created by Intel's Advanced Threat Research team. It inspects the low-level security configuration of x86 platform firmware and hardware — the layer below the operating system where bootkits and firmware implants live. CHIPSEC loads a signed kernel driver (Linux, Windows, or it can run from the UEFI shell) to read and write hardware registers, Model-Specific Registers (MSRs), PCI config space, SPI flash, and UEFI variables, then runs an automated test suite that checks whether the platform's defensive locks are actually engaged.

The threat CHIPSEC addresses is MITRE ATT&CK T1542.001 — Pre-OS Boot: System Firmware: adversaries who modify system firmware (the BIOS/UEFI image on SPI flash) to gain stealthy, persistent, OS-survivable control. Firmware implants persist across OS reinstall and disk replacement and are invisible to most EDR. CHIPSEC's value is verifying the prerequisites that prevent such implants: that the SPI flash BIOS region is write-protected (BIOS_CNTL BLE/SMM_BWP, SPI Protected Ranges), that the flash descriptor locks region access, that SMRAM/SMRR are configured, and that Secure Boot variables are protected. It also dumps the SPI flash for offline forensic comparison.

Sources: Intel/CHIPSEC project (https://github.com/chipsec/chipsec), CHIPSEC documentation (https://chipsec.github.io/).

When to Use

  • Baseline firmware-security assessment of a new laptop/server platform or fleet image
  • Verifying that BIOS write protection and SPI flash locks are correctly enabled by the OEM
  • Firmware forensics: dumping SPI flash to compare against a known-good image
  • Validating Secure Boot variable protection and S3 boot-script protection
  • Hunting for evidence of a firmware implant or misconfiguration enabling one

Prerequisites

  • Physical or admin/root access to the target x86 platform (Intel or AMD)
  • Linux (root) or Windows (Administrator), or a UEFI shell environment
  • Ability to load a kernel driver (Secure Boot may need to allow the CHIPSEC driver, or use --no_driver for limited checks)
  • Python 3.8+ and a C compiler/build tools for the kernel module on Linux
  • Dedicated test hardware strongly recommended

Install CHIPSEC:

# From PyPI
pip install chipsec
 
# Or from source (builds the kernel helper/driver)
git clone https://github.com/chipsec/chipsec
cd chipsec
python setup.py install        # builds and installs, including the Linux driver
 
# Verify
sudo chipsec_main --help
sudo chipsec_util --help

Objectives

  • Run the full automated platform-security test suite and interpret PASS/FAIL/WARNING
  • Verify BIOS write protection (BIOS_CNTL) and SPI Protected Ranges
  • Verify the SPI flash descriptor locks region read/write access
  • Verify SMRAM/SMRR and SMI handler protections
  • Verify Secure Boot variable protection and S3 boot-script protection
  • Dump SPI flash and decode it for offline analysis
  • Enumerate UEFI variables and detect anomalous/unexpected entries

MITRE ATT&CK Mapping

Technique ID Name Tactic
T1542.001 Pre-OS Boot: System Firmware Persistence / Defense Evasion

CHIPSEC defends against T1542.001 by verifying that the controls preventing unauthorized firmware modification are enabled. A FAIL on common.bios_wp (BIOS not write-protected) or chipsec.modules.common.spi_lock (flash descriptor unlocked) means an attacker with OS privileges could rewrite the SPI flash and implant persistent firmware — exactly the precondition for this technique.

Workflow

Step 1: Run the full automated test suite

chipsec_main with no module argument runs every applicable security check for the detected platform and prints a summary of PASS/FAIL/WARNING/INFORMATION results.

sudo chipsec_main
 
# Save machine-readable output for reporting / diffing
sudo chipsec_main -j results.json -x results.xml -l chipsec.log

Step 2: Run the core firmware-protection modules individually

The common module group contains the OEM-independent security checks. Run the group or specific modules:

# Run the whole common group
sudo chipsec_main -m common
 
# BIOS write protection: checks BIOS_CNTL BLE/SMM_BWP and SPI protected ranges
sudo chipsec_main -m common.bios_wp
 
# SPI flash descriptor lock (FLOCKDN) — are flash region accesses locked?
sudo chipsec_main -m common.spi_lock
 
# SMRR programming — protects SMRAM from cache-based attacks
sudo chipsec_main -m common.smrr
 
# SMM BIOS write protection
sudo chipsec_main -m common.smm
 
# S3 resume boot-script protection (against bootscript table attacks)
sudo chipsec_main -m common.uefi.s3bootscript

Step 3: Verify Secure Boot variable protection

# Checks that Secure Boot UEFI variables are properly protected
sudo chipsec_main -m common.secureboot.variables
 
# To actively test write protection of the variables (test hardware ONLY):
sudo chipsec_main -m common.secureboot.variables -a modify

Step 4: Inspect SPI flash region access permissions

# Report SPI flash regions, descriptor, and access permissions
sudo chipsec_util spi info
 
# Check the SPI access-control module
sudo chipsec_main -m common.spi_access

Step 5: Dump SPI flash for offline forensics

Dumping the flash lets you decode the firmware volumes and compare against a known-good OEM image.

# Dump the entire SPI flash to a file
sudo chipsec_util spi dump rom.bin
 
# Decode the dumped image: extracts firmware volumes, files, NVRAM variables, etc.
sudo chipsec_util decode rom.bin

Step 6: Enumerate and triage UEFI variables

# List all UEFI variables from the runtime interface
sudo chipsec_util uefi var-list
 
# List variables directly from the SPI image (offline)
sudo chipsec_util uefi var-find PK
sudo chipsec_util uefi var-read db <GUID> db.bin
 
# Decode the UEFI firmware structure
sudo chipsec_util uefi decode rom.bin

Step 7: Limited assessment without a kernel driver

Where loading the driver is impossible (locked-down Secure Boot), some checks still run read-only.

sudo chipsec_main -n            # --no_driver: skip checks that need the driver
sudo chipsec_main -p <PLATFORM> # force platform code if auto-detect fails

Step 8: Triage results and report

  • FAIL on bios_wp / spi_lock → firmware is rewritable from the OS: high risk for T1542.001.
  • FAIL on secureboot.variables → Secure Boot policy can be tampered.
  • Compare the spi dump against the OEM's known-good image (hash firmware volumes) to detect unauthorized modification.
  • Record platform, BIOS version, and every FAIL/WARNING with the relevant register values for the report.

Tools and Resources

Tool Purpose Source
chipsec_main Automated platform-security test suite https://github.com/chipsec/chipsec
chipsec_util Manual hardware/firmware access (spi, uefi, decode) https://chipsec.github.io/
UEFITool GUI/CLI parsing of dumped UEFI images https://github.com/LongSoft/UEFITool
Binarly fwhunt Firmware vulnerability/implant hunting rules https://github.com/binarly-io/fwhunt-scan
NSA UEFI Secure Boot guidance Hardening reference https://media.defense.gov/

Core Module Reference

Module Checks
common.bios_wp BIOS_CNTL BLE / SMM_BWP and SPI Protected Ranges
common.spi_lock SPI flash descriptor FLOCKDN
common.spi_access SPI flash region read/write permissions
common.smrr System Management Range Registers programming
common.smm SMM BIOS write protection
common.secureboot.variables Secure Boot variable protection
common.uefi.s3bootscript S3 resume boot-script protection

Validation Criteria

  • CHIPSEC installed and driver loads (or -n documented if not)
  • Full chipsec_main suite executed with JSON/XML/log output saved
  • common.bios_wp result interpreted (write protection state)
  • common.spi_lock / spi_access result interpreted (descriptor lock)
  • SMRR/SMM module results recorded
  • Secure Boot variable protection checked
  • SPI flash dumped and decoded for offline analysis
  • UEFI variables enumerated and triaged
  • All FAIL/WARNING findings documented with platform/BIOS version
  • Write/modify modules NOT run on production hardware
Source materials

References and resources

Everything below is rendered for inspection. Script files are read-only and never run.

References 2

api-reference.md2.3 KB

Command Reference - CHIPSEC

chipsec_main (test suite)

Command / Flag Purpose
chipsec_main Run all applicable security modules for the platform
-m, --module <name> Run a specific module, e.g. -m common.bios_wp
-m common Run the whole OEM-independent module group
-mx <modules> Exclude listed modules
-a, --module_args Pass arguments to a module (e.g. -a modify)
-p, --platform <code> Force platform code when auto-detect fails
-n, --no_driver Skip checks requiring the kernel driver
-l, --log <file> Write output to a log file
-j, --json <file> JSON results output
-x, --xml <file> JUnit-style XML results output
-v / -vv / -d Verbose / very verbose / debug logging

Key security modules

Module Checks
common.bios_wp BIOS_CNTL BLE / SMM_BWP and SPI Protected Ranges
common.spi_lock SPI flash descriptor FLOCKDN lock
common.spi_access SPI flash region access permissions
common.smrr SMRR programming (SMRAM cache protection)
common.smm SMM BIOS write protection
common.secureboot.variables Secure Boot variable protection (-a modify to test writes)
common.uefi.s3bootscript S3 resume boot-script protection

chipsec_util (manual access)

Command Purpose
chipsec_util spi info Report SPI flash regions/descriptor/permissions
chipsec_util spi dump rom.bin Dump entire SPI flash to file
chipsec_util spi read <addr> <len> out.bin Read SPI flash range
chipsec_util decode rom.bin Decode dumped image into volumes/files/variables
chipsec_util uefi var-list List UEFI variables (runtime)
chipsec_util uefi var-find <name> Find a UEFI variable
chipsec_util uefi var-read <name> <GUID> out.bin Read a variable
chipsec_util uefi decode rom.bin Decode UEFI firmware structure from image
chipsec_util platform Show detected platform info

Result interpretation

Result Meaning
PASSED Protection is correctly enabled
FAILED Protection missing/misconfigured — exploitable
WARNING Potential issue / needs manual review
INFORMATION Informational, no pass/fail
standards.md1.4 KB

Standards and References - Auditing UEFI Firmware with CHIPSEC

MITRE ATT&CK

Technique ID Name Tactic Rationale
T1542.001 Pre-OS Boot: System Firmware Persistence / Defense Evasion CHIPSEC verifies the SPI flash and BIOS write-protection locks whose absence enables adversaries to modify system firmware for stealthy, OS-survivable persistence.

NIST Cybersecurity Framework 2.0

ID Name Rationale
ID.AM-02 Inventories of software, services, and systems managed by the organization are maintained Firmware version, SPI flash image, and platform-security configuration are part of the asset/software inventory that CHIPSEC enumerates and baselines.

Official Resources

Key Research

  • Intel ATR: original CHIPSEC framework and BlackHat arsenal presentations
  • "Exploring Your System Deeper with CHIPSEC" (CSW)
  • NSA UEFI Secure Boot Customization / firmware hardening guidance

Scripts 1

agent.py4.3 KB
Display-only source. This catalog never executes bundled scripts.
#!/usr/bin/env python3
"""
chipsec-audit — run a CHIPSEC firmware-posture baseline and parse results.

Wraps the real CHIPSEC CLIs:
  - chipsec_main : module runner
  - chipsec_util : SPI/UEFI utilities
Project: https://github.com/chipsec/chipsec

Install:
    pip install chipsec     # needs root and a kernel driver build

Examples:
    sudo python agent.py baseline --log chipsec.log --json report.json
    sudo python agent.py module --name common.bios_wp
    sudo python agent.py dump --out rom.bin
"""
import argparse
import json
import os
import re
import shutil
import subprocess
import sys

# CHIPSEC prints lines like:  [+] PASSED: BIOS region write protection ...
RESULT_RE = re.compile(r"\[[+\-!*]\]\s*(PASSED|FAILED|WARNING|ERROR|NOT APPLICABLE|INFORMATION)\b[:\s]*(.*)",
                       re.IGNORECASE)

CORE_MODULES = [
    "common.bios_wp",
    "common.spi_lock",
    "common.spi_desc",
    "common.smm",
    "common.secureboot.variables",
]


def _require(tool: str) -> None:
    if shutil.which(tool) is None:
        sys.exit(f"error: '{tool}' not found on PATH. Install CHIPSEC: pip install chipsec")


def _warn_root() -> None:
    if hasattr(os, "geteuid") and os.geteuid() != 0:
        print("[!] warning: CHIPSEC needs root/Administrator to load its driver.", file=sys.stderr)


def _run(argv: list) -> subprocess.CompletedProcess:
    print(f"[*] {' '.join(argv)}", file=sys.stderr)
    return subprocess.run(argv, capture_output=True, text=True)


def parse_results(stdout: str) -> list:
    findings = []
    for line in stdout.splitlines():
        m = RESULT_RE.search(line)
        if m:
            findings.append({"result": m.group(1).upper(), "detail": m.group(2).strip()})
    return findings


def cmd_baseline(args) -> int:
    _require("chipsec_main")
    _warn_root()
    argv = ["chipsec_main"]
    if args.log:
        argv += ["-l", args.log]
    proc = _run(argv)
    findings = parse_results(proc.stdout)
    fails = [f for f in findings if f["result"] in ("FAILED", "ERROR")]
    warns = [f for f in findings if f["result"] == "WARNING"]
    summary = {
        "total_results": len(findings),
        "failed": len(fails),
        "warnings": len(warns),
        "failures": fails,
        "warning_items": warns,
    }
    if args.json:
        with open(args.json, "w", encoding="utf-8") as fh:
            json.dump({"summary": summary, "all": findings}, fh, indent=2)
        print(f"[+] report written to {args.json}", file=sys.stderr)
    print(json.dumps(summary, indent=2))
    return 1 if fails else 0


def cmd_module(args) -> int:
    _require("chipsec_main")
    _warn_root()
    targets = [args.name] if args.name else CORE_MODULES
    out = {}
    rc = 0
    for mod in targets:
        proc = _run(["chipsec_main", "-m", mod])
        res = parse_results(proc.stdout)
        out[mod] = res
        if any(r["result"] in ("FAILED", "ERROR") for r in res):
            rc = 1
    print(json.dumps(out, indent=2))
    return rc


def cmd_dump(args) -> int:
    _require("chipsec_util")
    _warn_root()
    _run(["chipsec_util", "spi", "info"])
    proc = _run(["chipsec_util", "spi", "dump", args.out])
    if proc.returncode != 0 or not os.path.exists(args.out):
        print("[!] SPI dump failed", file=sys.stderr)
        print(proc.stderr, file=sys.stderr)
        return 1
    size = os.path.getsize(args.out)
    print(json.dumps({"dump": args.out, "bytes": size}, indent=2))
    print("[*] decode offline with: chipsec_util uefi decode " + args.out, file=sys.stderr)
    return 0


def main() -> int:
    p = argparse.ArgumentParser(description="CHIPSEC firmware-posture audit helper.")
    sub = p.add_subparsers(dest="cmd", required=True)

    b = sub.add_parser("baseline", help="run full chipsec_main and summarize")
    b.add_argument("--log", help="CHIPSEC log file path")
    b.add_argument("--json", help="write parsed JSON report here")
    b.set_defaults(func=cmd_baseline)

    m = sub.add_parser("module", help="run one or the core security modules")
    m.add_argument("--name", help="specific module, e.g. common.bios_wp (default: core set)")
    m.set_defaults(func=cmd_module)

    d = sub.add_parser("dump", help="dump SPI flash (read-only)")
    d.add_argument("--out", default="rom.bin")
    d.set_defaults(func=cmd_dump)

    args = p.parse_args()
    return args.func(args)


if __name__ == "__main__":
    sys.exit(main())
Keep exploring
Detecting Secure Boot BypassDetect bootkits such as BlackLotus and Bootkitty and Secure Boot bypass via DBX and binary checks.Hunting Bootkits in the EFI System PartitionBaseline the EFI System Partition and hunt malicious EFI binaries (ESPecter, BlackLotus, Bootkitty, Glupteba) by mounting the ESP, hashing and verifying boot loaders, scanning with YARA, and detecting anomalous non-EFI files.Validating TPM Measured Boot and AttestationVerify TPM PCRs and measured-boot and remote-attestation integrity.Analyzing UEFI Bootkit PersistenceAnalyzes UEFI bootkit persistence mechanisms including firmware implants in SPI flash, EFI System Partition (ESP) modifications, Secure Boot bypass techniques, and UEFI variable manipulation. Covers detection of known bootkit families (BlackLotus, LoJax, MosaicRegressor, MoonBounce, CosmicStrand), ESP partition forensic inspection, chipsec-based firmware integrity verification, and Secure Boot configuration auditing. Activates for requests involving UEFI malware analysis, firmware persistence investigation, boot chain integrity verification, or Secure Boot bypass detection.Analyzing Bootkit and Rootkit SamplesAnalyzes bootkit and advanced rootkit malware that infects the Master Boot Record (MBR), Volume Boot Record (VBR), or UEFI firmware to gain persistence below the operating system. Covers boot sector analysis, UEFI module inspection, and anti-rootkit detection techniques. Activates for requests involving bootkit analysis, MBR malware investigation, UEFI persistence analysis, or pre-OS malware detection.Performing Firmware Malware AnalysisAnalyzes firmware images for embedded malware, backdoors, and unauthorized modifications targeting routers, IoT devices, UEFI/BIOS, and embedded systems. Covers firmware extraction, filesystem analysis, binary reverse engineering, and bootkit detection. Activates for requests involving firmware security analysis, IoT malware investigation, UEFI rootkit detection, or embedded device compromise assessment.