Firmware Analysis

Firmware security and vulnerability scanning commands.

Binarly

The Binarly test step executes a scan using the Binarly service to analyze firmware binaries. For more information, visit Binarly Risk Hunt.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	binarly	Must be `binarly report`
`name`	`string`	Yes		Uniquely identifies the test step in reports and logs
`parameters`	`BinarlyParameters`	Yes		Binarly-specific parameters
`options`	`OptionsObject`	No		Additional command options

Binarly Parameters

Attribute	Type	Required	Description
`token`	`string`	Yes	Authentication token for Binarly service
`file_path`	`string`	Yes	Path to the binary file to be scanned

Binarly Example

cmd: binarly report
name: "Scan BIOS for vulnerabilities"
parameters:
  token: "your-binarly-token"
  file_path: "/path/to/firmware.bin"
options:
  timeout: "10m" # Scan might take a while

ChipSec

Run ChipSec on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`chipsec`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	No		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`ChipSecOptions`	Yes		Options passed into ChipSec

ChipSec Options

Attribute	Type	Required	Description
`modules`	`[]string`	Yes	List of modules that get executed from the `ChipSec` test suite
`pch`	`string`	No	PCH parameter that gets passed into `ChipSec` as `--pch` parameter
`platform`	`string`	No	Platform parameter that gets passed into `ChipSec` as `--platform` parameter

ChipSec Example

cmd: chipsec
name: Run chipsec tests
transport:
  proto: ssh
  options:
    host: "[[attributes.Host]]"
    user: root
    password: root
parameters:
  modules:
    [
      common.bios_kbrd_buffer,
      common.bios_smi,
      common.bios_ts,
      common.bios_wp,
      common.ia32cfg,
      common.me_mfg_mode,
      common.memlock,
      common.rtclock,
      common.smm,
      common.smrr,
      common.spi_access,
      common.spi_desc,
      common.spi_fdopss,
      common.spi_lock,
      common.uefi.access_uefispec,
      common.memconfig,
      common.remap,
      common.smm_dma,
    ]

Firmware Version

Check the ESRT Firmware version entry on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`firmware version`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`FirmwareVersionOptions`	Yes		Options passed into the `firmware version` cmd

Firmware Version Options

Attribute	Type	Required	Default	Description
`format`	`string`	No	`number`	Format of the tool’s output. Available options: `number`, `hex`, `pair`, `triplet`, `quad`.
`expect`	`Firmware Version Expect Options`	Yes		Expected Options

Firmware Version Expect Options

Attribute	Type	Required	Default	Description
`version`	`string`	Yes	`expect`	Expected firmware version in the specified format.

Firmware Version Example

cmd: firmware version
name: Get firmware version (ESRT)
transport: *transport
parameters:
  format: pair
  expect:
    version: "1.11"

FWHunt

Run Firmware Hunt on the firmware binary file.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`fwhunt`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`options`	`OptionsObject`	No		Additional command options
`parameters`	`FWHuntOptions`	Yes		Options passed into the `fwhunt` cmd

FWHunt Options

Attribute	Type	Required	Default	Description
`path`	`string`	Yes		Path of the binary to be analyzed.
`rules_dirs`	`[]string`	No		List of directories to search for rules. If not specified, the default rules directory will be used.
`rules`	`[]string`	No		List of rules to run.
`report_only`	`boolean`	No	`false`	Only report findings, do not interpret the output.

FWHunt Example

name: FwHunt Test
steps:
  - cmd: fwhunt
    name: Run FwHunt tests
    parameters:
      path: "[[input.Binary]]"
      report_only: true

FWTS

Run Firmware Test-Suite on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`fwts`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options
`options`	`OptionsObject`	No		Additional command options
`parameters`	`FWTS Options`	Yes		Options passed into the `fwts` cmd

FWTS Options

Attribute	Type	Required	Default	Description
`flags`	`[]string`	No		List of flags to pass to `fwts`.
`report_only`	`boolean`	No	`false`	Only report findings, do not interpret the output.

FWTS Example

cmd: fwts
name: Run Firmware Testsuite tests
options:
  timeout: 10m
transport: *transport
parameters:
  flags: [-b]
  report_only: true

HSI

Report Host Firmware Security on the DUT.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`hsi`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`transport`	`TransportObject`	Yes		Additional transport options

HSI Example

cmd: hsi
name: Report Host Firmware Security
options:
  timeout: 10m
transport: *transport