Lead.Sandbox 1.0.1

Lead

A secure, virtualized plugin sandbox for .NET 8+.

Lead loads any .NET assembly — including unsafe, P/Invoke, or unmanaged code — into an isolated environment where every operation is controlled, monitored, or virtualized. Plugins cannot tell whether they are running in a real system or a honeypot.

Why Lead?

.NET 10 currently lacks mature hook frameworks and embeddable sandbox solutions. Existing options either don't support .NET 10, require runtime instrumentation that breaks across framework versions, or provide only hard-deny isolation that malicious code can detect and evade.

Lead solves this by providing a pure managed-code sandbox that works on .NET 8+ and .NET 10 out of the box — no native hooks, no runtime patching, no framework-specific dependencies. The honeypot virtualization model makes plugins believe they are operating on a real system while all data is fake and all access is logged.

Features

• Load Any Assembly — no interface requirement, no format restriction; load any .NET DLL and execute it safely
• Static Analysis — IL-level scanning detects unsafe code, P/Invoke, reflection, dynamic IL generation, and 40+ attack vectors; results are advisory by default, blockable via StrictValidation
• Runtime Isolation — AssemblyLoadContext blocks native DLL loading, restricts dangerous system assemblies, and isolates plugin dependencies
• Virtualization — Three modes for file/HTTP access:
  • Block — hard deny with error codes
  • Redirect — transparent path/URL remapping into sandbox VFS
  • Honeypot — returns realistic fake data, silently logs all access
• Service Injection — plugins receive only the APIs you register; nothing else is accessible
• Resource Limits — file size, I/O throughput, HTTP request count, execution timeout
• Custom Redirectors — implement IFileRedirector / IHttpResponder to define your own virtualization logic

Quick Start

Load an ISandboxedPlugin

using Lead;

var config = new SandboxConfiguration
{
    SandboxRootDirectory = "./sandbox_data",
    AllowedUrlPatterns = { @"^https://api\.example\.com/.*$" },
    MaxExecutionSeconds = 30
};

config.UseHoneypotDefaults();

using var loader = new PluginLoader(config);

var result = await loader.LoadPluginAsync("ThirdPartyPlugin.dll");
if (result.Success)
{
    await loader.ExecutePluginAsync(result.PluginId);
    loader.UnloadPlugin(result.PluginId);
}

Load Any Assembly

var config = new SandboxConfiguration();
config.UseHoneypotDefaults();

using var loader = new PluginLoader(config);

var result = await loader.LoadPluginAsync("SomeUnsafeLibrary.dll");
// result.IsRawAssembly == true — no ISandboxedPlugin interface found
// result.Validation contains static analysis warnings (not errors)

if (result.Success)
{
    // Invoke a specific method by name
    var output = await loader.InvokeMethodAsync(
        result.PluginId,
        typeName: "SomeNamespace.SomeClass",
        methodName: "ProcessData",
        args: new object[] { "input" }
    );

    // Or get the Assembly for reflection
    var assembly = loader.GetLoadedAssembly(result.PluginId);

    loader.UnloadPlugin(result.PluginId);
}

Strict Mode (Block Unsafe Code)

var config = new SandboxConfiguration
{
    StrictValidation = true  // reject assemblies with unsafe code
};

Writing a Plugin

using Lead;

public class MyPlugin : ISandboxedPlugin
{
    private IPluginContext? _ctx;

    public string Id => "my-plugin";
    public string Name => "My Plugin";
    public string Version => "1.0.0";

    public void Initialize(IPluginContext context) => _ctx = context;

    public async Task ExecuteAsync(CancellationToken ct)
    {
        var fs = _ctx!.GetService<IFileService>();
        var content = await fs!.ReadTextFileAsync("data.txt", ct);
    }

    public void Shutdown() { }
}

Redirect Modes

Custom Virtualization

// Custom virtual files
var redirector = new VirtualFileRedirector();
redirector.AddVirtualFile(@"C:\Secret\db.txt", "host=10.0.0.1;password=honey");
config.FileRedirector = redirector;

// Custom HTTP responses
var responder = new HoneypotHttpResponder();
responder.AddResponder("http://internal-api/users", "[{\"id\":1,\"name\":\"John\"}]");
config.HttpResponder = responder;

// Or implement your own
config.FileRedirector = new MyCustomRedirector();
config.HttpResponder = new MyCustomResponder();

License

MIT