Handleiding bij de broncodepreview · 0.1.0
Broncode uitbreiden met duidelijke contracten
Vind de scanner-, bewijs-, client- en workflowgrenzen die een gerichte bijdrage moet behouden.
De API-referentie is in het Engels.
De broncode biedt bruikbare bijdragemogelijkheden: scanneradapters en regels, genormaliseerd bewijs, duurzame workflows, de React-werkbank en VS Code-client. Dit zijn beoordeelde implementatiegrenzen. Er is geen runtimeplugin-SDK, willekeurig uitvoerbaar register of algemene API-sleutelintegratie.
Kies een begrensde bijdrage
- Vind het contract
Begin bij openbaar toolregister, adapterdispatch en genormaliseerd bevindingenschema.
- Beoordeel tool- en gegevensinvoer
Werk relevante vastgelegde buildinvoer, vermeldingen en scannergegevensvereisten bij.
- Implementeer de begrensde adapter
Definieer exacte argumenten, omgeving en parsing. Behoud reikwijdte, uitvoergrenzen en redactie van bekende patronen.
- Verbind gereedheid en dekking
Maak ontbrekende gegevens, onbeschikbare tools en beperkte analyse zichtbaar in voorcontrole en resulterende scan.
- Controleer gewijzigd gedrag
Gebruik kleine synthetische fixtures en gerichte controles voor parsing, foutpaden, gereedheid en resultaatverzameling.
- Beoordeel de volledige wijziging
Verbind bronwijzigingen aan getroffen UI- en API-contracten voordat je een bijdrage deelt.
| Gebied | Implementatiestartpunt | Te behouden contract |
|---|---|---|
| Scanneruitvoering | Register en native adapters | Vastgelegde identiteit, eigen configuratie, begrensde uitvoering en eerlijke parser-/dekkingsuitkomsten. |
| Regels en scannergegevens | Toollock, regellock en generatievalidatie | Beoordeelde invoer, inhoudsidentiteit, compatibiliteit, versheid en atomaire activering. |
| Bevindingen en artefacten | Scannernormalisatie en artefactgrens | Canonieke locatie en fingerprint, begrensde metadata, redactie en geattesteerde publicatie. |
| Duurzame workflows | Jobrepository en workeruitvoering | Idempotentie, lease-/pogingafscherming, deadlines, annulering en herstelbare checkpoints. |
| Browserworkflows | React-toepassing | Gezaghebbende resourceverversing, verwachte revisies, bruikbare wacht-/fouttoestanden en toegankelijkheid. |
| Editorworkflows | VS Code-bron | Actieve capabilitygeneratie, Workspace Trust, bronidentiteit en expliciete hostacties. |
Een kleine regelfixture of nauwe workflowcorrectie kan een nuttige eerste wijziging zijn. Beschrijf het te corrigeren gedrag en het bewijs daarvan. Gebruik een brede categorie zoals SAST-ondersteuning niet als belofte voor elke taal of zwakte.
Voeg een scanner toe of wijzig hem gecoördineerd
Het vaste register valideert toolversies, versieopdrachten, argumenten, aanvullende passes, omgevingen en uitvoerformaten tegen de lock. Alleen een binary aan een image toevoegen is dus onvoldoende. Uitvoering weigert onbekende scanner-ID’s.
- Beoordeel upstreambron, licentie, wijzigingen en exacte build-/downloadinvoer. Behoud vereiste vermeldingen en bind de image-identiteit.
- Werk catalogus en locks bij met bedoelde opdracht, uitvoerformaat en vereiste regels of gegevens. Houd netwerkvoorbereiding los van bronuitvoering.
- Implementeer adapter en parser met eigen bediening, eindige uitvoering en uitvoergrenzen, canonieke bronlocaties en eerlijke fouten. Maak van ongeldige uitvoer geen nul bevindingen.
- Integreer gereedheid en brondekking. Een ontbrekende vereiste moet zichtbaar blijven vóór toelating of in onvolledig bewijs.
- Voeg waar passend positieve, nulbevinding-, ongeldige, te grote, timeout- en bronbesturingsgevallen toe. Verifieer de native tool naast parserfixtures.
- Beoordeel genormaliseerde bevindingen, redactie, deterministische fingerprints en het volledige workerpublicatiepad. Een ruw native rapport is niet automatisch een ondersteund artefact.
De huidige scanneruitvoeringsmatrix verklaart adapterverschillen. Trivy heeft twee passes; Grype hangt van Syft af; Checkov beheert zijn configuratieontdekking; Bearer gebruikt een gewijzigde build. Elke upgrade vereist vernieuwd bewijs voor die specifieke contracten.
Bewaar bewijsbetekenis bij nieuwe workflows
Een nieuwe status of UI-actie beïnvloedt mogelijk meer dan een label. Bevindingen hebben eigen revisies en beoordelingen; scans hebben dekking en gatebeslissingen; jobs hebben leases en einduitkomsten. Houd die betekenissen gescheiden.
Risico accepteren sluit bijvoorbeeld een bestaande bevinding uit van gatetellingen maar vult geen ontbrekende scannerdekking. Fixed markeren legt een beoordeling vast maar verifieert geen gewijzigde bron. Een afgeronde werkboomscan autoriseert geen beschermde push waarvan eerdere uitgaande commits andere bomen bevatten.
Clientwijzigingen moeten REST-toestand verzoenen na events, resets en mutaties in plaats van aanwijzingen als volledige resources te behandelen. Een verouderd antwoord mag geen nieuwere beslissing overschrijven. Beoordeel API-revisiecontract én zichtbaar gedrag tijdens navigatie, herverbinden, annulering en fouten.
Houd integraties binnen bestaande bevoegdheid
Controlclients gebruiken browsersessie-/CSRF-regels of exacte toegestane IDE-capabilityscopes plus route-eigendomscontroles. Interne scanner-, updater- en Advisor-protocollen zijn geen ondersteunde integratie-API’s. Een nieuwe route mag niet per ongeluk elke gekoppelde editor eigenaaracties of een bredere bronmount geven.
Advisor-uitbreidingen moeten de openbaarmakingsgrens behouden. Externe bevestiging voor één bevinding bindt bestemming, model, configuratie, toestemming en promptidentiteit; automatische scanbrede selectie blijft lokaal. De huidige connector spreekt de beoordeelde Ollama-routes. Ondersteuning van een andere provider is een bron- en beveiligingscontractwijziging, geen verborgen configuratietruc.
Gebruik bronbevoegdheid en interne diensten om aanroeper en vertrouwensgrens te bepalen voordat je een wijziging voorstelt.
Meld bewijs op het niveau dat het aantoont
Gerichte unittests bewijzen de uitgevoerde gevallen. Native scannerfixtures bewijzen gedrag van exacte gebruikte tool-/gegevensinvoer. Browsertrajecten bewijzen de waargenomen clientworkflow. Image-uitgangscontroles, hosthookgedrag en platformacceptatie vereisen eigen waarnemingen. Geen daarvan mag volledige releasekwalificatie worden genoemd.
De repository bevat gerichte tests voor jobeigendom, events, artefacttoelating en bronbeheerde scannercontroles. Hun bestaan is een routekaart voor bijdragers, geen claim dat ze bij een nieuwe wijziging zijn uitgevoerd.
Volg de bijdragegids, ontwikkelcontroles en releasegrenzen. Leg exacte bron en geteste invoer, waargenomen resultaat en resterende hiaten vast.