peter/spectre-meltdown-checker
1
0
Fork 0
mirror of https://github.com/speed47/spectre-meltdown-checker.git synced 2026-04-09 10:13:18 +02:00
Code Issues Projects Releases Wiki Activity

enh: better explain the 4 run modes

Browse Source
This commit is contained in:
Stéphane Lesimple
2026-04-08 20:53:50 +02:00
parent f1c0d5548c
commit 60ea669e41
2 changed files with 59 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
dist/README.md vendored
View File

@@ -238,6 +238,28 @@ What is the purpose of this tool? Why was it written? How can it be useful to me
All these questions (and more) have detailed answers in the [FAQ](FAQ.md), please have a look! All these questions (and more) have detailed answers in the [FAQ](FAQ.md), please have a look!
## Operating modes
The script supports four operating modes, depending on whether you want to inspect the running kernel, a kernel image, the CPU hardware, or a combination.
| Mode | Flag | CPU hardware | Running kernel | Kernel image | Use case |
|------|------|:---:|:---:|:---:|----------|
| **Live** *(default)* | *(none)* | Yes | Yes | auto-detect | Day-to-day auditing of the current system |
| **No-runtime** | `--no-runtime` | Yes | No | required | Check a different kernel against this CPU (e.g. pre-deployment) |
| **No-hardware** | `--no-hw` | No | No | required | Pure static analysis of a kernel image for another system or architecture |
| **Hardware-only** | `--hw-only` | Yes | No | No | Quickly check CPU affectedness without inspecting any kernel |
In **Live** mode (the default), the script inspects both the CPU and the running kernel.
You can optionally pass `--kernel`, `--config`, or `--map` to point the script at files it couldn't auto-detect.
In **No-runtime** mode, the script still reads the local CPU (CPUID, MSRs, microcode) but skips all running-kernel artifacts (`/sys`, `/proc`, `dmesg`).
Use this when you have a kernel image from another system but want to evaluate it against the current CPU.
In **No-hardware** mode, both CPU inspection and running-kernel artifacts are skipped entirely.
This is useful for cross-architecture analysis, for example inspecting an ARM kernel image on an x86 workstation.
In **Hardware-only** mode, the script only reports CPU information and per-CVE hardware affectedness, without inspecting any kernel.
## Running the script ## Running the script
### Direct way (recommended) ### Direct way (recommended)

82
src/libs/002_core_globals.sh
View File

