Anhänge scannen
Das Scannen von Anhängen liest den Textinhalt von Jira-Issue-Anhängen mit denselben Erkennungsregeln wie Issue-Felder und Kommentare.
Es ist standardmässig aus. Aktivieren Sie es je Konfiguration mit
Anhangsinhalte scannen unter Administration -> Scan-Konfiguration;
beachten Sie, dass es das Lizenzmerkmal SCAN_ATTACHMENTS erfordert, siehe
Lizenz.
Ist in einer Scan-Konfiguration das Scannen von Anhängen aktiviert, die
installierte Lizenz enthält aber SCAN_ATTACHMENTS nicht, läuft der Scan über
Issue-Felder und Kommentare trotzdem normal - Anhänge werden schlicht nicht
gelesen - und der Lauf meldet:
Attachment scanning is not included in your license; attachments were not scanned.
Formate, die gescannt werden
| Format | Endungen | Was extrahiert wird |
|---|---|---|
| Textinhalt | ||
| Word | docx, doc | Fliesstext |
| Excel | xlsx, xls | Zellwerte über alle Blätter |
| PowerPoint | pptx, ppt | Folientext |
| OpenDocument | odt, ods, odp | Fliesstext, Zellwerte, Folientext |
| Rich Text | rtf | Fliesstext |
| Klartext | txt, log, md | Ganze Datei als Text |
| Trennzeichentext | csv, tsv | Ganze Datei als Text |
| Strukturierte Daten | json, xml, yaml, yml | Ganze Datei als Text (XML: Elementtext, Tags entfernt) |
| HTML | html, htm | Gerenderter Text, kein Markup |
| eml, msg | Kopfzeilen, Text und Anhänge eine Ebene tief | |
| Archive (eine Ebene) | zip, tar, gz | Jeder Eintrag, geparst als eigenes Format |
| Bilder (OCR) | png, jpg, jpeg, gif, bmp, tif, tiff, webp | Per OCR erkannter Text; siehe Bilder |
Der Dateiname jedes Anhangs wird gegen die Erkennungsregeln geprüft,
unabhängig davon, ob sein Inhalt eines der Formate oben ist. Eine Datei namens
aws-prod-key.txt.png wird allein aufgrund ihres Namens gemeldet, unabhängig
davon, ob sein Inhalt gelesen werden kann.
Ein aus einem Anhang entstandener Fund hält fest, aus welchem Anhang er stammt - sichtbar auf der Funddetailseite - niemals aber den extrahierten Text des Anhangs.
Wie das Format bestimmt wird
Der Scanner vertraut nie dem von Jira gemeldeten Medientyp eines Anhangs;
Client-Software kennzeichnet Uploads häufig falsch. Die Formaterkennung basiert
auf den Bytes des Anhangs, mit dem Dateinamen als sekundärem Hinweis - eine als
application/octet-stream hochgeladene .docx wird also trotzdem als
Word-Dokument gelesen.
Bilder
Screenshots und andere Bitmap-Anhänge (PNG, JPEG, GIF, BMP, TIFF, WebP) werden
per OCR gelesen: mit Tesseract und englischen sowie deutschen Sprachdaten
(eng+deu), in einem separaten, ressourcenbegrenzten Prozess. Der erkannte Text
durchläuft dieselben Erkennungsregeln wie jeder andere Anhangstext. Ein daraus
entstandener Fund zeigt die Textvariante OCR, sodass erkennbar bleibt, dass er
aus einem Bild stammt - das ist weniger sicher als Text aus einem Dokument.
Text wird gescannt, sobald OCR ihn mit ausreichender Sicherheit erkennt, auch wenn das Bild zusätzlich geprüft werden muss: Ein auf einem fotografierten Whiteboard lesbares Passwort ergibt trotzdem einen Fund.
Manche Bilder lassen sich per OCR nicht verantwortungsvoll beurteilen. Sie erscheinen auf der Seite Manuelle Prüfungen, mit einem dieser Gründe:
| Grund | Bedeutung |
|---|---|
PHOTO | Kamerafoto; kann einen Ausweis, ein Whiteboard oder einen Bildschirm zeigen |
SCANNED_DOCUMENT | Gescanntes Dokument; OCR ist nicht verlässlich genug |
NO_TEXT | Im Bild wurde kein lesbarer Text gefunden |
LOW_CONFIDENCE_TEXT | Text wurde gefunden, liess sich aber nicht verlässlich lesen |
NOT_ANALYZED | Das Bild liess sich innerhalb der Sicherheitsgrenzen nicht analysieren |
EMBEDDED_IMAGES | Das Dokument enthält eingebettete Bilder, die nicht gelesen wurden |
SCANNED_PAGES | Das PDF hat Seiten ohne Textebene |
Ein Bild gilt als PHOTO, wenn es Kamerahersteller oder -modell oder eine
GPS-Position enthält, und als SCANNED_DOCUMENT, wenn es 150 DPI oder mehr
angibt (Bildschirme melden 72, 96 oder 144). Ein Bild über der maximalen
Bildgrösse, ein animiertes Bild oder ein Bild, dessen OCR von einem
Ressourcenlimit beendet wird oder die Zeit überschreitet, ist NOT_ANALYZED.
Ein eigenständiges Bild mit einem Prüfgrund wird in der Anhangsabdeckung als
NEEDS_REVIEW gemeldet; der Scan zeigt daher COMPLETED WITH GAPS. Ein
Dokument mit EMBEDDED_IMAGES oder SCANNED_PAGES zählt weiterhin als
gescannt: Sein Text wurde gelesen, und die Prüfung wird zusätzlich erfasst.
In Dokumenten und Archiven eingebettete Bilder werden nicht per OCR gelesen. Eingebettete Bitmaps unter 20.480 Byte (Logos, Icons, E-Mail-Signaturbilder) werden ignoriert. Eine PDF-Seite mit weniger als 20 Zeichen Text gilt als reine Bildseite; auch eine leere Trennseite erscheint daher einmal. Unterdrücken Sie sie unter Manual reviews, bleibt sie über erneute Scans hinweg unterdrückt.
Sind Tesseract oder seine Sprachdaten nicht installiert, werden Bilder wie bisher nur über den Dateinamen geprüft, und jeder Scan, der Anhänge liest, meldet:
Image analysis is unavailable on this installation; image attachments were matched by file name only.
Was nicht gescannt wird, und warum
| Situation | Gemeldet als | Warum |
|---|---|---|
| Bilder, wenn die Bildanalyse auf der Installation nicht verfügbar ist (png, jpg, gif, bmp, tiff, ...) | UNSUPPORTED_FORMAT | Tesseract oder seine Sprachdaten sind nicht installiert; der Scan meldet eine Warnung, und Bilder werden nur über den Dateinamen geprüft. |
| SVG | UNSUPPORTED_FORMAT | SVG ist XML, keine Bitmap; es wird nicht per OCR gelesen. |
| Audio und Video | UNSUPPORTED_FORMAT | Keine Spracherkennung. |
| CAD-Zeichnungen, eigenständige Schriftdateien, PGP-/PKCS7-/Zeitstempelformate, RSS-/Atom-Feeds, WARC-Webarchive, Apple Property Lists und iWork-Dokumente (Pages, Numbers, Keynote) | UNSUPPORTED_FORMAT | Ausserhalb der unterstützten Formatliste. |
| Jedes andere nicht aufgeführte Format | UNSUPPORTED_FORMAT | Entschieden anhand des aus den Bytes erkannten Formats, nie danach, ob der extrahierte Text zufällig leer war - eine leere .txt wird normal gescannt. |
| Passwortgeschützte Dateien | ENCRYPTED | Der Scanner versucht nie, ein Passwort zu erraten oder zu knacken. |
| Ein vollständig leerer Anhang (0 Byte) | CORRUPT | Abgewiesen, bevor ein Format erkannt werden kann - unabhängig von der Endung. |
| Anhänge über der Grössengrenze | TOO_LARGE | Siehe Grenzwerte. Zweifach geprüft: gegen die von Jira gemeldete Grösse vor dem Download und erneut gegen die tatsächlich empfangenen Bytes, sodass eine ungenaue Grössenangabe keinen Anhang durchschlüpfen lässt. |
| Dateien, die sich nicht parsen lassen | CORRUPT | Abgeschnittene oder fehlerhafte Eingabe. |
| Dateien, die das Parse-Budget überschreiten | TIMEOUT | Siehe Grenzwerte. |
| Bilder und Dokumente mit nicht lesbaren Bildern, die ein Mensch ansehen muss | NEEDS_REVIEW | Siehe Bilder. Der Anhang erscheint mit dem konkreten Grund auf der Seite Manuelle Prüfungen. |
| Anhänge, die zwischen Auflistung und Download gelöscht wurden | NOT_FOUND | Bei langen Scans zu erwarten; kein Fehler. |
Übersprungene Anhänge werden getrennt von fehlgeschlagenen gezählt. Ein Scan,
der Anhänge überspringt, wird als COMPLETED WITH GAPS gekennzeichnet. Die
Scan-Detailseite zeigt unter den Zahlen gescannter und übersprungener Anhänge
eine Abdeckungsaufschlüsselung: eine Zeile je Grund aus der Tabelle oben, mit
der Anzahl der Anhänge, die darauf entfallen.
Jeder Grund wird auch dann aufgeführt, wenn seine Anzahl null ist, damit
"keine passwortgeschützten Dateien gefunden" unterscheidbar bleibt von
"passwortgeschützte Dateien wurden nie geprüft". Dieselbe Aufschlüsselung
liefert GET /api/scans/{id}/attachment-coverage; damit wird die Abdeckung
eines Scans überprüfbar, statt nur behauptet zu sein.
Verschachtelte Archive
Ein Archiveintrag, der selbst ein Archiv ist - ein ZIP im ZIP - wird nicht geöffnet; die Extraktion geht nur eine Ebene tief. Alles innerhalb dieser einen Ebene trägt weiterhin zum extrahierten Text und zu Funden bei, genauso wie ein Archiv mit mehr Einträgen als der Grenzwert bei diesem Grenzwert stoppt, statt die ganze Datei scheitern zu lassen. Ein Secrets-Scanner sollte melden, was eine Verschachtelungsebene enthielt, statt eine sonst erfolgreiche Extraktion wegen eines zu tief verschachtelten Eintrags zu verwerfen. Zu tiefe Verschachtelung wird nicht als eigener Übersprungsgrund gemeldet und ändert nichts daran, ob der umgebende Anhang als gescannt zählt.
Grenzwerte
| Grenzwert | Standard | Umgebungsvariable |
|---|---|---|
| Maximale Anhangsgrösse | 25 MB (26.214.400 Byte) | SCAN_ATTACHMENTS_MAX_DOWNLOAD_BYTES |
| Parse-Budget je Anhang | 60 Sekunden | SCAN_ATTACHMENTS_PARSE_TIMEOUT |
| Maximal extrahierter Text je Anhang | 20.000.000 Zeichen | SCAN_ATTACHMENTS_MAX_EXTRACTED_CHARS |
| Maximal gelesene Einträge je Archiv | 1.000 | SCAN_ATTACHMENTS_MAX_ARCHIVE_ENTRIES |
| Maximal entpackte Bytes je Archiv | 50 MB (52.428.800 Byte) | SCAN_ATTACHMENTS_MAX_ARCHIVE_BYTES |
| Gleichzeitig geparste Anhänge | 20 | SCAN_ATTACHMENTS_MAX_PARSE_THREADS |
| OCR-Sprachen | eng+deu | SCAN_ATTACHMENTS_IMAGES_OCR_LANGUAGES |
| Maximale Bildgrösse | 40.000.000 Pixel | SCAN_ATTACHMENTS_IMAGES_MAX_PIXELS |
| OCR-Budget je Bild | 30 Sekunden | SCAN_ATTACHMENTS_IMAGES_OCR_TIMEOUT |
| OCR-Speichergrenze | 536.870.912 Byte | SCAN_ATTACHMENTS_IMAGES_OCR_MAX_MEMORY_BYTES |
| OCR-CPU-Grenze | 30 Sekunden | SCAN_ATTACHMENTS_IMAGES_OCR_CPU_SECONDS |
| Gleichzeitig per OCR gelesene Bilder | Die Hälfte der CPU-Kerne, mindestens 1 | SCAN_ATTACHMENTS_IMAGES_MAX_CONCURRENT_OCR |
| Minimale Grösse eingebetteter Bilder | 20.480 Byte | SCAN_ATTACHMENTS_IMAGES_MIN_EMBEDDED_IMAGE_BYTES |
Ein Anhang, der die Textgrenze erreicht, wird nicht verworfen: Der bis zu dieser Grenze erfasste Text wird weiterhin auf Funde durchsucht, statt den ganzen Anhang wegen eines Zeichens zu viel zu verwerfen.
Datenverarbeitung
Die Erkennungsregeln laufen über den vollständigen extrahierten Text eines Anhangs. Genau das ist Anhang-Scanning: Dieselben Regeln, die Issue-Felder und Kommentare lesen, lesen auch den Text in der Datei.
Der Text selbst, extrahiert oder per OCR erkannt, bleibt nur im Arbeitsspeicher, solange dieser eine Anhang gescannt wird, und wird verworfen, sobald die Regeln darüber gelaufen sind. Er wird nie in die Datenbank geschrieben, nie geloggt und nie an die Mustererkennung weitergegeben - diese sieht ausschliesslich Issue-Felder und Kommentare. Ein Fund speichert einen Offset und einen geschlüsselten Fingerabdruck, nie den Trefferwert und nie den umgebenden Dateiinhalt. Siehe Sicherheit und Datenverarbeitung.
Bild-Bytes werden für die Dauer der OCR in ein privates temporäres Verzeichnis (Berechtigungen nur für den Eigentümer) geschrieben und danach gelöscht, unabhängig davon, ob die OCR gelingt, scheitert oder die Zeit überschreitet. Das ist der einzige Fall, in dem Anhangsinhalte die Festplatte berühren.
Manuelle Prüfungen speichern den Dateinamen des Anhangs, den Issue-Schlüssel und den Grund sowie die Entscheidung der prüfenden Person - nie Bild-Bytes, Vorschaubilder, OCR-Text oder Ausschnitte.
OCR läuft in einem separaten Prozess, der keines der Geheimnisse des Scanners erhält (keine Datenbank-, Jira-, SMTP- oder Lizenz-Zugangsdaten in seiner Umgebung) und mit Speicher-, CPU- und Zeitgrenzen läuft. Der Netzwerkzugriff dieses Prozesses ist nicht eingeschränkt; Tesseract selbst enthält keinen Netzwerkcode.
Planung
Das Scannen von Anhängen ist das Teuerste, was der Scanner tut. Es lädt Bytes von
Jira herunter, erzeugt also Netzwerklast auf der Jira-Seite und Speicherdruck auf
dem Scanner. Erhöhen Sie den Speicher des Containers, bevor Sie
SCAN_ATTACHMENTS_MAX_PARSE_THREADS erhöhen, und erwägen Sie, Scans mit
aktivierten Anhängen auf einen engeren Projekt-Scope zu beschränken als Ihre
routinemässigen Feld- und Kommentar-Scans.
OCR ist CPU-gebunden. Geben Sie dem Container mehr CPU, bevor Sie
SCAN_ATTACHMENTS_IMAGES_MAX_CONCURRENT_OCR erhöhen.