Ein Semantic-Kernel-Plugin sicher obfuskieren
Ein [KernelFunction]-Plugin ist ein per Reflexion entdeckter Vertrag, der dem LLM als Tool-Schema geschickt wird. Funktionsname, Parameternamen und Beschreibungen sind tragend; der Methodenrumpf ist Ihr geistiges Eigentum. Fixieren Sie die Namen mit Attributen, damit die Bezeichner frei umbenannt werden, und lassen Sie Nebula die Implementierung härten.
Die meisten „Das nicht obfuskieren”-Ratschläge drehen sich um Serialisierung: Der Name eines Members ist zugleich der Schlüssel auf der Leitung, also zerbricht ihn umzubenennen den Vertrag. Ein Semantic-Kernel-Plugin ist dieselbe Geschichte in neuen Kleidern. Sie schreiben eine ganz normale C#-Klasse, versehen einige Methoden mit [KernelFunction], und der Kernel verwandelt diese Klasse — per Reflexion — in ein JSON-Tool-Schema, das er an das Sprachmodell schickt. Der Funktionsname, die Parameternamen und die Beschreibungen sind der Vertrag, den das Modell liest und zurückruft. Die Methodenrümpfe sind Ihr geistiges Eigentum. Ein Plugin sicher zu obfuskieren besteht vollständig darin, diese beiden auseinanderzuhalten.
Wie Semantic Kernel eine Klasse in Tools verwandelt
Ein Plugin ist eine Klasse, deren Methoden [KernelFunction] tragen. Signatur und Attribute jeder Methode werden zu einem Tool im Schema, das an das Modell geschickt wird:
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); // proprietäres Modell-Blending — Ihr geistiges Eigentum
}
private string Blend(IReadOnlyList<Reading> readings) { /* ... */ }
}
Sie importieren es unter einem Plugin-Namen und lassen das Modell es aufrufen:
var builder = Kernel.CreateBuilder();
builder.Services.AddSingleton<IWeatherSource, NoaaWeatherSource>();
var kernel = builder.Build();
kernel.ImportPluginFromType<ForecastPlugin>("weather");
Zum Aufrufzeitpunkt reflektiert der Kernel über das Plugin und gibt eine Tool-Definition aus. Mit dem OpenAI-Connector sieht sie so aus — man beachte den Trenner -, der den Plugin-Namen mit dem Funktionsnamen verbindet, da OpenAI-Tool-Namen ^[a-zA-Z0-9_-]+$ erfüllen müssen:
{
"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"]
}
}
}
Jeder String in diesem JSON stammt aus der Reflexion: weather aus dem Import-Aufruf, get_forecast aus dem Attribut, city/days aus den Parameternamen und die Beschreibungen aus [Description]. Die CLR-Bezeichner ForecastPlugin, GetForecastAsync, _source und Blend erscheinen darin nirgends. Diese Trennung ist die ganze Chance.
Die drei Namensebenen
Jeder Bezeichner eines Plugins fällt in eine von drei Ebenen, und jede Ebene hat eine andere Obfuskierungs-Antwort.
Ebene 1 — Plugin- und Funktionsnamen fixieren, dann die Bezeichner umbenennen lassen
Der Plugin-Name und der Funktionsname sind die modell-sichtbare Identität des Tools. Sie machen sie von Ihren CLR-Namen unabhängig, indem Sie sie als Strings liefern:
kernel.ImportPluginFromType<ForecastPlugin>("weather")fixiert den Plugin-Namen auf das Literal"weather".[KernelFunction("get_forecast")]fixiert den Funktionsnamen auf das Literal"get_forecast".
Sobald beide explizit sind, tragen der Typname und der Methodenname keinen Vertrag mehr. Ein Obfuskator kann ForecastPlugin in p0 und GetForecastAsync in a umbenennen, und der Kernel gibt weiterhin weather-get_forecast aus, weil das Schema aus dem Attribut-String und dem Import-String gebaut wird, nicht aus den Bezeichnern. Das ist genau die [AliasAs]- / [ProtoMember(N)]-Gewohnheit aus Serialisierungsverträgen, angewandt auf Tool-Metadaten: Fixieren Sie den Leitungsnamen, und der Codename wird frei.
Ebene 2 — Parameternamen und Beschreibungen: behalten, nicht verstecken
Parameternamen unterscheiden sich vom Funktionsnamen, weil Semantic Kernel kein Attribut hat, um sie zu überschreiben — es liest ParameterInfo.Name direkt ins Schema. Also werden city und days wortwörtlich zu den Eigenschaftsschlüsseln des Schemas. Sie könnten den Obfuskator sie umbenennen lassen: SK bindet die vom Modell zurückgegebenen Argumente über denselben reflektierten Namen, sodass a und b mechanisch weiterhin funktionieren würden. Tun Sie es nicht. Zwei Gründe:
- Der Sicherheitswert ist null. Diese Namen werden ohnehin bei jedem Aufruf im Klartext an das Modell geschickt. Sie im Binärprogramm umzubenennen verbirgt nichts, was ein Angreifer nicht durch Beobachten einer einzigen Anfrage lesen könnte.
- Die Qualitätskosten sind real. Das Modell wählt Argumente zum Teil anhand der Eigenschaftsnamen. Ein Schema aus
{ "a": ..., "b": ... }mit guten Beschreibungen ruft schlechter auf als{ "city": ..., "days": ... }. Sie würden Genauigkeit dafür bezahlen, etwas zu verschleiern, das bereits öffentlich ist.
Die [Description]-Strings sind auf derselben Ebene und erledigen sich von selbst. Ein [Description("...")]-Argument wird im Blob des benutzerdefinierten Attributs in den Metadaten gespeichert, nicht als ldstr in einem Methodenrumpf, sodass die String-Verschlüsselung — die String-Ladevorgänge im Methodenrumpf umschreibt — es nie berührt. SK liest es per Reflexion und schickt es unverändert an das Modell. Das ist das gewünschte Verhalten.
Ebene 3 — die Implementierung ist das geistige Eigentum
Alles, was das Modell nicht erreicht, ist der Ort, an dem sich die Obfuskierung lohnt: die Methodenrümpfe Ihrer [KernelFunction]s, die private Blend-Hilfsmethode, die Abstraktion IWeatherSource und ihre Implementierung NoaaWeatherSource, DTOs wie Reading und jedes String-Literal in diesen Rümpfen — API-Routen, Prompt-Fragmente, Ranking-Schwellen. Benennen Sie sie alle um, flachen Sie den Kontrollfluss ab und verschlüsseln Sie die Rumpf-Strings. Nichts davon ist Teil des Tool-Schemas, also ist nichts durch die Modellgrenze eingeschränkt.
Die Falle: eine namenlose Funktion wird stillschweigend umbenannt
Hier ist der Fehler, der keine Ausnahme erzeugt. Angenommen, Sie haben beide expliziten Namen übersprungen:
[KernelFunction] // der Name nimmt standardmäßig den Methodennamen
public async Task<string> GetForecastAsync(...) { }
kernel.ImportPluginFromType<ForecastPlugin>(); // der Plugin-Name nimmt den Typnamen
Nun leitet sich die Tool-Identität aus Ihren Bezeichnern ab: Das Modell sieht ForecastPlugin-GetForecastAsync. Lassen Sie den Obfuskator laufen, und diese Bezeichner werden zu p0 und a umbenannt, sodass das Schema stillschweigend zu Folgendem wird:
{ "function": { "name": "p0-a", "parameters": { "properties": { "a": {...}, "b": {...} } } } }
Nichts wirft eine Ausnahme. Der Kernel erzeugt das Schema aus den Namen, die die Member jetzt tragen, und bindet Antworten über dieselben Namen, sodass ein Hin und Zurück weiterhin funktioniert. Aber alles, was sich auf das Tool unter seinem alten Namen bezog, ist nun kaputt:
- Ein Prompt-Vorlagen-Literal wie
{{ForecastPlugin.GetForecastAsync $city}}löst sich gegen eine Funktion auf, die es nicht mehr gibt. - System-Prompts, Few-Shot-Beispiele und Planner-Hinweise, die das Tool benennen, zeigen auf einen Geist.
- Konversationsprotokolle und Offline-Evaluierungen, die auf
ForecastPlugin-GetForecastAsyncindexiert sind, passen stillschweigend nicht mehr.
Es ist der klassische Serialisierungs-Umbenennungsfehler: kein Fehler, nur ein Vertrag, der sich unter den Füßen aller, die auf ihn angewiesen waren, verschoben hat. Die Lösung ist Ebene 1: Fixieren Sie die Namen mit Strings, und die Umbenennung wird für das Modell unsichtbar.
Die Nebula-Konfiguration
Da die Funktionsidentität durch Strings fixiert ist, gibt es fast nichts zu behalten. Sie müssen den Plugin-Typ oder die Namen seiner Methoden nicht bewahren — sie dürfen frei umbenannt werden. Das Einzige, was die Reflexion ins Schema zieht und das Sie schützen müssen, sind die Parameternamen. Begrenzen Sie eine Bewahrungsregel auf die Methoden, die [KernelFunction] tragen, und lassen Sie alles andere umbenennen. In MSBuild:
<Nebula>
<!-- Der Plugin-Name und die Funktionsnamen sind durch String-Literale
fixiert (das Argument von ImportPluginFromType("weather") und
[KernelFunction("get_forecast")]), sodass die Typ- und
Methodenbezeichner frei umbenannt werden. Das Einzige, was die
Reflexion in das modell-sichtbare Schema verwandelt, sind
Parameternamen — behalten Sie diese. -->
<Preserve parameters="true"
attribute="Microsoft.SemanticKernel.KernelFunctionAttribute" />
</Nebula>
Wenn Sie den Schutz stattdessen über eine nebula.config.json steuern, liest sich dieselbe Absicht als ein enger Behalten-Eintrag plus volle Transformationen überall sonst:
{
"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
}
]
}
Beachten Sie, was nicht in dieser Behalten-Regel steht: keepName und keepMembers fehlen, sodass die Plugin-Klasse und ihre Methoden normal umbenannt werden. Lassen Sie dann den Protector über das kompilierte Assembly laufen:
nebula protect --config nebula.config.json
Die Build-Zeit-Integration ist eine Pro-Funktion von Nebula; die kostenlose Edition führt dieselben Transformationen über die CLI mit Obergrenzen aus.
Überprüfen, dass das Tool-Schema unverändert ist
Der Beweis, dass die Obfuskierung den Vertrag nicht berührt hat, ist, dass das Schema, das das Modell erhält, vorher und nachher byte-für-byte identisch ist. Semantic Kernel legt es ohne Netzwerkaufruf über KernelFunctionMetadata offen, sodass Sie direkt darauf prüfen können:
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
Lassen Sie das über das ursprüngliche Assembly laufen, dann über die Ausgabe von nebula protect — mit ForecastPlugin in p0 umbenannt, GetForecastAsync in a umbenannt, der Blend-Hilfsmethode umbenannt und ihrem Rumpf abgeflacht sowie den Routen-Literalen darin verschlüsselt. Beide Durchläufe geben get_forecast und city,days aus, weil der Funktionsname aus dem Attribut-String stammte, die Parameternamen behalten wurden und die Beschreibungen im Metadaten-Blob leben. Das Modell sieht ein identisches Tool; Ihre Implementierung ist unlesbar.
Zusammenfassung
Ein Semantic-Kernel-Plugin ist ein auf ein Sprachmodell gerichteter Serialisierungsvertrag. Sortieren Sie jeden Bezeichner in drei Ebenen: Fixieren Sie Plugin- und Funktionsnamen mit String-Argumenten, damit Typ- und Methodennamen frei umbenannt werden (Ebene 1); behalten Sie die Parameternamen und lassen Sie die Beschreibungen in den Metadaten mitreisen, weil das Modell sie ohnehin liest und ihr Verstecken nur Genauigkeit kostet (Ebene 2); und werfen Sie das volle Gewicht von Umbenennung, Kontrollfluss-Abflachung und String-Verschlüsselung auf die Methodenrümpfe und Hilfsmethoden, die Ihr tatsächliches geistiges Eigentum sind (Ebene 3). Fixieren Sie die Namen, behalten Sie die Parameter, härten Sie den Rest — und lassen Sie Nebula Pro die Implementierung schützen, während das Modell es nie bemerkt.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.