mod findings

module findings

Vulnerability scanner findings per installed module, with the rebuild closure of each module.

A scanner exports one row per finding: the severity, the advisory id, the package and version it matched, the version that fixes it, and the modules that carry the package. parse_findings_csv reads that export. summarize groups the rows by module and joins them with a RebuildDocument computed over the same installed list, so every module with a finding gets two costs:

  • in_place: the patched module, bundles that ship it as an extension, and builddependency-only dependents left in review. This is what a backported patch that keeps the version forces.

  • bump: the patched module and every installed module that depends on it, at runtime or at build time, within its toolchain generation. A new version is a new module path, and EasyBuild writes dependency versions into each dependent’s module file and run path, so this is what a version bump forces.

summarize also records a reach class for each module. justifies_backport is true only for cross-user and network-facing. The built-in names are the packages named for those two classes. Every other name stays unclassified until a site file passed to ReachTable::overlay says otherwise. render_backport is that list.

Variables

const FINDINGS_SCHEMA_VERSION: u32

Schema of FindingsDocument. Bumped when a field changes meaning.

Version 2 adds reach, backport, python_patch_in_place, and fixed_in on each ranked module, plus backport_modules and reachability_file on the document.

const REACH_CROSS_USER: &str

A service another user on the same node can reach.

const REACH_LOCAL: &str

A hostile file in the job of the user who runs it.

The built-in table assigns this to nobody. A site file does.

const REACH_NETWORK: &str

A component that accepts network input.

const REACH_NOT_REACHABLE: &str

Not reachable on Linux x86_64.

The built-in table assigns this to nobody. A site file does.

const REACH_UNCLASSIFIED: &str

No built-in name and no site file names this package or module.

const SEVERITIES: [&str; 5]

Severities in descending order, as scanners spell them.

Functions

fn changed_easyconfigs(findings: &[Finding], installed: &BTreeSet<String>) -> Vec<String>

Easyconfig filenames of the installed modules the findings name, sorted.

fn easyconfig_filename(module: &str) -> Option<String>

The easyconfig filename EasyBuild gives a module: Name/Version becomes Name-Version.eb. None when there is no / or either side is empty.

fn installed_easystack(installed: &BTreeSet<String>) -> StackEasystack

An easystack whose entries are the installed modules, for a stack that was installed without one. A module whose name gives no filename is left out.

fn justifies_backport(class: &str) -> bool

true for the two classes that justify a backport.

fn parse_findings(text: &str, installed: &BTreeSet<String>) -> Result<Vec<Finding>, FindingsError>

Read a scanner export.

