Snyk test

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+- package-ecosystem: gomod
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+- package-ecosystem: gomod
+  directory: "/tools"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10

.github/workflows/snyk.yml

@@ -0,0 +1,20 @@
+name: Code Scanning with Snyk
+on:
+  pull_request:
+    types: [opened, reopened]
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Snyk to check for vulnerabilities
+        uses: snyk/actions/golang@master
+        continue-on-error: true # To make sure that SARIF upload gets called
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+        with:
+          args: --sarif-file-output=snyk.sarif
+      - name: Upload result to GitHub Code Scanning
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: snyk.sarif

cmd/vfkit/root.go

@@ -9,7 +9,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-const vfkitVersion = "0.1.1"
+const vfkitVersion = "0.5.1"
 
 var opts = &cmdline.Options{}
 

doc/quickstart.md

@@ -0,0 +1,111 @@
+# vfkit quick start
+
+## Introduction
+
+vfkit is a macOS command-line-based hypervisor, which uses [Apple's Virtualization Framework](https://developer.apple.com/documentation/virtualization?language=objc) to run virtual machines.
+You start a virtual machine by running vfkit with a set of arguments describing the virtual machine configuration/hardware.
+When vfkit stops, the virtual machine stops running.
+It requires macOS 11 or newer, and runs on both x86_64 and aarch64 Macs.
+File sharing is only available on macOS 12 or newer.
+UEFI boot and graphical user interface support are only available on macOS 13 or newer.
+
+
+## Installation
+
+You can get vfkit either by downloading it from [its release page](https://github.com/crc-org/vfkit/releases), or get it from [brew](https://brew.sh/):
+```
+# Only the first time
+$ brew tap cfergeau/crc
+
+$ brew install vfkit
+```
+
+
+## Quick start
+
+### Getting a disk image
+
+Your virtual machine will need an operating system to run, so you need to download a disk image first.
+The image needs to be in the raw or iso format. Please note that qcow2 or
+VirtualBox images cannot be used by vfkit.
+
+For example, Fedora images can be downloaded with:
+```
+# For Apple silicon Macs
+$ curl -L -O https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/aarch64/images/Fedora-Cloud-Base-38-1.6.aarch64.raw.xz
+$ xz -d ./Fedora-Cloud-Base-38-1.6.aarch64.raw.xz
+$ mv Fedora-Cloud-Base-38-1.6.aarch64.raw vfkit-test-image.raw
+
+# For Intel Macs
+$ curl -L https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora-Cloud-Base-38-1.6.x86_64.raw.xz
+$ xz -d ./Fedora-Cloud-Base-38-1.6.x86_64.raw.xz
+$ mv Fedora-Cloud-Base-38-1.6.x86_64.raw vfkit-test-image.raw
+```
+
+
+### Starting a virtual machine
+
+
+Now that we have a disk image, we can start a virtual machine with 2 virtual CPUs and 2GiB of RAM:
+
+```
+$ vfkit \
+    --cpus 2 --memory 2048 \
+    --bootloader efi,variable-store=efi-variable-store,create \
+    --device virtio-blk,path=vfkit-test-image.raw
+```
+
+No logs from the virtual machine are displayed in the terminal where vfkit was started, but it should show:
+```
+INFO[0000] virtual machine is running
+INFO[0000] waiting for VM to stop
+```
+
+The virtual machine will be running until you hit Ctrl+C or kill the vfkit process.
+If you are using an image or an older macOS version which does not support UEFI boot, you can use the `linux` bootloader.
+This requires a separate kernel, initrd file and kernel command-line arguments.
+Details can be found in the [usage instructions](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#linux-bootloader).
+
+
+### Adding a serial console for boot logs
+
+To get some logs from the virtual machine, we can add a virtio-serial device to vfkit command-line:
+```
+--device virtio-serial,stdio
+```
+
+The logs will be shown in the terminal where vfkit was started.
+With the Fedora image, only the login prompt is shown after approximately 30s.
+On more verbose images, the boot logs are only shown late in the boot process as they only start to appear after the virtio-serial module and associated console have been loaded and configured.
+
+
+### Adding a network card
+
+To make the interactions with the virtual machine easier, we can add a virtio-net device to it:
+```
+    --device virtio-net,nat
+```
+
+After booting, the Fedora image prints the IP address of the VM in the serial console before the login prompt.
+
+You can specify the mac address of the network interface on the command-line:
+```
+--device virtio-net,nat,mac=72:20:43:d4:39:63
+```
+
+This allows to lookup the IP which was assigned to the virtual machine by searching for the mac address in the `/var/db/dhcpd_leases` file on the host.
+
+
+### Next steps
+
+
+Once you have a virtual machine up and running, here are some additional features which can be useful:
+- [sparse/copy-on-write disk images](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#thin-images)
+- [host/guest communication over virtio-vsock](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#virtio-vsock-communication)
+- [host/guest file sharing with virtio-fs](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#file-sharing)
+- [Rosetta support to run x86_64 binaries in virtual machines on Apple silicon Macs](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#rosetta)
+- [GUI support](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#enabling-a-graphical-user-interface)
+- [REST API to control the virtual machine](https://github.com/crc-org/vfkit/blob/main/doc/usage.md#restful-service)
+- [user-mode networking with the `gvproxy` command from gvisor-tap-vsock](https://github.com/containers/gvisor-tap-vsock)
+
+Any questions/issues/... with vfkit can be reported [on GitHub](https://github.com/crc-org/vfkit/issues/new).

doc/usage.md

@@ -119,9 +119,33 @@ Various devices can be added to the virtual machines. They are all paravirtualiz
 #### Description
 
 The `--device virtio-blk` option adds a disk to the virtual machine. The disk is backed by an image file on the host machine. This file is a raw image file.
-This means an empty 1GiB disk can be created with `dd if=/dev/zero of=vfkit.img bs=1G count=1`.
 See also [vz/CreateDiskImage](https://pkg.go.dev/github.com/Code-Hex/vz/v3#CreateDiskImage).
 
+
+#### Thin images
+
+Apple Virtualization Framework only support raw disk images and ISO images.
+There is no support for thin image formats such as [qcow2](https://en.wikipedia.org/wiki/Qcow).
+
+However, APFS, the default macOS filesystem has support for sparse files and copy-on-write files, so it offers the main features of thin image format.
+
+A sparse raw image can be created/expanded using the `truncate` command or
+using
+[`truncate(2)`](https://manpagez.com/man/2/truncate/).
+For example, an empty 1GiB disk can be created with `truncate --size 1G
+vfkit.img`. Such an image will only use disk space when content is written to
+it. It initially only uses a few bytes of actual disk space even if it's size
+is 1G.
+
+A copy-on-write image is a raw image file which references a backing file. Its
+initial content is the same as its backing file, and the data is shared with
+the backing file. This means the copy-on-write image does not use extra disk
+space when it's created. When this image is modified, the changes will only be
+made to the copy-on-write image, and not to the backing file. Only the
+modified data will use actual disk space.
+A copy-on-write image can be created using `cp -c` or [clonefile(2)](http://www.manpagez.com/man/2/clonefile/).
+
+
 #### Arguments
 - `path`: the absolute path to the disk image file.
 - `deviceId`: `/dev/disk/by-id/` identifier to use for this device.
@@ -351,17 +375,19 @@ None
 Used to obtain the state of the virtual machine that is being run by VFKit.
 
 GET `/vm/state`
-Response: {"state": "string"}
+Response: { "state": string, "canStart": bool, "canPause": bool, "canResume": bool, "canStop": bool, "canHardStop": bool }
+
+> `canHardStop` is only supported on macOS 12 and newer, false will always be returned on older versions.
 
 ### Change VM State
 
 Change the state of the virtual machine. Valid states are:
-* Hardstop
+* HardStop
 * Pause
 * Resume
 * Stop
 
-POST `/vm/state` {"new_state": "new value"}
+POST `/vm/state` { "state": "new value"}
 
 Response: http 200
 

go.mod

@@ -3,44 +3,46 @@ module github.com/crc-org/vfkit
 go 1.18
 
 require (
-	github.com/Code-Hex/vz/v3 v3.0.6
-	github.com/docker/go-units v0.4.0
-	github.com/gin-gonic/gin v1.9.0
+	github.com/Code-Hex/vz/v3 v3.1.0
+	github.com/docker/go-units v0.5.0
+	github.com/gin-gonic/gin v1.9.1
 	github.com/prashantgupta24/mac-sleep-notifier v1.0.1
-	github.com/sirupsen/logrus v1.9.0
-	github.com/spf13/cobra v1.7.0
+	github.com/sirupsen/logrus v1.9.3
+	github.com/spf13/cobra v1.8.0
 	github.com/spf13/pflag v1.0.5
-	github.com/stretchr/testify v1.8.1
-	golang.org/x/sys v0.5.0
-	inet.af/tcpproxy v0.0.0-20220326234310-be3ee21c9fa0
+	github.com/stretchr/testify v1.8.4
+	golang.org/x/sys v0.16.0
+	inet.af/tcpproxy v0.0.0-20231102063150-2862066fc2a9
 )
 
 require (
 	github.com/Code-Hex/go-infinity-channel v1.0.0 // indirect
-	github.com/bytedance/sonic v1.8.0 // indirect
-	github.com/chenzhuoyu/base64x v0.0.0-20221115062448-fe3a3abad311 // indirect
+	github.com/bytedance/sonic v1.10.2 // indirect
+	github.com/chenzhuoyu/base64x v0.0.0-20230717121745-296ad89f973d // indirect
+	github.com/chenzhuoyu/iasm v0.9.1 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
-	github.com/go-playground/validator/v10 v10.11.2 // indirect
-	github.com/goccy/go-json v0.10.0 // indirect
+	github.com/go-playground/validator/v10 v10.17.0 // indirect
+	github.com/goccy/go-json v0.10.2 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/klauspost/cpuid/v2 v2.0.9 // indirect
-	github.com/leodido/go-urn v1.2.1 // indirect
-	github.com/mattn/go-isatty v0.0.17 // indirect
-	github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421 // indirect
+	github.com/klauspost/cpuid/v2 v2.2.6 // indirect
+	github.com/leodido/go-urn v1.2.4 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/pelletier/go-toml/v2 v2.0.6 // indirect
+	github.com/pelletier/go-toml/v2 v2.1.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
-	github.com/ugorji/go/codec v1.2.9 // indirect
-	golang.org/x/arch v0.0.0-20210923205945-b76863e36670 // indirect
-	golang.org/x/crypto v0.5.0 // indirect
-	golang.org/x/mod v0.9.0 // indirect
-	golang.org/x/net v0.7.0 // indirect
-	golang.org/x/text v0.7.0 // indirect
-	google.golang.org/protobuf v1.28.1 // indirect
+	github.com/ugorji/go/codec v1.2.12 // indirect
+	golang.org/x/arch v0.7.0 // indirect
+	golang.org/x/crypto v0.18.0 // indirect
+	golang.org/x/mod v0.14.0 // indirect
+	golang.org/x/net v0.20.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	google.golang.org/protobuf v1.32.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )