trapline 0.1.0

data/lib/generators/trapline/templates/initializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+Trapline.configure do |config|
+  # Where rules and their test files live (`semgrep --test` layout).
+  config.rules_path = Rails.root.join("security", "semgrep").to_s
+
+  # Engine binary. nil = look for `opengrep`, then `semgrep`, on PATH.
+  # config.engine_binary = "/usr/local/bin/opengrep"
+
+  # Who can open the editor. Receives the Rack env; return true to allow access.
+  # Example with Devise/Warden:
+  #   config.authorize = ->(env) { env["warden"]&.user&.admin? }
+  # Or HTTP Basic:
+  #   config.authorize = [ENV.fetch("TRAPLINE_USER"), ENV.fetch("TRAPLINE_PASSWORD")]
+  config.authorize = ->(_env) { Rails.env.development? }
+
+  # Read-only outside development (the editor still validates and runs rules).
+  config.read_only = !Rails.env.development?
+
+  # NVD/OSV lookups by the CVE generator.
+  # config.allow_network = true
+  # config.nvd_api_key = ENV["NVD_API_KEY"]
+end

data/lib/tasks/trapline.rake

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+namespace :trapline do
+  desc "Runs all semgrep/opengrep rules against their test files"
+  task test: :environment do
+    require "trapline/cli"
+    code = Trapline::CLI.start(["test"])
+    exit(code) unless code.zero?
+  end
+
+  desc "Validates the structure of all rules"
+  task validate: :environment do
+    require "trapline/cli"
+    files = Dir.glob(File.join(Trapline.config.rules_path, "**", "*.{yaml,yml}"))
+    abort "no rules in #{Trapline.config.rules_path}" if files.empty?
+    code = Trapline::CLI.start(["validate", *files])
+    exit(code) unless code.zero?
+  end
+end

data/lib/trapline/cli.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+
+module Trapline
+  class CLI
+    USAGE = <<~TXT
+      Usage: trapline <command> [options]
+
+      Commands:
+        server              Opens the web editor (default: http://127.0.0.1:9292)
+        validate FILE...    Validates rule files (--engine also uses opengrep/semgrep)
+        test                Runs saved rules against their test files
+        run RULE TARGET     Runs a rule against a source file
+        cve ID              Generates rule drafts from a CVE/GHSA
+        templates           Lists the available templates
+        version             Shows the version and the detected engine
+
+      Global options:
+        -r, --rules DIR     Rules directory (default: ./rules or $TRAPLINE_RULES_PATH)
+            --engine-bin B  Engine binary (opengrep, semgrep or a path)
+    TXT
+
+    TEST_LABELS = { "pass" => "ok   ", "fail" => "FAIL ", "error" => "ERROR", "skipped" => "no test",
+                    "no-annotations" => "no annotations" }.freeze
+
+    def self.start(argv = ARGV, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv.dup)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(argv)
+      leading_globals(argv)
+      command = argv.shift
+      case command
+      when "server", "s" then server(argv)
+      when "validate", "v" then validate(argv)
+      when "test", "t" then test(argv)
+      when "run" then run_rule(argv)
+      when "cve", "new" then cve(argv)
+      when "templates" then list_templates
+      when "version", "-v", "--version" then version
+      when nil, "help", "-h", "--help" then @out.puts(USAGE) || 0
+      else
+        @err.puts "unknown command: #{command}\n\n#{USAGE}"
+        1
+      end
+    rescue OptionParser::ParseError, Error => e
+      @err.puts "error: #{e.message}"
+      1
+    end
+
+    private
+
+    def leading_globals(argv)
+      leading = []
+      while (arg = argv.first) && arg.start_with?("-r", "--rules", "--engine-bin")
+        leading << argv.shift
+        leading << argv.shift if %w[-r --rules --engine-bin].include?(arg)
+      end
+      OptionParser.new { |o| global(o) }.parse!(leading) if leading.any?
+    end
+
+    def global(opts)
+      opts.on("-r", "--rules DIR") { |d| Trapline.config.rules_path = File.expand_path(d) }
+      opts.on("--engine-bin BIN") do |b|
+        Trapline.config.engine_binary = b
+        Trapline.engine = nil
+      end
+    end
+
+    def server(argv)
+      host = "127.0.0.1"
+      port = 9292
+      OptionParser.new do |o|
+        global(o)
+        o.on("-p", "--port PORT", Integer) { |p| port = p }
+        o.on("-b", "--host HOST") { |h| host = h }
+        o.on("--read-only") { Trapline.config.read_only = true }
+        o.on("--basic-auth USER:PASS") { |v| Trapline.config.authorize = v.split(":", 2) }
+        o.on("--offline") { Trapline.config.allow_network = false }
+      end.parse!(argv)
+
+      require_relative "web/server"
+      @err.puts "warning: no engine found (install opengrep or semgrep); structural validation only" unless Trapline.engine
+      @out.puts "Rules in #{File.expand_path(Trapline.config.rules_path)}"
+      Web::Server.start(Web::App.new, host: host, port: port, logger: @out)
+      0
+    end
+
+    def validate(argv)
+      use_engine = false
+      json = false
+      OptionParser.new do |o|
+        global(o)
+        o.on("--engine") { use_engine = true }
+        o.on("--json") { json = true }
+      end.parse!(argv)
+      raise Error, "provide at least one file" if argv.empty?
+
+      engine = use_engine ? (Trapline.engine || raise(Error, "no engine found")) : nil
+      results = argv.to_h { |f| [f, Validator.new(engine: engine).validate(File.read(f))] }
+      if json
+        @out.puts JSON.pretty_generate(results.transform_values(&:to_h))
+      else
+        results.each do |file, r|
+          @out.puts "#{r.valid? ? 'ok   ' : 'ERROR'} #{file}"
+          r.issues.reject { |i| i.level == "info" }.each { |i| @out.puts "      #{i.level}: #{i.path}: #{i.message}" }
+        end
+      end
+      results.values.all?(&:valid?) ? 0 : 1
+    end
+
+    def test(argv)
+      OptionParser.new { |o| global(o) }.parse!(argv)
+      Trapline.config.rules_path = File.expand_path(argv.first) if argv.first
+      results = Suite.new.run
+      @out.puts "no rules in #{Trapline.store.root}" if results.empty?
+      results.each do |r|
+        @out.puts "#{TEST_LABELS[r.status]} #{r.slug}#{" (#{r.passed}/#{r.total})" if r.total.positive?}"
+        (r.errors + r.failures).each { |m| @out.puts "      #{m}" }
+      end
+      failed = results.count { |r| %w[fail error].include?(r.status) }
+      @out.puts "\n#{results.size} rules, #{failed} with problems"
+      failed.zero? ? 0 : 1
+    end
+
+    def run_rule(argv)
+      json = false
+      OptionParser.new do |o|
+        global(o)
+        o.on("--json") { json = true }
+      end.parse!(argv)
+      rule_file, target = argv
+      raise Error, "usage: trapline run RULE.yaml TARGET" unless rule_file && target
+
+      engine = Trapline.engine || raise(Error, "no engine found")
+      lang = Languages.from_extension(File.extname(target))&.key
+      res = engine.run(File.read(rule_file), code: File.read(target), language: lang)
+      if json
+        @out.puts JSON.pretty_generate(res.to_h)
+      else
+        res.errors.each { |e| @err.puts "error: #{e}" }
+        res.findings.each { |f| @out.puts "#{target}:#{f.line}: [#{f.rule_id}] #{f.code.strip}" }
+        if (a = res.annotations)
+          @out.puts "annotations: #{a[:passed]}/#{a[:total]} ok"
+          a[:results].select { |r| r[:status] == "fail" }.each { |r| @out.puts "  #{r[:reason]}" }
+        end
+      end
+      res.ok? && res.annotations_passed? ? 0 : 1
+    end
+
+    def cve(argv)
+      language = nil
+      save = false
+      pick = nil
+      from_json = nil
+      OptionParser.new do |o|
+        global(o)
+        o.on("-l", "--lang LANG") { |l| language = l }
+        o.on("--save", "Saves the first candidate (or --pick) to the rules directory") { save = true }
+        o.on("--pick N", Integer) { |n| pick = n }
+        o.on("--osv-json FILE", "Uses a saved OSV JSON instead of the network") { |f| from_json = f }
+      end.parse!(argv)
+
+      gen = Generator.new
+      result = if from_json
+                 gen.analyze(Cve::Client.parse_osv(JSON.parse(File.read(from_json))), language: language)
+               else
+                 raise Error, "usage: trapline cve CVE-YYYY-NNNN [--lang ruby]" if argv.empty?
+
+                 gen.from_cve(argv.first, language: language)
+               end
+
+      rec = result[:record]
+      @out.puts "#{rec[:id]} #{rec[:severity]} #{rec[:cwes].join(', ')}"
+      @out.puts "  #{rec[:summary] || rec[:description].to_s[0, 200]}"
+      result[:notes].each { |n| @out.puts "  - #{n}" }
+      @out.puts
+      result[:candidates].each_with_index { |c, i| @out.puts "  [#{i + 1}] #{c[:title]} — #{c[:language]}" }
+
+      index = (pick || 1) - 1
+      chosen = (result[:candidates][index] unless index.negative?) || raise(Error, "no such candidate: #{pick}")
+      if save
+        store = Trapline.store
+        slug = store.suggest_slug(Rule.parse(chosen[:yaml]).id)
+        store.write(slug, chosen[:yaml], test_code: chosen[:test_code], language: chosen[:language])
+        @out.puts "\nSaved to #{File.join(store.root, slug)}.yaml"
+      else
+        @out.puts "\n#{chosen[:yaml]}"
+      end
+      0
+    end
+
+    def list_templates
+      Templates.all.each { |t| @out.puts "#{t.cwe.ljust(9)} #{t.title.ljust(45)} #{t.languages.keys.join(', ')}" }
+      0
+    end
+
+    def version
+      e = Trapline.engine
+      @out.puts "trapline #{VERSION}"
+      @out.puts e ? "engine: #{e.name} #{e.version} (#{e.binary})" : "engine: not found (install opengrep or semgrep)"
+      0
+    end
+  end
+end

data/lib/trapline/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Trapline
+  class Configuration
+    attr_accessor :rules_path, :engine_binary, :engine_timeout, :cve_timeout, :nvd_api_key,
+                  :allow_network, :authorize, :read_only
+
+    def initialize
+      @rules_path = ENV.fetch("TRAPLINE_RULES_PATH", File.join(Dir.pwd, "rules"))
+      @engine_binary = ENV["TRAPLINE_ENGINE"]
+      @engine_timeout = Integer(ENV.fetch("TRAPLINE_ENGINE_TIMEOUT", "60"))
+      @cve_timeout = Float(ENV.fetch("TRAPLINE_CVE_TIMEOUT", "30"))
+      @nvd_api_key = ENV["NVD_API_KEY"]
+      @allow_network = ENV["TRAPLINE_OFFLINE"] != "1"
+      @authorize = nil
+      @read_only = false
+    end
+  end
+end

data/lib/trapline/cve/client.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Trapline
+  module Cve
+    class Client
+      NVD_URL = "https://services.nvd.nist.gov/rest/json/cves/2.0"
+      OSV_URL = "https://api.osv.dev/v1/vulns/"
+      CVE_ID = /\ACVE-\d{4}-\d{4,}\z/
+      ECOSYSTEM_ALIAS = /\A(?:GO|RUSTSEC)-\d{4}-\d+\z/
+      GHSA_ID = /\AGHSA(-[23456789cfghjmpqrvwx]{4}){3}\z/i
+
+      attr_reader :errors
+
+      # timeout: per request. total_timeout: for the whole #fetch; requests
+      # that would start after it are skipped.
+      def initialize(nvd_api_key: Trapline.config.nvd_api_key, http: nil, timeout: 15,
+                     total_timeout: Trapline.config.cve_timeout, clock: nil)
+        @nvd_api_key = nvd_api_key
+        @http = http || method(:http_get)
+        @timeout = timeout
+        @total_timeout = total_timeout
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @errors = []
+      end
+
+      def timed_out?
+        @timed_out || false
+      end
+
+      def fetch(id)
+        id = normalize_id(id)
+        @errors = []
+        @deadline = @total_timeout && @clock.call + @total_timeout
+
+        record = Record.new(id: id)
+        record.merge!(fetch_nvd(id)) if id.match?(CVE_ID)
+        osv = fetch_osv(id)
+        record.merge!(osv)
+        follow_osv_links(record, osv) if osv
+
+        cve_alias = record.aliases.grep(CVE_ID).first
+        if id.match?(GHSA_ID) && cve_alias
+          record.promote_cve!
+          record.merge!(fetch_nvd(cve_alias))
+        end
+
+        @timed_out = time_left&.<=(0) || false
+        if record.sources.empty?
+          within = @timed_out ? " within #{format('%g', @total_timeout)} s" : ""
+          raise NetworkError, "could not fetch #{id}#{within}: #{errors.uniq.join('; ')}"
+        end
+
+        record.aliases -= [record.id]
+        record
+      end
+
+      def fetch_nvd(id)
+        headers = {}
+        headers["apiKey"] = @nvd_api_key if @nvd_api_key
+        body = request("#{NVD_URL}?cveId=#{URI.encode_www_form_component(id)}", headers)
+        self.class.parse_nvd(JSON.parse(body))
+      rescue StandardError => e
+        @errors << "NVD: #{e.message}"
+        nil
+      end
+
+      def fetch_osv(id)
+        body = request("#{OSV_URL}#{URI.encode_www_form_component(id)}", {})
+        self.class.parse_osv(JSON.parse(body))
+      rescue StandardError => e
+        @errors << "OSV: #{e.message}"
+        nil
+      end
+
+      def self.parse_nvd(json)
+        cve = json.dig("vulnerabilities", 0, "cve") || json["cve"] || json
+        return nil unless cve.is_a?(Hash) && cve["id"]
+
+        metrics = cve["metrics"] || {}
+        cvss = %w[cvssMetricV40 cvssMetricV31 cvssMetricV30 cvssMetricV2].lazy.filter_map { |k| Array(metrics[k]).first }.first
+        cvss_data = cvss&.dig("cvssData") || {}
+        cwes = Array(cve["weaknesses"]).flat_map { |w| Array(w["description"]).map { |d| d["value"] } }
+        Record.new(
+          id: cve["id"], description: Array(cve["descriptions"]).find { |d| d["lang"] == "en" }&.dig("value"),
+          cwes: cwes.grep(/\ACWE-\d+\z/).uniq,
+          severity: cvss_data["baseSeverity"] || cvss&.dig("baseSeverity"),
+          cvss_score: cvss_data["baseScore"], cvss_vector: cvss_data["vectorString"],
+          published: cve["published"], references: Array(cve["references"]).filter_map { |r| r["url"] },
+          products: nvd_products(cve), sources: ["nvd"]
+        )
+      end
+
+      def self.nvd_products(cve)
+        Array(cve["configurations"]).flat_map { |c| Array(c["nodes"]) }.flat_map { |n| Array(n["cpeMatch"]) }
+                                    .select { |m| m["vulnerable"] }
+                                    .filter_map { |m| cpe_product(m["criteria"])&.merge("versions" => [cpe_range(m)].compact) }
+                                    .group_by { |p| p.values_at("vendor", "product") }
+                                    .map do |(vendor, product), matches|
+          { "vendor" => vendor, "product" => product, "versions" => matches.flat_map { |m| m["versions"] }.uniq }
+        end
+      end
+
+      def self.parse_osv(json)
+        return nil unless json.is_a?(Hash) && json["id"]
+
+        packages = Array(json["affected"]).filter_map do |a|
+          pkg = a["package"] || {}
+          next if pkg["name"].to_s.empty?
+
+          events = Array(a["ranges"]).flat_map { |r| Array(r["events"]) }
+          fixed = events.filter_map { |e| e["fixed"] }.uniq
+          Package.new(ecosystem: pkg["ecosystem"].to_s.split(":").first, name: pkg["name"],
+                      introduced: events.filter_map { |e| e["introduced"] }.find { |v| v != "0" },
+                      fixed: fixed.empty? ? nil : fixed.join(", "),
+                      last_affected: events.filter_map { |e| e["last_affected"] }.first,
+                      ranges: event_ranges(events))
+        end
+        sev = json.dig("database_specific", "severity")&.upcase
+        Record.new(
+          id: json["id"], aliases: Array(json["aliases"]), summary: json["summary"],
+          description: json["details"], cwes: Array(json.dig("database_specific", "cwe_ids")),
+          severity: sev == "MODERATE" ? "MEDIUM" : sev, published: json["published"],
+          references: Array(json["references"]).filter_map { |r| r["url"] },
+          packages: packages, related: Array(json["related"]), sources: ["osv"]
+        )
+      end
+
+      def self.event_ranges(events)
+        events.each_with_object([]) do |e, ranges|
+          if e["introduced"]
+            ranges << { "introduced" => e["introduced"] }
+          elsif ranges.any? && (e["fixed"] || e["last_affected"])
+            ranges.last.merge!(e.slice("fixed", "last_affected"))
+          end
+        end
+      end
+
+      def self.cpe_range(match)
+        version = match["criteria"].to_s.split(":")[5]
+        return { "exact" => version } unless ["*", "-", nil, ""].include?(version)
+
+        { "start_including" => match["versionStartIncluding"], "start_excluding" => match["versionStartExcluding"],
+          "end_including" => match["versionEndIncluding"], "end_excluding" => match["versionEndExcluding"] }.compact
+          .then { |r| r.empty? ? nil : r }
+      end
+
+      def self.cpe_product(cpe)
+        parts = cpe.to_s.split(":")
+        return nil if parts.size < 5
+
+        { "vendor" => parts[3], "product" => parts[4] }
+      end
+
+      private
+
+      def normalize_id(id)
+        id = id.to_s.strip.upcase
+        id = "GHSA-#{id[5..].downcase}" if id.match?(GHSA_ID)
+        return id if id.match?(CVE_ID) || id.match?(GHSA_ID)
+
+        raise Error, "invalid identifier: #{id} (use CVE-YYYY-NNNN or GHSA-xxxx-xxxx-xxxx)"
+      end
+
+      # The OSV record of a CVE often has no packages: they are in the GHSA it
+      # links to. Go and RustSec advisories may list packages the GHSA lacks.
+      def follow_osv_links(record, osv)
+        linked = osv.aliases + osv.related
+        linked.grep(GHSA_ID).first(2).each { |ghsa| record.merge!(fetch_osv(ghsa)) } if osv.packages.empty?
+        linked.grep(ECOSYSTEM_ALIAS).uniq.first(2).each { |alias_id| record.merge!(fetch_osv(alias_id)) }
+      end
+
+      def time_left
+        @deadline && (@deadline - @clock.call)
+      end
+
+      def request(url, headers)
+        left = time_left
+        raise Error, "time limit reached, request skipped" if left && left <= 0
+
+        @request_timeout = left ? [@timeout, left].min : @timeout
+        @http.call(url, headers)
+      end
+
+      def http_get(url, headers)
+        uri = URI(url)
+        req = Net::HTTP::Get.new(uri)
+        req["Accept"] = "application/json"
+        req["User-Agent"] = "trapline/#{VERSION}"
+        headers.each { |k, v| req[k] = v }
+        t = @request_timeout
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                  open_timeout: t, read_timeout: t, write_timeout: t) { |h| h.request(req) }
+        raise Error, "HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+
+        res.body
+      end
+    end
+  end
+end

data/lib/trapline/cve/record.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Trapline
+  module Cve
+    ECOSYSTEM_LANGUAGES = {
+      "npm" => "javascript", "pypi" => "python", "rubygems" => "ruby", "maven" => "java",
+      "go" => "go", "packagist" => "php", "nuget" => "csharp", "crates.io" => "rust",
+      "hex" => "elixir", "pub" => "dart", "swifturl" => "swift", "cocoapods" => "swift"
+    }.freeze
+
+    PRODUCT_LANGUAGES = {
+      "php:php" => "php", "python:python" => "python", "python:cpython" => "python",
+      "nodejs:node.js" => "javascript", "ruby-lang:ruby" => "ruby", "golang:go" => "go",
+      "oracle:jdk" => "java", "oracle:jre" => "java", "oracle:openjdk" => "java",
+      "microsoft:.net" => "csharp", "microsoft:.net_core" => "csharp", "microsoft:asp.net_core" => "csharp",
+      "rust-lang:rust" => "rust",
+      "rubyonrails:rails" => "ruby", "rubyonrails:ruby_on_rails" => "ruby", "djangoproject:django" => "python",
+      "palletsprojects:flask" => "python", "expressjs:express" => "javascript", "vmware:spring_framework" => "java",
+      "laravel:framework" => "php", "wordpress:wordpress" => "php", "drupal:drupal" => "php",
+      "symfony:symfony" => "php"
+    }.freeze
+
+    RUNTIME_PACKAGES = {
+      "go/stdlib" => { "vendor" => "golang", "product" => "go" },
+      "go/toolchain" => { "vendor" => "golang", "product" => "go" }
+    }.freeze
+
+    def self.product_key(product)
+      "#{product['vendor']}:#{product['product']}"
+    end
+
+    Package = Struct.new(:ecosystem, :name, :introduced, :fixed, :last_affected, :ranges, keyword_init: true) do
+      def language
+        ECOSYSTEM_LANGUAGES[ecosystem.to_s.downcase]
+      end
+
+      def runtime_product
+        RUNTIME_PACKAGES["#{ecosystem.to_s.downcase}/#{name}"]
+      end
+
+      # OSV ranges in the NVD CPE shape. Pre-release markers are dropped: Go
+      # writes 1.22.0 as "1.22.0-0".
+      def cpe_ranges
+        Array(ranges).filter_map do |r|
+          release = ->(v) { v&.sub(/-.*\z/, "") }
+          range = { "start_including" => (release.(r["introduced"]) unless [nil, "", "0"].include?(r["introduced"])),
+                    "end_excluding" => release.(r["fixed"]), "end_including" => release.(r["last_affected"]) }.compact
+          range unless range.empty?
+        end
+      end
+
+      def to_h
+        super.except(:ranges).compact.merge(language: language).compact
+      end
+    end
+
+    class Record
+      attr_accessor :id, :aliases, :summary, :description, :cwes, :severity, :cvss_score,
+                    :cvss_vector, :published, :references, :packages, :products, :sources, :related
+
+      def initialize(**attrs)
+        @aliases = []
+        @cwes = []
+        @references = []
+        @packages = []
+        @products = []
+        @sources = []
+        @related = []
+        attrs.each { |k, v| public_send("#{k}=", v) }
+      end
+
+      def self.from_h(h)
+        h = h.transform_keys(&:to_s)
+        new(
+          id: h["id"].to_s.strip.upcase,
+          summary: h["summary"], description: h["description"],
+          cwes: Array(h["cwes"] || h["cwe"]).flat_map { |c| c.to_s.split(/[,\s]+/) }.filter_map { |c| normalize_cwe(c) }.uniq,
+          severity: h["severity"]&.to_s&.upcase, cvss_score: h["cvss_score"],
+          references: Array(h["references"]).flat_map { |r| r.to_s.split(/\s+/) }.reject(&:empty?),
+          packages: Array(h["packages"]).map { |p| p.is_a?(Package) ? p : Package.new(**p.transform_keys(&:to_sym).slice(*Package.members)) },
+          products: Array(h["products"]).map { |p| p.transform_keys(&:to_s) },
+          sources: ["manual"]
+        )
+      end
+
+      def self.normalize_cwe(value)
+        n = value.to_s[/\d+/]
+        "CWE-#{n}" if n
+      end
+
+      def title
+        summary.to_s.strip.empty? ? description.to_s.split(/(?<=\.)\s/).first.to_s : summary
+      end
+
+      def languages
+        (packages.filter_map(&:language) + products.filter_map { |p| PRODUCT_LANGUAGES[Cve.product_key(p)] }).uniq
+      end
+
+      # NVD products plus the runtimes OSV lists as packages (Go's "stdlib").
+      # NVD's version ranges win when it has them.
+      def runtime_products
+        with_versions = products.select { |p| Array(p["versions"]).any? }.map { |p| Cve.product_key(p) }
+        from_packages = packages.filter_map { |p| p.runtime_product&.merge("versions" => p.cpe_ranges) }
+                                .reject { |p| with_versions.include?(Cve.product_key(p)) }
+                                .group_by { |p| Cve.product_key(p) }
+                                .transform_values { |ps| ps.first.merge("versions" => ps.flat_map { |p| p["versions"] }.uniq) }
+        products.reject { |p| from_packages.key?(Cve.product_key(p)) } + from_packages.values
+      end
+
+      # "vendor/product" names. Known runtimes/frameworks come first: the rest
+      # are usually appliances that embed them.
+      def product_names
+        runtimes, others = products.partition { |p| PRODUCT_LANGUAGES.key?(Cve.product_key(p)) }
+        (runtimes.any? ? runtimes : others).map { |p| p["vendor"] == p["product"] ? p["product"] : "#{p['vendor']}/#{p['product']}" }
+      end
+
+      def merge!(other)
+        return self unless other
+
+        self.id = other.id if id.to_s.empty?
+        self.summary ||= other.summary
+        self.description ||= other.description
+        self.severity ||= other.severity
+        self.cvss_score ||= other.cvss_score
+        self.cvss_vector ||= other.cvss_vector
+        self.published ||= other.published
+        self.aliases = (aliases + other.aliases + [other.id]).compact.uniq - [id]
+        self.cwes = (cwes + other.cwes).uniq
+        self.references = (references + other.references).uniq
+        self.products = (products + other.products).uniq
+        self.sources = (sources + other.sources).uniq
+        other.packages.each { |p| packages << p if packages.none? { |q| [q.ecosystem, q.name] == [p.ecosystem, p.name] } }
+        self
+      end
+
+      def promote_cve!
+        cve = aliases.grep(/\ACVE-\d{4}-\d+\z/).first
+        return self unless id.to_s.start_with?("GHSA-") && cve
+
+        self.aliases = (aliases - [cve] + [id]).uniq
+        self.id = cve
+        self
+      end
+
+      def rule_severity
+        sev = severity.to_s.upcase
+        %w[CRITICAL HIGH LOW].include?(sev) ? sev : "MEDIUM"
+      end
+
+      def to_h
+        {
+          id: id, aliases: aliases, summary: summary, description: description, cwes: cwes,
+          severity: severity, cvss_score: cvss_score, cvss_vector: cvss_vector, published: published,
+          references: references, packages: packages.map(&:to_h), products: products,
+          languages: languages, sources: sources
+        }
+      end
+    end
+  end
+end