Skip to content
← Todas las publicaciones
· Delta1 Labs SemanticKernelNebula

Ofuscar un plugin de Semantic Kernel de forma segura

Un plugin [KernelFunction] es un contrato descubierto por reflexión que se envía al LLM como esquema de herramientas. El nombre de la función, los nombres de los parámetros y las descripciones son portadores; el cuerpo del método es tu PI. Fija los nombres con atributos para que los identificadores se renombren libremente y deja que Nebula blinde la implementación.

La mayoría de los consejos de “no ofusques esto” tienen que ver con la serialización: el nombre de un miembro es también la clave del cable, así que renombrarlo rompe el contrato. Un plugin de Semantic Kernel es la misma historia con ropa nueva. Escribes una clase C# normal, decoras algunos métodos con [KernelFunction], y el Kernel convierte esa clase —por reflexión— en un esquema de herramientas JSON que envía al modelo de lenguaje. El nombre de la función, los nombres de los parámetros y las descripciones son el contrato que el modelo lee y vuelve a invocar. Los cuerpos de los métodos son tu propiedad intelectual. Ofuscar un plugin con seguridad consiste por completo en distinguir esas dos cosas.

Cómo Semantic Kernel convierte una clase en herramientas

Un plugin es una clase cuyos métodos llevan [KernelFunction]. La firma y los atributos de cada método se convierten en una herramienta del esquema enviado al modelo:

using System.ComponentModel;
using Microsoft.SemanticKernel;

public sealed class ForecastPlugin
{
    private readonly IWeatherSource _source;
    public ForecastPlugin(IWeatherSource source) => _source = source;

    [KernelFunction("get_forecast")]
    [Description("Gets the multi-day weather forecast for a city.")]
    public async Task<string> GetForecastAsync(
        [Description("City name, e.g. 'Berlin'.")] string city,
        [Description("Number of days, 1-7.")] int days = 3)
    {
        var readings = await _source.QueryAsync(city, days);
        return Blend(readings);          // mezcla de modelos propietaria — tu PI
    }

    private string Blend(IReadOnlyList<Reading> readings) { /* ... */ }
}

Lo importas bajo un nombre de plugin y dejas que el modelo lo llame:

var builder = Kernel.CreateBuilder();
builder.Services.AddSingleton<IWeatherSource, NoaaWeatherSource>();
var kernel = builder.Build();
kernel.ImportPluginFromType<ForecastPlugin>("weather");

En el momento de la llamada, el Kernel reflexiona sobre el plugin y emite una definición de herramienta. Con el conector de OpenAI tiene este aspecto —fíjate en el separador - que une el nombre del plugin con el de la función, porque los nombres de herramienta de OpenAI deben cumplir ^[a-zA-Z0-9_-]+$:

{
  "type": "function",
  "function": {
    "name": "weather-get_forecast",
    "description": "Gets the multi-day weather forecast for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string",  "description": "City name, e.g. 'Berlin'." },
        "days": { "type": "integer", "description": "Number of days, 1-7." }
      },
      "required": ["city"]
    }
  }
}

Cada cadena de ese JSON vino de la reflexión: weather de la llamada de importación, get_forecast del atributo, city/days de los nombres de los parámetros, y las descripciones de [Description]. Los identificadores CLR ForecastPlugin, GetForecastAsync, _source y Blend no aparecen en ninguna parte de él. Esa separación es toda la oportunidad.

Los tres niveles de nombres

Cada identificador de un plugin cae en uno de tres niveles, y cada nivel tiene una respuesta de ofuscación distinta.

Reflejado en el esquema de herramientas JSON que lee el modeloNIVEL 1 — FIJA con cadenas (los identificadores luego se renombran)ImportPluginFromType<T>("weather")[KernelFunction("get_forecast")]NIVEL 2 — MANTÉN legible (ya lo ve el LLM)(string city, int days) — nombres de parámetro[Description("...")] — en el blob de metadatosEl modelo de lenguajellama: weather-get_forecastargs: { city, days }esquemaNIVEL 3 — tu PI · renombrado total + flujo de control + cifrado de cadenasclass ForecastPlugin → p0 GetForecastAsync → aBlend() IWeatherSource NoaaWeatherSource → renombradoscuerpos de método aplanados · literales de ruta y umbral cifrados · nada aquí llega al modelo

Nivel 1 — fija el nombre del plugin y de las funciones, y deja que los identificadores se renombren

