CHIPSEC is a framework for analyzing the security of PC platforms, including their hardware, BIOS, and platform configuration.  It includes a security test suite, security assessment tools for various low level components/interfaces, and basic forensic capabilities for firmware.  CHIPSEC can run from Windows, Linux, and the UEFI Shell.

CHIPSEC began its life as an internal Intel tool.  As the tool matured and grew in utility, Intel released it as open source, available on Github.  Anyone can download it and run it on any UEFI-based system.

CHIPSEC Architecture

CHIPSEC is a Python-based set of tools that depend upon an OS-specific helper layer to talk to the system hardware.  CHIPSEC is really two tools in one:
  1. chipsec_main.py:  An automated test suite that scans for typical security vulnerabilities, such as SMI implementation mistakes, BIOS write protection, SMRAM protection, correct SMRR programming, SPI flash region access control, Secure Boot variable protection, UEFI variable access control, S3 resume boot script protection, memory remapping lock, and TSEG range configuration.  This automated test suite is similar in form to something like the SCT or FWTS.
  2. chipsec_util.py:  a collection of many various commands for examining the BIOS and hardware.  These commandlets are not necessarily security-related—they can be of great benefit in a variety of BIOS debugging scenarios.  An abbreviated run-down of what’s possible:
    • chipsec_util acpi table <name>|<file_path>
    • chipsec_util cmos readl|writel|readh|writeh <byte_offset> [byte_val]
    • chipsec_util cpu info
    • chipsec_util cpu cr <cpu_id> <cr_number> [value]
    • chipsec_util idt|gdt|ldt [cpu_id]
    • chipsec_util nmi
    • chipsec_util smi <thread_id> <SMI_code> <SMI_data> [RAX] [RBX] [RCX] [RDX] [RSI] [RDI]
    • chipsec_util io <io_port> <width> [value]
    • chipsec_util iommu status [iommu_engine]
    • chipsec_util mem <op> <physical_address> <length> [value|buffer_file]
    • chipsec_util mmio read <MMIO_BAR_name> <offset> <width>
    • chipsec_util msr <msr> [eax] [edx] [cpu_id]
    • chipsec_util pci <bus> <device> <function> <offset> <width> [value]
    • chipsec_util smbus read <device_addr> <start_offset> [size]
    • chipsec_util spi info|dump|read|write|erase|disable-wp [flash_address] [length] [file]
    • chipsec_util uefi var-find <name>|<GUID>
image
Obligatory CHIPSEC architectural diagram


Installation

Unfortunately, installation is not 100% straightforward; the installation documentation could be better.  Some steps are implied but not explicitly explained, and installation steps are mixed between the manual and Readme text files.  Fortunately, you are a reader of BasicInputOutput.com!  Therefore, you can benefit from all the pain I went through!
Here is the method I used to setup a USB flash drive for the use of CHIPSEC in either the UEFI shell or 64-bit Windows 7:
  1. Format a USB flash drive as FAT32
  2. Create a root directory \EFI, with a sub-directory boot
  3. In EFI\boot, place a UEFI shell executable with filename BOOTX64.EFI
  4. Create a root directory \chipsec
  5. From the CHIPSEC Github page, click the Download ZIP button:image
  6. After downloading chipsec-master.zip, extract the directory source to the USB flash drive’s \chipsec directory created previously
  7. From chipsec-master.zip, open the nested .ZIP file __install__\UEFI\chipsec_uefi_x64.zip
    1. Extaract the StdLib and Tools directories from the efi directory in the .ZIP file to the \EFI directory on your USB flash drive
  8. At this point, your USB flash drive should look like:
    image
  9. To build the Windows 7 64-bit helper driver, direct your attention to the file \chipsec\source\drivers\win7\readme
    1. Install the Windows Driver Kit 7600.16385.1
    2. Open CMD.EXE with Administrator privileges
    3. CD to C:\WinDDK\7600.16385.1\bin
    4. Setup the environment by running:
      setenv.bat C:\WinDDK\7600.16385.1 fre x64
    5. CD to your USB flash drive:
      \chipsec\source\drivers\win7
    6. run build –cZg.  You should see:
      image
  10. Now you need to digitally sign the driver:
    1. While still on the USB flash drive in the \chipsec\source\drivers\win7 directory type:
      makecert -r -n "CN=Chipsec" -ss ChipsecCertStore -sr LocalMachine
    2. CD sign
    3. run the batch file sign64_sys.bat
    4. copy the driver chipsec_hlpr.sys to:
      \chipsec\source\tool\chipsec\helper\win\win7_amd64
  11. Now you need to setup Windows by turning off kernel signed driver checks
    1. Open CMD.EXE with Administrator privileges
    2. run BcdEdit /set TESTSIGNING ON
    3. reboot
  12. Install Python 2.7.x and pywin32 to get Python support in Windows.  I used the following binaries:
    python-2.7.11.amd64.msi
    pywin32-220.win-amd64-py2.7.exe
