Source preview guide · 0.1.0
Extend the source with clear contracts
Find the scanner, evidence, client and workflow boundaries that a focused contribution must preserve.
CodeSecurity exposes useful places to contribute through its source: scanner adapters and rules, normalized evidence, durable workflows, the React workbench and the VS Code client. These are reviewed implementation boundaries. There is no runtime plugin SDK, arbitrary executable registry or generic API-key integration.
Choose a bounded contribution
- Locate the contract
Start with the public tool registry, adapter dispatch and normalized finding schema.
- Review tool and data inputs
Update the relevant pinned build inputs, notices and scanner-data requirements.
- Implement the bounded adapter
Define exact arguments, environment and parsing. Preserve scope, output limits and known-pattern redaction.
- Connect readiness and coverage
Make missing data, unavailable tools and limited analysis visible to preflight and the resulting scan.
- Exercise the changed behavior
Use small synthetic fixtures and focused checks for parsing, failure paths, readiness and result collection.
- Review the complete change
Connect source changes to the affected UI and API contracts before sharing a contribution.
| Area | Implementation starting point | Contract to preserve |
|---|---|---|
| Scanner execution | Registry and native adapters | Pinned identity, owned configuration, bounded execution and honest parser/coverage outcomes. |
| Rules and scanner data | Tool lock, rules lock and generation validation | Reviewed inputs, content identity, compatibility, freshness and atomic activation. |
| Findings and artifacts | Scanner normalization and artifact boundary | Canonical location and fingerprint, bounded metadata, redaction and attested publication. |
| Durable workflows | Job repository and worker execution | Idempotency, lease/attempt fencing, deadlines, cancellation and recoverable checkpoints. |
| Browser workflows | React application | Authoritative resource refresh, expected revisions, useful pending/error states and accessibility. |
| Editor workflows | VS Code source | Active capability generation, Workspace Trust, source identity and explicit host actions. |
A small rule fixture or a narrowly scoped workflow correction can be a useful first change. Describe the behavior being corrected and the evidence that demonstrates it. Avoid using a broad category such as SAST support as a promise about every language or weakness.
Add or change a scanner as a coordinated source change
The fixed registry validates tool versions, version commands, arguments, supplemental passes, environments and output formats against the lock. Adding a binary to an image is therefore insufficient. Unknown scanner IDs are refused by execution.
- Review the upstream source, license, modifications and exact build/download inputs. Preserve required notices and bind the image identity.
- Update the catalog and locks with the intended command, output format and required rules or data. Keep networked preparation separate from source execution.
- Implement the adapter and parser with owned controls, finite execution and output bounds, canonical source locations and truthful errors. Do not turn malformed output into zero findings.
- Integrate readiness and source coverage. A missing prerequisite must remain visible before admission or in incomplete evidence.
- Add positive, zero-finding, malformed, oversized, timeout and source-control cases as appropriate. Verify the native tool as well as parser fixtures.
- Review normalized findings, redaction, deterministic fingerprints and the complete worker publication path. A raw native report is not automatically a supported artifact.
The current scanner execution matrix shows why adapters differ. Trivy has two passes; Grype depends on Syft; Checkov owns its configuration-discovery behavior; Bearer uses a modified build. Upgrading any of them requires renewed evidence for those specific contracts.
Preserve evidence semantics when adding workflows
A new status or UI action can affect more than a label. Findings have their own revisions and dispositions; scans have coverage and gate decisions; jobs have leases and terminal outcomes. Keep those meanings separate.
For example, accepting risk excludes an existing finding from gate counts but does not fill missing scanner coverage. Marking a finding fixed records a review decision but does not verify changed source. A completed working-tree scan cannot authorize a protected push whose earlier outgoing commits contain different trees.
Client changes should reconcile REST state after events, resets and mutations rather than treating event hints as complete resources. A stale response must not overwrite a newer decision. Review both the API’s revision contract and the visible behavior during navigation, reconnect, cancellation and failure.
Keep integrations within existing authority
Control clients use browser session/CSRF rules or the exact allowed IDE capability scopes, plus each route’s ownership checks. Internal scanner, updater and Advisor protocols are not supported integration APIs. Adding a new route must not accidentally grant every paired editor access to owner-only actions or a wider source mount.
Advisor extensions must preserve the disclosure boundary. A single-finding remote confirmation binds destination, model, configuration, consent and prompt identity; automatic scan-wide resolution remains local-only. The current connector speaks the reviewed Ollama routes, so supporting another provider is a source and security-contract change, not an undocumented configuration trick.
Use source authority and internal services to identify the caller and trust boundary before proposing a change.
Report evidence at the level it proves
Focused unit tests establish the cases they execute. Native scanner fixtures establish behavior of the exact tool/data inputs used. Browser journeys establish the observed client workflow. Image egress checks, host-hook behavior and platform acceptance require their own observations. None should be relabeled as full release qualification.
The repository includes focused tests for job ownership, events, artifact admission and source-owned scanner controls. Their existence is a map for contributors, not a claim that they were run for a new change.
Follow the contribution guide, development checks and release limits. Record the exact source and tested inputs, the observed result and any remaining gap.