Add plugin support: load custom protections from a plugins directory (#227)

Drop plugin DLLs (custom IProtection implementations) into a `plugins`
directory and BitMono discovers and runs them like the built-ins. External
plugin dependencies are resolved via a single AppDomain.AssemblyResolve
handler, which is the only mechanism that works across every BitMono target
(net462, netstandard2.0/2.1, net6-net10) since AssemblyLoadContext is absent
on the older ones.

- PluginLoader + PluginProbing in BitMono.Shared, hooked from AddProtections
- The resolver prefers already-loaded host assemblies so plugins bind to the
  host's BitMono.API (avoids the duplicate-contract trap), then probes the
  plugin directories; the hook is AppDomain-global and attached once
- Plugins live at the plugins root or one folder deep; nested folders (e.g.
  a libs/ of NuGet deps) are resolved lazily by the handler
- Type discovery now uses IProtection.IsAssignableFrom (warns on a shadowed
  BitMono.API), skips open generics, and instantiates each protection
  defensively so one broken plugin can't abort the run
- PluginsDirectoryName setting in obfuscation.json (default "plugins")
- Unit tests for the probing logic and developer docs (developers/plugins)

Closes #227

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sunnamed434

README.md

@@ -84,6 +84,7 @@ Read the **[docs][bitmono_docs]** to read protection, functionality, and more.
 * AntiDe4dot
 * AntiILdasm
 * and you can integrate existing/make own feature ;)
