bundler-trivy-plugin 0.1.0

data/lib/bundler/trivy/scan_result.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "vulnerability"
+
+module Bundler
+  module Trivy
+    # Represents the results of a Trivy security scan.
+    #
+    # ScanResult wraps the raw JSON output from Trivy and provides convenient
+    # methods for accessing vulnerability information, filtering by severity,
+    # grouping vulnerabilities, and generating summaries. It automatically
+    # filters out ignored CVEs based on configuration.
+    #
+    # @example Basic usage
+    #   results = scanner.scan
+    #   puts "Found #{results.vulnerability_count} vulnerabilities"
+    #   puts "Critical: #{results.critical_vulnerabilities.count}"
+    #
+    # @example Filtering by severity
+    #   critical_vulns = results.critical_vulnerabilities
+    #   critical_vulns.each do |vuln|
+    #     puts "#{vuln.id}: #{vuln.package_name}"
+    #   end
+    #
+    # @example Grouping vulnerabilities
+    #   results.by_severity.each do |severity, vulns|
+    #     puts "#{severity}: #{vulns.count} vulnerabilities"
+    #   end
+    class ScanResult
+      # @return [Hash] Raw Trivy scan data
+      attr_reader :data
+
+      # Initializes a new ScanResult instance.
+      #
+      # @param data [Hash] Raw JSON data from Trivy scan
+      # @param config [Config, nil] Configuration object for filtering ignored CVEs
+      #
+      # @example Create from scan data
+      #   data = JSON.parse(trivy_output)
+      #   results = ScanResult.new(data, config)
+      def initialize(data, config = nil)
+        @data = data || {}
+        @config = config
+      end
+
+      # Returns all vulnerabilities found in the scan.
+      #
+      # Vulnerabilities are wrapped in Vulnerability objects for convenient access.
+      # CVEs marked as ignored in the configuration are automatically filtered out.
+      #
+      # @return [Array<Vulnerability>] Array of vulnerability objects
+      #
+      # @example Get all vulnerabilities
+      #   results.vulnerabilities.each do |vuln|
+      #     puts "#{vuln.severity}: #{vuln.package_name} - #{vuln.id}"
+      #   end
+      def vulnerabilities
+        results = @data["Results"] || []
+
+        results.flat_map do |result|
+          vulns = result["Vulnerabilities"]
+          next [] if vulns.nil? || vulns.empty?
+
+          vulns.map { |v| Vulnerability.new(v, result["Target"]) }
+        end.compact.reject { |v| ignored?(v) }
+      end
+
+      # Groups vulnerabilities by severity level.
+      #
+      # @return [Hash<String, Array<Vulnerability>>] Hash with severity levels as keys
+      #
+      # @example Group by severity
+      #   results.by_severity.each do |severity, vulns|
+      #     puts "#{severity}: #{vulns.count}"
+      #   end
+      def by_severity
+        vulnerabilities.group_by(&:severity)
+      end
+
+      # Returns only CRITICAL severity vulnerabilities.
+      #
+      # @return [Array<Vulnerability>] Array of critical vulnerabilities
+      #
+      # @example Get critical vulnerabilities
+      #   critical = results.critical_vulnerabilities
+      #   puts "#{critical.count} critical issues found"
+      def critical_vulnerabilities
+        vulnerabilities.select(&:critical?)
+      end
+
+      # Returns only HIGH severity vulnerabilities.
+      #
+      # @return [Array<Vulnerability>] Array of high severity vulnerabilities
+      def high_vulnerabilities
+        vulnerabilities.select(&:high?)
+      end
+
+      # Checks if any vulnerabilities were found.
+      #
+      # @return [Boolean] true if vulnerabilities exist
+      #
+      # @example Check for vulnerabilities
+      #   if results.has_vulnerabilities?
+      #     puts "Security issues detected!"
+      #   end
+      def has_vulnerabilities?
+        !vulnerabilities.empty?
+      end
+
+      # Checks if any CRITICAL severity vulnerabilities were found.
+      #
+      # This is useful for implementing fail-on-critical policies.
+      #
+      # @return [Boolean] true if critical vulnerabilities exist
+      #
+      # @example Fail on critical
+      #   exit 1 if results.has_critical_vulnerabilities?
+      def has_critical_vulnerabilities?
+        !critical_vulnerabilities.empty?
+      end
+
+      # Returns the total count of all vulnerabilities.
+      #
+      # @return [Integer] Total vulnerability count
+      #
+      # @example Get total count
+      #   puts "Total: #{results.vulnerability_count}"
+      def vulnerability_count
+        vulnerabilities.size
+      end
+
+      # Returns vulnerability counts grouped by severity level.
+      #
+      # @return [Hash<String, Integer>] Hash with severity levels as keys and counts as values
+      #
+      # @example Get severity breakdown
+      #   counts = results.severity_counts
+      #   # => {"CRITICAL" => 2, "HIGH" => 5, "MEDIUM" => 10}
+      def severity_counts
+        by_severity.transform_values(&:size)
+      end
+
+      private
+
+      # Checks if a vulnerability should be ignored based on configuration.
+      #
+      # @param vulnerability [Vulnerability] The vulnerability to check
+      # @return [Boolean] true if the vulnerability should be ignored
+      def ignored?(vulnerability)
+        return false unless @config
+
+        @config.cve_ignored?(vulnerability.id)
+      end
+    end
+  end
+end