Wow, can you believe it?  That’s what it takes to get CHIPSEC installed!!!  Don’t worry, it’s worth it.

To use CHIPSEC from within the UEFI shell, just do a UEFI boot to the USB flash drive.  Since we named the shell using the canonical BOOTX64.EFI filename, the BIOS should automatically find it.  Mount the file system (e.g. fs1:) representing your removable USB flash drive and you’re ready to go.

To use CHIPSEC from within Windows 7, just boot to Windows and open CMD.EXE as an Administrator.

Documentation

The CHIPSEC documentation can be found in the chipsec-master.zip file that you downloaded from Github.  Look for the file chipsec-manual.pdf in the root of the .ZIP file.

Running CHIPSEC

CHIPSEC_MAIN.PY

Running the automated test suite is easy.  To run the automated security tests, CD into \chipsec\source\tool and run:
python chipsec_main.py

There are several command-line options accepted by the tool.  For example, you can turn on verbose mode, create a log file, and more.  I won’t reproduce all the options here—see chipsec-manual.pdf.

I ran the test suite on an Intel Broadwell-based system.  The test took mere seconds to run.  Look here to see the log.  This should give you a better understanding of what the tool does so that you can determine if these kinds of tests are valuable to you. (hint:  they should be!)

CHIPSEC_UTIL.PY

The basic form of the utility command is:
python chipsec_util.py <command> <sub-command> <options>

I made only a brief list of the various commands above.  Refer to the manual chipsec-manual.pdf for more information on all the commands, sub-commands, and options.  After looking over the supported functionality, you will be able to decide for yourself how CHIPSEC can help you in whatever development effort you’re attempting.

An Alternative Way of Running CHIPSEC

CHIPSEC is included in the Linux UEFI Validation project (luvOS) test suite.  As of this writing, the latest version of luvOS is v2.0, released 1 Apr 2016, and it contains CHIPSEC v1.2.2.  The luvOS live image can be downloaded from:
https://01.org/linux-uefi-validation/downloads

The advantage here is that you simply burn the live image to a USB flash drive, boot to it, and luvOS will automatically run not only CHIPSEC’s chipsec_main.py, but also the Firmware Test Suite (fwts) and the Intel BIOS Implementation Test Suite (BITS).  Less work for you, and three times the testing!

Advanced Topics

There are more advanced usages of CHIPSEC, for example you can use CHIPSEC from within a Python shell, you can compile the tool into a Windows .EXE, and you can even write your own CHIPSEC modules.  See the chipsec-manual.pdf for more information on these advanced topics.

Resources

I hope you derived benefit in this introduction to CHIPSEC.  Here are some additional resources you might find helpful:

Post a Comment

  1. Thanks, this blog is really helpful, the manual is not very straight fwd as you said.

    ReplyDelete
  2. work on windows 10?

    ReplyDelete
    Replies
    1. Yes, it ran fine for me on Win10. Just remember to install Python, plus turn TESTSIGNING on, as described above. If you do that, chipsec_hlpr.sys will work equally well on Win10 as Win7.

      Delete
  3. how do i set uefi shell for the EFI/boot directory? i could not make it work well

    ReplyDelete
    Replies
    1. You create a directory on your boot device called "EFI", then create inside it a subdirectory called "boot". Then you put your EFI Shell in "boot", and give it the name bootx64.efi. UEFI will automatically detect this and allow you to boot to it.

      Delete
    2. How can i install the uefi Shell?

      Delete
    3. This comment has been removed by the author.

      Delete
    4. I finally got Chipsec running from a USB drive!

      I downloaded an open source EFI shell that was recommended elsewhere in the ChipSec github directory. Copied it to the USB boot folder and renamed it bootx64.efi.

      https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2/EdkShellBinPkg/FullShell/X64/Shell_Full.efi

      Had no luck running from Windows.

      Delete
  4. hi,
    Can use win10 wdk build chipsec_hlpr.sys?

    ReplyDelete
  5. I keep getting an error running the chipsec_main.py script.

    File "chipsec_main.py, line 36
    print "%-35s _> %s" % (caller.f_globals.get('__name__'), name)

    SyntaxError: invalid syntax

    I've even tried downgrading from Python 3.5 to 2.7 with no luck.

    The instructions also threw me off a bit, there is no subdirectory within tools with \tool\chipsec\helper\win\win7_amd64. The Helper\win folder is within the main chipset directory. There was also no Win7_AMD folder created after the build process.

    My girlfriend is going to kill me :) Followed both Intel and your instructions, so far without any luck. The same Syntax error coming up when I run the script.

    ReplyDelete

Be sure to select an account profile (e.g. Google, OpenID, etc.) before typing your comment!