+* **Plugins** - drop your own protections in a `plugins` folder, no rebuild required ([guide](https://bitmono.readthedocs.io/en/latest/developers/plugins.html))
 
 ## Documentation
 

docs/source/developers/plugins.rst

@@ -0,0 +1,143 @@
+Plugins
+=======
+
+BitMono can load **plugins** - external assemblies that contribute your own protections - without
+rebuilding BitMono. Drop a plugin DLL into the plugins directory and BitMono discovers and runs the
+protections inside it, exactly like the built-in ones. (`#227 <https://github.com/sunnamed434/BitMono/issues/227>`_)
+
+.. warning::
+
+    Plugins are loaded into the BitMono process with full trust - .NET cannot sandbox them. Only drop
+    in plugins from sources you trust, just as you would with any other executable.
+
+
+Where plugins live
+------------------
+
+By default BitMono scans a ``plugins`` directory next to the BitMono executable. You can change the
+directory name (or point it at an absolute path) with ``PluginsDirectoryName`` in ``obfuscation.json``:
+
+.. code-block:: json
+
+    {
+      "PluginsDirectoryName": "plugins"
+    }
+
+Two layouts are supported:
+
+- **Flat** - drop the DLL straight into the directory: ``plugins/MyProtections.dll``.
+- **Per-plugin folder** - give each plugin its own folder: ``plugins/MyProtections/MyProtections.dll``.
+  Put any extra dependencies in a nested folder (for example ``plugins/MyProtections/libs/``); they are
+  resolved on demand and are not themselves treated as plugins.
+
+If the directory does not exist, BitMono simply skips plugin loading.
+
+
+Writing a plugin
+----------------
+
+A plugin is an ordinary class library that references ``BitMono.API`` (and usually ``BitMono.Core`` for
+the ``Protection`` base class) and exposes one or more public protections. Writing a protection is the
+same as :doc:`creating a built-in one <first-protection>`:
+
+.. code-block:: csharp
+
+    using BitMono.Core;
+    using BitMono.Core.Attributes;
+    using BitMono.Shared.DependencyInjection;
+    using BitMono.Shared.Logging;
+
+    [ProtectionName("HelloPlugin")]
+    public class HelloPlugin : Protection
+    {
+        private readonly ILogger _logger;
+
+        public HelloPlugin(IBitMonoServiceProvider serviceProvider) : base(serviceProvider)
+        {
+            _logger = serviceProvider.GetRequiredService<ILogger>().ForContext<HelloPlugin>();
+        }
+
+        public override Task ExecuteAsync()
+        {
+            _logger.Information("Hello from a BitMono plugin!");
+            return Task.CompletedTask;
+        }
+    }
+
+.. note::
+
+    The container builds your protection by calling its **first** constructor and resolving each
+    parameter. Take ``IBitMonoServiceProvider`` (as above) to reach BitMono's services. If a parameter
+    cannot be resolved the protection is skipped and the error is logged - it never aborts the run.
+
+
+.. _plugins-reference-the-host:
+
+Reference BitMono, don't ship it
+--------------------------------
+
+Reference the BitMono assemblies with ``Private="false"`` so they are **not** copied next to your
+plugin. Your plugin must bind to the *same* ``BitMono.API`` the host is running; if you ship your own
+copy, your protection implements a *different* ``IProtection`` type and BitMono will ignore it (and warn
+you in the log).
+
+.. code-block:: xml
+
+    <ItemGroup>
+      <Reference Include="BitMono.API">
+        <HintPath>path\to\BitMono.API.dll</HintPath>
+        <Private>false</Private>
+      </Reference>
+      <Reference Include="BitMono.Core">
+        <HintPath>path\to\BitMono.Core.dll</HintPath>
+        <Private>false</Private>
+      </Reference>
+      <Reference Include="BitMono.Shared">
+        <HintPath>path\to\BitMono.Shared.dll</HintPath>
+        <Private>false</Private>
+      </Reference>
+    </ItemGroup>
+
+
+External dependencies
+---------------------
+
+If your plugin uses external libraries (NuGet packages, your own helpers), ship those DLLs alongside the
+plugin - either next to it or in a nested folder such as ``libs``. BitMono installs an
+``AppDomain.AssemblyResolve`` handler that probes the plugin directories and loads dependencies on
+demand, so they don't have to sit in BitMono's own folder.
+
+A typical per-plugin layout::
+
+    plugins/
+      MyProtections/
+        MyProtections.dll        <- your plugin
+        libs/
+          SomeNuGetPackage.dll   <- resolved automatically when needed
+
+
+Enabling a plugin protection
+----------------------------
+
+Plugin protections are configured exactly like the built-in ones - by name (the class name, or the
+``[ProtectionName("...")]`` value). Add them to ``protections.json``:
+
+.. code-block:: json
+
+    {
+      "Protections": [
+        {
+          "Name": "HelloPlugin",
+          "Enabled": true
+        }
+      ]
+    }
+
+or pass them on the command line:
+
+.. code-block:: bash
+
+    BitMono.CLI -f MyApp.dll -p HelloPlugin
+
+Execution order follows the configuration order, the same as built-in protections. See
+:doc:`obfuscation-execution-order` for details.

docs/source/index.rst

@@ -60,6 +60,7 @@ Table of Contents:
    :name: sec-developers
 
    developers/first-protection
+   developers/plugins
    developers/obfuscation-execution-order
    developers/which-base-protection-select
    developers/protection-runtime-moniker

src/BitMono.Host/Extensions/ContainerExtensions.cs

@@ -1,5 +1,8 @@
 using BitMono.API.Protections;
 using BitMono.Shared.DependencyInjection;
+using BitMono.Shared.Logging;
+using BitMono.Shared.Models;
+using BitMono.Shared.Plugins;
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
@@ -18,9 +21,10 @@ public static class BitMonoContainerExtensions
 {
     private const string ProtectionsFileName = "BitMono.Protections.dll";
     private const string UnityFileName = "BitMono.Unity.dll";
+    private const string DefaultPluginsDirectoryName = "plugins";
 
     /// <summary>
-    /// Loads and registers protection assemblies.
+    /// Loads and registers protection assemblies, including any drop-in plugins (see #227).
     /// </summary>
     /// <param name="container">Container to register protections in</param>
     /// <param name="file">Optional path to protections DLL</param>
@@ -38,6 +42,12 @@ public static Container AddProtections(this Container container, string? file =
             Assembly.Load(unityRawData);
         }
 
+        var logger = container.GetService(typeof(ILogger)) as ILogger;
+
+        // Load drop-in plugins before scanning so their protections are discovered alongside the built-ins.
+        LoadPlugins(container, logger);
+
+        var scanLogger = logger?.ForContext(typeof(BitMonoContainerExtensions));
         var assemblies = AppDomain.CurrentDomain.GetAssemblies();
 
         // Collect all protection types (excluding IPhaseProtection)
@@ -52,23 +62,37 @@ public static Container AddProtections(this Container container, string? file =
             catch (ReflectionTypeLoadException ex)
             {
                 types = ex.Types.Where(t => t != null).ToArray()!;
+                scanLogger?.Warning("Some types in '{0}' could not be loaded: {1}",
+                    assembly.GetName().Name ?? assembly.FullName ?? "?",
+                    string.Join("; ", ex.LoaderExceptions.Where(e => e != null).Select(e => e!.Message).Distinct()));
             }
 
             foreach (var type in types)
             {
-                if (!type.IsClass || type.IsAbstract || !type.IsPublic)
+                // Open generic definitions can't be instantiated by the container, so skip them.
+                if (!type.IsClass || type.IsAbstract || !type.IsPublic || type.IsGenericTypeDefinition)
                     continue;
 
-                // Skip IPhaseProtection, only register IProtection
-                if (type.GetInterface(nameof(IPhaseProtection)) != null)
+                // IPhaseProtection extends IProtection, so it MUST be checked first - phase protections
+                // are driven by their pipeline, not registered as standalone protections.
+                if (typeof(IPhaseProtection).IsAssignableFrom(type))
                     continue;
 
-                if (type.GetInterface(nameof(IProtection)) != null)
+                if (typeof(IProtection).IsAssignableFrom(type))
                 {
                     protectionTypes.Add(type);
                     // Register the concrete type
                     container.Register(type, type).AsSingleton();
                 }
+                else if (type.GetInterfaces().Any(i => i.Name == nameof(IProtection)))
+                {
+                    // Implements an interface *named* IProtection but not BitMono's contract - almost always
+                    // a plugin shipping its own copy of BitMono.API, which would be silently ignored (#227).
+                    scanLogger?.Warning(
+                        "Type '{0}' in '{1}' looks like a protection but references a different BitMono.API and " +
+                        "will be ignored. Reference BitMono.API with Private=\"false\" and don't ship it beside your plugin.",
+                        type.FullName ?? type.Name, type.Assembly.GetName().Name ?? "?");
+                }
             }
         }
 
@@ -78,15 +102,43 @@ public static Container AddProtections(this Container container, string? file =
             var list = new List<IProtection>();
             foreach (var protType in protectionTypes)
             {
-                var instance = container.GetService(protType);
-                if (instance is IProtection protection)
+                try
+                {
+                    var instance = container.GetService(protType);
+                    if (instance is IProtection protection)
+                    {
+                        list.Add(protection);
+                    }
+                }
+                catch (Exception ex)
                 {
-                    list.Add(protection);
+                    // A broken plugin protection must not abort the whole run - log and skip it (#227).
+                    scanLogger?.Error(ex,
+                        "Failed to instantiate protection '{0}'. Its constructor parameters must be resolvable by the container.",
+                        protType.FullName ?? protType.Name);
                 }
             }
             return list;
         }).AsSingleton();
 
         return container;
     }
+
+    private static void LoadPlugins(Container container, ILogger? logger)
+    {
+        // No logger means the host wasn't fully set up; plugin loading relies on logging for diagnostics.
+        if (logger == null)
+            return;
+
+        var obfuscationSettings = container.GetService(typeof(ObfuscationSettings)) as ObfuscationSettings;
+        var directoryName = obfuscationSettings?.PluginsDirectoryName;
+        if (string.IsNullOrWhiteSpace(directoryName))
+            directoryName = DefaultPluginsDirectoryName;
+
+        var pluginsDirectory = Path.IsPathRooted(directoryName)
+            ? directoryName!
+            : Path.Combine(AppContext.BaseDirectory, directoryName!);
+
+        new PluginLoader(pluginsDirectory, logger).LoadPlugins();
+    }
 }