data/lib/bundler/trivy/scanner.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+require_relative "scan_result"
+
+module Bundler
+  module Trivy
+    # Executes Trivy security scans on Ruby projects.
+    #
+    # The Scanner class is responsible for invoking the Trivy command-line tool,
+    # parsing its JSON output, and returning structured results. It handles
+    # timeout management, error conditions, and severity filtering.
+    #
+    # @example Basic usage
+    #   config = Config.new
+    #   scanner = Scanner.new("/path/to/project", config)
+    #   if scanner.trivy_available?
+    #     results = scanner.scan
+    #     puts "Found #{results.vulnerability_count} vulnerabilities"
+    #   end
+    class Scanner
+      # @return [String] the root directory of the project being scanned
+      attr_reader :project_root
+
+      # @return [Config] the configuration object for the scanner
+      attr_reader :config
+
+      # Initializes a new Scanner instance.
+      #
+      # @param project_root [String] The root directory of the project to scan
+      # @param config [Config, nil] Configuration object. If nil, creates a new Config with defaults
+      #
+      # @example Create scanner with default config
+      #   scanner = Scanner.new("/path/to/project")
+      #
+      # @example Create scanner with custom config
+      #   config = Config.new
+      #   scanner = Scanner.new("/path/to/project", config)
+      def initialize(project_root, config = nil)
+        @project_root = project_root
+        @config = config || Config.new
+      end
+
+      # Executes a Trivy security scan on the project.
+      #
+      # This method runs the Trivy CLI tool with appropriate arguments, captures
+      # its JSON output, and parses it into a ScanResult object. The scan checks
+      # for known vulnerabilities in Ruby dependencies listed in Gemfile.lock.
+      #
+      # @return [ScanResult] Parsed scan results containing vulnerability information
+      #
+      # @raise [ScanError] If Trivy execution fails with exit code > 1
+      # @raise [ScanError] If Trivy output is not valid JSON
+      # @raise [ScanError] If the scan exceeds the configured timeout
+      #
+      # @example Scanning a project
+      #   scanner = Scanner.new("/path/to/project")
+      #   begin
+      #     results = scanner.scan
+      #     puts "Scan completed: #{results.vulnerability_count} issues found"
+      #   rescue ScanError => e
+      #     puts "Scan failed: #{e.message}"
+      #   end
+      def scan
+        args = build_trivy_args
+        timeout = @config.trivy_timeout
+
+        # Execute Trivy with Open3 for robust command execution
+        stdout, stderr, status = Open3.capture3(
+          *args,
+          timeout: timeout
+        )
+
+        # Handle Trivy exit codes:
+        # 0 = success, no vulnerabilities
+        # 1 = success, vulnerabilities found
+        # >1 = error condition
+        raise ScanError, build_error_message(status.exitstatus, stderr) if status.exitstatus > 1
+
+        # Parse JSON output into structured data
+        data = parse_json(stdout)
+        ScanResult.new(data, @config)
+      rescue JSON::ParserError => e
+        raise ScanError, build_json_error_message(e, stdout)
+      rescue Timeout::Error
+        raise ScanError, build_timeout_error_message(timeout)
+      end
+
+      # Checks if the Trivy binary is available in the system PATH.
+      #
+      # This method performs a defensive check to verify that Trivy is installed
+      # and accessible before attempting to run a scan. It prevents cryptic errors
+      # by failing early with a clear message.
+      #
+      # @return [Boolean] true if Trivy is available, false otherwise
+      #
+      # @example Check availability before scanning
+      #   scanner = Scanner.new("/path/to/project")
+      #   if scanner.trivy_available?
+      #     results = scanner.scan
+      #   else
+      #     puts "Please install Trivy first"
+      #   end
+      def trivy_available?
+        system("which trivy > /dev/null 2>&1")
+      end
+
+      private
+
+      # Builds the command-line arguments for the Trivy invocation.
+      #
+      # @return [Array<String>] Array of command arguments
+      def build_trivy_args
+        args = [
+          "trivy", "fs",
+          "--scanners", "vuln",
+          "--format", "json",
+          "--quiet"
+        ]
+
+        # Add severity filtering if configured
+        severity_filter = @config.severity_filter
+        args += ["--severity", severity_filter.join(",")] if severity_filter && severity_filter.any?
+
+        args << @project_root
+        args
+      end
+
+      # Parses Trivy JSON output into a Ruby hash.
+      #
+      # @param json_string [String] JSON string from Trivy
+      # @return [Hash] Parsed JSON data
+      def parse_json(json_string)
+        return {} if json_string.empty?
+
+        JSON.parse(json_string)
+      end
+
+      # Builds a detailed error message for Trivy execution failures.
+      #
+      # @param exit_code [Integer] The exit code from Trivy
+      # @param stderr [String] Standard error output from Trivy
+      # @return [String] Formatted error message with troubleshooting guidance
+      def build_error_message(exit_code, stderr)
+        <<~ERROR
+          Trivy scan failed with exit code #{exit_code}
+
+          Error output:
+          #{stderr}
+
+          Possible causes:
+          - Trivy database is outdated or corrupted
+          - Network connectivity issues during database update
+          - Invalid or corrupted Gemfile.lock
+          - Insufficient disk space
+
+          Troubleshooting steps:
+          1. Update Trivy database: trivy image --download-db-only
+          2. Check network connectivity
+          3. Verify Gemfile.lock is valid: bundle check
+          4. Check disk space: df -h
+
+          For more information, visit: https://trivy.dev/docs/
+        ERROR
+      end
+
+      # Builds an error message for JSON parsing failures.
+      #
+      # @param error [JSON::ParserError] The JSON parsing error
+      # @param output [String] The output that failed to parse
+      # @return [String] Formatted error message
+      def build_json_error_message(error, output)
+        <<~ERROR
+          Invalid JSON output from Trivy: #{error.message}
+
+          This may indicate:
+          - Trivy version incompatibility (requires Trivy v0.40.0 or later)
+          - Corrupted output due to interrupted execution
+          - System error messages mixed with JSON output
+
+          Output received:
+          #{output.slice(0, 500)}#{"...\n[truncated]" if output.length > 500}
+
+          Troubleshooting:
+          1. Check Trivy version: trivy --version
+          2. Update Trivy to latest version
+          3. Run Trivy manually: trivy fs --format json #{@project_root}
+        ERROR
+      end
+
+      # Builds an error message for timeout conditions.
+      #
+      # @param timeout [Integer] The timeout value that was exceeded
+      # @return [String] Formatted error message
+      def build_timeout_error_message(timeout)
+        <<~ERROR
+          Trivy scan timed out after #{timeout} seconds
+
+          This may occur when:
+          - Scanning a very large project with many dependencies
+          - Slow network connection during database updates
+          - System resource constraints
+
+          Solutions:
+          1. Increase timeout in config: scanning.timeout: #{timeout * 2}
+          2. Update Trivy database before scanning: trivy image --download-db-only
+          3. Check system resources: top or htop
+
+          Current timeout: #{timeout} seconds
+          Suggested timeout for large projects: 300+ seconds
+        ERROR
+      end
+    end
+
+    # Exception raised when a Trivy scan fails.
+    #
+    # This error is raised for various scan failures including:
+    # - Trivy execution errors (exit code > 1)
+    # - Invalid JSON output
+    # - Timeout conditions
+    # - Database update failures
+    class ScanError < StandardError; end
+  end
+end