A file that starts with { or [ is Trivy (Results), Grype (matches), or OSV-scanner (results of packages). Anything else is the comma-separated export parse_findings_csv reads. A JSON row has no EasyBuild module column: installed supplies used_in by matching the package name and version to Name/version-toolchain.

fn parse_findings_csv(text: &str) -> Result<Vec<Finding>, FindingsError>

Read the scanner export: comma-separated, a header row, RFC 4180 quoting.

Required columns are severity, vuln_id, package, and used_in. version, fixed_in, and fix_state are read when present. Column names ignore ASCII case. used_in holds one or more modules separated by ;. Blank lines are skipped.

fn reach_for_easyconfigs(table: &ReachTable, files: &[String]) -> BTreeMap<String, String>

Reach class of each easyconfig filename.

The name is the toolchain split, then the same fallback as crate::gap::software_name. The class is ReachTable::class_of on that name. Filenames stay in the order files gives them only as map keys; a std::collections::BTreeMap sorts them.

fn reach_key(name: &str) -> String

Normalize a package or module name for the reach table.

ASCII case is folded and - becomes _, so cURL and jupyter-server match the built-in keys. The whole name has to match: curl does not match libcurl, and jupyterlab does not match jupyterlab_server.

fn render_backport(document: &FindingsDocument, reach: &ReachTable, findings: &[Finding], filter: &FilterDeps) -> String

The backport list: modules whose reach class justifies a backport, the modules a site file recorded and left off that list, and the modules still unclassified.

fn render_csv(document: &FindingsDocument) -> String

One line per ranked module, comma-separated with a header.

fn render_markdown(document: &FindingsDocument) -> String

The ranked table and the per-severity totals as Markdown.

fn severity_rank(severity: &str) -> Option<usize>

Position in SEVERITIES, ignoring ASCII case. None for anything else.

fn severity_weight(severity: &str) -> u64

Weight of one finding of each severity in ModuleFindings::score.

Critical 10, High 5, Medium 2, Low 1, Negligible and unknown 0.

fn summarize(findings: &[Finding], installed: &BTreeSet<String>, document: &RebuildDocument, reach: &ReachTable) -> FindingsDocument

Group findings by installed module and attach the closure document computed for those modules’ easyconfigs.

reach classifies each module. A site file is an overlay on the built-in names; ReachTable::builtin leaves every other module unclassified.

Enums

enum FindingsError

Why a findings export could not be read.

MissingColumn(String)

The header lacks a required column.

UnclosedQuote(usize)

A quoted field is not closed before the end of the file.

ShortRecord

A record has fewer fields than the header.

line: usize

Line the record starts on, counting from 1.

found: usize

Fields in the record.

expected: usize

Fields in the header.

Empty

The file has no header.

Scanner(String)

The file is JSON and is not a Trivy, Grype, or OSV-scanner export.

enum ReachabilityError

Why a reachability file could not be read.

Line

One line is not name class.

line: usize

Line number, counting from 1.

message: String

What is wrong with the line.

Structs and Unions

struct Finding

One row of the scanner export.

severity: String

Scanner severity, as written.

vuln_id: String

CVE or advisory id.

package: String

Package the scanner matched.

version: String

Installed version of that package.

fixed_in: String

Version that fixes it. Empty when the scanner names none.

fix_state: String

fixed, not-fixed, or empty.

modules: Vec<String>

Modules that carry the package, Name/VersionFull.

fix_commits: Vec<String>

Commit URLs the advisory names. Empty when the export names none.

struct FindingsDocument

Findings of one installed stack, joined with its rebuild closure.

schema_version: u32

FINDINGS_SCHEMA_VERSION.

generated_at: String

When it was computed.

installed_source: String

Where the installed list came from.

rows: usize

Rows in the export.

ids: usize

Unique advisory ids in the export, over every module.

modules: usize

Installed modules with a finding.

totals: Vec<SeverityTotal>

Per severity, from Critical down.

ranked: Vec<ModuleFindings>

Modules ranked by value_per_rebuild, then score, then name.

backport_modules: usize

Ranked modules whose reach class justifies a backport.

reachability_file: Option<String>

Site reachability file. Omitted when the built-in names were used alone.

not_installed: Vec<String>

Modules named in the export that are not installed, sorted.

not_in_graph: Vec<String>

Installed modules with findings whose easyconfig is not in the graph.

struct ModuleClosure

What a fix of one module costs in rebuilds.

must_rebuild: usize

Must-rebuild rows: the module and bundles that ship it.

review: usize

Builddependency-only dependents left in review.

runtime: usize

Runtime dependents, direct or transitive.

in_place: usize

must_rebuild + review: what a patch that keeps the version forces.

bump: usize

The module plus every installed dependent: what a version bump forces.

dependents: Vec<String>

Installed dependents, sorted.

in_place_dependents: Vec<String>

Dependents counted in in_place: review rows and bundles, sorted.

struct ModuleFindings

One installed module with at least one finding.

module: String

Name/VersionFull.

easyconfig: String

Easyconfig filename derived from the module name.

highest: String

Highest severity among its findings.

counts: SeverityCounts

Unique advisory ids per severity.

findings: usize

Unique advisory ids.

fixed: usize

Ids whose fix state is fixed.

not_fixed: usize

Ids whose fix state is not-fixed.

unknown_fix: usize

Ids with no fix state.

packages: Vec<String>

Packages the scanner matched in this module, sorted.

score: u64

Sum of severity_weight over the unique ids.

closure: Option<ModuleClosure>

Rebuild cost. None when the easyconfig is not in the deployed graph.

value_per_rebuild: f64

score / in_place, rounded to two decimals. Zero without a closure.

reach: String

cross-user, network-facing, local-only, not-reachable, or unclassified.

backport: bool

justifies_backport of Self::reach.

python_patch_in_place: bool

The module is the Python interpreter, and every named fix stays on the installed minor. Applying that patch release under the same module path costs ModuleClosure::in_place. Renaming the easyconfig to the new patch version costs ModuleClosure::bump.

fixed_in: Vec<String>

Fix versions the export names for this module, sorted and unique.

struct ReachTable

Package and module names mapped to a reach class.

source: Option<String>

Path of the site file. None when only the built-in names are used.

Implementations

impl ReachTable

Functions

fn builtin() -> Self

The built-in names and no site file.

fn builtin_applied(&self) -> Vec<(&'static str, &str)>

Built-in names and the class the table uses for each, in name order.

fn class_of(&self, module: &str, packages: &[&str]) -> String

The class of module given the scanner packages found in it.

The module’s software name (the text before /) and each package are looked up. The strongest class wins. No hit is REACH_UNCLASSIFIED.

fn overlay(&self, text: &str, source: impl Into<String>) -> Result<Self, ReachabilityError>

Built-in names, with text replacing or adding names.

source is the path recorded on the findings document. A blank line or a line whose first non-whitespace character is # is skipped. Each other line is a name and one class, separated by whitespace. A name may appear once. The class is cross-user, network-facing, local-only, or not-reachable.

fn site_names(&self) -> Vec<(&str, &str)>

Names the site file set, in order.

struct SeverityCounts

Unique advisory ids per severity.

critical: usize

Critical.

high: usize

High.

medium: usize

Medium.

low: usize

Low.

negligible: usize

Negligible.

other: usize

A severity outside SEVERITIES.

Implementations

impl SeverityCounts
struct SeverityTotal

Cost of fixing every module with a finding at this severity or above.

severity: String

The severity.

ids: usize

Unique advisory ids at exactly this severity.

modules: usize

Installed modules with a finding at exactly this severity.

modules_highest: usize

Installed modules whose highest finding is this severity.

modules_at_or_above: usize

Installed modules with a finding at this severity or above.

in_place_at_or_above: usize

Union of ModuleClosure::in_place over those modules.

bump_at_or_above: usize

Union of ModuleClosure::bump over those modules.