El nombre del plugin y el de la función son la identidad visible para el modelo de la herramienta. Los haces independientes de tus nombres CLR suministrándolos como cadenas:

  • kernel.ImportPluginFromType<ForecastPlugin>("weather") fija el nombre del plugin al literal "weather".
  • [KernelFunction("get_forecast")] fija el nombre de la función al literal "get_forecast".

Una vez que ambos son explícitos, el nombre del tipo y el del método no llevan contrato alguno. Un ofuscador puede renombrar ForecastPlugin a p0 y GetForecastAsync a a, y el Kernel sigue emitiendo weather-get_forecast, porque el esquema se construye a partir de la cadena del atributo y la cadena de importación, no de los identificadores. Es exactamente el hábito [AliasAs] / [ProtoMember(N)] de los contratos de serialización, aplicado a los metadatos de las herramientas: fija el nombre del cable y el nombre del código queda libre.

Nivel 2 — nombres de parámetro y descripciones: consérvalos, no los ocultes

Los nombres de los parámetros son distintos del nombre de la función, porque Semantic Kernel no tiene ningún atributo para sobrescribirlos: lee ParameterInfo.Name directamente al esquema. Así que city y days se convierten en las claves de propiedad del esquema tal cual. Podrías dejar que el ofuscador los renombrara: SK vincula los argumentos devueltos por el modelo por el mismo nombre reflejado, así que a y b aún funcionarían mecánicamente. No lo hagas. Dos razones:

  1. El valor de seguridad es nulo. Esos nombres ya se envían al modelo en texto plano en cada llamada. Renombrarlos en el binario no oculta nada que un atacante no pudiera leer observando una sola petición.
  2. El coste de calidad es real. El modelo elige los argumentos en parte por los nombres de las propiedades. Un esquema de { "a": ..., "b": ... } con buenas descripciones llama peor que { "city": ..., "days": ... }. Estarías pagando precisión por oscurecer algo que ya es público.

Las cadenas de [Description] están en el mismo nivel y se cuidan solas. Un argumento [Description("...")] se almacena en el blob del atributo personalizado en los metadatos, no como un ldstr en el cuerpo de un método, así que el cifrado de cadenas —que reescribe las cargas de cadenas del cuerpo del método— nunca lo toca. SK lo lee por reflexión y lo envía al modelo sin cambios. Ese es el comportamiento que quieres.

Nivel 3 — la implementación es la PI

Todo lo que no llega al modelo es donde la ofuscación se gana el sueldo: los cuerpos de los métodos de tus [KernelFunction], el ayudante privado Blend, la abstracción IWeatherSource y su implementación NoaaWeatherSource, los DTO como Reading, y cada literal de cadena dentro de esos cuerpos —rutas de API, fragmentos de prompt, umbrales de ranking—. Renómbralos todos, aplana el flujo de control y cifra las cadenas de los cuerpos. Nada de ello forma parte del esquema de herramientas, así que nada está limitado por la frontera del modelo.

La trampa: una función sin nombre se renombra en silencio

Este es el fallo que no produce ninguna excepción. Supón que te saltaste ambos nombres explícitos:

[KernelFunction]                                   // el nombre toma por defecto el del método
public async Task<string> GetForecastAsync(...) { }

kernel.ImportPluginFromType<ForecastPlugin>();     // el nombre del plugin toma el del tipo

Ahora la identidad de la herramienta deriva de tus identificadores: el modelo ve ForecastPlugin-GetForecastAsync. Ejecuta el ofuscador y esos identificadores se renombran a p0 y a, así que el esquema se convierte en silencio en:

{ "function": { "name": "p0-a", "parameters": { "properties": { "a": {...}, "b": {...} } } } }

Nada lanza una excepción. El Kernel genera el esquema con los nombres que tengan ahora los miembros y vincula las respuestas por esos mismos nombres, así que un viaje de ida y vuelta aún funciona. Pero todo lo que se refería a la herramienta por su nombre antiguo queda ahora roto:

  • Un literal de plantilla de prompt como {{ForecastPlugin.GetForecastAsync $city}} resuelve contra una función que ya no existe.
  • Los prompts de sistema, los ejemplos de pocos disparos y las pistas del planificador que nombran la herramienta apuntan a un fantasma.
  • Los registros de conversación y las evaluaciones offline indexados por ForecastPlugin-GetForecastAsync dejan de coincidir en silencio.

