Anleitung zur Quellcode-Vorschau · 0.1.0

Dauerhafte Jobs und Veröffentlichung von Nachweisen

Verstehe Lease-Eigentum, Ergebnisvalidierung, Commit vor Bestätigung und Befundrevisionen.

Die API-Referenz ist auf Englisch.

Die Datenbank besitzt angenommene Arbeit. Seiten können neu laden, Editoren die Verbindung und Worker ihre Lease verlieren, ohne den Browser zur maßgeblichen Aufzeichnung zu machen. Dauerhafter Jobzustand, Scannertransportzustand und veröffentlichte Scannachweise bleiben getrennt.

Identifiziere Befehle vor der Ausführung

Das Jobrepository bindet einen Idempotenzschlüssel an Client und Jobart. Wiederholen desselben Befehls liefert den bestehenden Job; Wiederverwendung für einen anderen Befehl ist ein Konflikt. Der Job hat außerdem eine stabile externe Laufidentität, begrenzte Nutzlast-/Checkpoint-Dokumente und eine Revision.

Jobzustände sind queued, leased, running, cancelling, completed, failed und cancelled. Erfolgreiches Einreichen bedeutet angenommene Arbeit, keinen ausgeführten Scanner oder vollständige Nachweise.

claim_next_job benötigt PostgreSQL. Es sperrt geeignete Zeilen ohne auf die Auswahl eines anderen Workers zu warten und behandelt abgelaufene Leases und Wiederherstellungskandidaten. Jobänderungen prüfen unter Sperre Job-ID, Workeridentität, Versuch, erlaubten Zustand und nicht abgelaufene Lease. Heartbeats erneuern genau dieses Eigentum. Frühere Besitzer können Jobs nicht abschließen, nur weil sie einmal die Lease hielten.

Wiederholbare Fehler stellen Jobs nur innerhalb ihrer Versuchs- und Operationsbudgetgrenzen zurück in die Warteschlange. Wiederholen verlängert keine Vorbereitungsfrist unbegrenzt. Siehe Jobrepository und Jobdatenmodell.

Veröffentliche Nachweise vor erlaubter Bereinigung

Der Scanner versiegelt ein normalisiertes Ergebnis und stellt Manifest und begrenzte Befundseiten bereit. Der Worker behandelt bloße Verfügbarkeit nicht als dauerhafte Veröffentlichung.

1. Validiere das Manifest und binde Lauf, Anfragedigest, Ergebnisdigest, Artefaktmanifestdigest und Artefaktherkunft im dauerhaften Jobcheckpoint.
2. Beginne eine PostgreSQL-Transaktion, sperre den übergeordneten Scan und verweigere die Veröffentlichung, falls dafür bereits Befunde oder Artefaktindizes vorhanden sind. Hole jede begrenzte Seite und validiere ihre Identitäten, Cursor, Ordnungsnummern, Bytezahlen, Hashes, kanonischen Werte, Reihenfolge und eindeutigen Fingerprints. Bereinige die zugelassenen Befunde dieser Seite und füge sie ohne Commit ein.
3. Gleiche den vollständigen Stream und die Zusammenfassung mit dem Manifest ab. Lasse die genau attestierten Artefakte zu, aktualisiere Revisionen und speichere scanner_persisted=true in derselben Transaktion.
4. Stelle den Commit fest, bevor ACK für die genaue Lauf-, Anfrage- und Ergebnisbindung gesendet wird.
5. Lass den Scanner das temporäre Ergebnis entfernen und fahre mit Scan-/Gate-Abschluss fort. Ein gespeichertes Ergebnis mit noch abzugleichender Bereinigung bleibt von unveröffentlichten Nachweisen verschieden.

Dies ist eine Einmal-Einfügegrenze für Nachweise. Wiederholung muss den committeten Checkpoint wiederherstellen, statt bestehende Befunde und Operatorbewertungen zu ersetzen. Die Implementierung lehnt widersprüchliche Veröffentlichung mit scan_evidence_conflict ab. Maßgeblich ist die Speichertransaktion.

Rollt der Commit zurück, werden teilweise eingefügte Befunde nicht maßgeblich. Bei unklarem Ergebnis gleicht der Worker vor Bereinigung dauerhaften Zustand ab. Sobald scanner_persisted=true dauerhaft ist, besteht Wiederherstellung nur aus ACK; die Sammlung wird nicht erneut geladen und eingefügt. Ein Scanner-404 darf nur in diesem bereits gespeicherten Wiederherstellungspfad als schon bereinigt gelten. Bestätigungswiederherstellung bindet diese Ausnahme.

Begrenze temporären Transport getrennt vom Speicher

