PII in einem PDF über Connect schwärzen

PII in einem PDF über Connect schwärzen

Auf einen Blick

In diesem Rezept entfernen Sie erkannte personenbezogene Daten aus der Textebene eines Dokuments mithilfe der Schwärzungs-Tools, die NextPDF Connect bereitstellt. Diese Tools gehören zur Enterprise-Stufe. Die ToolRegistry erstellt redact_pdf, zone_redact_pdf und deidentify_pdf, indem sie mit class_exists() nach den Enterprise-Datenschutzklassen (RedactionEngine + PiiDetector) sucht, und registriert jedes Tool nur dann für die Stufe enterprise, wenn diese Klassen per Autoloading verfügbar sind. Bei einer reinen Open-Source-Installation fehlen die Tools: Der Aufruf schlägt mit einem Unknown-Tool-Fehler fehl, statt stillschweigend auf eine schwächere Verarbeitung zurückzufallen. Alle drei Tools deklarieren destructiveHint: true. Die Bearbeitung schreibt den Seiteninhalt neu und ist aus dem bearbeiteten Dokument nicht umkehrbar.

Diese Seite dokumentiert das Tool-Verhalten an der Connect-Schnittstelle. Ein Schwärzungs-Workflow ist keine Zertifizierung dafür, dass ein bestimmtes Dokument nach dem Aufruf frei von personenbezogenen Daten ist. Die Erkennung arbeitet ausschließlich auf der extrahierbaren Textebene; die Deployment-Umgebung bleibt für die Überprüfung des Ergebnisses verantwortlich.

Installation

composer require nextpdf/server

Die Schwärzungs-Tools registrieren sich nur, wenn das Enterprise-Datenschutzmodul zusammen mit dem Server installiert ist. Dieses Modul wird in nextpdf/premium ausgeliefert. Stellen Sie sicher, dass das Tool in der laufenden Deployment-Umgebung vorhanden ist, bevor Sie sich darauf verlassen:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

Wenn redact_pdf im Ergebnis von tools/list fehlt, wurden die Enterprise-Datenschutzklassen in dieser Installation nicht aufgelöst. Wie die Registry beim Start die Tool-Menge pro Stufe berechnet, ist unter /connect/tool-catalog/ beschrieben.

Konzeptioneller Überblick

Drei Tools decken drei Schwärzungsstrategien ab. Alle gehören zur Enterprise-Stufe und setzen den Destructive-Hint:

• redact_pdf — erkennt und entfernt personenbezogene Daten im Klartextinhalt des Dokuments mithilfe eines integrierten Detektors und gibt den bearbeiteten Inhalt sowie einen strukturierten Bericht zurück.
• zone_redact_pdf — wendet koordinatenbasierte Zonenschwärzungen auf den Klartextinhalt an. Verwenden Sie es, wenn Sie die zu entfernende Region nach Position statt nach Muster kennen.
• deidentify_pdf — wendet eine systematische De-Identifikationsstrategie (Schwärzen oder Unterdrücken) auf erkannte Entitäten an.

Das Entfernen von Inhalt aus einem Seiteninhalts-Stream ist eine destruktive Bearbeitung dieses Streams: Die betroffenen Bytes werden neu geschrieben und sind aus dem bearbeiteten Dokument nicht wiederherstellbar (ISO 32000-2 §14.11). Konstruktionsbedingt erfasst der Bericht zu jeder Entfernung die Zeichenanzahl und Position, niemals den entfernten Text selbst.

API-Oberfläche

Das genaue Request- und Response-Schema für jedes Tool wird mit dem Enterprise-Paket ausgeliefert, das es definiert. Diese Seite dokumentiert den Connect-Aufrufvertrag, keine feste Parameterliste. Die in der laufenden Registry verifizierten Tool-Namen sind redact_pdf, zone_redact_pdf und deidentify_pdf, alle in der Kategorie document mit destructiveHint: true. Der maßgebliche Katalog ist /connect/tool-catalog/. Dieses Rezept wiederholt keine Anzahl der Tools, weil sie eine Laufzeiteigenschaft der Deployment-Umgebung ist.

Codebeispiel — Schnellstart

Erkennung und Entfernung über MCP (tools/call). Die folgenden Argumente veranschaulichen die Form des Aufrufs. Maßgeblich ist das Argument-Schema, das tools/list in Ihrer Deployment-Umgebung zurückgibt:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "redact_pdf",
    "arguments": {
      "source": "/var/lib/nextpdf/in/employee-directory.pdf"
    }
  }
}

Ein erfolgreicher Aufruf gibt einen Bericht zurück. Für jede Entfernung erfasst ein Eintrag die Seite, ein Kategorie-Label, die ursprüngliche Zeichenanzahl und eine Bounding-Box, nicht den entfernten Text.

Codebeispiel — Produktion

Behandeln Sie den Schwärzungsaufruf als destruktive Operation und prüfen Sie den Bericht, bevor Sie das Dokument freigeben. Bei einem vernetzten Transport sind ein Transportfehler und ein Fehler auf Tool-Ebene zwei getrennte Fälle:

curl -sS -X POST https://connect.example.com/v1/tools/redact_pdf \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/legal-discovery-batch.pdf"}' \
  -o /tmp/redaction-report.json -w '%{http_code}' > /tmp/redaction-status

status="$(cat /tmp/redaction-status)"
if [ "$status" != "200" ]; then
  # 4xx/5xx is a normal HTTP outcome the caller inspects, not a transport
  # failure. A connection error (curl non-zero exit) is the separate case.
  echo "redact_pdf returned HTTP $status; inspect the body, do not release the document" >&2
  exit 1
fi

Geben Sie das bearbeitete Dokument erst frei, nachdem ein Mensch oder eine nachgelagerte Kontrolle den Bericht geprüft hat. Die Freigabe an diese Prüfung zu knüpfen, platziert die Kontrollmaßnahme an dem Punkt, an dem die automatisierte Bearbeitung das Risiko von Restdaten einführt (IEC 31010:2019).

Grenzfälle & Fallstricke

• Gescanntes PDF ohne Textebene. Die Erkennung läuft auf der extrahierbaren Textebene. Eine reine Bildseite ergibt null Entfernungen und ist kein Fehler. Wenn der Inhalt gerastert ist, führen Sie vor der Schwärzung eine OCR des Dokuments durch.
• Verschlüsselte Quelle. Übergeben Sie das Dokumentpasswort über das Argument-Schema des Tools. Ohne es schlägt der Aufruf fehl, statt das Dokument teilweise zu verarbeiten.
• Tool fehlt. Bei einer reinen Open-Source-Installation werden die Enterprise-Datenschutzklassen nicht aufgelöst und redact_pdf ist nicht registriert, sodass der Aufruf mit einem Unknown-Tool-Fehler fehlschlägt. Dies ist die beabsichtigte Grenze, kein Fallback auf eine schwächere Verarbeitung.
• Überlappende Erkennungen. Wenn mehrere Detektoren dieselbe Region treffen, wird die Region einmal entfernt und der Bericht entfernt Duplikate.

Performance

Das Performance-Budget im Front-Matter ist eine dokumentierte Obergrenze, keine Service-Level-Garantie. Große Dokumente werden Seite für Seite verarbeitet. Planen Sie ein, den Aufruf für eine Teilmenge eines Seitenbereichs erneut auszuführen, statt ein globales Timeout zu erhöhen.

Sicherheitshinweise

Datenresidenz & PII-Mitigationen

Der Dokumenttext wird in-process auf dem Connect-Host verarbeitet. Der Bericht lässt entfernten Text bewusst aus und meldet nur Anzahlen und Positionen, sodass der Bericht selbst die von ihm beschriebenen personenbezogenen Daten nicht erneut einführt. Die Datenresidenz auf Deployment-Ebene für die Eingabe und die bearbeitete Ausgabe liegt in der Verantwortung des Integrators und ist keine Eigenschaft des Tools.

