Pilma

Der privacy-first PII-Firewall-Companion fuer LLM-Workflows: localhost-only, sicherheitsbewusst und so gebaut, dass sensible Texte anonymisiert werden, bevor sie die Maschine verlassen.

Pilma schuetzt persoenliche Daten in LLM-gestuetzten UIs, indem PII vor dem Absenden durch kurzlebige Tokens ersetzt und spaeter lokal wiederhergestellt wird. Der aktuelle Repo-Stand liefert den geharteten Companion-Service; die Browser-Extension ist in den Architektur-Dokumenten beschrieben, aber noch kein Build-Ziel dieses Repos.

Schnellstart · API · Architektur · Security · OpenSSF · Mitmachen

Inhaltsverzeichnis

• Warum Pilma?
• Was heute im Repo steckt
• Security by Default
• Ablauf in 4 Schritten
• API im Ueberblick
• Schnellstart
• Projektstruktur
• Qualitaetsgates
• Roadmap
• Dokumentation und Vertrauen
• Mitmachen
• Lizenzstatus

Warum Pilma?

Viele LLM-Workflows scheitern nicht an der Modellqualitaet, sondern an der Frage: "Wie halte ich Namen, E-Mails, IDs oder andere PII aus fremden Systemen heraus?" Pilma beantwortet genau das mit einem klaren Architekturprinzip:

• PII wird vor dem Versand anonymisiert
• Mappings bleiben nur im Speicher
• der Dienst bleibt standardmaessig auf 127.0.0.1
• Logs und Traces enthalten keine Rohtexte und keine Roh-PII

Das Ergebnis ist ein Baustein fuer lokale oder browsergestuetzte AI-Workflows, der Privacy und Developer-Ergonomie zusammenbringt.

Zurueck nach oben

Was heute im Repo steckt

Der aktuelle Lieferumfang ist bewusst fokussiert und produktnah:

• POST /anonymize ersetzt erkannte PII durch vault-gestuetzte Tokens
• POST /deanonymize stellt Tokens fuer dieselbe Session lokal wieder her
• POST /session/reset leert die In-Memory-Vault einer Session
• POST /model/warmup waermt ein konfiguriertes Modell vor, wenn es bereits gecacht ist oder Remote-Download explizit erlaubt wurde
• GET /health liefert den Service-Zustand

Wichtig fuer Erwartungsmanagement:

• Der Companion-Service ist heute der echte, gebaute Deliverable in diesem Repository.
• Die Browser-Extension ist architektonisch vorgesehen, aber noch nicht als fertiges Produkt im Repo enthalten.
• Modelle werden nicht gebuendelt und sollen nutzerseitig geladen bzw. gecacht werden.

Zurueck nach oben

Security by Default

Pilma ist nicht nur "privacy-themed", sondern in seinen Defaults absichtlich restriktiv:

• bindet standardmaessig an 127.0.0.1
• verweigert Non-Loopback-Binds ohne explizites ALLOW_NON_LOOPBACK_HOST=true
• verlangt X-Pilma-Secret auf allen POST-Routen
• authentifiziert Requests, bevor Request-Bodies gelesen werden
• akzeptiert auf POST nur application/json
• begrenzt JSON-Request-Bodies auf 1 MiB
• speichert PII-Mappings nur im Speicher und raeumt per TTL auf
• emittiert strukturierte Traces ohne Rohtext, Roh-PII oder Secrets

Diese Regeln sind keine Randnotiz, sondern Teil des Vertrags in SECURITY.md, RUNBOOK.md und THREAT_MODEL.md.

Zurueck nach oben

Ablauf in 4 Schritten

flowchart LR
  A[User gibt Text ein] --> B[Pilma anonymisiert PII]
  B --> C[Tokenisierter Text geht an das LLM]
  C --> D[Pilma deanonymisiert lokal]

Loading

Kurz erklaert:

1. Ein Client schickt Text an den lokalen Companion.
2. Pilma ersetzt erkannte PII durch kurzlebige Platzhalter wie §§EMAIL_1~...§§.
3. Nur der anonymisierte Text verlaesst den lokalen Kontext.
4. Antworten koennen spaeter fuer dieselbe Session wieder deanonymisiert werden.

Mehr Kontext dazu steht in ARCHITECTURE.md und ARCHITECTURE_DECISIONS.md.

Zurueck nach oben

API im Ueberblick

Alle POST-Routen erwarten:

Content-Type: application/json
X-Pilma-Secret: <shared-secret>

GET /health

{ "status": "ok", "sessions": 0 }

POST /anonymize

Request:

{ "sessionId": "demo-session", "text": "Email me at user@example.com" }

Response:

