hyperlight-wasm 0.8.0

Library that enables wasm modules and components to be run inside lightweight Virtual Machine backed Sandbox. It is built on top of Hyperlight. 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# Hyperlight-Wasm - Run Wasm Modules in a Virtual Machine backed sandbox

_Hyperlight-Wasm_ is a component that enables Wasm Modules to be run inside lightweight  Virtual Machine backed Sandbox. Its purpose is to enable applications to  safely run untrusted or third party Wasm code within a VM with very low latency/overhead. It is built on top of [Hyperlight](https://github.com/hyperlight-dev/hyperlight).

Hyperlight-Wasm currently supports running applications using either the [Windows Hypervisor Platform](https://docs.microsoft.com/en-us/virtualization/api/#windows-hypervisor-platform) on Windows, [KVM](https://www.linux-kvm.org/page/Main_Page) on Linux or [/dev/mshv](https://github.com/rust-vmm/mshv).

WARNING: This is experimental code. It is not considered production-grade by its developers, neither is it "supported" software.

This repo contains hyperlight-wasm along with a couple of sample Wasm modules and an example host application that can be used to either test or try it out.

This document contains instructions on  building `Hyperlight-Wasm`. For usage instructions, please see [RustDev.md](./RustDev.md).

## Prerequisites

### Windows

Make sure the following are installed:

1. [Rust](https://www.rust-lang.org/tools/install)
1. [just](https://github.com/casey/just).  is used as a command runner  `cargo install just`. Do not install `just` with Chocolately because it installs an older incompatible version, make sure to use at least version 1.5.0 if not installed through cargo.
1. [pwsh](https://github.com/PowerShell/PowerShell)
1. [git](https://gitforwindows.org/)
1. [GitHub CLI](https://github.com/cli/cli#installation)
1. [wasm-tools](https://github.com/bytecodealliance/wasm-tools?tab=readme-ov-file#installation)
1. [cargo component](https://github.com/bytecodealliance/cargo-component?tab=readme-ov-file#installation)   

Ensure that Windows Hypervisor Platform is enabled:

```PowerShell
Enable-WindowsOptionalFeature -Online -FeatureName HyperVisorPlatform
```

### Linux

#### Ubuntu/KVM

Make sure the following are installed:

1. build-essential: `sudo apt install build-essential`
1. [Rust](https://www.rust-lang.org/tools/install) `curl --proto '=https' --tlsv1.3 https://sh.rustup.rs -sSf | sh`
1. [just](https://github.com/casey/just).  is used as a command runner  `cargo install just`. Do not install `just` through a package manager as it may install an older incompatible version, make sure to use at least version 1.5.0 if not installed through cargo.
1. [GitHub CLI](https://github.com/cli/cli#installation)
1. [wasm-tools](https://github.com/bytecodealliance/wasm-tools?tab=readme-ov-file#installation)
1. [cargo component](https://github.com/bytecodealliance/cargo-component?tab=readme-ov-file#installation)   

Ensure that KVM is enabled: On an Azure VM using a size that supports nested virtualisation:

`sudo apt install cpu-checker && kvm-ok`

If KVM is installed and available you should see the output

``` console
INFO: /dev/kvm exists
KVM acceleration can be used
```

You should also add your user to the kvm group: `sudo adduser $USER kvm`

## Building

NOTE: Ensure that you use version 1.86.0 of rust toolchain.

```Console
rustup install 1.86.0
rustup default 1.86.0
```

Now you can build the Rust Wasm library:

```Console
just build
```

And the example wasm modules used by the tests:
```Console
just build-wasm-examples
just build-rust-wasm-examples
```

Then you can test the Rust Wasm library and run the example:

```Console
just test
cargo run --example helloworld
```

## Component Model support

Hyperlight-Wasm has experimental support for running WebAssembly
Component Model components, rather than core wasm modules.  In this
mode, set the `WIT_WORLD` environment variable to point to
a binary encoding of a component type (e.g. the result of running
`wasm-tools component wit -w -o /path/to/output.wasm
/path/to/input.wit`), which will ensure that the resultant library
includes a guest binary that is specialised to load components with
that type. Then, use `hyperlight_component_macro::host_bindgen!()` to
generate bindings from the same component type in the host.  For a
complete (albeit small) example of this, see [this
example](https://aka.ms/hyperlight-wasm-sockets-sample).

### Debugging the macro

You can get more detailed error messages by expanding the Macro locally:

```
cargo clean -p hyperlight-wasm
WIT_WORLD=</path/to/output.wasm>  HYPERLIGHT_COMPONENT_MACRO_DEBUG=/tmp/guest.rs cargo build -p hyperlight-wasm
HYPERLIGHT_COMPONENT_MACRO_DEBUG=/tmp/host.rs cargo build
```


## Code of Conduct

This project has adopted the [Microsoft Open Source Code of
Conduct](https://opensource.microsoft.com/codeofconduct/).

For more information see the [Code of Conduct
FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact
[opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

## FOSSA Status
[![FOSSA License Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhyperlight-dev%2Fhyperlight-wasm.svg?type=shield&issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhyperlight-dev%2Fhyperlight-wasm?ref=badge_shield&issueType=license)
[![FOSSA Security Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fhyperlight-dev%2Fhyperlight-wasm.svg?type=shield&issueType=security)](https://app.fossa.com/projects/git%2Bgithub.com%2Fhyperlight-dev%2Fhyperlight-wasm?ref=badge_shield&issueType=security)