Skip to content
← Tous les articles
· Delta1 Labs SemanticKernelNebula

Obfusquer un plugin Semantic Kernel en toute sécurité

Un plugin [KernelFunction] est un contrat découvert par réflexion, envoyé au LLM sous forme de schéma d'outil. Le nom de la fonction, les noms des paramètres et les descriptions sont porteurs ; le corps de la méthode est votre PI. Fixez les noms avec des attributs pour que les identifiants se renomment librement, puis laissez Nebula blinder l'implémentation.

La plupart des conseils « n”obfusquez pas ceci » concernent la sérialisation : le nom d”un membre est aussi la clé du fil, donc le renommer casse le contrat. Un plugin Semantic Kernel est la même histoire sous des habits neufs. Vous écrivez une classe C# ordinaire, décorez quelques méthodes avec [KernelFunction], et le Kernel transforme cette classe — par réflexion — en un schéma d”outil JSON qu”il envoie au modèle de langage. Le nom de la fonction, les noms des paramètres et les descriptions sont le contrat que le modèle lit et rappelle. Les corps des méthodes sont votre propriété intellectuelle. Obfusquer un plugin en toute sécurité consiste entièrement à distinguer ces deux choses.

Comment Semantic Kernel transforme une classe en outils

Un plugin est une classe dont les méthodes portent [KernelFunction]. La signature et les attributs de chaque méthode deviennent un outil dans le schéma envoyé au modèle :

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);          // mélange de modèles propriétaire — votre PI
    }

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

Vous l”importez sous un nom de plugin et laissez le modèle l”appeler :

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

Au moment de l”appel, le Kernel réfléchit sur le plugin et émet une définition d”outil. Avec le connecteur OpenAI, elle ressemble à ceci — notez le séparateur - qui joint le nom du plugin à celui de la fonction, car les noms d”outils OpenAI doivent respecter ^[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"]
    }
  }
}

Chaque chaîne de ce JSON vient de la réflexion : weather de l”appel d”importation, get_forecast de l”attribut, city/days des noms des paramètres, et les descriptions de [Description]. Les identifiants CLR ForecastPlugin, GetForecastAsync, _source et Blend n”y apparaissent nulle part. Cette séparation est toute l”opportunité.

Les trois niveaux de noms

Chaque identifiant d”un plugin tombe dans l”un des trois niveaux, et chaque niveau a une réponse d”obfuscation différente.

Réfléchi dans le schéma d'outil JSON que lit le modèleNIVEAU 1 — FIXEZ avec des chaînes (les identifiants se renomment ensuite)ImportPluginFromType<T>("weather")[KernelFunction("get_forecast")]NIVEAU 2 — GARDEZ lisible (déjà vu par le LLM)(string city, int days) — noms de paramètres[Description("...")] — dans le blob de métadonnéesLe modèle de langageappelle : weather-get_forecastargs : { city, days }schémaNIVEAU 3 — votre PI · renommage total + flux de contrôle + chiffrement des chaînesclass ForecastPlugin → p0 GetForecastAsync → aBlend() IWeatherSource NoaaWeatherSource → renomméscorps de méthode aplatis · littéraux de route et de seuil chiffrés · rien ici n'atteint le modèle

Niveau 1 — fixez les noms du plugin et des fonctions, puis laissez les identifiants se renommer

Le nom du plugin et celui de la fonction sont l”identité visible par le modèle de l”outil. Vous les rendez indépendants de vos noms CLR en les fournissant sous forme de chaînes :

  • kernel.ImportPluginFromType<ForecastPlugin>("weather") fixe le nom du plugin au littéral "weather".
  • [KernelFunction("get_forecast")] fixe le nom de la fonction au littéral "get_forecast".

Une fois que les deux sont explicites, le nom du type et celui de la méthode ne portent aucun contrat. Un obfuscateur peut renommer ForecastPlugin en p0 et GetForecastAsync en a, et le Kernel émet toujours weather-get_forecast, car le schéma est construit à partir de la chaîne de l”attribut et de la chaîne d”importation, non des identifiants. C”est exactement l”habitude [AliasAs] / [ProtoMember(N)] des contrats de sérialisation, appliquée aux métadonnées d”outil : fixez le nom du fil et le nom du code devient libre.

Niveau 2 — noms de paramètres et descriptions : conservez-les, ne les cachez pas

Les noms des paramètres diffèrent du nom de la fonction, car Semantic Kernel n”a aucun attribut pour les remplacer : il lit ParameterInfo.Name directement dans le schéma. Ainsi city et days deviennent les clés de propriété du schéma telles quelles. Vous pourriez laisser l”obfuscateur les renommer : SK relie les arguments renvoyés par le modèle par le même nom réfléchi, donc a et b fonctionneraient toujours mécaniquement. Ne le faites pas. Deux raisons :

  1. La valeur de sécurité est nulle. Ces noms sont déjà envoyés au modèle en clair à chaque appel. Les renommer dans le binaire ne cache rien qu”un attaquant ne puisse lire en observant une seule requête.
  2. Le coût de qualité est réel. Le modèle choisit les arguments en partie d”après les noms des propriétés. Un schéma de { "a": ..., "b": ... } avec de bonnes descriptions appelle moins bien que { "city": ..., "days": ... }. Vous paieriez de la précision pour obscurcir quelque chose déjà public.

Les chaînes [Description] sont au même niveau et se gèrent toutes seules. Un argument [Description("...")] est stocké dans le blob de l”attribut personnalisé dans les métadonnées, non comme un ldstr dans un corps de méthode, de sorte que le chiffrement des chaînes — qui réécrit les chargements de chaînes du corps de méthode — n”y touche jamais. SK le lit par réflexion et l”envoie au modèle inchangé. C”est le comportement que vous voulez.