{
  "text": "Email me at §§EMAIL_1~D2B9D7F4§§",
  "counts": { "EMAIL": 1 },
  "traceId": "trace-..."
}

POST /deanonymize

{ "sessionId": "demo-session", "text": "Email me at §§EMAIL_1~D2B9D7F4§§" }

POST /session/reset

{ "sessionId": "demo-session" }

POST /model/warmup

{ "modelId": "iiiorg/piiranha-v1-detect-personal-information" }

oder:

{ "locale": "en" }

Wenn Remote-Download deaktiviert ist und kein Cache-Treffer existiert, liefert die Route bewusst einen Fehler statt still im Hintergrund nachzuladen.

Zurueck nach oben

Schnellstart

npm install
npm run lint
npm run typecheck
npm run build
npm test
npm run openssf:check

Dann den Shared Secret setzen und den Companion starten:

export SECRET='replace-with-a-long-random-shared-value'
npm run companion

PowerShell:

$env:SECRET = 'replace-with-a-long-random-shared-value'
npm run companion

Standardadresse:

http://127.0.0.1:8787

Der Dienst startet nur mit explizitem SECRET und gibt diesen Wert nicht auf stdout aus.

Zurueck nach oben

Projektstruktur

• src/companion - Companion-Service, HTTP-Endpunkte, Auth, Vault und Modellvorbereitung
• src/tracing - strukturierte Traces ohne Rohdaten
• tests - Unit- und Integrationsabdeckung fuer Server, Vault, Warmup und Konfiguration
• ARCHITECTURE.md - Systembild und geplanter Extension-Kontext
• ARCHITECTURE_DECISIONS.md - wichtige Architekturentscheidungen
• THREAT_MODEL.md - Risiken, Missbrauchspfade und Gegenmassnahmen
• RUNBOOK.md - Betrieb, Releases und Incident-orientierte Hinweise
• OPENSSF.md - Nachweise fuer Badge- und Scorecard-Arbeit
• .motherlode/ - wiederverwendbare Engineering-Standards fuer Repo-Hygiene und Audits

Zurueck nach oben

Qualitaetsgates

Pilma haertet nicht nur den Runtime-Pfad, sondern auch die Repo-Pipeline:

• npm run lint
• npm run typecheck
• npm run build
• npm test
• npm run openssf:check
• GitHub Actions fuer CI, CodeQL und OpenSSF Scorecards

Das Ziel ist ein Repo, das fuer lokale Privacy-Software nicht nur funktional, sondern auch nachvollziehbar wartbar und reviewbar ist.

Zurueck nach oben

Roadmap (Now / Next / Later)

Now

• geharteter localhost-Companion mit Auth, Vault, Tracing und Warmup-Endpunkten
• Tests fuer Server-Verhalten, Vault-Lifecycle, Warmup und Konfiguration
• OpenSSF-Basis fuer Security-Dokumente, CI, CodeQL und Scorecards

Next

• Extension-MVP fuer Chrome/Firefox entlang der dokumentierten Architektur
• klarere Modell-Download- und Cache-Flows fuer mehrere Locales
• weitere Evaluations- und Leakage-Checks in CI

Later

• komfortablere End-to-End-UX fuer Chat-UIs
• breitere Integrationen rund um privacy-sensible AI-Workflows
• staerkere Automatisierung fuer Security- und Release-Nachweise

Zurueck nach oben

Dokumentation und Vertrauen

Wenn du Pilma beurteilen, betreiben oder weiterentwickeln willst, sind diese Dokumente die schnellsten Einstiegspunkte:

• ARCHITECTURE.md
• ARCHITECTURE_DECISIONS.md
• THREAT_MODEL.md
• RUNBOOK.md
• SECURITY.md
• OPENSSF.md
• CONTRIBUTING.md
• MAINTAINERS.md
• CODE_OF_CONDUCT.md
• Motherlode README

Zurueck nach oben

Mitmachen

Beitraege sollen klein, reversibel und pruefbar bleiben. Wenn du mithelfen willst:

• lies CONTRIBUTING.md fuer Review- und Change-Erwartungen
• beachte SECURITY.md fuer vertrauliche Meldungen
• behandle RUNBOOK.md und THREAT_MODEL.md als Teil des technischen Vertrags

Falls du an Auth, Token-Format, Modell-Download-Verhalten oder Netzexposition arbeitest, sollten Tests mit aktualisiert oder erweitert werden.

Zurueck nach oben

Lizenzstatus

Dieses Repository hat aktuell noch keine committed Top-Level-LICENSE. Das ist bewusst in OPENSSF.md als offener manueller Blocker dokumentiert und sollte vor einer breiteren Distribution geklaert werden.

Zurueck nach oben