Sichere Telemetrie & Log-Bereinigung

Protokollieren Sie weder den Pfad des Quelldokuments noch den Berichtskörper in Logs, die extern ausgeliefert werden. Protokollieren Sie nur den Tool-Namen, die Request-ID und das pass/fail-Ergebnis.

Bedrohungsmodell

Eine Schwärzung, die Text visuell verdeckt, ihn aber nicht entfernt, belässt die Daten in extrahierbarer Form. Diese Tools schreiben den betroffenen Content-Stream neu, statt ein Rechteck zu überlagern; das Wiederherstellen entfernter Bytes aus dem bearbeiteten Dokument ist nicht möglich (ISO 32000-2 §14.11). Das Restrisiko ist Inhalt, den der Detektor nicht getroffen hat: ein Muster außerhalb seines Regelumfangs oder Text, der nur als gerastertes Bild vorhanden ist. Der Workflow mindert dieses Risiko durch die obligatorische Berichtsprüfung, nicht durch eine Behauptung der Vollständigkeit.

FIPS-Modus-Verhalten

Die Schwärzung führt keine kryptografische Operation durch und ist von einer FIPS-Modus-Richtlinie auf dem Host nicht betroffen.

Konformität

Aussage	Klausel	reference_id
Das Entfernen von Inhalt schreibt den betroffenen Content-Stream neu	ISO 32000-2 §14.11
Die Schwärzung markiert und entfernt dann; die Entfernung ist eine Inhaltsbearbeitung	ISO 32000-2 §14.11
Kontrolle an dem Punkt platziert, an dem die automatisierte Bearbeitung Risiko einführt	IEC 31010:2019

Die Unterstützung der Schwärzungs-Tools ist keine Zertifizierung, dass ein verarbeitetes Dokument frei von personenbezogenen Daten ist. Diese Feststellung muss eine unabhängige Prüfung treffen.

Kommerzieller Kontext

Die Schwärzungs-Tools gehören zur Enterprise-Stufe. Sie registrieren sich nur, wenn nextpdf/premium zusammen mit dem Server installiert ist. Siehe den Conversion-Link im Front-Matter.

Connect-Besonderheiten

Transport-Verfügbarkeit (MCP / REST / gRPC)

Sie rufen die Tools über jeden Transport, der den gemeinsamen Tool-Executor antreibt, identisch auf: MCP tools/call, den REST-Tool-Endpunkt und den gRPC-Dienst. Das Argument-Schema ist transportunabhängig. Es ist das Schema, das tools/list (MCP) oder der Service-Deskriptor (gRPC) zurückgibt.

HITL-Risikostufe

Alle drei Tools deklarieren destructiveHint: true. Ein Operator, der ein Tool über eine Konfigurationsüberschreibung auf die Risikostufe approval_required anhebt, sperrt den Aufruf hinter dem ConfirmationGate. Die Überschreibung darf das Risiko nur erhöhen, niemals senken. Siehe /connect/hitl-risk-tiers/.

JSON-Envelope des Bestätigungs-Gates

Wenn das Tool gesperrt und ohne gültiges Token aufgerufen wird, gibt das Gate einen Challenge-Envelope dieser Form zurück:

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

Der Aufrufer ruft dasselbe Tool erneut auf, wobei arguments._confirmation_token auf das ausgestellte Token gesetzt ist. Das Token bindet den Tool-Namen, eine Nonce und eine TTL von 300 Sekunden — nicht die Argumente — und ist einmalig verwendbar.

Siehe auch

• /connect/tool-catalog/ — wie die Registry die Tool-Menge pro Stufe berechnet.
• /connect/hitl-risk-tiers/ — das vierstufige Risikomodell und das Gate.
• /cookbook/connect/extract-text-content/ — die extrahierbare Textebene vor dem Schwärzen in der Vorschau ansehen.
• /cookbook/connect/digital-signature/ — das bearbeitete Dokument für die Chain-of-Custody signieren.