holger-server-lib 0.6.9

//! Móðguðr (modgunn) security integration — Engine A verdicts for holger.
//!
//! modgunn is the **single home** of the verdict logic (shared with nornir to
//! break the dependency cycle). This module is only the holger↔modgunn *adapter*:
//!
//! - map a holger artifact (a file inside a repository's znippy archive, or an
//!   explicit coord) → a [`modgunn::scan::Artifact`];
//! - run the lean `OsvScanner` verdict (CVE / license / provenance) over a
//!   listing;
//! - aggregate the per-artifact [`Verdict`]s into a [`ScanReport`] the Tools#3
//!   Security pane (UI) and the `holger-server scan` CLI verb both surface.
//!
//! Only modgunn's DEFAULT `scan` feature (Engine A) is pulled — never the heavy
//! `scip`/`warehouse` engines. The advisory DB + policy here are a representative
//! **offline** set for the demo + tests; a real deployment swaps in an imported
//! OSV/GHSA snapshot via [`modgunn::osv`].

use serde_json::{json, Value};
use traits::ArtifactFormat;

pub use modgunn::core::{ArtifactRef, Decision, Finding, Severity, Verdict};
pub use modgunn::scan::{
    Advisory, AdvisoryDb, Artifact, LicensePolicy, OsvScanner, Policy, Provenance,
    ProvenancePolicy, ScanEngine,
};

/// The modgunn ecosystem label for a holger repository type / format string.
/// Stable, lowercase; used consistently for BOTH the advisory DB and the
/// artifacts so [`Advisory::matches`] keys line up. Falls back to the raw lower
/// of an unknown string so a custom format still scans (license/provenance
/// checks still apply even with no advisories for that ecosystem).
pub fn ecosystem_for(repo_type: &str) -> String {
    match ArtifactFormat::from_format_str(repo_type) {
        Some(fmt) => ecosystem_of(fmt).to_string(),
        None => repo_type.to_ascii_lowercase(),
    }
}

/// The canonical modgunn ecosystem label for a known [`ArtifactFormat`]. Shared
/// by [`ecosystem_for`] (string path) and [`ecosystem_for_format`] (the
/// promotion gate, which has a repository backend's `format()` directly).
fn ecosystem_of(fmt: ArtifactFormat) -> &'static str {
    match fmt {
        ArtifactFormat::Rust => "cargo",
        ArtifactFormat::Pip => "pip",
        ArtifactFormat::Maven3 => "maven",
        ArtifactFormat::Go => "go",
        ArtifactFormat::Nuget => "nuget",
        ArtifactFormat::Npm => "npm",
        ArtifactFormat::Gem => "gem",
        ArtifactFormat::Deb => "deb",
        ArtifactFormat::Rpm => "rpm",
        ArtifactFormat::Helm => "helm",
        ArtifactFormat::Docker => "docker",
        ArtifactFormat::Conda => "conda",
        ArtifactFormat::Composer => "composer",
        ArtifactFormat::Znippy => "znippy",
        ArtifactFormat::Raw => "raw",
    }
}

/// The modgunn ecosystem label for a repository backend's [`ArtifactFormat`] —
/// the seam the promotion policy gate uses to key its scan (the source repo's
/// `format()` is known directly, so no repo-type string round-trip is needed).
pub fn ecosystem_for_format(fmt: ArtifactFormat) -> String {
    ecosystem_of(fmt).to_string()
}

/// Archive entries that are index/metadata, not artifacts — skipped by the
/// scanner (they carry no coords to key a verdict by).
fn is_metadata_path(path: &str) -> bool {
    let lower = path.to_ascii_lowercase();
    let base = lower.rsplit('/').next().unwrap_or(&lower);
    lower.contains("/index/")
        || lower.starts_with("index/")
        || base.ends_with(".json")
        || base.ends_with(".xml")
        || base == "packages"
        || base == "packages.gz"
        || base == "release"
        || base == "release.gz"
        || base.starts_with("repomd")
        || base.starts_with("repodata")
        || base == "config.json"
}