data/lib/bundler/trivy/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Trivy
+    # Version constant for bundler-trivy-plugin
+    VERSION = "0.1.0"
+  end
+end

data/lib/bundler/trivy/vulnerability.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Bundler
+  module Trivy
+    # Represents a single security vulnerability found in a Ruby gem.
+    #
+    # Vulnerability wraps vulnerability data from Trivy and provides convenient
+    # accessors for all vulnerability attributes. It includes helper methods for
+    # severity checking, version comparison, and determining if a fix is available.
+    #
+    # Vulnerabilities are sortable by severity (critical first) and then by package name.
+    #
+    # @example Basic usage
+    #   vuln = Vulnerability.new(trivy_data, "Gemfile.lock")
+    #   puts "#{vuln.id}: #{vuln.package_name} (#{vuln.severity})"
+    #   puts "Fixed in: #{vuln.fixed_version}" if vuln.fixable?
+    #
+    # @example Checking severity
+    #   if vuln.critical?
+    #     puts "CRITICAL: Immediate action required!"
+    #   end
+    #
+    # @example Sorting vulnerabilities
+    #   vulns.sort.each { |v| puts v.package_name }
+    class Vulnerability
+      # Severity ranking for sorting (lower number = higher priority)
+      SEVERITY_ORDER = {
+        "CRITICAL" => 0,
+        "HIGH" => 1,
+        "MEDIUM" => 2,
+        "LOW" => 3,
+        "UNKNOWN" => 4
+      }.freeze
+
+      # @return [Hash] Raw vulnerability data from Trivy
+      attr_reader :data
+
+      # @return [String] Target file where vulnerability was found (e.g., "Gemfile.lock")
+      attr_reader :target
+
+      # Initializes a new Vulnerability instance.
+      #
+      # @param data [Hash] Raw vulnerability data from Trivy JSON output
+      # @param target [String] Target file path where the vulnerability was found
+      #
+      # @example Create from Trivy data
+      #   vuln = Vulnerability.new(data, "Gemfile.lock")
+      def initialize(data, target)
+        @data = data
+        @target = target
+      end
+
+      # Returns the CVE or vulnerability identifier.
+      #
+      # @return [String] CVE ID (e.g., "CVE-2023-12345") or other vulnerability ID
+      #
+      # @example Get vulnerability ID
+      #   vuln.id # => "CVE-2023-12345"
+      def id
+        @data["VulnerabilityID"]
+      end
+
+      # Returns the name of the vulnerable package.
+      #
+      # @return [String] Package/gem name
+      #
+      # @example Get package name
+      #   vuln.package_name # => "rails"
+      def package_name
+        @data["PkgName"]
+      end
+
+      # Returns the currently installed version of the vulnerable package.
+      #
+      # @return [String] Installed version number
+      def installed_version
+        @data["InstalledVersion"]
+      end
+
+      # Returns the version(s) that fix this vulnerability.
+      #
+      # May contain multiple versions separated by commas (e.g., "2.1.4, 3.0.1").
+      #
+      # @return [String, nil] Fixed version string, or nil if no fix available
+      def fixed_version
+        @data["FixedVersion"]
+      end
+
+      # Returns an array of all available fixed versions.
+      #
+      # Parses the fixed_version string and splits on commas.
+      #
+      # @return [Array<String>] Array of fixed version strings, empty if no fix available
+      #
+      # @example Get all fixed versions
+      #   vuln.fixed_versions # => ["2.1.4", "3.0.1", "4.0.0"]
+      def fixed_versions
+        return [] unless fixable?
+
+        fixed_version.split(",").map(&:strip)
+      end
+
+      # Returns the most applicable fixed version for the installed version.
+      #
+      # Attempts to find a fixed version in the same major.minor series as the
+      # installed version. For example, if version 2.1.0 is installed and fixes
+      # exist for 2.1.4 and 3.0.1, this returns 2.1.4.
+      #
+      # @return [String, nil] Most applicable fixed version, or nil if no fix available
+      #
+      # @example Get applicable fix
+      #   # If installed: 2.1.0, fixes: ["2.1.4", "3.0.1"]
+      #   vuln.applicable_fixed_version # => "2.1.4"
+      def applicable_fixed_version
+        return nil unless fixable?
+
+        begin
+          installed = Gem::Version.new(installed_version)
+
+          fixed_versions.find do |v|
+            fixed = Gem::Version.new(v)
+            fixed.segments[0..1] == installed.segments[0..1]
+          end
+        rescue ArgumentError
+          # If version parsing fails, return the first fixed version
+          fixed_versions.first
+        end
+      end
+
+      # Returns the severity level of this vulnerability.
+      #
+      # @return [String] Severity level: "CRITICAL", "HIGH", "MEDIUM", "LOW", or "UNKNOWN"
+      #
+      # @example Get severity
+      #   vuln.severity # => "CRITICAL"
+      def severity
+        sev = @data["Severity"]
+        return "UNKNOWN" if sev.nil? || sev.empty?
+
+        sev
+      end
+
+      # Returns a human-readable title for the vulnerability.
+      #
+      # @return [String] Vulnerability title or default message
+      def title
+        @data["Title"] || "No title available"
+      end
+
+      # Returns a detailed description of the vulnerability.
+      #
+      # @return [String] Vulnerability description or default message
+      def description
+        @data["Description"] || "No description available"
+      end
+
+      # Returns the primary URL for more information about the vulnerability.
+      #
+      # @return [String, nil] URL to vulnerability details (often NVD or GitHub Advisory)
+      def primary_url
+        @data["PrimaryURL"]
+      end
+
+      # Returns additional reference URLs for this vulnerability.
+      #
+      # @return [Array<String>] Array of reference URLs
+      def references
+        @data["References"] || []
+      end
+
+      # Returns the date this vulnerability was published.
+      #
+      # @return [String, nil] Publication date in ISO 8601 format
+      def published_date
+        @data["PublishedDate"]
+      end
+
+      # Checks if this is a CRITICAL severity vulnerability.
+      #
+      # @return [Boolean] true if severity is CRITICAL
+      def critical?
+        severity == "CRITICAL"
+      end
+
+      # Checks if this is a HIGH severity vulnerability.
+      #
+      # @return [Boolean] true if severity is HIGH
+      def high?
+        severity == "HIGH"
+      end
+
+      # Checks if this is a MEDIUM severity vulnerability.
+      #
+      # @return [Boolean] true if severity is MEDIUM
+      def medium?
+        severity == "MEDIUM"
+      end
+
+      # Checks if this is a LOW severity vulnerability.
+      #
+      # @return [Boolean] true if severity is LOW
+      def low?
+        severity == "LOW"
+      end
+
+      # Returns the numeric rank for this severity level.
+      #
+      # Lower numbers indicate higher severity. Used for sorting.
+      #
+      # @return [Integer] Severity rank (0-4, or 999 for unknown)
+      def severity_rank
+        SEVERITY_ORDER[severity] || 999
+      end
+
+      # Compares this vulnerability with another for sorting.
+      #
+      # Vulnerabilities are sorted by severity (critical first), then by package name.
+      #
+      # @param other [Vulnerability] Another vulnerability to compare with
+      # @return [Integer] -1, 0, or 1 for sorting
+      #
+      # @example Sort vulnerabilities
+      #   vulnerabilities.sort # Critical vulnerabilities first
+      def <=>(other)
+        # Sort by severity first (critical first), then by package name
+        comparison = severity_rank <=> other.severity_rank
+        comparison.zero? ? package_name <=> other.package_name : comparison
+      end
+
+      # Checks if a fix is available for this vulnerability.
+      #
+      # @return [Boolean] true if a fixed version exists
+      #
+      # @example Check if fixable
+      #   if vuln.fixable?
+      #     puts "Update to #{vuln.fixed_version}"
+      #   else
+      #     puts "No fix available yet"
+      #   end
+      def fixable?
+        !fixed_version.nil? && !fixed_version.empty?
+      end
+    end
+  end
+end

data/plugins.rb

@@ -0,0 +1,11 @@
+# plugins.rb
+require_relative "lib/bundler/trivy/plugin"
+
+Bundler::Plugin.register("bundler-trivy-plugin") do |plugin|
+  # Registers the plugin with Bundler and declares a hook.
+  # The 'after-install-all' hook ensures our scanning logic runs
+  # immediately after all gems have been installed.
+  plugin.hook("after-install-all") do
+    Bundler::Trivy::Plugin.scan_after_install
+  end
+end