Handleiding bij de broncodepreview · 0.1.0

Duurzame jobs en publicatie van bewijs

Begrijp lease-eigendom, resultaatvalidatie, commit vóór bevestiging en bevindingrevisies.

De API-referentie is in het Engels.

De database bezit geaccepteerd werk. Een pagina kan herladen, een editor kan de verbinding verliezen en een worker kan zijn lease kwijtraken zonder dat de browser het verslag wordt van wat er gebeurde. Duurzame jobstatus, scannertransportstatus en gepubliceerd scanbewijs blijven gescheiden.

Identificeer een opdracht vóór uitvoering

De jobrepository bindt een idempotentiesleutel aan client en jobsoort. Dezelfde opdracht herhalen geeft de bestaande job terug; die identiteit voor een andere opdracht hergebruiken is een conflict. De job heeft ook een stabiele externe runidentiteit, begrensde payload-/checkpointdocumenten en een revisie.

Jobstatussen zijn queued, leased, running, cancelling, completed, failed en cancelled. Geslaagde indiening betekent geaccepteerd werk. Ze betekent niet dat een scanner draaide of volledig bewijs bestaat.

claim_next_job vereist PostgreSQL. Het vergrendelt geschikte rijen zonder op de door een andere worker gekozen rij te wachten en behandelt verlopen leases en herstelkandidaten. Jobwijzigingen controleren onder een lock job-ID, workeridentiteit, poging, toegestane status en geldige lease. Heartbeats vernieuwen dat exacte eigendom. Een voormalige eigenaar kan een job niet afronden alleen omdat hij ooit de lease had.

Een herhaalbare fout zet een job alleen binnen zijn poging- en operatiebudgetgrenzen terug in de wachtrij. Een herpoging verlengt de voorbereidingsdeadline niet onbeperkt. Zie jobrepository en jobgegevensmodel.

Publiceer bewijs voordat opruimen mag

De scanner verzegelt een genormaliseerd resultaat en biedt manifest en begrensde bevindingenpagina’s aan. De worker behandelt hun beschikbaarheid niet als duurzame publicatie.

1. Valideer het manifest en bind run, verzoekdigest, resultaatdigest, artefactmanifestdigest en artefactherkomst in het duurzame jobcheckpoint.
2. Begin één PostgreSQL-transactie, vergrendel de bovenliggende scan en weiger publicatie als daarvoor al bevindingen of artefactindexen bestaan. Haal elke begrensde pagina op en valideer de identiteiten, cursor, volgnummers, byteaantallen, hashes, canonieke waarden, ordening en unieke fingerprints. Scherm gevoelige gegevens af en voeg de toegelaten bevindingen van die pagina in zonder te committen.
3. Controleer of de volledige stream en samenvatting overeenkomen met het manifest. Laat de exact geattesteerde artefacten toe, werk revisies bij en registreer scanner_persisted=true in diezelfde transactie.
4. Stel vast dat de transactie is gecommit vóór ACK voor de exacte run-, verzoek- en resultaatbinding.
5. Laat de scanner het tijdelijke resultaat verwijderen en ga verder met scan-/gateafronding. Een opgeslagen resultaat waarvan opruiming nog controle en afstemming vereist, blijft een andere toestand dan ongepubliceerd bewijs.

Dit is een eenmalige invoeggrens voor bewijs. Een herpoging moet haar gecommitte checkpoint herstellen, niet bestaande bevindingen vervangen en de beoordeling van een operator wissen. De code weigert conflicterende publicatie met scan_evidence_conflict. De bepalende implementatie is de opslagtransactie.

Bij teruggerolde commit worden gedeeltelijk ingevoegde bevindingen niet gezaghebbend. Bij een onzekere uitkomst controleert de worker eerst de duurzaam opgeslagen toestand en stemt die af vóór het opruimen. Zodra scanner_persisted=true duurzaam is, bestaat herstel alleen uit ACK en wordt de collectie niet opnieuw opgehaald en ingevoegd. Een scanner-404 mag uitsluitend op dit al opgeslagen herstelpad als reeds opgeruimd gelden. Bevestigingsherstel bindt die uitzondering.

Begrens tijdelijk transport apart van opslag