/// Parse `(name, version)` from an artifact filename/path across ecosystems.
///
/// Heuristic but real: takes the last path segment, strips a known archive
/// extension, then splits at the first `-` that is immediately followed by a
/// digit (the name↔version boundary that holds for cargo `.crate`, npm `.tgz`,
/// Python wheels/sdists, Maven `.jar`/`.pom`, `.gem`, `.nupkg`, …). The version
/// is the run up to the next `-` (so a wheel's `-py3-none-any` build tags are
/// dropped). Returns `None` for metadata files or anything without a coord.
pub fn parse_coords(path: &str) -> Option<(String, String)> {
    if is_metadata_path(path) {
        return None;
    }
    let base = path.rsplit('/').next().unwrap_or(path);
    // Strip the longest matching known extension (handles multi-part ones).
    let exts = [
        ".tar.gz", ".tar.zst", ".tar.bz2", ".crate", ".whl", ".tgz", ".jar",
        ".pom", ".war", ".gem", ".deb", ".rpm", ".nupkg", ".conda", ".zip",
        ".tar", ".gz", ".tbz",
    ];
    let stem = exts
        .iter()
        .find_map(|e| base.strip_suffix(e))
        .unwrap_or(base);
    if stem.is_empty() {
        return None;
    }
    let bytes = stem.as_bytes();
    let mut split = None;
    for i in 0..bytes.len().saturating_sub(1) {
        if bytes[i] == b'-' && bytes[i + 1].is_ascii_digit() {
            split = Some(i);
            break;
        }
    }
    let idx = split?;
    let name = &stem[..idx];
    let rest = &stem[idx + 1..];
    // Version = run up to the next '-' (drops wheel build tags etc.).
    let version = rest.split('-').next().unwrap_or(rest);
    if name.is_empty() || version.is_empty() {
        return None;
    }
    Some((name.to_string(), version.to_string()))
}

/// Build a modgunn [`Artifact`] for a file in `ecosystem`. Provenance is taken
/// from `signed` (a holger znippy archive that passed signature verification can
/// pass `true`); the declared `license` is optional (filename listings carry
/// none — `None`). `None` when the path has no parseable coords.
pub fn artifact_for(
    ecosystem: &str,
    path: &str,
    license: Option<String>,
    signed: bool,
) -> Option<Artifact> {
    let (name, version) = parse_coords(path)?;
    let provenance = if signed {
        Provenance::signed_by("holger-archive")
    } else {
        Provenance::unsigned()
    };
    Some(Artifact::new(
        ArtifactRef {
            ecosystem: ecosystem.to_string(),
            name,
            version,
            blob_sha256: String::new(),
        },
        license,
        provenance,
    ))
}

/// Build a modgunn [`Artifact`] from EXPLICIT coordinates (`name`/`version`) in
/// `ecosystem`. This is the promotion path: the coords are known directly from
/// the [`traits::ArtifactId`] crossing the boundary, so there is no filename to
/// parse. `signed` sets provenance (a signature-verified znippy archive passes
/// `true`). This is the REAL scan seam the promotion policy gate feeds — it uses
/// the caller's configured scanner, never `demo_*`.
pub fn artifact_from_coords(ecosystem: &str, name: &str, version: &str, signed: bool) -> Artifact {
    let provenance = if signed {
        Provenance::signed_by("holger-archive")
    } else {
        Provenance::unsigned()
    };
    Artifact::new(
        ArtifactRef {
            ecosystem: ecosystem.to_string(),
            name: name.to_string(),
            version: version.to_string(),
            blob_sha256: String::new(),
        },
        None,
        provenance,
    )
}

/// A representative **offline** advisory DB for the demo + tests — a handful of
/// well-known advisories across ecosystems so a real corpus surfaces a mix of
/// Pass / Warn / Block. A real deployment replaces this with an imported OSV/
/// GHSA/RUSTSEC snapshot (`modgunn::osv`).
pub fn demo_advisory_db() -> AdvisoryDb {
    let mut log4shell = Advisory::basic(
        "CVE-2021-44228",
        "maven",
        "log4j-core",
        vec!["2.14.1".into(), "2.14.0".into(), "2.15.0".into()],
        Severity::Critical,
        "Log4Shell: JNDI RCE in Apache Log4j2",
    );
    log4shell.kev = true; // confirmed exploited in the wild
    AdvisoryDb::new(
        "holger-demo-db-v1",
        vec![
            Advisory::basic(
                "RUSTSEC-2023-0044",
                "cargo",
                "openssl",
                vec!["0.10.55".into()],
                Severity::High,
                "use-after-free in openssl::x509",
            ),
            Advisory::basic(
                "GHSA-pad-left",
                "npm",
                "left-pad",
                vec![], // every version
                Severity::Low,
                "left-pad unpublish incident",
            ),
            Advisory::basic(
                "CVE-2018-18074",
                "pip",
                "requests",
                vec!["2.19.0".into()],
                Severity::Medium,
                "requests leaks Authorization header on redirect",
            ),
            log4shell,
        ],
    )
}