Es el clásico fallo de renombrado de serialización: ningún error, solo un contrato que se movió bajo los pies de todos los que dependían de él. El arreglo es el Nivel 1: fija los nombres con cadenas y el renombrado se vuelve invisible para el modelo.

La configuración de Nebula

Como la identidad de la función está fijada por cadenas, casi no hay nada que conservar. No necesitas preservar el tipo del plugin ni los nombres de sus métodos: son libres de renombrarse. Lo único que la reflexión lleva al esquema y que debes proteger son los nombres de los parámetros. Limita una regla de preservación a los métodos que llevan [KernelFunction] y deja que todo lo demás se renombre. En MSBuild:

<Nebula>
  <!-- El nombre del plugin y los nombres de función están fijados por
       literales de cadena (el argumento de ImportPluginFromType("weather")
       y [KernelFunction("get_forecast")]), así que los identificadores de
       tipo y método se renombran libremente. Lo único que la reflexión
       convierte en el esquema visible para el modelo son los nombres de
       parámetro — consérvalos. -->
  <Preserve parameters="true"
            attribute="Microsoft.SemanticKernel.KernelFunctionAttribute" />
</Nebula>

Si diriges la protección desde un nebula.config.json en su lugar, la misma intención se lee como una entrada de conservación estrecha más transformaciones completas en todo lo demás:

{
  "input": "bin/Release/net8.0/Acme.Ai.Plugins.dll",
  "output": "dist/Acme.Ai.Plugins.dll",
  "rename": {
    "enabled": true,
    "renameParameters": true
  },
  "stringEncryption": { "enabled": true },
  "controlFlow": { "enabled": true },
  "keep": [
    {
      "comment": "Keep parameter names on KernelFunction methods — reflection makes them the JSON tool-schema property names the model reads. Type and method names still rename.",
      "attribute": "Microsoft.SemanticKernel.KernelFunctionAttribute",
      "keepParameters": true
    }
  ]
}

Fíjate en lo que no está en esa regla de conservación: keepName y keepMembers están ausentes, así que la clase del plugin y sus métodos se renombran con normalidad. Luego ejecuta el protector contra el ensamblado compilado:

nebula protect --config nebula.config.json

La integración en tiempo de compilación es una función Pro de Nebula; la edición gratuita ejecuta las mismas transformaciones desde la CLI con topes.

Verificar que el esquema de herramientas no ha cambiado

La prueba de que la ofuscación no tocó el contrato es que el esquema que recibe el modelo es idéntico byte a byte antes y después. Semantic Kernel lo expone sin una llamada de red a través de KernelFunctionMetadata, así que puedes hacer aserciones sobre él directamente:

var fn = kernel.Plugins["weather"]["get_forecast"];
var md = fn.Metadata;

Console.WriteLine(md.Name);                       // get_forecast
Console.WriteLine(string.Join(",", md.Parameters.Select(p => p.Name)));  // city,days

Ejecuta eso contra el ensamblado original y luego contra la salida de nebula protect —con ForecastPlugin renombrado a p0, GetForecastAsync renombrado a a, el ayudante Blend renombrado y su cuerpo aplanado, y los literales de ruta dentro de él cifrados—. Ambas ejecuciones imprimen get_forecast y city,days, porque el nombre de la función vino de la cadena del atributo, los nombres de los parámetros se conservaron y las descripciones viven en el blob de metadatos. El modelo ve una herramienta idéntica; tu implementación es ilegible.

Resumen

Un plugin de Semantic Kernel es un contrato de serialización dirigido a un modelo de lenguaje. Clasifica cada identificador en tres niveles: fija los nombres del plugin y de las funciones con argumentos de cadena para que los nombres de tipo y método se renombren libremente (Nivel 1); conserva los nombres de los parámetros y deja que las descripciones viajen en los metadatos, porque el modelo ya los lee y ocultarlos solo cuesta precisión (Nivel 2); y vuelca todo el peso del renombrado, el aplanamiento del flujo de control y el cifrado de cadenas sobre los cuerpos de los métodos y los ayudantes que son tu verdadera PI (Nivel 3). Fija los nombres, conserva los parámetros, blinda el resto, y deja que Nebula Pro proteja la implementación mientras el modelo nunca se entera.

Prueba Nebula.NET

Endurece tu código .NET en minutos — empieza con la edición gratuita.