feat(tool): Add fingerprint dump feature

Add a feature to dump a fingerprint consisting of guest CPU config and
host information (fingerprint version, kernel version, microcode
version, etc.).

Signed-off-by: Takahiro Itazuri <[email protected]>

Author: zulinx86

Cargo.lock

@@ -10,6 +10,8 @@ license = "Apache-2.0"
 
 [dependencies]
 clap = { version = "4.2.3", features = ["derive", "string"] }
+libc = "0.2.117"
+serde = { version = "1.0.136", features = ["derive"] }
 serde_json = "1.0.78"
 thiserror = "1.0.32"
 

src/cpu-template-helper/Cargo.toml

@@ -0,0 +1,127 @@
+// Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use std::fs::read_to_string;
+use std::sync::{Arc, Mutex};
+
+use vmm::Vmm;
+
+use crate::fingerprint::Fingerprint;
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    /// Failed to dump CPU configuration.
+    #[error("Failed to dump CPU config: {0}")]
+    DumpCpuConfig(#[from] crate::template::dump::Error),
+    /// Failed to read sysfs file.
+    #[error("Failed to read {0}: {1}")]
+    ReadSysfsFile(String, std::io::Error),
+    /// Failed to get kernel version.
+    #[error("Failed to get kernel version: {0}")]
+    GetKernelVersion(std::io::Error),
+    /// Shell command failed.
+    #[error("`{0}` failed: {1}")]
+    ShellCommand(String, String),
+}
+
+pub fn dump(vmm: Arc<Mutex<Vmm>>) -> Result<Fingerprint, Error> {
+    Ok(Fingerprint {
+        firecracker_version: crate::utils::CPU_TEMPLATE_HELPER_VERSION.to_string(),
+        kernel_version: get_kernel_version()?,
+        #[cfg(target_arch = "x86_64")]
+        microcode_version: read_sysfs_file("/sys/devices/system/cpu/cpu0/microcode/version")?,
+        #[cfg(target_arch = "aarch64")]
+        microcode_version: read_sysfs_file(
+            "/sys/devices/system/cpu/cpu0/regs/identification/revidr_el1",
+        )?,
+        bios_version: read_sysfs_file("/sys/devices/virtual/dmi/id/bios_version")?,
+        // TODO: Replace this with `read_sysfs_file("/sys/devices/virtual/dmi/id/bios_release")`
+        // after the end of kernel 4.14 support.
+        // https://github.com/firecracker-microvm/firecracker/issues/3677
+        bios_revision: run_shell_command(
+            "dmidecode -t bios | grep \"BIOS Revision\" | cut -d':' -f2 | tr -d ' \\n'",
+        )?,
+        guest_cpu_config: crate::template::dump::dump(vmm)?,
+    })
+}
+
+fn get_kernel_version() -> Result<String, Error> {
+    // SAFETY: An all-zeroed value for `libc::utsname` is valid.
+    let mut name: libc::utsname = unsafe { std::mem::zeroed() };
+    // SAFETY: The passed arg is a valid mutable reference of `libc::utsname`.
+    let ret = unsafe { libc::uname(&mut name) };
+    if ret < 0 {
+        return Err(Error::GetKernelVersion(std::io::Error::last_os_error()));
+    }
+
+    // SAFETY: The fields of `libc::utsname` are terminated by a null byte ('\0').
+    // https://man7.org/linux/man-pages/man2/uname.2.html
+    let c_str = unsafe { std::ffi::CStr::from_ptr(name.release.as_ptr()) };
+    // SAFETY: The `release` field is an array of `char` in C, in other words, ASCII.
+    let version = c_str.to_str().unwrap();
+    Ok(version.to_string())
+}
+
+fn read_sysfs_file(path: &str) -> Result<String, Error> {
+    let s = read_to_string(path).map_err(|err| Error::ReadSysfsFile(path.to_string(), err))?;
+    Ok(s.trim_end_matches('\n').to_string())
+}
+
+fn run_shell_command(cmd: &str) -> Result<String, Error> {
+    let output = std::process::Command::new("sh")
+        .args(["-c", cmd])
+        .output()
+        .map_err(|err| Error::ShellCommand(cmd.to_string(), err.to_string()))?;
+    if !output.status.success() {
+        return Err(Error::ShellCommand(
+            cmd.to_string(),
+            format!(
+                "code: {:?}\nstdout: {}\nstderr: {}",
+                output.status.code(),
+                std::str::from_utf8(&output.stdout).unwrap(),
+                std::str::from_utf8(&output.stderr).unwrap(),
+            ),
+        ));
+    }
+    Ok(std::str::from_utf8(&output.stdout).unwrap().to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_get_kernel_version() {
+        // `get_kernel_version()` should always succeed.
+        get_kernel_version().unwrap();
+    }
+
+    #[test]
+    fn test_read_valid_sysfs_file() {
+        // The sysfs file for microcode version should exist and be read.
+        let valid_sysfs_path = "/sys/devices/virtual/dmi/id/bios_version";
+        read_sysfs_file(valid_sysfs_path).unwrap();
+    }
+
+    #[test]
+    fn test_read_invalid_sysfs_file() {
+        let invalid_sysfs_path = "/sys/invalid/path";
+        if read_sysfs_file(invalid_sysfs_path).is_ok() {
+            panic!("Should fail with `No such file or directory`");
+        }
+    }
+
+    #[test]
+    fn test_run_valid_shell_command() {
+        let valid_cmd = "ls";
+        run_shell_command(valid_cmd).unwrap();
+    }
+
+    #[test]
+    fn test_run_invalid_shell_command() {
+        let invalid_cmd = "unknown_command";
+        if run_shell_command(invalid_cmd).is_ok() {
+            panic!("Should fail with `unknown_command: not found`");
+        }
+    }
+}

src/cpu-template-helper/src/fingerprint/dump.rs

@@ -0,0 +1,17 @@
+// Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use serde::{Deserialize, Serialize};
+use vmm::cpu_config::templates::CustomCpuTemplate;
+
+pub mod dump;
+
+#[derive(Serialize, Deserialize)]
+pub struct Fingerprint {
+    pub firecracker_version: String,
+    pub kernel_version: String,
+    pub microcode_version: String,
+    pub bios_version: String,
+    pub bios_revision: String,
+    pub guest_cpu_config: CustomCpuTemplate,
+}

src/cpu-template-helper/src/fingerprint/mod.rs

@@ -7,6 +7,7 @@ use std::path::PathBuf;
 use clap::{Parser, Subcommand};
 use vmm::cpu_config::templates::{CustomCpuTemplate, GetCpuTemplate, GetCpuTemplateError};
 
+mod fingerprint;
 mod template;
 mod utils;
 
@@ -16,6 +17,8 @@ const EXIT_CODE_ERROR: i32 = 1;
 enum Error {
     #[error("Failed to operate file: {0}")]
     FileIo(#[from] std::io::Error),
+    #[error("{0}")]
+    FingerprintDump(#[from] fingerprint::dump::Error),
     #[error("CPU template is not specified: {0}")]
     NoCpuTemplate(#[from] GetCpuTemplateError),
     #[error("Failed to serialize/deserialize JSON file: {0}")]
@@ -76,7 +79,17 @@ enum TemplateOperation {
 }
 
 #[derive(Subcommand)]
-enum FingerprintOperation {}
+enum FingerprintOperation {
+    /// Dump fingerprint consisting of host-related information and guest CPU config.
+    Dump {
+        /// Path of fingerprint config file.
+        #[arg(short, long, value_name = "PATH")]
+        config: PathBuf,
+        /// Path of output file.
+        #[arg(short, long, value_name = "PATH", default_value = "fingerprint.json")]
+        output: PathBuf,
+    },
+}
 
 fn run(cli: Cli) -> Result<()> {
     match cli.command {
@@ -120,7 +133,17 @@ fn run(cli: Cli) -> Result<()> {
                 template::verify::verify(cpu_template, cpu_config)?;
             }
         },
-        Command::Fingerprint(_) => {}
+        Command::Fingerprint(op) => match op {
+            FingerprintOperation::Dump { config, output } => {
+                let config = read_to_string(config)?;
+                let (vmm, _) = utils::build_microvm_from_config(&config)?;
+
+                let fingerprint = fingerprint::dump::dump(vmm)?;
+
+                let fingerprint_json = serde_json::to_string_pretty(&fingerprint)?;
+                write(output, fingerprint_json)?;
+            }
+        },
     }
 
     Ok(())
@@ -326,4 +349,29 @@ mod tests {
 
         run(cli).unwrap();
     }
+
+    #[test]
+    fn test_fingerprint_dump_command() {
+        let kernel_image_path = kernel_image_path(None);
+        let rootfs_file = TempFile::new().unwrap();
+        let config_file = generate_config_file(
+            &kernel_image_path,
+            rootfs_file.as_path().to_str().unwrap(),
+            None,
+        );
+        let output_file = TempFile::new().unwrap();
+
+        let args = vec![
+            "cpu-template-helper",
+            "fingerprint",
+            "dump",
+            "--config",
+            config_file.as_path().to_str().unwrap(),
+            "--output",
+            output_file.as_path().to_str().unwrap(),
+        ];
+        let cli = Cli::parse_from(args);
+
+        run(cli).unwrap();
+    }
 }