@@ -3,68 +3,60 @@
show_usage() { show_usage() {
# shellcheck disable=SC2086 # shellcheck disable=SC2086
cat <<EOF cat <<EOF
Usage:
Live mode: $(basename $0) [options] [--kernel <kimage>] [--config <kconfig>] [--map <mapfile>]
No-runtime: $(basename $0) [options] --no-runtime <--kernel <kimage>> [--config <kconfig>] [--map <mapfile>]
No-hw: $(basename $0) [options] --no-hw <--kernel <kimage>> [--config <kconfig>] [--map <mapfile>]
Modes: Modes:
Three modes are available. * Live mode: $(basename $0) [options] [--kernel <kimage>] [--config <kconfig>] [--map <mapfile>]
Inspect the currently running kernel within the context of the CPU it's running on.
You can optionally specify --kernel, --config, or --map to help the script locate files it couldn't auto-detect
First mode is the "live" mode (default), it does its best to find information about the currently * No-runtime mode: $(basename $0) [options] --no-runtime <--kernel <kimage>> [--config <kconfig>] [--map <mapfile>]
running kernel. To run under this mode, just start the script without any option. Inspect the CPU hardware, but skips all running-kernel artifacts (/sys, /proc, dmesg).
You can optionally specify --kernel, --config, or --map to help the script locate files it Use this when you have a kernel image different from the kernel you're running but want to check it against this CPU.
couldn't auto-detect, without changing the mode.
--kernel kernel_file specify a (possibly compressed) Linux or BSD kernel file * No-hardware mode: $(basename $0) [options] --no-hw <--kernel <kimage>> [--config <kconfig>] [--map <mapfile>]
--config kernel_config specify a kernel config file (Linux only) Ignore both CPU hardware and running-kernel artifacts. Use this for pure static analysis of a kernel image,
--map kernel_map_file specify a kernel System.map file (Linux only) for example when inspecting a kernel targeted for another system or CPU.
Second mode is "no-runtime" (--no-runtime), where the script inspects the local CPU hardware * Hardware-only mode: $(basename $0) [options] --hw-only
but skips all running-kernel artifacts (/sys, /proc, dmesg). Use this when you have a kernel Only inspect the CPU hardware, and report information and affectedness per vulnerability.
image from another system but want to check it against this CPU.
Third mode is "no-hw" (--no-hw), where the script skips both CPU hardware inspection and Vulnerability selection:
running-kernel artifacts. Use this for pure static analysis of a kernel image, for example --variant VARIANT specify which variant you'd like to check, by default all variants are checked.
when inspecting an embedded kernel from a different architecture. can be used multiple times (e.g. --variant 3a --variant l1tf). For a list use 'help'.
--cve CVE specify which CVE you'd like to check, by default all supported CVEs are checked
can be used multiple times (e.g. --cve CVE-2017-5753 --cve CVE-2020-0543)
Options: Check scope:
--no-color don't use color codes --no-sysfs don't use the /sys interface even if present [Linux]
--verbose, -v increase verbosity level, possibly several times --sysfs-only only use the /sys interface, don't run our own checks [Linux]
--explain produce an additional human-readable explanation of actions to take to mitigate a vulnerability
Strictness:
--paranoid require all mitigations to be enabled to the fullest extent, including those that --paranoid require all mitigations to be enabled to the fullest extent, including those that
are not strictly necessary but provide defense in depth (e.g. SMT disabled, IBPB are not strictly necessary but provide defense in depth (e.g. SMT disabled, IBPB
always-on); without this flag, the script follows the security community consensus always-on); without this flag, the script follows the security community consensus
--extra run additional checks for issues that don't have a CVE but are still security-relevant, --extra run additional checks for issues that don't have a CVE but are still security-relevant,
such as compile-time mitigations not enabled by default (e.g. Straight-Line Speculation) such as compile-time mitigations not enabled by default (e.g. Straight-Line Speculation)
--no-sysfs don't use the /sys interface even if present [Linux] Hardware and platform:
--sysfs-only only use the /sys interface, don't run our own checks [Linux] --cpu [#,all] interact with CPUID and MSR of CPU core number #, or all (default: CPU core 0)
--coreos special mode for CoreOS (use an ephemeral toolbox to inspect kernel) [Linux]
--arch-prefix PREFIX specify a prefix for cross-inspecting a kernel of a different arch, for example "aarch64-linux-gnu-",
so that invoked tools will be prefixed with this (i.e. aarch64-linux-gnu-objdump)
--batch text produce machine readable output, this is the default if --batch is specified alone
--batch short produce only one line with the vulnerabilities separated by spaces
--batch json produce comprehensive JSON output with system, CPU, and vulnerability details
--batch json-terse produce a terse JSON array of per-CVE results (legacy format)
--batch nrpe produce machine readable output formatted for NRPE
--batch prometheus produce Prometheus metrics (smc_* schema)
--variant VARIANT specify which variant you'd like to check, by default all variants are checked.
can be used multiple times (e.g. --variant 3a --variant l1tf)
for a list of supported VARIANT parameters, use --variant help
--cve CVE specify which CVE you'd like to check, by default all supported CVEs are checked
can be used multiple times (e.g. --cve CVE-2017-5753 --cve CVE-2020-0543)
--hw-only only check for CPU information, don't check for any variant
--no-runtime skip running-kernel checks (/sys, /proc, dmesg), still inspect local CPU hardware
--no-hw skip CPU information and running-kernel checks (implies --no-runtime)
--vmm [auto,yes,no] override the detection of the presence of a hypervisor, default: auto --vmm [auto,yes,no] override the detection of the presence of a hypervisor, default: auto
--allow-msr-write allow probing for write-only MSRs, this might produce kernel logs or be blocked by your system --allow-msr-write allow probing for write-only MSRs, this might produce kernel logs or be blocked by your system
--cpu [#,all] interact with CPUID and MSR of CPU core number #, or all (default: CPU core 0) --arch-prefix PREFIX specify a prefix for cross-inspecting a kernel of a different arch, for example "aarch64-linux-gnu-",
so that invoked tools will be prefixed with this (i.e. aarch64-linux-gnu-objdump)
--coreos special mode for CoreOS (use an ephemeral toolbox to inspect kernel) [Linux]
Output:
--batch FORMAT produce machine readable output; FORMAT is one of:
text (default), short, json, json-terse, nrpe, prometheus
--no-color don't use color codes
--verbose, -v increase verbosity level, possibly several times
--explain produce an additional human-readable explanation of actions to take to mitigate a vulnerability
Firmware database:
--update-fwdb update our local copy of the CPU microcodes versions database (using the awesome --update-fwdb update our local copy of the CPU microcodes versions database (using the awesome
MCExtractor project and the Intel firmwares GitHub repository) MCExtractor project and the Intel firmwares GitHub repository)
--update-builtin-fwdb same as --update-fwdb but update builtin DB inside the script itself --update-builtin-fwdb same as --update-fwdb but update builtin DB inside the script itself
Debug:
--dump-mock-data used to mimick a CPU on an other system, mainly used to help debugging this script --dump-mock-data used to mimick a CPU on an other system, mainly used to help debugging this script
Return codes: Return codes: