still_active 2.0.0 → 3.0.0.rc1

data/lib/still_active/ecosystem_lens.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require_relative "deps_dev_client"
+require_relative "osv_client"
+require_relative "ecosystems_client"
+require_relative "github_client"
+require_relative "pypi_client"
+require "time"
+require_relative "../helpers/activity_helper"
+require_relative "../helpers/constraint_helper"
+require_relative "../helpers/libyear_helper"
+require_relative "../helpers/pep440_helper"
+require_relative "../helpers/runtime_ceiling_helper"
+require_relative "../helpers/vulnerability_helper"
+
+module StillActive
+  # The cross-ecosystem maintenance lens. Given one SBOM-derived dependency
+  # ({ecosystem, name, version}), it assembles the same maintenance signals the
+  # native Ruby path produces -- latest release date, archived, advisories,
+  # scorecard -- into a gem_data hash StatusHelper.gem_status can read directly.
+  # The breadth counterpart to the depth Bundler path gives Ruby.
+  #
+  # Security: the SBOM supplies only ecosystem/name/version. The repository is
+  # discovered from deps.dev (a public source still_active opts into), never from
+  # a lockfile-derived URL, so a hostile SBOM can't redirect a lookup. Anything
+  # unresolvable (a private package deps.dev doesn't index) degrades to nil
+  # signals -> :unknown, never a fabricated "ok".
+  module EcosystemLens
+    extend self
+
+    # still_active ecosystem symbol -> ecosyste.ms registry name for the declared
+    # dependency (poison-pill) lookup. Only the ecosystems where the ecosyste.ms
+    # registry name and the deps.dev package name align cleanly are wired; maven
+    # (group:artifact) and go (module paths) need name-format handling and are
+    # left out for now, so they simply carry no constraint signal rather than a
+    # wrong one.
+    ECOSYSTEM_REGISTRIES = {
+      rubygems: "rubygems.org",
+      npm: "npmjs.org",
+      pypi: "pypi.org",
+      cargo: "crates.io",
+    }.freeze
+
+    # A transitive cap only holds the WHOLE tree hostage where the ecosystem
+    # forces one version per package. Ruby/Bundler and pip do (flat resolution);
+    # npm nests multiple versions and cargo coexists majors, so a below-latest cap
+    # there pins a duplicate copy in one subtree -- not a tree-wide block. The one
+    # npm case that DOES block (peerDependencies / de-facto singletons) isn't
+    # visible in ecosyste.ms data (its parser drops peerDependencies), so emitting
+    # poison for npm/cargo would over-claim on the non-blocking cases and miss the
+    # blocking ones. Suppress it there until peer requirements are sourced from
+    # deps.dev; silence beats a false "holds your tree hostage".
+    FLAT_RESOLUTION_ECOSYSTEMS = [:rubygems, :pypi].freeze
+
+    def assess(ecosystem:, name:, version:, constraint_cache: {}, python_range: nil)
+      info = DepsDevClient.version_info(gem_name: name, version: version, system: ecosystem)
+      default = DepsDevClient.default_version_info(name: name, system: ecosystem)
+      # Retry the version lookup once when it came back empty but the package DID
+      # resolve: HttpHelper collapses a genuine 404 and a transient network blip to
+      # the same nil, and a healthy version must not be mis-flagged as unresolved
+      # (below) on a one-off miss. A real 404 stays nil; a blip recovers the data.
+      info ||= DepsDevClient.version_info(gem_name: name, version: version, system: ecosystem) if default
+      # Recover the repo from the default version when the exact locked version
+      # isn't indexed (yanked/normalization mismatch): otherwise its project link
+      # vanishes and a still-fresh package date would read a false :ok with
+      # archived/scorecard silently dropped. The native Bundler path resolves the
+      # repo independently of deps.dev's per-version record; this gives the lens
+      # the same resilience.
+      # The pinned version isn't indexed by deps.dev (info nil) while the package IS
+      # (default present, so the feed is up): the version is yanked/nonexistent, not a
+      # transient miss. Flag it so status reads :unknown rather than letting the still-
+      # fresh PACKAGE date report a nonexistent version as :ok.
+      version_unresolved = info.nil? && !default.nil?
+      project_id = info&.dig(:project_id) || project_id_from(name, ecosystem, default)
+      vulnerabilities = vulnerabilities_for(info)
+      # Enrich with OSV: a real GHSA severity label (deps.dev can't score a CVSS-4-only
+      # advisory) and the fixed-version ranges the "capped below the fix" signal needs.
+      OsvClient.enrich(vulnerabilities, ecosystem: ecosystem, name: name)
+      scorecard = DepsDevClient.project_scorecard(project_id: project_id)
+      repo = repo_signals(project_id)
+
+      used_release_date = info&.dig(:published_at)
+      latest_release_date = default&.dig(:published_at)
+      latest_version = default&.dig(:version)
+      gem_data = {
+        ecosystem: ecosystem,
+        name: name,
+        version_used: version,
+        version_used_release_date: used_release_date,
+        latest_version_release_date: latest_release_date,
+        # libyear parity with the native path: how far behind latest the locked
+        # version is, in release-years. Both dates come from deps.dev responses
+        # already fetched above (no extra call); nil when either date is missing.
+        libyear: LibyearHelper.gem_libyear(
+          version_used_release_date: parse_time(used_release_date),
+          latest_version_release_date: parse_time(latest_release_date),
+        ),
+        # Whether the pinned version is at or ahead of deps.dev's latest stable, so a
+        # prerelease or an ahead-of-stable pin reads current (true), not "behind" --
+        # parity with the native path's `>=` comparison. nil when latest is unknown.
+        up_to_date: version_current?(version, latest_version),
+        repository_url: project_id && "https://#{project_id}",
+        last_commit_date: repo[:last_commit_date],
+        archived: repo[:archived],
+        scorecard_score: scorecard&.dig(:score),
+        scorecard_maintained: scorecard&.dig(:maintained),
+        vulnerability_count: vulnerabilities.length,
+        vulnerabilities: vulnerabilities,
+      }
+      gem_data[:version_unresolved] = true if version_unresolved
+      attach_constraints(gem_data, ecosystem: ecosystem, name: name, version: version, cache: constraint_cache)
+      attach_language_ceiling(gem_data, ecosystem: ecosystem, name: name, version: version, latest_version: default&.dig(:version), python_range: python_range)
+      gem_data
+    end
+
+    private
+
+    # Language-runtime ceiling for the cross-ecosystem path, the sibling of the
+    # native Ruby ceiling in Workflow. Python declares its runtime constraint as a
+    # PEP 440 `requires_python`, an enforced pip install wall; translate it and run
+    # the same generic RuntimeCeilingHelper against Python's support window. Unlike
+    # poison this is NOT gated on dormancy (a cap is a fact of the resolved version
+    # whether or not the package is maintained), so it costs one PyPI read per
+    # pypi package; other ecosystems carry no ceiling here rather than a wrong one
+    # (cargo's rust_version is a soft MSRV hint, not an install wall). Best-effort:
+    # a nil range (endoflife feed down) or absent requires_python yields nothing.
+    def attach_language_ceiling(gem_data, ecosystem:, name:, version:, latest_version:, python_range:)
+      return if python_range.nil?
+      return unless ecosystem == :pypi
+
+      requirement = Pep440Helper.to_gem_requirement_string(PypiClient.requires_python(name: name, version: version))
+      finding = requirement && RuntimeCeilingHelper.analyze(requirement: requirement, support_window: python_range)
+      return if finding.nil?
+
+      finding[:runtime] = "Python"
+      finding[:fixed_by_upgrade] = python_ceiling_lifted_by_upgrade?(name: name, version: version, latest_version: latest_version, python_range: python_range)
+      gem_data[:language_ceiling] = finding
+    end
+
+    # Does upgrading the package to its latest release lift the cap? Requires
+    # POSITIVE confirmation, unlike the native ruby_ceiling_lifted_by_upgrade?
+    # whose latest requirement is read from data already in hand. Here the latest
+    # requires_python is a fresh PyPI read, and PypiClient returns nil for BOTH
+    # "declares no constraint" AND "the fetch failed" -- indistinguishable. Reading
+    # that nil as "no ceiling, safe to bump" would fabricate remediation on a
+    # transient PyPI error, the exact over-claim this tool must never make. So a
+    # nil specifier yields false (we don't advise an upgrade we couldn't verify);
+    # only a readable constraint that analyze confirms is non-capping lifts it.
+    def python_ceiling_lifted_by_upgrade?(name:, version:, latest_version:, python_range:)
+      return false if latest_version.nil? || latest_version == version
+
+      latest_specifier = PypiClient.requires_python(name: name, version: latest_version)
+      return false if latest_specifier.nil?
+
+      latest_requirement = Pep440Helper.to_gem_requirement_string(latest_specifier)
+      RuntimeCeilingHelper.analyze(requirement: latest_requirement, support_window: python_range).nil?
+    end
+
+    # Constraint enrichment for the cross-ecosystem path, gated on dormancy so a
+    # maintained package is never flagged. Two shapes by ecosystem:
+    #
+    # FLAT (rubygems/pypi): the poison-pill signal as-is -- a below-latest cap holds
+    # the whole tree hostage, so it renders directly (`constraints` + `poison`).
+    #
+    # NESTED (npm/cargo): the pure below-latest cap is subtree-local noise (nested
+    # copies, caret default), so no poison here. Instead keep every declared dep as a
+    # security CANDIDATE (`capped_deps`); the correlator, which alone sees the tree's
+    # resolved versions and advisories, promotes only the ones that pin a vulnerable
+    # copy below its fix. Candidates are NOT filtered to below-latest-major (npm/cargo
+    # fixes are mostly same-major patch bumps that filter would miss) and need no
+    # dep_latest fetch (the wall test is patch-precise on the requirement itself).
+    def attach_constraints(gem_data, ecosystem:, name:, version:, cache:)
+      registry = ECOSYSTEM_REGISTRIES[ecosystem]
+      return if registry.nil?
+      return unless [:critical, :archived].include?(ActivityHelper.activity_level(gem_data))
+
+      declared = EcosystemsClient.declared_dependencies(name: name, version: version, registry: registry)
+      if FLAT_RESOLUTION_ECOSYSTEMS.include?(ecosystem)
+        attach_flat_poison(gem_data, ecosystem, declared, cache)
+      else
+        attach_nested_candidates(gem_data, declared)
+      end
+    end
+
+    def attach_flat_poison(gem_data, ecosystem, declared, cache)
+      findings = ConstraintHelper.poison_findings(declared) do |dep_name|
+        latest_version_for(ecosystem, dep_name, cache)
+      end
+      return if findings.empty?
+
+      gem_data[:constraints] = findings
+      gem_data[:poison] = findings.any? { |finding| finding[:kind] == :ceiling }
+      gem_data[:poison_severity] = ConstraintHelper.worst_severity(findings) if gem_data[:poison]
+    end
+
+    def attach_nested_candidates(gem_data, declared)
+      candidates = declared.filter_map do |dep|
+        next if dep[:package_name].to_s.empty? || dep[:requirements].to_s.empty?
+
+        { dependency: dep[:package_name], requirement: dep[:requirements] }
+      end
+      gem_data[:capped_deps] = candidates unless candidates.empty?
+    end
+
+    # A capped dep's current latest version in `ecosystem`, via deps.dev's default
+    # (latest stable) version. Memoized per run, keyed by ecosystem+name so an npm
+    # `foo` and a pypi `foo` never collide. Only a RESOLVED version is cached: a
+    # nil can mean "genuinely unindexed" or "deps.dev was momentarily down / rate-
+    # limited" (both surface as nil here), and caching the transient case would
+    # suppress the pill for every later dormant package capping the same dep. So an
+    # unresolved dep is re-attempted rather than remembered as a permanent miss.
+    def latest_version_for(ecosystem, dep_name, cache)
+      key = "#{ecosystem}/#{dep_name}"
+      cache[key] ||= DepsDevClient.default_version_info(name: dep_name, system: ecosystem)&.dig(:version)
+    end
+
+    def vulnerabilities_for(info)
+      advisory_keys = info&.dig(:advisory_keys) || []
+      # The keys ARE the evidence the locked version is vulnerable; the detail
+      # fetch only enriches CVSS/title. A failed enrichment must not drop the
+      # count to zero and read a known-vulnerable dep as clean, so a key whose
+      # detail can't be loaded still contributes a minimal advisory.
+      deps_dev = advisory_keys.map { DepsDevClient.advisory_detail(advisory_id: _1) || { id: _1, source: "deps.dev" } }
+      # No ruby-advisory-db here: that database is Ruby-only and the native
+      # Bundler path already merges it. Cross-ecosystem advisories come from
+      # deps.dev/OSV, which covers every system the lens serves.
+      VulnerabilityHelper.merge_advisories(deps_dev: deps_dev, ruby_advisory_db: [])
+    end
+
+    # The repo project_id from the package's default version, used only when the
+    # locked version's deps.dev record is missing or carries no link.
+    def project_id_from(name, ecosystem, default)
+      version = default&.dig(:version)
+      return if version.nil?
+
+      DepsDevClient.version_info(gem_name: name, version: version, system: ecosystem)&.dig(:project_id)
+    end
+
+    # archived + last-commit for a flat github.com/owner/repo project, or {} for
+    # anything else. deps.dev indexes github.com and gitlab.com only, but gitlab
+    # subgroups nest arbitrarily and ecosyste.ms's repo crawler is GitHub-centric,
+    # so a gitlab (or nested, or unresolved) project keeps archived unknown rather
+    # than risk a bogus owner/name lookup.
+    def repo_signals(project_id)
+      host, owner, name, *rest = project_id.to_s.split("/")
+      return {} unless host == "github.com" && owner && name && rest.empty?
+
+      repo_provider.repo_signals(owner: owner, name: name) || {}
+    end
+
+    # Mirrors Workflow#provider_for(:github): the live GitHub API when a token is
+    # configured (freshest), else ecosyste.ms (5000 anonymous req/hr vs GitHub's
+    # 60), so an untokened cross-ecosystem run still resolves a large SBOM.
+    def repo_provider
+      StillActive.config.github_oauth_token ? GithubClient : EcosystemsClient
+    end
+
+    # Is the pinned version at or ahead of latest stable? nil when latest is unknown.
+    # Gem::Version handles semver prereleases (`16.3.0-canary.7` sorts as a prerelease
+    # of 16.3.0, so ahead of a 16.2.x stable -> current), so a beta/ahead pin reads
+    # true, not "behind". Versions Gem::Version can't parse (pypi epoch `1!2.3`, build
+    # metadata, a `v` prefix) fall back to exact match -- ahead reads false there, the
+    # safe direction, and libyear still carries the real magnitude.
+    def version_current?(version, latest)
+      return false if latest.nil?
+      return version == latest unless Gem::Version.correct?(version) && Gem::Version.correct?(latest)
+
+      Gem::Version.new(version) >= Gem::Version.new(latest)
+    end
+
+    # deps.dev renders dates as ISO8601 strings; libyear needs Time to subtract.
+    # nil-safe, and a malformed value degrades to nil rather than raising.
+    def parse_time(value)
+      # Guard the type, not just nil: a non-String publishedAt (schema drift) would
+      # make Time.parse raise TypeError (unrescued) and, since this enrichment runs
+      # in assess, demote an otherwise-healthy package. Best-effort must degrade.
+      return unless value.is_a?(String)
+
+      Time.parse(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/still_active/ecosystems_client.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../helpers/http_helper"
+require_relative "version"
+
+module StillActive
+  # Tokenless repo signals (archived?, last-commit date) for github.com-hosted
+  # gems, sourced from ecosyste.ms instead of the GitHub API. Used as the
+  # fallback when no GitHub token is configured, so an unauthenticated run isn't
+  # capped at GitHub's 60 req/hr (ecosyste.ms allows 5000 anonymous) -- the
+  # difference between "works on a large Gemfile" and "dies after a handful".
+  #
+  # GitHub-only by design: ecosyste.ms's repos service doesn't populate commit
+  # recency for GitLab/Codeberg (its repo crawler is GitHub-centric), so those
+  # hosts keep their own live clients.
+  #
+  # Data is CC-BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0/);
+  # still_active queries it live (no redistribution) and attributes ecosyste.ms
+  # in the README data sources.
+  module EcosystemsClient
+    extend self
+
+    BASE_URI = URI("https://repos.ecosyste.ms/")
+    # The packages service is a distinct host from the repos service above; it
+    # carries per-version declared dependency constraints (the poison-pill input).
+    PACKAGES_BASE_URI = URI("https://packages.ecosyste.ms/")
+    # ecosyste.ms asks consumers to identify themselves for its "polite pool".
+    USER_AGENT = "still_active/#{StillActive::VERSION} (+https://github.com/SeanLF/still_active)"
+
+    # archived + last-commit date from a single repository call. ecosyste.ms's
+    # pushed_at mirrors GitHub's, so this returns the same shape as GithubClient.
+    # Returns {} when the repo can't be read, so the caller leaves both blank.
+    def repo_signals(owner:, name:)
+      return {} if owner.nil? || name.nil?
+
+      path = "/api/v1/hosts/GitHub/repositories/#{encode_repo(owner, name)}"
+      body = HttpHelper.get_json(BASE_URI, path, headers: { "User-Agent" => USER_AGENT }, params: politeness_params)
+      # A non-Hash 200 body (error envelope rendered as an array, schema drift)
+      # would otherwise raise on indexing and vanish the gem from the audit via
+      # the workflow's rescue; degrade to "no signal" like any other read failure.
+      return {} unless body.is_a?(Hash)
+
+      signals = { last_commit_date: parse_time(body["pushed_at"], owner, name) }
+      # Only assert archived when the field is actually present. A missing field
+      # must read as unknown, not be invented as false -- otherwise a partial
+      # crawl could silently mask the most actionable verdict (gem is archived).
+      signals[:archived] = body["archived"] == true if body.key?("archived")
+      signals
+    end
+
+    # ecosyste.ms dependency-kind labels that ship at RUNTIME (so a cap on one
+    # holds the consumer's tree hostage). It is registry-specific vocabulary:
+    # rubygems/npm/pypi say "runtime", but cargo says "normal" (its "dev"/"build"
+    # kinds are excluded). An ALLOWLIST, not a denylist: an unrecognised kind is
+    # dropped rather than risk flagging a dev/build dep and breaking the FP
+    # discipline. Compared case-insensitively (rubygems's dev kind is
+    # "Development").
+    RUNTIME_KINDS = ["runtime", "normal"].freeze
+
+    # The runtime dependency constraints a package version declares: an array of
+    # { package_name:, requirements: } for runtime-shipped deps only (see
+    # RUNTIME_KINDS). Dev/build/test deps are dropped -- they don't cap the
+    # consumer's tree, so they can't be a poison-pill. `requirements` is the raw
+    # constraint string ("< 5.0, >= 4.0.1") ConstraintHelper reads. `registry` is
+    # the ecosyste.ms registry name (rubygems.org, pypi.org, npmjs.org,
+    # crates.io), defaulting to Ruby.
+    #
+    # Returns [] whenever the version can't be read (unindexed, 404, timeout,
+    # schema drift), so a caller degrades to "no constraints known" rather than
+    # crashing the per-gem audit.
+    def declared_dependencies(name:, version:, registry: "rubygems.org")
+      return [] if name.nil? || version.nil?
+
+      path = "/api/v1/registries/#{encode(registry)}/packages/#{encode(name)}/versions/#{encode(version)}"
+      body = HttpHelper.get_json(PACKAGES_BASE_URI, path, headers: { "User-Agent" => USER_AGENT }, params: politeness_params)
+      return [] unless body.is_a?(Hash)
+
+      dependencies = body["dependencies"]
+      return [] unless dependencies.is_a?(Array)
+
+      dependencies.filter_map do |dep|
+        next unless dep.is_a?(Hash) && RUNTIME_KINDS.include?(dep["kind"].to_s.downcase)
+
+        package_name = dep["package_name"]
+        requirements = dep["requirements"]
+        next if package_name.nil? || requirements.nil?
+
+        { package_name: package_name, requirements: requirements }
+      end
+    end
+
+    private
+
+    # ecosyste.ms raises the rate limit and prioritises requests that identify a
+    # contact via a mailto query param (its "polite pool"). Opt-in: empty unless
+    # the user configures an email, since anonymous already suffices for a typical
+    # lockfile and we don't attribute every user's traffic to one address.
+    def politeness_params
+      email = StillActive.config.ecosystems_email
+      email ? { mailto: email } : {}
+    end
+
+    # nil or a non-string (numeric/array from an off-spec payload) -> no date,
+    # never a crash; only an unparseable string is worth warning about.
+    def parse_time(value, owner, name)
+      return unless value.is_a?(String)
+
+      Time.parse(value)
+    rescue ArgumentError
+      $stderr.puts("warning: could not parse repo date for #{owner}/#{name}: #{value.inspect}")
+      nil
+    end
+
+    def encode_repo(owner, name)
+      URI.encode_www_form_component("#{owner}/#{name}")
+    end
+
+    def encode(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

data/lib/still_active/options.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "optparse"
+require_relative "../helpers/constraint_helper"
 require_relative "../helpers/cyclonedx_helper"
 require_relative "../helpers/vulnerability_helper"
 
@@ -15,6 +16,7 @@ module StillActive
         add_tail_options(opts)
         add_gemfile_option(opts)
         add_gems_option(opts)
+        add_sbom_option(opts)
         add_ignore_option(opts)
         add_output_options(opts)
         add_token_options(opts)
@@ -34,7 +36,11 @@ module StillActive
     private
 
     def validate_options
-      raise ArgumentError, "provide gemfile or gems, not both" if options[:provided_gemfile] && options[:provided_gems]
+      inputs = [options[:provided_gemfile], options[:provided_gems], options[:provided_sbom]].compact
+      raise ArgumentError, "provide only one of --gemfile, --gems, --sbom" if inputs.size > 1
+      if options[:provided_sbom] && !File.exist?(StillActive.config.sbom_path)
+        raise ArgumentError, "SBOM file not found: #{StillActive.config.sbom_path}"
+      end
       if options[:provided_baseline] && !File.exist?(StillActive.config.baseline_path)
         raise ArgumentError, "baseline file not found: #{StillActive.config.baseline_path}"
       end
@@ -55,6 +61,13 @@ module StillActive
       end
     end
 
+    def add_sbom_option(opts)
+      opts.on("--sbom=PATH", String, "audit a CycloneDX SBOM cross-ecosystem (npm/pypi/cargo/go/maven/nuget) instead of a Gemfile; JSON output") do |value|
+        options[:provided_sbom] = true
+        StillActive.config { |config| config.sbom_path = value }
+      end
+    end
+
     def add_ignore_option(opts)
       opts.on("--ignore=GEM,GEM2,...", Array, "Gem(s) to exclude from pass/fail checks") do |value|
         StillActive.config { |config| config.ignored_gems = value }
@@ -94,6 +107,11 @@ module StillActive
       opts.on("--gitlab-token=TOKEN", String, "GitLab personal access token for API calls") do |value|
         StillActive.config { |config| config.gitlab_token = value }
       end
+      opts.on("--ecosystems-email=EMAIL", String, "Contact email for the ecosyste.ms polite pool (used only when falling back to ecosyste.ms without a GitHub token)") do |value|
+        email = value.strip
+        warn("warning: --ecosystems-email=#{value.inspect} doesn't look like an email (no @); ecosyste.ms will keep you in the anonymous pool") unless email.include?("@")
+        StillActive.config { |config| config.ecosystems_email = email }
+      end
       opts.on("--artifactory-token=TOKEN", String, "Artifactory token for private gem registry API calls") do |value|
         StillActive.config { |config| config.artifactory_token = value }
       end
@@ -145,6 +163,31 @@ module StillActive
       opts.on("--fail-if-outdated=LIBYEARS", Float, "Exit 1 if any gem exceeds LIBYEARS behind latest") do |value|
         StillActive.config { |config| config.fail_if_outdated = value }
       end
+      opts.on("--fail-if-poison[=TIER]", "Exit 1 on a poison-pill at or above TIER (note|warning|critical; default warning)") do |value|
+        if value
+          valid = StillActive::ConstraintHelper::SEVERITY.map(&:to_s)
+          raise ArgumentError, "--fail-if-poison tier must be one of: #{valid.join(", ")} (got #{value})" unless valid.include?(value)
+
+          StillActive.config { |config| config.fail_if_poison = value.to_sym }
+        else
+          StillActive.config { |config| config.fail_if_poison = true }
+        end
+      end
+      opts.on("--fail-if-language-ceiling[=TIER]", "Exit 1 on a language-runtime ceiling (Ruby/Python; default: EOL-forced only; =note also gates latest-not-yet)") do |value|
+        if value
+          valid = StillActive::ConstraintHelper::SEVERITY.map(&:to_s)
+          raise ArgumentError, "--fail-if-language-ceiling tier must be one of: #{valid.join(", ")} (got #{value})" unless valid.include?(value)
+
+          # Ceiling findings are only ever :critical or :note, so =warning can't
+          # match anything the bare (=critical) default doesn't already catch.
+          if value == "warning"
+            $stderr.puts("warning: --fail-if-language-ceiling=warning has no effect (runtime ceilings are only critical or note); behaves as =critical")
+          end
+          StillActive.config { |config| config.fail_if_language_ceiling = value.to_sym }
+        else
+          StillActive.config { |config| config.fail_if_language_ceiling = true }
+        end
+      end
     end
 
     def add_emoji_options(opts)

data/lib/still_active/osv_client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "../helpers/http_helper"
+require_relative "../helpers/cvss_helper"
+
+module StillActive
+  # OSV (api.osv.dev) enrichment for advisories deps.dev has already discovered.
+  # deps.dev is the discovery source -- it lists a package version's advisory ids --
+  # but it stores only CVSS 3.x (a CVSS-4-only advisory comes back with cvss3Score
+  # 0, which reads as unscored) and carries no fixed-version ranges at all. OSV
+  # supplies all three gaps: a GHSA severity LABEL (`database_specific.severity`)
+  # that reads correctly even for a v4-only advisory, the CVSS v4 VECTOR (turned into
+  # a real score, so the finding carries a security-severity number), and the
+  # per-package fixed versions the "capped below the fix" signal compares against a
+  # poison cap's ceiling.
+  #
+  # Enrichment is best-effort: any failure (missing record, transport error, odd
+  # shape) leaves the advisory exactly as deps.dev produced it. It must never drop
+  # an advisory the audit already found, so it only ever ADDS fields.
+  module OsvClient
+    extend self
+
+    BASE_URI = URI("https://api.osv.dev/")
+
+    # Every ecosystem SbomReader/deps.dev resolve, mapped to OSV's package-ecosystem
+    # casing (verified against live OSV records). One advisory can name the same
+    # package in several ecosystems, so `affected` is filtered to the one being
+    # audited; the native Bundler path carries no ecosystem and is always rubygems.
+    # Anything unmapped falls back to name-only fix filtering rather than dropping fixes.
+    ECOSYSTEM_NAMES = {
+      rubygems: "RubyGems",
+      pypi: "PyPI",
+      npm: "npm",
+      cargo: "crates.io",
+      maven: "Maven",
+      go: "Go",
+      nuget: "NuGet",
+    }.freeze
+
+    # Prefer the newest CVSS version a record carries (v4 is the whole point: it's the
+    # one deps.dev can't score). `severity[].score` is the vector STRING, oddly named.
+    CVSS_PRIORITY = { "CVSS_V4" => 3, "CVSS_V3" => 2, "CVSS_V2" => 1 }.freeze
+    # A v2 vector has no `CVSS:X.Y` prefix, so the version can't be read from the
+    # string; fall back to the entry type so the CycloneDX rating method labels it v2.
+    TYPE_VERSIONS = { "CVSS_V4" => "4.0", "CVSS_V3" => "3.1", "CVSS_V2" => "2.0" }.freeze
+
+    # Enrich each advisory in place with the OSV severity label and the fixed
+    # versions for the audited package. A missing/failed lookup is a no-op on that
+    # advisory (it keeps whatever deps.dev gave it), never a raise.
+    def enrich(advisories, ecosystem:, name:)
+      advisories.each do |advisory|
+        record = detail(advisory_id: advisory[:id])
+        next if record.nil?
+
+        advisory[:osv_severity] = record[:severity_label]
+        advisory[:osv_cvss_score] = record[:cvss_score]
+        advisory[:cvss_version] = record[:cvss_version]
+        advisory[:cvss_vector] = record[:cvss_vector]
+        advisory[:fixed_versions] = fixed_versions(record, ecosystem: ecosystem, name: name)
+      rescue StandardError => e
+        # Enrichment is additive and best-effort. An unexpected OSV shape must never
+        # raise out through the workflow's per-gem rescue, which would DROP the whole
+        # gem and read a known-vulnerable dependency as clean. Leave the advisory
+        # exactly as deps.dev produced it.
+        $stderr.puts("warning: OSV enrichment for #{advisory[:id]} failed: #{e.class} (#{e.message}); leaving advisory unchanged")
+      end
+    end
+
+    # Fetch and parse one OSV record by advisory id (GHSA/CVE). Returns
+    # { severity_label:, cvss_score:, cvss_version:, cvss_vector:, affected: [...] }
+    # or nil when the id is absent or OSV has no usable record for it. A non-object
+    # body (a CDN/error envelope that parses to an array or scalar) yields nil rather
+    # than raising on `dig`.
+    def detail(advisory_id:)
+      return if advisory_id.nil?
+
+      body = HttpHelper.get_json(BASE_URI, "/v1/vulns/#{encode(advisory_id)}")
+      return unless body.is_a?(Hash)
+
+      cvss = best_cvss(body)
+      {
+        severity_label: body.dig("database_specific", "severity"),
+        cvss_score: cvss[:score],
+        cvss_version: cvss[:version],
+        cvss_vector: cvss[:vector],
+        affected: Array(body["affected"]).filter_map { |entry| parse_affected(entry) },
+      }
+    end
+
+    private
+
+    # The highest-version CVSS vector the record carries, as { score:, version:,
+    # vector: } (a computed base score, the "3.1"/"4.0" version, and the raw string),
+    # or all-nil. deps.dev has no v4 score, so this is what gives a CVSS-4-only
+    # advisory a real number for the security-severity/rating.
+    def best_cvss(body)
+      entry = Array(body["severity"])
+        .select { |s| s.is_a?(Hash) && CVSS_PRIORITY.key?(s["type"]) }
+        .max_by { |s| CVSS_PRIORITY[s["type"]] }
+      return {} if entry.nil?
+
+      vector = entry["score"]
+      { score: CvssHelper.score(vector), version: cvss_version(vector) || TYPE_VERSIONS[entry["type"]], vector: vector }
+    end
+
+    # The X.Y version from a "CVSS:X.Y/..." vector prefix, or nil.
+    def cvss_version(vector)
+      vector.to_s[%r{\ACVSS:(\d+\.\d+)/}, 1]
+    end
+
+    # The fixed versions declared for `name` in `ecosystem` across the record's
+    # affected packages (a branch-structured advisory carries one fix per maintained
+    # line, so several can apply). Empty when the package is enumerated by
+    # `versions` with no fix boundary, or isn't present in this ecosystem. When the
+    # ecosystem symbol has no OSV mapping (an ecosystem we don't audit for fixes),
+    # match by name alone rather than silently dropping every fix.
+    def fixed_versions(record, ecosystem:, name:)
+      osv_ecosystem = ECOSYSTEM_NAMES.fetch(ecosystem || :rubygems, nil)
+      record[:affected]
+        .select { |a| a[:name] == name && (osv_ecosystem.nil? || a[:ecosystem] == osv_ecosystem) }
+        .flat_map { |a| a[:fixed] }
+        .uniq
+    end
+
+    # Shape guards throughout: a malformed entry (null/scalar where an object is
+    # expected, or an object where an array is) is skipped, not raised on, so one
+    # bad `affected`/`ranges`/`events` element can't discard the good fixed versions
+    # beside it in the same record.
+    def parse_affected(entry)
+      return unless entry.is_a?(Hash)
+
+      package = entry["package"]
+      return unless package.is_a?(Hash) && package["name"]
+
+      fixed = Array(entry["ranges"]).flat_map do |range|
+        next [] unless range.is_a?(Hash)
+
+        Array(range["events"]).filter_map { |event| event["fixed"] if event.is_a?(Hash) }
+      end
+      { ecosystem: package["ecosystem"], name: package["name"], fixed: fixed }
+    end
+
+    def encode(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end