Documentation
¶
Overview ¶
Package scan is the importable scan pipeline shared by the CLI and the test corpus. It lowers source at a path to gIR (dispatching to the right language frontend, or all present frontends for a directory) and runs the taint engine plus the hardcoded-secrets scanner over the result. Keeping this out of package main lets tests exercise exactly the same code path the CLI runs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CoverageSummary ¶
func CoverageSummary(coverage []LangCoverage) string
CoverageSummary renders a one-line per-language coverage summary, so a degraded scan — a frontend that failed on detected source, or one that silently dropped part of it — is visible even when the run is not strict. Empty when no language was detected. It lives here rather than in a command because both binaries print it and the wording is the thing that must agree.
func LanguageOf ¶
LanguageOf reports which frontend claims path, off the same languageFrontends table the scan dispatches on. ok is false when no frontend handles it — which is the difference between a file that was skipped and one that is not code.
Types ¶
type LangCoverage ¶
type LangCoverage struct {
Language string
Detected bool
Converted bool
Err string
// Files is how many source files of this language the walk found, and Skipped
// how many of them the frontend could not lower. Converted is all-or-nothing
// and so hides a PARTIAL failure: a frontend that lowers three files out of two
// hundred still reports ok. Skipped is 0 for a frontend whose unit of work is
// not a file (Go lowers packages), so 0 means "nothing known to be dropped",
// not a guarantee.
Files int
Skipped int
}
LangCoverage records what happened to one language frontend during a scan: whether its source was Detected in the target, whether the frontend successfully Converted it, and the error if it did not. It exists so a caller (the CI gate) can tell "analyzed and clean" apart from "never analyzed" — a frontend/build/type-check failure must not masquerade as a clean result.
type Option ¶
type Option func(*config)
Option configures a scan.
func WithDiagnostics ¶
func WithDiagnostics() Option
WithDiagnostics collects the telemetry behind the HTML report's scan diagnostics panel. Off by default: it is a second read pass over the source for the line count, plus a glob of every distinct callee against every rule, and nothing but that panel reads it — a gate run, `rules test` over every sample, and the corpus loop would all pay for a number they discard.
func WithSources ¶
func WithSources() Option
WithSources retains the list of source files the walk handed the frontends, in Result.Sources. Off by default for the same reason as WithDiagnostics: it is a selection pass nothing on the gate path reads. A caller that wants to know which files produced no gIR needs it, and asking here is far cheaper than walking the tree a second time — on a large repo that second walk is seconds, and it stats every entry.
type Result ¶
type Result struct {
Findings []analysis.Finding
Program *ir.Program
// Coverage reports, per language present in the target, whether that
// frontend actually converted its source. A Detected-but-not-Converted entry
// means findings for that language are missing because analysis failed, not
// because the code is clean.
Coverage []LangCoverage
// Diag is scan telemetry for the HTML report's diagnostics section. It is
// observational only: nothing in the pipeline reads it back.
Diag scaninfo.Info
// Sources lists the files the walk handed the frontends, under the same
// selection policy they lower. Populated only under WithSources.
Sources []string
}
Result is the outcome of scanning a path.
func Scan ¶
Scan lowers the source at path to gIR and runs the taint engine (with rs) alongside the non-dataflow dangerous-call (weak-crypto / insecure-RNG) and hardcoded-secrets passes over it. path may be a single .go/.py/.js/.java/.rs/.rb/.c/.cpp file or a directory (every present language is converted and merged). The returned findings are pre-LLM-review; the CLI applies that optional stage. Result.Coverage records which frontends ran and which failed.
func ScanFiles ¶
ScanFiles analyzes an explicit list of paths (the changed-files / pre-commit entry point) in one process: every source path is lowered and merged into a single program so the engine runs once (cross-file taint among the changed files still connects), while every path — source or not — is also scanned for hardcoded secrets so a changed .env/compose/Dockerfile is covered. A path with an unsupported extension contributes only its secrets scan; a frontend failure is warned on stderr and skipped rather than aborting the batch, since pre-commit hands over mixed file types. A batch with no analyzable source returns cleanly rather than erroring, so a docs-only commit does not fail.
func (Result) Failed ¶
func (r Result) Failed() []LangCoverage
Failed returns the languages that were detected but failed to convert (so their code went un-analyzed). A CI gate can use this to fail closed instead of reporting a false "clean".
Source Files