De tijdelijke scannerspool is private tmpfs. Hij is geen duurzame bewijsopslag, downloadbaar artefact of back-up. Onbevestigde resultaten worden niet verwijderd enkel om een eindrecordslot vrij te maken; capaciteitsdruk kan dus nieuw werk weigeren. De tijdslimiet blijft gelden. Een scannerherstart verliest procesregister en cursorgeheim en verwijdert herkende oude spoolbestanden.

Paginacursors binden proces, run, verzoek, resultaat en volgende positie. Ze zijn niet voor een ander resultaat bruikbaar. Het runregister implementeert dit tijdelijke transportcontract.

Bewaar bruikbaar bewijs zonder ruwe rapporten te publiceren

Bevindingen bewaren genormaliseerde scanner-/regelidentiteit, ernst, bronlocatie, melding, fragment, fingerprint en begrensde metadata. Gevoelige gegevens worden vóór scannerpublicatie en opnieuw vóór database-invoeging afgeschermd. Deze afscherming herkent bekende patronen en gevoelige structuren, maar garandeert geen verwijdering van elk mogelijk geheim.

De artefactgrens laat begrensde gesaneerde Syft CycloneDX JSON-SBOM’s toe. Ze valideert het speciale pad met no-follow-operaties, bindt herkomst van ruwe naar gesaneerde vorm en indexeert de inhoudsidentiteit. Download controleert grootte en digest tegen de index en kopieert geverifieerde bytes naar begrensde antwoordopslag. Ruwe scanner-stdout, stderr, SARIF, JSONV2 en JSONL zijn geen gepubliceerde artefacten.

Lees afscherming van gevoelige scannergegevens en artefacttoelating en download. Deze controles beperken blootstelling; ze maken willekeurige vijandige broncode niet veilig uitvoerbaar.

Zet de levenscyclus na publicatie voort

Nieuwe bevindingen beginnen open, niet onderdrukt, niet gatevrijgesteld en op revisie één. De zeven beoordelingen zijn open, needs_review, gate_exempt, accepted_risk, ignore, false_positive en fixed. Het zijn selecteerbare toestanden, geen verplichte lineaire workflow.

open en needs_review tellen mee voor de gate. gate_exempt en accepted_risk blijven niet-onderdrukt maar tellen niet mee voor de gate. ignore, false_positive en fixed onderdrukken de bevinding. De vijf uitsluitende beoordelingen vereisen een niet-lege reden. Elke wijziging controleert de verwachte revisie, werkt beoordelingsmetadata bij en ververst bevindingenoverzicht en gate-evaluatie van de scan.

fixed markeren inspecteert geen bewerkt bestand. Een nieuwe scan levert nieuw bewijs en begint zijn bevindingen open. Overeenkomende scanner-/fingerprintwaarden tussen projectscans ondersteunen herhalingsgeschiedenis; ze erven geen oudere beoordelingen. Een bevinding verwijderen wist haar rij en is een afzonderlijke actie met revisie- en actieve-jobcontroles.

Pagina’s en details zijn aan collectierevisies gebonden zodat oude weergaven geen nieuwere beslissingen stilzwijgend overschrijven. Advisor-velden zijn gescheiden van levenscyclusvelden. Advies onderdrukt geen bevinding automatisch, accepteert geen risico en verandert geen gate. Zie levenscycluswijziging en de bevindingenworkflow.

Behandel annulering en herstel als waarneembare uitkomsten

Een annuleringsverzoek wordt opgeslagen en kan de race met normale voltooiing winnen. Einduitkomsten blijven definitief. Scannercache-operaties weigeren annulering tijdens commit of activering, wanneer publicatie haar beschermde grens passeerde. Annulering draait geen geactiveerde cachegeneratie terug en haalt geen al geleverde Advisor-gegevens terug.

Een afgeronde job, volledige scan en geslaagde gate zijn verschillende resultaten. Alleen volledig scanbewijs bereikt normale beleidsevaluatie; beoordelingen repareren geen ontbrekende dekking. De gate-implementatie bewaart dit onderscheid.

Duurzame jobs ondersteunen het herstellen en afstemmen van de toestand na een onderbreking. Ze bewijzen geen volledige crash- of noodherstelkwalificatie. De huidige back-uphelper is experimenteel, niet-atomair en uitgeschakeld zonder expliciete opt-in voor wegwerptests. Volg de herstelgids en bewaar exacte bewijsidentiteiten bij foutonderzoek.