/// The demo [`Policy`]: deny strong copyleft, allow anything else (an empty
/// allow-list ⇒ no "unreviewed" noise), and treat an unstated license as Pass
/// (filename listings carry no license, so unknown must NOT flood Warn).
/// Provenance is `Ignore` for the demo (synthetic artifacts are unsigned).
pub fn demo_policy() -> Policy {
    Policy {
        version: "holger-demo-v1".into(),
        license: LicensePolicy {
            allow: Vec::new(),
            deny: vec!["GPL-3.0".into(), "AGPL-3.0".into()],
            on_unknown: Decision::Pass,
        },
        provenance: ProvenancePolicy::Ignore,
        ..Default::default()
    }
}

/// The default holger demo scanner (demo policy + demo advisory DB).
pub fn demo_scanner() -> OsvScanner {
    OsvScanner::new(demo_policy(), demo_advisory_db())
}

/// The aggregated result of scanning a repository listing — the per-artifact
/// [`Verdict`]s plus Pass/Warn/Block tallies and the overall (strongest)
/// decision. Surfaced as `state_json` for the Tools#3 pane + asserted headlessly.
#[derive(Debug, Clone, Default)]
pub struct ScanReport {
    pub ecosystem: String,
    pub verdicts: Vec<Verdict>,
    pub pass: usize,
    pub warn: usize,
    pub block: usize,
    /// Files that had no parseable coords (index/metadata), recorded for honesty.
    pub skipped: usize,
}

impl ScanReport {
    /// The overall decision — the strongest across all verdicts (Block > Warn >
    /// Pass); Pass for an empty/clean report.
    pub fn decision(&self) -> Decision {
        self.verdicts.iter().map(|v| v.decision).max().unwrap_or(Decision::Pass)
    }

    /// Observable state for the robot/headless tests: counts, overall decision,
    /// and the findings (id + severity + summary + coords) — never raw bytes.
    pub fn state_json(&self) -> Value {
        let decision = match self.decision() {
            Decision::Pass => "pass",
            Decision::Warn => "warn",
            Decision::Block => "block",
        };
        let findings: Vec<Value> = self
            .verdicts
            .iter()
            .filter(|v| !v.findings.is_empty())
            .map(|v| {
                json!({
                    "name": v.artifact.name,
                    "version": v.artifact.version,
                    "decision": match v.decision {
                        Decision::Pass => "pass",
                        Decision::Warn => "warn",
                        Decision::Block => "block",
                    },
                    "findings": v.findings.iter().map(|f| json!({
                        "id": f.id,
                        "severity": format!("{:?}", f.severity),
                        "summary": f.summary,
                    })).collect::<Vec<_>>(),
                })
            })
            .collect();
        json!({
            "ecosystem": self.ecosystem,
            "scanned": self.verdicts.len(),
            "skipped": self.skipped,
            "pass": self.pass,
            "warn": self.warn,
            "block": self.block,
            "decision": decision,
            "findings": findings,
        })
    }
}

/// Scan a repository `files` listing in `ecosystem` with `scanner`, folding the
/// per-artifact verdicts into a [`ScanReport`]. Files without parseable coords
/// (index/metadata) are counted as `skipped`, not scanned. The signature carries
/// over to the modgunn verdict so the report is fully reproducible.
pub fn scan_listing<'a, I>(ecosystem: &str, files: I, scanner: &OsvScanner) -> ScanReport
where
    I: IntoIterator<Item = &'a str>,
{
    let mut report = ScanReport {
        ecosystem: ecosystem.to_string(),
        ..Default::default()
    };
    for path in files {
        match artifact_for(ecosystem, path, None, false) {
            Some(art) => {
                let v = scanner.scan(&art);
                match v.decision {
                    Decision::Pass => report.pass += 1,
                    Decision::Warn => report.warn += 1,
                    Decision::Block => report.block += 1,
                }
                report.verdicts.push(v);
            }
            None => report.skipped += 1,
        }
    }
    report
}