src/BitMono.Host/obfuscation.json

@@ -24,6 +24,11 @@
   // Name of the output directory
   "OutputDirectoryName": "output",
 
+  // Directory scanned for drop-in plugins (custom protections). Drop a plugin DLL here (or in a
+  // subfolder with its dependencies) and BitMono loads it on start. Relative paths are resolved
+  // against BitMono's base directory; absolute paths are used as-is. See the Plugins docs.
+  "PluginsDirectoryName": "plugins",
+
   // Outputs information about protections (Enabled protections, disabled, deprecated, unknown, etc)
   // Set to true indicates whether enabled
   "NotifyProtections": true,

src/BitMono.Shared/Models/ObfuscationSettings.cs

@@ -7,6 +7,10 @@ public class ObfuscationSettings
     public bool ForceObfuscation { get; set; }
     public string ReferencesDirectoryName { get; set; }
     public string OutputDirectoryName { get; set; }
+
+    // Directory scanned for drop-in plugin assemblies that contain custom protections. Relative paths
+    // are resolved against BitMono's base directory; absolute paths are used as-is. See #227.
+    public string PluginsDirectoryName { get; set; } = "plugins";
     public bool NotifyProtections { get; set; }
     public bool Tips { get; set; } = true;
     public bool WpfBamlRewrite { get; set; } = true;