windows-development-sandbox 1.7.0 → 1.9.0

package/native/csharp/HcsHost/Hcs.cs

@@ -0,0 +1,256 @@
+// Calls into computecore.dll (Host Compute Service) and computestorage.dll (HcsGrantVmAccess). Signatures are from
+// the Microsoft HCS API reference (learn.microsoft.com/virtualization/api/hcs/reference/*), checked there for the
+// operation and compute-system functions; HcsGrantVmAccess is from the computestorage.h header (not re-checked).
+// Nothing here has run against a real HCS: the PC this was written on had no Hyper-V.
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+
+namespace AgentSandbox.HcsHost
+{
+    /// <summary>What an HCS call answered: the HRESULT and the JSON document (result or error) that came with it.</summary>
+    public sealed class HcsReply
+    {
+        public int HResult;
+        public string Json = "";
+
+        public bool Ok
+        {
+            get { return HResult == 0; }
+        }
+
+        public string Message()
+        {
+            if (HResult == 0)
+            {
+                return "ok";
+            }
+            string known = HcsErrorText((uint)HResult);
+            if (known != null)
+            {
+                return known;
+            }
+            Exception ex = Marshal.GetExceptionForHR(HResult);
+            return ex != null ? ex.Message : "error 0x" + HResult.ToString("X8");
+        }
+
+        /// <summary>The HCS-specific codes (learn.microsoft.com/virtualization/api/hcs/reference/hcshresult), or null.</summary>
+        private static string HcsErrorText(uint hr)
+        {
+            switch (hr)
+            {
+                case 0x80370102u:
+                    return "a required Windows feature is not installed (HCS_E_HYPERV_NOT_INSTALLED)";
+                case 0x8037010Du:
+                    return "the compute system document is invalid (HCS_E_INVALID_JSON)";
+                case 0x8037010Eu:
+                    return "no compute system has that id (HCS_E_SYSTEM_NOT_FOUND)";
+                case 0x8037010Fu:
+                    return "a compute system with that id already exists (HCS_E_SYSTEM_ALREADY_EXISTS)";
+                case 0x80370110u:
+                    return "the compute system is not running (HCS_E_SYSTEM_ALREADY_STOPPED)";
+                case 0x80370114u:
+                    return "a required Windows feature is not installed (HCS_E_SERVICE_NOT_AVAILABLE)";
+                case 0x80370118u:
+                    return "the operation did not complete in time (HCS_E_OPERATION_TIMEOUT)";
+                case 0x8037011Bu:
+                    return "only Administrators or Hyper-V Administrators may do this (HCS_E_ACCESS_DENIED, see https://aka.ms/hcsadmin)";
+                default:
+                    return null;
+            }
+        }
+    }
+
+    public static class Hcs
+    {
+        private const uint GenericAll = 0x10000000;
+        private const uint QueryMs = 15000;
+        private const uint ChangeMs = 180000;
+
+        private delegate int Begin(IntPtr operation);
+
+        private delegate int BeginOn(IntPtr system, IntPtr operation);
+
+        private static class NativeMethods
+        {
+            [DllImport("computecore.dll", ExactSpelling = true, SetLastError = true)]
+            public static extern IntPtr HcsCreateOperation(IntPtr context, IntPtr callback);
+
+            [DllImport("computecore.dll", ExactSpelling = true)]
+            public static extern void HcsCloseOperation(IntPtr operation);
+
+            [DllImport("computecore.dll", ExactSpelling = true)]
+            public static extern int HcsWaitForOperationResult(IntPtr operation, uint timeoutMs, out IntPtr resultDocument);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsEnumerateComputeSystems(string query, IntPtr operation);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsCreateComputeSystem(string id, string configuration, IntPtr operation, IntPtr securityDescriptor, out IntPtr computeSystem);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsOpenComputeSystem(string id, uint requestedAccess, out IntPtr computeSystem);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsStartComputeSystem(IntPtr computeSystem, IntPtr operation, string options);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsTerminateComputeSystem(IntPtr computeSystem, IntPtr operation, string options);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsGetComputeSystemProperties(IntPtr computeSystem, IntPtr operation, string propertyQuery);
+
+            [DllImport("computecore.dll", ExactSpelling = true)]
+            public static extern void HcsCloseComputeSystem(IntPtr computeSystem);
+
+            [DllImport("computecore.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsGetServiceProperties(string propertyQuery, out IntPtr result);
+
+            [DllImport("computestorage.dll", ExactSpelling = true, CharSet = CharSet.Unicode)]
+            public static extern int HcsGrantVmAccess(string vmId, string filePath);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern IntPtr LocalFree(IntPtr mem);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern IntPtr LoadLibrary(string fileName);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern bool FreeLibrary(IntPtr module);
+        }
+
+        /// <summary>A LocalFree-able wide string from HCS, as text (empty when null).</summary>
+        private static string TakeString(IntPtr p)
+        {
+            if (p == IntPtr.Zero)
+            {
+                return "";
+            }
+            try
+            {
+                return Marshal.PtrToStringUni(p);
+            }
+            finally
+            {
+                NativeMethods.LocalFree(p);
+            }
+        }
+
+        /// <summary>Whether a DLL (computecore.dll) can be loaded at all on this PC.</summary>
+        public static bool CanLoad(string dll)
+        {
+            IntPtr module = NativeMethods.LoadLibrary(dll);
+            if (module == IntPtr.Zero)
+            {
+                return false;
+            }
+            NativeMethods.FreeLibrary(module);
+            return true;
+        }
+
+        public static HcsReply ServiceProperties(string queryJson)
+        {
+            HcsReply reply = new HcsReply();
+            IntPtr result = IntPtr.Zero;
+            reply.HResult = NativeMethods.HcsGetServiceProperties(queryJson, out result);
+            reply.Json = TakeString(result);
+            return reply;
+        }
+
+        /// <summary>Starts an operation with `begin`, waits for it and returns its result document.</summary>
+        private static HcsReply Run(Begin begin, uint waitMs)
+        {
+            HcsReply reply = new HcsReply();
+            IntPtr operation = NativeMethods.HcsCreateOperation(IntPtr.Zero, IntPtr.Zero);
+            if (operation == IntPtr.Zero)
+            {
+                reply.HResult = Marshal.GetHRForLastWin32Error();
+                return reply;
+            }
+            try
+            {
+                int hr = begin(operation);
+                if (hr != 0)
+                {
+                    reply.HResult = hr;
+                    return reply;
+                }
+                IntPtr doc = IntPtr.Zero;
+                reply.HResult = NativeMethods.HcsWaitForOperationResult(operation, waitMs, out doc);
+                reply.Json = TakeString(doc);
+                return reply;
+            }
+            finally
+            {
+                NativeMethods.HcsCloseOperation(operation);
+            }
+        }
+
+        public static HcsReply Enumerate(string queryJson)
+        {
+            return Run(delegate(IntPtr op) { return NativeMethods.HcsEnumerateComputeSystems(queryJson, op); }, QueryMs);
+        }
+
+        /// <summary>Creates a compute system from a document. The handle is closed again: the system stays.</summary>
+        public static HcsReply Create(string id, string document)
+        {
+            IntPtr system = IntPtr.Zero;
+            try
+            {
+                return Run(
+                    delegate(IntPtr op) { return NativeMethods.HcsCreateComputeSystem(id, document, op, IntPtr.Zero, out system); },
+                    ChangeMs);
+            }
+            finally
+            {
+                if (system != IntPtr.Zero)
+                {
+                    NativeMethods.HcsCloseComputeSystem(system);
+                }
+            }
+        }
+
+        private static HcsReply WithSystem(string id, uint waitMs, BeginOn call)
+        {
+            IntPtr system = IntPtr.Zero;
+            int hr = NativeMethods.HcsOpenComputeSystem(id, GenericAll, out system);
+            if (hr != 0)
+            {
+                HcsReply failed = new HcsReply();
+                failed.HResult = hr;
+                return failed;
+            }
+            try
+            {
+                return Run(delegate(IntPtr op) { return call(system, op); }, waitMs);
+            }
+            finally
+            {
+                NativeMethods.HcsCloseComputeSystem(system);
+            }
+        }
+
+        public static HcsReply Start(string id)
+        {
+            return WithSystem(id, ChangeMs, delegate(IntPtr system, IntPtr op) { return NativeMethods.HcsStartComputeSystem(system, op, null); });
+        }
+
+        public static HcsReply Terminate(string id)
+        {
+            return WithSystem(id, ChangeMs, delegate(IntPtr system, IntPtr op) { return NativeMethods.HcsTerminateComputeSystem(system, op, null); });
+        }
+
+        public static HcsReply Properties(string id, string queryJson)
+        {
+            return WithSystem(id, QueryMs, delegate(IntPtr system, IntPtr op) { return NativeMethods.HcsGetComputeSystemProperties(system, op, queryJson); });
+        }
+
+        /// <summary>Lets the virtual machine `vmId` open the file (its disk). The file must exist.</summary>
+        public static HcsReply GrantVmAccess(string vmId, string filePath)
+        {
+            HcsReply reply = new HcsReply();
+            reply.HResult = NativeMethods.HcsGrantVmAccess(vmId, filePath);
+            return reply;
+        }
+    }
+}

package/native/csharp/HcsHost/Json.cs

@@ -0,0 +1,78 @@
+// Minimal JSON output for HcsHost's response file: one flat object of strings and a boolean. Requests are read with
+// JavaScriptSerializer (System.Web.Extensions, part of .NET 4.x).
+using System.Collections.Generic;
+using System.Text;
+
+namespace AgentSandbox.HcsHost
+{
+    public static class Json
+    {
+        public static string Quote(string text)
+        {
+            StringBuilder sb = new StringBuilder();
+            sb.Append('"');
+            if (text != null)
+            {
+                foreach (char ch in text)
+                {
+                    if (ch == '"')
+                    {
+                        sb.Append("\\\"");
+                    }
+                    else if (ch == '\\')
+                    {
+                        sb.Append("\\\\");
+                    }
+                    else if (ch == '\n')
+                    {
+                        sb.Append("\\n");
+                    }
+                    else if (ch == '\r')
+                    {
+                        sb.Append("\\r");
+                    }
+                    else if (ch == '\t')
+                    {
+                        sb.Append("\\t");
+                    }
+                    else if (ch < ' ')
+                    {
+                        sb.Append("\\u").Append(((int)ch).ToString("x4"));
+                    }
+                    else
+                    {
+                        sb.Append(ch);
+                    }
+                }
+            }
+            sb.Append('"');
+            return sb.ToString();
+        }
+
+        /// <summary>{"ok":..,"hresult":"0x..","message":"..","json":"..","values":{..}}</summary>
+        public static string Response(bool ok, int hresult, string message, string json, IDictionary<string, string> values)
+        {
+            StringBuilder sb = new StringBuilder();
+            sb.Append("{\"ok\":").Append(ok ? "true" : "false");
+            sb.Append(",\"hresult\":").Append(Quote("0x" + hresult.ToString("X8")));
+            sb.Append(",\"message\":").Append(Quote(message));
+            sb.Append(",\"json\":").Append(Quote(json));
+            sb.Append(",\"values\":{");
+            bool first = true;
+            if (values != null)
+            {
+                foreach (KeyValuePair<string, string> pair in values)
+                {
+                    if (!first)
+                    {
+                        sb.Append(',');
+                    }
+                    first = false;
+                    sb.Append(Quote(pair.Key)).Append(':').Append(Quote(pair.Value));
+                }
+            }
+            sb.Append("}}");
+            return sb.ToString();
+        }
+    }
+}

package/native/csharp/HcsHost/Program.cs

@@ -0,0 +1,185 @@
+// HcsHost.exe <verb> [arguments] --out <response.json>
+// Verbs: check, enumerate, properties <id>, create <request.json>, start <id>, terminate <id>,
+//        grant-vm-access <vmId> <file>, create-vhdx <path> <maxGb>.
+// The answer is one JSON file (see Json.Response); exit code 0 = ok, 1 = failed, 2 = wrong use. A create request is
+// {"id": "...", "document": "<the HCS document as a JSON string>"}. Never attaches a disk to this PC.
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Security.Principal;
+using System.Text;
+using System.Web.Script.Serialization;
+
+namespace AgentSandbox.HcsHost
+{
+    public static class Program
+    {
+        private const long MaxRequestBytes = 1024 * 1024;
+        private const int ExitOk = 0;
+        private const int ExitFailed = 1;
+        private const int ExitUsage = 2;
+        private static readonly SecurityIdentifier HyperVAdministrators = new SecurityIdentifier("S-1-5-32-578");
+
+        public static int Main(string[] args)
+        {
+            string outFile = null;
+            List<string> rest = new List<string>();
+            for (int i = 0; i < args.Length; i++)
+            {
+                if (args[i] == "--out" && i + 1 < args.Length)
+                {
+                    outFile = args[i + 1];
+                    i++;
+                }
+                else
+                {
+                    rest.Add(args[i]);
+                }
+            }
+            string response;
+            int code;
+            try
+            {
+                code = Dispatch(rest, out response);
+            }
+            catch (Exception ex)
+            {
+                response = Json.Response(false, ex.HResult, ex.Message, "", null);
+                code = ExitFailed;
+            }
+            Write(outFile, response);
+            return code;
+        }
+
+        private static void Write(string outFile, string text)
+        {
+            if (outFile == null)
+            {
+                Console.Out.WriteLine(text);
+                return;
+            }
+            File.WriteAllText(outFile, text, new UTF8Encoding(false));
+        }
+
+        private static int Usage(out string response, string what)
+        {
+            response = Json.Response(false, 0, "Usage: " + what, "", null);
+            return ExitUsage;
+        }
+
+        private static int FromReply(HcsReply reply, IDictionary<string, string> values, out string response)
+        {
+            response = Json.Response(reply.Ok, reply.HResult, reply.Message(), reply.Json, values);
+            return reply.Ok ? ExitOk : ExitFailed;
+        }
+
+        private static int Dispatch(List<string> args, out string response)
+        {
+            if (args.Count == 0)
+            {
+                return Usage(out response, "HcsHost <check|enumerate|properties|create|start|terminate|grant-vm-access|create-vhdx> ... --out file");
+            }
+            string verb = args[0];
+            if (verb == "check")
+            {
+                return Check(out response);
+            }
+            if (verb == "enumerate")
+            {
+                return FromReply(Hcs.Enumerate(null), null, out response);
+            }
+            if (verb == "properties" && args.Count == 2)
+            {
+                if (Refused(Guard.IdProblem(args[1]), out response))
+                {
+                    return ExitUsage;
+                }
+                return FromReply(Hcs.Properties(args[1], "{\"PropertyTypes\":[]}"), null, out response);
+            }
+            if (verb == "create" && args.Count == 2)
+            {
+                return Create(args[1], out response);
+            }
+            if ((verb == "start" || verb == "terminate") && args.Count == 2)
+            {
+                // Twice guarded: the id must look like ours, and HCS itself must say the system is ours.
+                if (Refused(Guard.IdProblem(args[1]), out response) || Refused(Guard.OwnerProblem(args[1]), out response))
+                {
+                    return ExitUsage;
+                }
+                return FromReply(verb == "start" ? Hcs.Start(args[1]) : Hcs.Terminate(args[1]), null, out response);
+            }
+            if (verb == "grant-vm-access" && args.Count == 3)
+            {
+                if (Refused(Guard.IdProblem(args[1]), out response) || Refused(Guard.DiskProblem(args[2]), out response))
+                {
+                    return ExitUsage;
+                }
+                return FromReply(Hcs.GrantVmAccess(args[1], args[2]), null, out response);
+            }
+            if (verb == "create-vhdx" && args.Count == 3)
+            {
+                long maxGb;
+                if (!long.TryParse(args[2], out maxGb))
+                {
+                    return Usage(out response, "create-vhdx <path> <maxGb>");
+                }
+                VirtualDisk.Create(args[1], maxGb);
+                response = Json.Response(true, 0, "ok", "", null);
+                return ExitOk;
+            }
+            return Usage(out response, "unknown verb or wrong number of arguments: " + verb);
+        }
+
+        /// <summary>Read-only facts: can computecore load, who am I, what does the service say.</summary>
+        private static int Check(out string response)
+        {
+            Dictionary<string, string> values = new Dictionary<string, string>();
+            values["computecore"] = Hcs.CanLoad("computecore.dll") ? "yes" : "no";
+            WindowsPrincipal principal = new WindowsPrincipal(WindowsIdentity.GetCurrent());
+            values["administrator"] = principal.IsInRole(WindowsBuiltInRole.Administrator) ? "yes" : "no";
+            values["hyperVAdministrators"] = principal.IsInRole(HyperVAdministrators) ? "yes" : "no";
+            if (values["computecore"] != "yes")
+            {
+                response = Json.Response(false, 0, "computecore.dll is not on this PC", "", values);
+                return ExitFailed;
+            }
+            HcsReply reply = Hcs.ServiceProperties(null);
+            return FromReply(reply, values, out response);
+        }
+
+        private static int Create(string requestFile, out string response)
+        {
+            FileInfo info = new FileInfo(requestFile);
+            if (!info.Exists || info.Length > MaxRequestBytes)
+            {
+                return Usage(out response, "create <request.json> (a file of at most 1 MB)");
+            }
+            JavaScriptSerializer serializer = new JavaScriptSerializer();
+            Dictionary<string, object> request = serializer.Deserialize<Dictionary<string, object>>(File.ReadAllText(requestFile, Encoding.UTF8));
+            object id;
+            object document;
+            if (!request.TryGetValue("id", out id) || !request.TryGetValue("document", out document) || !(id is string) || !(document is string))
+            {
+                return Usage(out response, "the request needs a text id and a text document");
+            }
+            if (Refused(Guard.IdProblem((string)id), out response) || Refused(Guard.DocumentProblem((string)document), out response))
+            {
+                return ExitUsage;
+            }
+            return FromReply(Hcs.Create((string)id, (string)document), null, out response);
+        }
+
+        /// <summary>True (with the refusal as the response) when `problem` says why the request is not allowed.</summary>
+        private static bool Refused(string problem, out string response)
+        {
+            if (problem == null)
+            {
+                response = null;
+                return false;
+            }
+            response = Json.Response(false, 0, "Refused: " + problem, "", null);
+            return true;
+        }
+    }
+}

package/native/csharp/HcsHost/VirtualDisk.cs

@@ -0,0 +1,95 @@
+// Creates a blank dynamic VHDX with CreateVirtualDisk (virtdisk.dll). The disk is never attached to this PC: no
+// AttachVirtualDisk, no mount, no drive letter. Signatures from the Microsoft virtdisk.h reference (not re-checked).
+using System;
+using System.ComponentModel;
+using System.IO;
+using System.Runtime.InteropServices;
+
+namespace AgentSandbox.HcsHost
+{
+    public static class VirtualDisk
+    {
+        private const uint VirtualStorageTypeDeviceVhdx = 3;
+        private static readonly Guid VendorMicrosoft = new Guid("EC984AEC-A0F9-47e9-901F-71415A66345B");
+        private const uint CreateVirtualDiskVersion1 = 1;
+        private const uint AccessNone = 0;
+        private const uint FlagNone = 0;
+
+        [StructLayout(LayoutKind.Sequential)]
+        private struct VirtualStorageType
+        {
+            public uint DeviceId;
+            public Guid VendorId;
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        private struct CreateVirtualDiskParametersV1
+        {
+            public uint Version;
+            public Guid UniqueId;
+            public ulong MaximumSize;
+            public uint BlockSizeInBytes;
+            public uint SectorSizeInBytes;
+            public IntPtr ParentPath;
+            public IntPtr SourcePath;
+        }
+
+        private static class NativeMethods
+        {
+            [DllImport("virtdisk.dll", CharSet = CharSet.Unicode)]
+            public static extern int CreateVirtualDisk(
+                ref VirtualStorageType storageType,
+                string path,
+                uint accessMask,
+                IntPtr securityDescriptor,
+                uint flags,
+                uint providerSpecificFlags,
+                ref CreateVirtualDiskParametersV1 parameters,
+                IntPtr overlapped,
+                out IntPtr handle);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern bool CloseHandle(IntPtr handle);
+        }
+
+        /// <summary>A new sparse VHDX of at most maxGb GB. An existing file is never touched.</summary>
+        public static void Create(string path, long maxGb)
+        {
+            if (!path.EndsWith(".vhdx", StringComparison.OrdinalIgnoreCase))
+            {
+                throw new ArgumentException("The disk file must end in .vhdx");
+            }
+            if (maxGb < 1 || maxGb > 4096)
+            {
+                throw new ArgumentException("The size must be 1 to 4096 GB");
+            }
+            if (File.Exists(path))
+            {
+                throw new IOException("The disk file already exists: " + path);
+            }
+            VirtualStorageType type = new VirtualStorageType();
+            type.DeviceId = VirtualStorageTypeDeviceVhdx;
+            type.VendorId = VendorMicrosoft;
+            CreateVirtualDiskParametersV1 parameters = new CreateVirtualDiskParametersV1();
+            parameters.Version = CreateVirtualDiskVersion1;
+            parameters.MaximumSize = (ulong)maxGb * 1024UL * 1024UL * 1024UL;
+            IntPtr handle = IntPtr.Zero;
+            try
+            {
+                // CreateVirtualDisk returns the error code itself (not through GetLastError).
+                int error = NativeMethods.CreateVirtualDisk(ref type, path, AccessNone, IntPtr.Zero, FlagNone, 0, ref parameters, IntPtr.Zero, out handle);
+                if (error != 0)
+                {
+                    throw new Win32Exception(error);
+                }
+            }
+            finally
+            {
+                if (handle != IntPtr.Zero && handle != new IntPtr(-1))
+                {
+                    NativeMethods.CloseHandle(handle);
+                }
+            }
+        }
+    }
+}

package/native/csharp/HostTools/AssemblyInfo.cs

@@ -0,0 +1,14 @@
+// What HostTools.exe says about itself in its file properties (publisher, product, description, version), so Windows,
+// antivirus software and you can tell what it is. It is built on this PC from the sources next to this file.
+using System.Reflection;
+using System.Runtime.InteropServices;
+
+[assembly: AssemblyTitle("Windows Development Sandbox host helper")]
+[assembly: AssemblyDescription("Helper of windows-development-sandbox (open source, MIT): keeps this PC awake while a sandbox runs, shows and hides the Windows Sandbox window, reads the Windows events that end a sandbox and adds its folder to your PATH. Source: https://github.com/JoshDiDuca/windows-development-sandbox")]
+[assembly: AssemblyCompany("windows-development-sandbox (open source)")]
+[assembly: AssemblyProduct("Windows Development Sandbox")]
+[assembly: AssemblyCopyright("MIT License, windows-development-sandbox contributors")]
+[assembly: AssemblyVersion("1.9.0.0")]
+[assembly: AssemblyFileVersion("1.9.0.0")]
+[assembly: AssemblyInformationalVersion("1.9.0")]
+[assembly: ComVisible(false)]