/// Import an offline OSV / GHSA / RUSTSEC advisory snapshot from a single JSON
/// file into an [`AdvisoryDb`] — the REAL feed the promotion policy gate scans
/// against (the airgap-served advisory mirror the design names, §4 v2 / §13-10),
/// replacing the `demo_*` stub on the enforcement path. Uses modgunn's `osv`
/// importer (one advisory per vuln×affected-package). A range-only entry (no
/// explicit `versions`) imports as "all versions" per the importer's contract.
pub fn advisory_db_from_osv_file(path: &str) -> anyhow::Result<AdvisoryDb> {
    let text = std::fs::read_to_string(path)
        .map_err(|e| anyhow::anyhow!("reading OSV advisory file '{path}': {e}"))?;
    let advisories = modgunn::osv::parse_doc(&text)
        .map_err(|e| anyhow::anyhow!("parsing OSV advisory file '{path}': {e}"))?;
    Ok(AdvisoryDb::new(format!("osv-file:{path}"), advisories))
}

/// A REAL (non-demo) promotion [`Policy`]: deny the given SPDX license ids, treat
/// an unstated license as `Pass` (coord listings carry none, so unknown must not
/// flood the gate), and ignore provenance (znippy signature verification is a
/// separate gate). The CVE verdict is driven by the imported advisory DB.
pub fn promotion_policy(deny_licenses: Vec<String>) -> Policy {
    Policy {
        version: "holger-promote-v1".into(),
        license: LicensePolicy {
            allow: Vec::new(),
            deny: deny_licenses,
            on_unknown: Decision::Pass,
        },
        provenance: ProvenancePolicy::Ignore,
        ..Default::default()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn ecosystem_mapping_is_canonical() {
        assert_eq!(ecosystem_for("rust"), "cargo");
        assert_eq!(ecosystem_for("cargo"), "cargo");
        assert_eq!(ecosystem_for("maven2"), "maven");
        assert_eq!(ecosystem_for("pypi"), "pip");
        assert_eq!(ecosystem_for("npm"), "npm");
        // Unknown format still yields a usable lowercase label.
        assert_eq!(ecosystem_for("WeirdFmt"), "weirdfmt");
    }

    #[test]
    fn parse_coords_across_ecosystems() {
        assert_eq!(parse_coords("crates/serde-1.0.0.crate"), Some(("serde".into(), "1.0.0".into())));
        assert_eq!(parse_coords("left-pad-1.3.0.tgz"), Some(("left-pad".into(), "1.3.0".into())));
        assert_eq!(
            parse_coords("requests-2.19.0-py3-none-any.whl"),
            Some(("requests".into(), "2.19.0".into()))
        );
        assert_eq!(
            parse_coords("org/apache/logging/log4j/log4j-core/2.14.1/log4j-core-2.14.1.jar"),
            Some(("log4j-core".into(), "2.14.1".into()))
        );
        assert_eq!(parse_coords("openssl-0.10.55.crate"), Some(("openssl".into(), "0.10.55".into())));
    }

    #[test]
    fn parse_coords_skips_metadata() {
        assert_eq!(parse_coords("index/config.json"), None);
        assert_eq!(parse_coords("repodata.json"), None);
        assert_eq!(parse_coords("dists/stable/Packages"), None);
        assert_eq!(parse_coords("repomd.xml"), None);
    }

    #[test]
    fn clean_listing_passes() {
        let s = demo_scanner();
        let report = scan_listing(
            "cargo",
            ["serde-1.0.0.crate", "tokio-1.40.0.crate"],
            &s,
        );
        assert_eq!(report.decision(), Decision::Pass);
        assert_eq!(report.pass, 2);
        assert_eq!(report.warn, 0);
        assert_eq!(report.block, 0);
    }

    #[test]
    fn known_high_vuln_blocks() {
        let s = demo_scanner();
        let report = scan_listing("cargo", ["openssl-0.10.55.crate", "serde-1.0.0.crate"], &s);
        assert_eq!(report.decision(), Decision::Block);
        assert_eq!(report.block, 1);
        assert_eq!(report.pass, 1);
        let blocked = report.verdicts.iter().find(|v| v.decision == Decision::Block).unwrap();
        assert_eq!(blocked.findings[0].id, "RUSTSEC-2023-0044");
    }

    #[test]
    fn low_npm_advisory_warns_all_versions() {
        let s = demo_scanner();
        let report = scan_listing("npm", ["left-pad-1.3.0.tgz"], &s);
        assert_eq!(report.decision(), Decision::Warn);
        assert_eq!(report.warn, 1);
    }

    #[test]
    fn log4shell_kev_blocks_as_critical() {
        let s = demo_scanner();
        let report = scan_listing("maven", ["log4j-core-2.14.1.jar"], &s);
        assert_eq!(report.decision(), Decision::Block);
        let v = &report.verdicts[0];
        assert_eq!(v.findings[0].id, "CVE-2021-44228");
        assert_eq!(v.findings[0].severity, Severity::Critical);
        assert!(v.findings[0].summary.contains("[KEV]"));
    }

    #[test]
    fn metadata_files_are_skipped_not_scanned() {
        let s = demo_scanner();
        let report = scan_listing(
            "cargo",
            ["serde-1.0.0.crate", "index/config.json", "crates.io-index/cfg"],
            &s,
        );
        assert_eq!(report.verdicts.len(), 1);
        assert!(report.skipped >= 1);
    }

    /// Every holger repository type maps to a non-empty, stable modgunn ecosystem
    /// label, and a clean filename in that ecosystem scans to Pass — the
    /// 14-ecosystem coverage sweep (the modgunn↔holger integration table).
    #[test]
    fn all_repository_types_map_and_scan_clean() {
        let cases: &[(&str, &str)] = &[
            ("rust", "serde-1.0.0.crate"),
            ("pip", "flask-3.0.0-py3-none-any.whl"),
            ("maven3", "com/foo/bar/1.0/bar-1.0.jar"),
            ("go", "golang.org/x/text-0.14.0.zip"),
            ("nuget", "Newtonsoft.Json-13.0.3.nupkg"),
            ("npm", "express-4.18.2.tgz"),
            ("gem", "rails-7.1.0.gem"),
            ("deb", "nginx-1.24.0.deb"),
            ("rpm", "httpd-2.4.57.rpm"),
            ("helm", "mychart-1.2.3.tgz"),
            ("docker", "alpine-3.20.tar"),
            ("conda", "numpy-1.26.0.conda"),
            ("composer", "monolog-2.9.0.zip"),
            ("znippy", "bundle-1.0.0.crate"),
        ];
        let s = demo_scanner();
        for (repo_type, file) in cases {
            let eco = ecosystem_for(repo_type);
            assert!(!eco.is_empty(), "{repo_type} has no ecosystem label");
            let report = scan_listing(&eco, [*file], &s);
            assert_eq!(
                report.decision(),
                Decision::Pass,
                "clean {repo_type} artifact {file} (eco {eco}) should Pass: {report:?}"
            );
        }
    }

    /// The three verdict states are reachable and ordered: a clean dep Passes, a
    /// Low advisory Warns, a High/Critical advisory Blocks — and the overall
    /// report decision is the strongest across a mixed listing.
    #[test]
    fn verdict_states_pass_warn_block_and_strongest_wins() {
        let s = demo_scanner();
        assert_eq!(scan_listing("cargo", ["serde-1.0.0.crate"], &s).decision(), Decision::Pass);
        assert_eq!(scan_listing("npm", ["left-pad-1.3.0.tgz"], &s).decision(), Decision::Warn);
        assert_eq!(scan_listing("cargo", ["openssl-0.10.55.crate"], &s).decision(), Decision::Block);
        // Mixed listing: Pass + Warn + Block ⇒ overall Block.
        let mixed = scan_listing(
            "cargo",
            ["serde-1.0.0.crate", "openssl-0.10.55.crate"],
            &s,
        );
        assert_eq!(mixed.decision(), Decision::Block);
        assert_eq!(mixed.pass, 1);
        assert_eq!(mixed.block, 1);
    }

    #[test]
    fn report_state_json_carries_counts_and_findings() {
        let s = demo_scanner();
        let report = scan_listing("cargo", ["openssl-0.10.55.crate", "serde-1.0.0.crate"], &s);
        let j = report.state_json();
        assert_eq!(j["ecosystem"], "cargo");
        assert_eq!(j["scanned"], 2);
        assert_eq!(j["block"], 1);
        assert_eq!(j["decision"], "block");
        assert!(j["findings"].as_array().unwrap().iter().any(|f| f["name"] == "openssl"));
    }
}