windows-development-sandbox 1.5.0 → 1.9.0

package/native/csharp/HcsHost/Guard.cs

@@ -0,0 +1,100 @@
+// What HcsHost may touch: only compute systems this tool created (id prefix and Owner), and only disk files it made
+// (.vhdx, not a link). A wrong or tampered id can never reach Windows Sandbox, WSL, Docker or anything else on this PC.
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Text.RegularExpressions;
+using System.Web.Script.Serialization;
+
+namespace AgentSandbox.HcsHost
+{
+    public static class Guard
+    {
+        public const string IdPrefix = "agent-sandbox-";
+        public const string Owner = "agent-sandbox";
+        private const int MaxIdLength = 120;
+        private static readonly Regex SafeId = new Regex("^agent-sandbox-[A-Za-z0-9._-]{1,100}$");
+
+        /// <summary>Null when the id is one of ours by its shape; otherwise why not.</summary>
+        public static string IdProblem(string id)
+        {
+            if (id == null || id.Length > MaxIdLength || !SafeId.IsMatch(id))
+            {
+                return "only compute systems whose id starts with " + IdPrefix + " can be used";
+            }
+            return null;
+        }
+
+        /// <summary>Null when an HCS document says it belongs to this tool (top-level "Owner").</summary>
+        public static string DocumentProblem(string document)
+        {
+            Dictionary<string, object> parsed;
+            try
+            {
+                parsed = new JavaScriptSerializer().Deserialize<Dictionary<string, object>>(document);
+            }
+            catch (ArgumentException)
+            {
+                return "the document is not JSON";
+            }
+            catch (InvalidOperationException)
+            {
+                return "the document is not JSON";
+            }
+            object owner;
+            if (parsed == null || !parsed.TryGetValue("Owner", out owner) || !(owner is string) || (string)owner != Owner)
+            {
+                return "the document's Owner must be " + Owner;
+            }
+            return null;
+        }
+
+        /// <summary>Null when the running system `id` reports this tool as its Owner (asked from HCS itself).</summary>
+        public static string OwnerProblem(string id)
+        {
+            HcsReply reply = Hcs.Properties(id, "{\"PropertyTypes\":[]}");
+            if (!reply.Ok)
+            {
+                return "its properties could not be read: " + reply.Message();
+            }
+            Dictionary<string, object> parsed;
+            try
+            {
+                parsed = new JavaScriptSerializer().Deserialize<Dictionary<string, object>>(reply.Json);
+            }
+            catch (ArgumentException)
+            {
+                return "its properties are not JSON";
+            }
+            catch (InvalidOperationException)
+            {
+                return "its properties are not JSON";
+            }
+            object owner;
+            if (parsed == null || !parsed.TryGetValue("Owner", out owner) || !(owner is string) || (string)owner != Owner)
+            {
+                return "it does not belong to this tool (Owner is not " + Owner + ")";
+            }
+            return null;
+        }
+
+        /// <summary>Null when `path` is an existing .vhdx file that is not a link (a disk this tool made).</summary>
+        public static string DiskProblem(string path)
+        {
+            if (string.IsNullOrEmpty(path) || !Path.IsPathRooted(path) || !path.EndsWith(".vhdx", StringComparison.OrdinalIgnoreCase))
+            {
+                return "only a full path to a .vhdx file can be used";
+            }
+            FileInfo info = new FileInfo(path);
+            if (!info.Exists)
+            {
+                return "the disk file does not exist";
+            }
+            if ((info.Attributes & FileAttributes.ReparsePoint) != 0)
+            {
+                return "the disk file is a link";
+            }
+            return null;
+        }
+    }
+}

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;
+        }
+    }
+}