Der temporäre Scannerspool ist private tmpfs. Er ist kein dauerhafter Nachweisspeicher, herunterladbares Artefakt oder Backup. Unbestätigte Ergebnisse werden nicht nur für einen freien Enddatensatzplatz entfernt; Kapazitätsdruck kann neue Arbeit ablehnen. Das Zeitlimit gilt weiter. Ein Scannerneustart verliert prozesslokales Register und Cursor-Geheimnis und entfernt erkannte alte Spooldateien.

Seitencursor binden Prozess, Lauf, Anfrage, Ergebnis und nächste Position. Sie sind nicht für andere Ergebnisse wiederverwendbar. Das Laufregister implementiert diesen temporären Transportvertrag.

Erhalte nützliche Nachweise ohne Rohberichte

Befunde speichern normalisierte Scanner-/Regelidentität, Schweregrad, Quellort, Meldung, Ausschnitt, Fingerprint und begrenzte Metadaten. Sie werden vor Scannerveröffentlichung und erneut vor Datenbankeinfügen bereinigt. Bereinigung erkennt bekannte Muster und sensible Strukturen, garantiert jedoch keine Entfernung jedes möglichen Geheimnisses.

Die Artefaktgrenze lässt begrenzte bereinigte Syft-CycloneDX-JSON-SBOMs zu. Sie validiert den vorgesehenen Pfad mit No-follow-Operationen, bindet Herkunft von Roh- zu bereinigten Daten und indexiert die Inhaltsidentität. Download prüft Größe und Digest gegen den Index und kopiert verifizierte Bytes in begrenzten Antwortspeicher. Rohe Scanner-stdout, stderr, SARIF, JSONV2 und JSONL sind keine veröffentlichten Artefakte.

Lies Scannerbereinigung und Artefaktzulassung und Download. Diese Kontrollen verringern Offenlegung; beliebige feindliche Quellen werden dadurch nicht sicher ausführbar.

Führe den Lebenszyklus nach Veröffentlichung fort

Neue Befunde beginnen open, nicht unterdrückt, ohne Gate-Ausnahme und bei Revision eins. Die sieben Bewertungen sind open, needs_review, gate_exempt, accepted_risk, ignore, false_positive und fixed. Es sind wählbare Zustände, kein vorgeschriebener linearer Ablauf.

open und needs_review zählen zum Gate. gate_exempt und accepted_risk bleiben nicht unterdrückt, zählen aber nicht zum Gate. ignore, false_positive und fixed unterdrücken den Befund. Die fünf ausschließenden Bewertungen verlangen eine nicht leere Begründung. Jede Änderung prüft die erwartete Revision, aktualisiert Bewertungsmetadaten und erneuert Befundübersicht und Gate-Bewertung des Scans.

fixed untersucht keine bearbeitete Datei. Ein neuer Scan erzeugt neue Nachweise und beginnt seine Befunde offen. Passende Scanner-/Fingerprintwerte zwischen Projektscans unterstützen die Auftretenshistorie, erben aber keine älteren Bewertungen. Löschen entfernt die Befundzeile und ist eine separate Aktion mit Revisions- und aktiven Jobprüfungen.

Befundseiten und Details sind an Sammlungsrevisionen gebunden, damit alte Ansichten keine neueren Entscheidungen stillschweigend überschreiben. Advisor-Felder sind von Lebenszyklusfeldern getrennt. Rat unterdrückt keinen Befund automatisch, akzeptiert kein Risiko und ändert kein Gate. Siehe Lebenszyklusänderung und Befundablauf.

Behandle Abbruch und Wiederherstellung als beobachtbare Ergebnisse

Abbruchanfragen werden gespeichert und können das Rennen gegen normalen Abschluss gewinnen. Endzustände bleiben endgültig. Scannercache-Operationen verweigern Abbruch während Commit oder Aktivierung nach der geschützten Veröffentlichungsgrenze. Abbruch macht keine aktivierte Generation rückgängig und holt keine bereits gelieferten Advisor-Daten zurück.

Abgeschlossener Job, vollständiger Scan und bestandenes Gate sind verschiedene Ergebnisse. Nur vollständige Scannachweise erreichen die normale Richtlinienbewertung; Bewertungen ergänzen keine fehlende Abdeckung. Die Gate-Implementierung erhält diesen Unterschied.

Dauerhafte Jobs unterstützen Abgleich nach Unterbrechung. Sie belegen keine vollständige Crash- oder Notfallwiederherstellungsqualifikation. Der aktuelle Backuphelfer ist experimentell, nicht atomar und ohne ausdrückliches Opt-in für Wegwerftests deaktiviert. Folge der Wiederherstellungsanleitung und bewahre genaue Nachweisidentitäten bei Fehlerbewertung.