Niveau 3 — l”implémentation est la PI

Tout ce qui n”atteint pas le modèle est l”endroit où l”obfuscation gagne sa croûte : les corps des méthodes de vos [KernelFunction], l”aide privée Blend, l”abstraction IWeatherSource et son implémentation NoaaWeatherSource, les DTO comme Reading, et chaque littéral de chaîne à l”intérieur de ces corps — routes d”API, fragments de prompt, seuils de classement. Renommez-les tous, aplatissez le flux de contrôle et chiffrez les chaînes des corps. Rien de tout cela ne fait partie du schéma d”outil, donc rien n”est contraint par la frontière du modèle.

Le piège : une fonction sans nom se renomme en silence

Voici l”échec qui ne produit aucune exception. Supposez que vous ayez sauté les deux noms explicites :

[KernelFunction]                                   // le nom prend par défaut celui de la méthode
public async Task<string> GetForecastAsync(...) { }

kernel.ImportPluginFromType<ForecastPlugin>();     // le nom du plugin prend celui du type

Désormais, l”identité de l”outil découle de vos identifiants : le modèle voit ForecastPlugin-GetForecastAsync. Lancez l”obfuscateur et ces identifiants se renomment en p0 et a, de sorte que le schéma devient en silence :

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

Rien ne lève d”exception. Le Kernel génère le schéma avec les noms que portent désormais les membres et relie les réponses par ces mêmes noms, donc un aller-retour fonctionne toujours. Mais tout ce qui faisait référence à l”outil par son ancien nom est maintenant cassé :

  • Un littéral de modèle de prompt comme {{ForecastPlugin.GetForecastAsync $city}} se résout contre une fonction qui n”existe plus.
  • Les prompts système, les exemples few-shot et les indices du planificateur qui nomment l”outil pointent vers un fantôme.
  • Les journaux de conversation et les évaluations hors ligne indexés sur ForecastPlugin-GetForecastAsync cessent de correspondre en silence.

C”est le classique bug de renommage de sérialisation : aucune erreur, juste un contrat qui a bougé sous les pieds de tous ceux qui en dépendaient. Le correctif est le Niveau 1 : fixez les noms avec des chaînes et le renommage devient invisible pour le modèle.

La configuration Nebula

Comme l”identité de la fonction est fixée par des chaînes, il n”y a presque rien à conserver. Vous n”avez pas besoin de préserver le type du plugin ni les noms de ses méthodes : ils sont libres de se renommer. La seule chose que la réflexion tire dans le schéma et que vous devez protéger, ce sont les noms des paramètres. Limitez une règle de préservation aux méthodes qui portent [KernelFunction] et laissez tout le reste se renommer. En MSBuild :

<Nebula>
  <!-- Le nom du plugin et les noms de fonction sont fixés par des
       littéraux de chaîne (l'argument de ImportPluginFromType("weather")
       et [KernelFunction("get_forecast")]), donc les identifiants de type
       et de méthode se renomment librement. La seule chose que la réflexion
       transforme en schéma visible par le modèle, ce sont les noms de
       paramètres — conservez-les. -->
  <Preserve parameters="true"
            attribute="Microsoft.SemanticKernel.KernelFunctionAttribute" />
</Nebula>

Si vous pilotez la protection depuis un nebula.config.json à la place, la même intention se lit comme une entrée de conservation étroite plus des transformations complètes partout ailleurs :

{
  "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
    }
  ]
}

Notez ce qui n”est pas dans cette règle de conservation : keepName et keepMembers sont absents, donc la classe du plugin et ses méthodes se renomment normalement. Lancez ensuite le protecteur sur l”assembly compilé :

nebula protect --config nebula.config.json

L”intégration à la compilation est une fonctionnalité Pro de Nebula ; l”édition gratuite exécute les mêmes transformations depuis la CLI avec des plafonds.

Vérifier que le schéma d”outil est inchangé

La preuve que l”obfuscation n”a pas touché le contrat, c”est que le schéma que reçoit le modèle est identique octet pour octet avant et après. Semantic Kernel l”expose sans appel réseau via KernelFunctionMetadata, vous pouvez donc faire des assertions dessus directement :

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

Lancez cela sur l”assembly original, puis sur la sortie de nebula protect — avec ForecastPlugin renommé en p0, GetForecastAsync renommé en a, l”aide Blend renommée et son corps aplati, et les littéraux de route à l”intérieur chiffrés. Les deux exécutions impriment get_forecast et city,days, car le nom de la fonction venait de la chaîne de l”attribut, les noms des paramètres ont été conservés, et les descriptions vivent dans le blob de métadonnées. Le modèle voit un outil identique ; votre implémentation est illisible.

Résumé

Un plugin Semantic Kernel est un contrat de sérialisation destiné à un modèle de langage. Classez chaque identifiant en trois niveaux : fixez les noms du plugin et des fonctions avec des arguments de chaîne pour que les noms de type et de méthode se renomment librement (Niveau 1) ; conservez les noms des paramètres et laissez les descriptions voyager dans les métadonnées, car le modèle les lit déjà et les cacher ne coûte que de la précision (Niveau 2) ; et déchaînez tout le poids du renommage, de l”aplatissement du flux de contrôle et du chiffrement des chaînes sur les corps des méthodes et les aides qui sont votre véritable PI (Niveau 3). Fixez les noms, conservez les paramètres, blindez le reste — et laissez Nebula Pro protéger l”implémentation sans que le modèle ne s”en aperçoive jamais.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.