Hyperlight 项目使用教程

Hyperlight 项目使用教程

hyperlight Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within micro virtual machines with very low latency and minimal overhead. 项目地址: https://gitcode.com/gh_mirrors/hy/hyperlight

1. 项目介绍

Hyperlight 是一个轻量级的虚拟机管理器（VMM），旨在嵌入应用程序中。它支持在微虚拟机中安全执行不可信代码，具有非常低的延迟和最小化开销。Hyperlight 适用于 Windows 和 Linux 系统，在 Windows 上使用 Windows Hypervisor Platform，在 Linux 上则可以使用 Microsoft Hypervisor (mshv) 或 KVM。这些微虚拟机不包含内核或操作系统，从而保持开销低。客人通过 Hyperlight 客户库构建，该库提供一组受控的 API 以便主机和客人之间进行交互。

2. 项目快速启动

以下是基于 Rust 语言环境的 Hyperlight 快速启动指南。

首先，确保已经安装了 Rust 和 Cargo。然后，你可以通过以下步骤创建并运行一个简单的 Hyperlight 客户端和服务器。

安装依赖

# 在项目根目录下执行以下命令
cargo build --release

主机代码示例

// src/main.rs
use std::thread;
use std::sync::{Arc, Mutex};
use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnType};
use hyperlight_host::{UninitializedSandbox, MultiUseSandbox, func::HostFunction0, sandbox_state::transition::Noop, sandbox_state::sandbox::EvolvableSandbox};

fn main() -> hyperlight_host::Result<()> {
    // 创建一个未初始化的沙盒，包含客人二进制文件
    let mut uninitialized_sandbox = UninitializedSandbox::new(
        hyperlight_host::GuestBinary::FilePath(hyperlight_testing::simple_guest_as_string().unwrap()),
        None,
        None,
        None,
    )?;

    // 注册一个主机函数
    fn sleep_5_secs() -> hyperlight_host::Result<()> {
        thread::sleep(std::time::Duration::from_secs(5));
        Ok(())
    }
    let host_function = Arc::new(Mutex::new(sleep_5_secs));

    // 注册主机函数以便客人调用
    host_function.register(&mut uninitialized_sandbox, "Sleep5Secs")?;

    // 初始化沙盒以调用主机函数
    let mut multi_use_sandbox: MultiUseSandbox = uninitialized_sandbox,evolve(Noop::default())?;

    // 调用客人中的函数
    let message = "Hello, World! I am executing inside of a VM :)".to_string();
    let result = multi_use_sandbox.call_guest_function_by_name(
        "PrintOutput",
        ReturnType::Int,
        Some(vec![ParameterValue::String(message)]),
    );

    assert!(result.is_ok());
    Ok(())
}

客人代码示例

// src/guest.rs
#![no_std]
#![no_main]
extern crate alloc;
use alloc::string::ToString;
use alloc::vec::Vec;
use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCall;
use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterType, ParameterValue, ReturnType};
use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
use hyperlight_common::flatbuffer_wrappers::util::get_flatbuffer_result_from_int;
use hyperlight_guest::error::{HyperlightGuestError, Result};
use hyperlight_guest::guest_function_definition::GuestFunctionDefinition;
use hyperlight_guest::guest_function_register::register_function;
use hyperlight_guest::host_function_call::{call_host_function, get_host_value_return_as_int};

fn print_output(function_call: &FunctionCall) -> Result<Vec<u8>> {
    if let ParameterValue::String(message) = function_call.parameters.clone().unwrap()[0].clone() {
        call_host_function("HostPrint", Some(Vec::from(&[ParameterValue::String(message.to_string())])), ReturnType::Int)?;
        let result = get_host_value_return_as_int()?;
        Ok(get_flatbuffer_result_from_int(result))
    } else {
        Err(HyperlightGuestError::new(ErrorCode::GuestFunctionParameterTypeMismatch, "Invalid parameters passed to simple_print_output".to_string()))
    }
}

#[no_mangle]
pub extern "C" fn hyperlight_main() {
    let print_output_def = GuestFunctionDefinition::new(
        "PrintOutput".to_string(),
        Vec::from(&[ParameterType::String]),
        ReturnType::Int,
        print_output as i64,
    );
    register_function(print_output_def);
}

#[no_mangle]
pub fn guest_dispatch_function(function_call: FunctionCall) -> Result<Vec<u8>> {
    let function_name = function_call.function_name.clone();
    Err(HyperlightGuestError::new(ErrorCode::GuestFunctionNotFound, function_name))
}

编译并运行你的项目。

# 编译项目
cargo run --release

# 运行项目（确保你的环境配置正确）
./target/release/my_hyperlight_project

3. 应用案例和最佳实践

Hyperlight 的设计使其非常适合在需要执行不可信代码的上下文中使用，例如沙箱执行环境或安全执行第三方代码。以下是一些应用案例：

• 安全执行第三方代码：在执行不可信的第三方代码时，使用 Hyperlight 可以隔离代码执行，避免潜在的恶意行为影响主应用程序。
• 沙箱环境：在开发或测试过程中，可以为每个测试用例创建一个独立的 Hyperlight 实例，以实现代码的隔离执行。

最佳实践：

• 最小权限原则：确保客人只能访问必要的主机功能。
• 代码审查：对所有将要在 Hyperlight 环境中运行的代码进行严格的代码审查。

4. 典型生态项目

Hyperlight 可以与多种开源项目配合使用，以增强其功能和适用性。以下是一些典型的生态项目：

• 安全增强工具：例如，可以结合使用 Hyperlight 和 SELinux 或 AppArmor 来提供额外的安全层。
• 容器管理平台：Hyperlight 可以与容器管理工具如 Docker 或 Kubernetes 集成，为容器化应用提供虚拟化隔离。

Hyperlight 项目的使用不仅可以增强应用程序的安全性，还可以为开发人员提供一种强大的工具来隔离和管理不可信代码。通过遵循上述指南，您可以快速开始使用 Hyperlight 并将其集成到您的项目中。

hyperlight Hyperlight is a lightweight Virtual Machine Manager (VMM) designed to be embedded within applications. It enables safe execution of untrusted code within micro virtual machines with very low latency and minimal overhead. 项目地址: https://gitcode.com/gh_mirrors/hy/hyperlight