foreman_cve_scanner 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d2e1f0a7bfd0f9bf0856ef7acb0a7aeb238dd35dfedccf2acd833824ba59790
-  data.tar.gz: c91bf1095a846cc47c1d73e551065c8fa80b0e7a1d18b474684b1b07d5127a38
+  metadata.gz: f5981f5ba5ce1973957b47fafc885a8ed8327addd63ba39d3a00a321011d7cf0
+  data.tar.gz: b51390f31766614e1ef417aa8461e65927305ef5426b3bee061f3e566b5432a8
 SHA512:
-  metadata.gz: be53822e1090aed249a18a64ad21b12f4142092fc8b9a8dafe7f4f204dbca0ab6f11893501480c1df5507a030ba89921b172b5bb80c457f8a4a8a321d015290f
-  data.tar.gz: 674c34da1ff2274566619e5ea9690cbf4537f285e95ec5f9d880272f081e5bae57e26e6b3aa079bdc246ffb7b758995a82a48a1aeed5e27d1732f34802b587fb
+  metadata.gz: b6c52f57ed6247e1755775962a46cd2856da13a6ade5e2ab66c41f03140730b3596c147ce61f700991626d797919278f1d5d175ad8ad7f7d7a6388cfe4a2013f
+  data.tar.gz: 9e9e12fdab5950f9f28a136da8c8f52f9c003f82da2788d752471e363e06514f7576c95118d006e2bf8d7ef2126f74d04eca6e2183ff1e0bf6fc0f55a1601a2f

data/README.md

@@ -1,7 +1,5 @@
 # ForemanCveScanner
 
-Version: 0.5.0
-
 Plugin to:
 1. install Trivy/Grype on a host using Foreman Remote Execution (REX)
 2. run CVE scans via REX and parse the results
@@ -10,18 +8,19 @@ Plugin to:
 5. show CVE findings in the Host details UI
 6. show summary status in the Hosts list
 
-![image](https://github.com/ATIX-AG/foreman_cve_scanner/assets/25485845/85e3b676-7d90-41e5-bea5-7e0b5f4a685c)
-
 ## Features
 
+- Support for Trivy and Grype scanners
 - REX job templates for installing and running CVE scans
 - JSON output parsing with robust handling of chunked stdout
 - Per-host scan history with totals and severity counts
 - API endpoints for scan history and latest scan
+- API endpoint to push external CVE scans
 - Host Details card with findings and modal view
 - Host Details tab “CVE scans” for full history
 - Hosts overview list column “CVE” with quick summary and modal
 - Integrated in the Host Status
+- Export scan results as CSV
 
 ## Installation
 
@@ -33,14 +32,111 @@ for how to install Foreman plugins
 - Run the REX job to install Trivy and/or Grype
 - Run the REX job to scan a host
 - You can configure recurring CVE scans via `Monitor -> Jobs`
+- You can configure the default scanner for the `Run CVE scan` template via `Administer -> Settings -> CVE Scanner -> Preferred CVE scanner`
+- The setting `Administer -> Settings -> CVE Scanner -> Run CVE scan after host profiles upload` takes effect only when Katello is installed and triggers a scan after host profiles uploads using the preferred scanner setting
 - View results in:
   - Hosts overview list column “CVE” (use 'Manage Columns' to enable)
   - Host Details card and modal
   - Host Details tab “CVE scans”
 
+## External Push API
+
+Push a normalized CVE scan for a host with:
+
+- `POST /api/v2/hosts/:host_id/cve_scans/import`
+
+Required permission:
+
+- `import_cve_scans`
+
+Required payload structure:
+
+```json
+{
+  "cve_scan": {
+    "scanner": "custom-scanner",
+    "source": "external",
+    "scanned_at": "2026-05-14T08:00:00Z",
+    "findings": [
+      {
+        "id": "CVE-2024-8373",
+        "name": "angular",
+        "severity": "LOW",
+        "version": "1.8.2",
+        "fixed": "open",
+        "status": "affected",
+        "title": "angular: From NVD collector",
+        "published": "2024-09-09T15:15:12.887Z",
+        "url": "https://avd.aquasec.com/nvd/cve-2024-8373"
+      },
+      {
+        "id": "CVE-2024-9991",
+        "name": "openssl",
+        "severity": "CRITICAL",
+        "version": "3.0.1",
+        "fixed": "3.0.8",
+        "status": "affected",
+        "title": "openssl: Example critical issue",
+        "published": "2024-10-01T10:00:00Z",
+        "url": "https://example.test/CVE-2024-9991"
+      },
+      {
+        "id": "CVE-2024-9992",
+        "name": "curl",
+        "severity": "HIGH",
+        "version": "8.5.0",
+        "fixed": "8.5.1",
+        "status": "affected",
+        "title": "curl: Example high issue",
+        "published": "2024-10-02T10:00:00Z",
+        "url": "https://example.test/CVE-2024-9992"
+      },
+      {
+        "id": "CVE-2024-9993",
+        "name": "tar",
+        "severity": "MEDIUM",
+        "version": "1.35",
+        "fixed": "1.36",
+        "status": "affected",
+        "title": "tar: Example medium issue",
+        "published": "2024-10-03T10:00:00Z",
+        "url": "https://example.test/CVE-2024-9993"
+      }
+    ]
+  }
+}
+```
+
+Notes:
+
+- `scanner` is a free-form producer name and can be an unknown external tool
+- `source` is stored and shown in the UI, for example `external`
+- `scanned_at` is required and is the only scan timestamp used in the UI
+- `summary` and severity counters are calculated on the server from `findings`
+- `raw` is not part of the public API contract
+
+## Retention
+
+You can configure automatic CVE scan cleanup with the plugin setting:
+
+- `Administer -> Settings -> CVE Scanner -> Delete CVE scans after X days`
+
+Behavior:
+
+- `0` disables automatic cleanup
+- scans older than the configured number of days are deleted
+- the cleanup runs after imports and can also be triggered manually
+
+Manual cleanup task:
+
+- `bundle exec rake foreman_cve_scanner:cleanup_scans`
+
+Override the configured retention for one run:
+
+- `bundle exec rake foreman_cve_scanner:cleanup_scans DAYS=30`
+
 ## TODO
 
-- Export scan results
 - Deliver Trivy/Grype via Katello
 
 ## Contributing

data/app/controllers/api/v2/cve_scans_controller.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'csv'
+
 module Api
   module V2
     # API controller for CVE scans per host.
@@ -35,6 +37,55 @@ module Api
         @cve_scan = resource_class.for_host(@host.id).find(params[:id])
       end
 
+      api :POST, '/hosts/:host_id/cve_scans/import', N_('Import CVE scan for a host')
+      description N_('Imports a CVE scan for a host from normalized findings data.')
+      param :host_id, :identifier, required: true
+      param :cve_scan, Hash, required: true do
+        param :scanner, String, required: true
+        param :source, String, required: true
+        param :scanned_at, String, required: true
+        param :findings, Array, required: true, desc: N_('Array of CVE finding objects.') do
+          param :id, String, required: true, desc: N_('CVE identifier')
+          param :name, String, required: true, desc: N_('Affected package name')
+          param :severity, String, required: true, desc: N_('Severity, for example CRITICAL, HIGH, MEDIUM or LOW')
+          param :version, String, required: false, desc: N_('Affected or installed version')
+          param :fixed, String, required: false, desc: N_('Fixed version or open')
+          param :status, String, required: false, desc: N_('Scanner-specific status such as affected or fixed')
+          param :title, String, required: false, desc: N_('Human-readable finding title')
+          param :published, String, required: false, desc: N_('Published timestamp')
+          param :url, String, required: false, desc: N_('Reference URL')
+        end
+      end
+      def import
+        @cve_scan = resource_class.new(build_import_attributes)
+
+        if @cve_scan.save
+          render 'api/v2/cve_scans/show', status: :created
+        else
+          render(
+            json: { error: { message: @cve_scan.errors.full_messages.to_sentence } },
+            status: :unprocessable_entity
+          )
+        end
+      end
+
+      api :GET, '/hosts/:host_id/cve_scans/compare', N_('Compare two CVE scans for a host')
+      description N_('Returns a comparison between two CVE scans for a host.')
+      param :host_id, :identifier, required: true
+      param :first_id, :identifier, required: true
+      param :second_id, :identifier, required: true
+      def compare
+        return compare_params_missing unless params[:first_id].present? && params[:second_id].present?
+
+        first_scan = find_scan_for_host(params[:first_id])
+        return unless first_scan
+
+        second_scan = find_scan_for_host(params[:second_id])
+        return unless second_scan
+
+        render json: ::ForemanCveScanner::ScanComparison.compare(first_scan, second_scan)
+      end
+
       api :DELETE, '/hosts/:host_id/cve_scans/:id', N_('Delete a CVE scan')
       description N_('Deletes a specific CVE scan by id for a host.')
       param :host_id, :identifier, required: true
@@ -44,8 +95,35 @@ module Api
         process_response @cve_scan.destroy
       end
 
+      api :GET, '/hosts/:host_id/cve_scans/:id/export', N_('Export a CVE scan as CSV')
+      description N_('Exports the findings of a specific CVE scan as CSV.')
+      param :host_id, :identifier, required: true
+      param :id, :identifier, required: true
+      def export
+        @cve_scan = resource_class.for_host(@host.id).find(params[:id])
+
+        send_data(
+          findings_csv(@cve_scan),
+          filename: export_filename(@cve_scan),
+          type: 'text/csv; charset=utf-8',
+          disposition: 'attachment'
+        )
+      end
+
       private
 
+      CSV_HEADERS = [
+        'Severity',
+        'Published',
+        'Package',
+        'Affected version',
+        'Fixed version',
+        'Status',
+        'CVE',
+        'Title',
+        'URL',
+      ].freeze
+
       def cve_scans_index_scope
         scope = resource_class.for_host(@host.id).recent_first
         return scope unless respond_to?(:resource_scope_for_index, true)
@@ -55,12 +133,103 @@ module Api
       end
 
       def find_host
-        scope = ::Host::Base.authorized(:view_hosts)
+        scope = ::Host::Base.authorized(host_permission)
         @host = scope.find_by(name: params[:host_id]) || scope.find_by(id: params[:host_id])
         return if @host.present?
 
         not_found
       end
+
+      def findings_csv(scan)
+        CSV.generate do |csv|
+          csv << CSV_HEADERS
+          Array(scan.findings).each { |finding| csv << csv_row_for(finding) }
+        end
+      end
+
+      def export_filename(scan)
+        timestamp = scan.scanned_at&.utc&.strftime('%Y-%m-%d-%H%M%S')
+        "#{['cve-report', @host.shortname, scan.id, timestamp].compact.join('-')}.csv"
+      end
+
+      def csv_row_for(finding)
+        [
+          finding['severity'],
+          finding['published'],
+          finding['name'],
+          finding['version'],
+          finding['fixed'],
+          finding['status'].presence || 'open',
+          finding['id'],
+          finding['title'],
+          finding['url'],
+        ]
+      end
+
+      def compare_params_missing
+        render(
+          json: { error: { message: 'first_id and second_id are required' } },
+          status: :unprocessable_entity
+        )
+      end
+
+      def scan_not_found(id)
+        render(
+          json: { error: { message: "CVE scan with id '#{id}' not found for this host" } },
+          status: :not_found
+        )
+      end
+
+      def find_scan_for_host(scan_id)
+        scan = resource_class.for_host(@host.id).find_by(id: scan_id)
+        scan_not_found(scan_id) unless scan
+        scan
+      end
+
+      def build_import_attributes
+        payload = import_params.to_h
+        findings = Array(payload['findings']).map(&:to_h)
+        metrics = findings_metrics(findings)
+
+        {
+          host: @host,
+          scanner: payload['scanner'],
+          source: payload['source'],
+          scanned_at: payload['scanned_at'],
+          raw: payload,
+          summary: metrics.merge('worst' => ::ForemanCveScanner::CveScan.worst_severity(metrics)),
+          findings: findings,
+          total: metrics['total'],
+          critical: metrics['critical'],
+          high: metrics['high'],
+          medium: metrics['medium'],
+          low: metrics['low'],
+        }
+      end
+
+      def import_params
+        params.require(:cve_scan).permit(
+          :scanner,
+          :source,
+          :scanned_at,
+          findings: %i[id name severity version fixed status title published url]
+        )
+      end
+
+      def findings_metrics(findings)
+        severities = findings.map { |finding| finding['severity'].to_s.upcase }
+        metrics = ::ForemanCveScanner::CveScan::SEVERITY_LEVELS.index_with do |severity|
+          severities.count(severity.upcase)
+        end
+        metrics.merge('total' => findings.size)
+      end
+
+      def host_permission
+        return :import_cve_scans if action_name == 'import'
+        return :destroy_cve_scans if action_name == 'destroy'
+
+        :view_cve_scans
+      end
     end
   end
 end

data/app/models/foreman_cve_scanner/cve_scan.rb

@@ -5,11 +5,24 @@ module ForemanCveScanner
   class CveScan < ApplicationRecord
     self.table_name = 'foreman_cve_scanner_cve_scans'
 
+    SEVERITY_LEVELS = %w[critical high medium low].freeze
+
     belongs_to :host, class_name: '::Host::Managed'
 
-    validates :host_id, :scanner, :raw, :summary, :findings, presence: true
+    validates :host_id, :scanner, :source, :scanned_at, :raw, :summary, presence: true
+    validate :findings_must_be_present
 
     scope :for_host, ->(host_id) { where(host_id: host_id) }
-    scope :recent_first, -> { order(created_at: :desc, id: :desc) }
+    scope :recent_first, -> { order(scanned_at: :desc, id: :desc) }
+
+    def self.worst_severity(metrics)
+      SEVERITY_LEVELS.find { |severity| metrics[severity].to_i.positive? } || 'none'
+    end
+
+    private
+
+    def findings_must_be_present
+      errors.add(:findings, :blank) if findings.nil?
+    end
   end
 end

data/app/models/host_status/cve_status.rb

@@ -20,6 +20,8 @@ module HostStatus
         N_('Medium CVEs')
       when :low
         N_('Low CVEs')
+      when :clean
+        N_('No CVEs found')
       when :none
         N_('No CVE scans')
       else
@@ -65,7 +67,7 @@ module HostStatus
       return :medium if scan.medium.to_i.positive?
       return :low if scan.low.to_i.positive?
 
-      :none
+      :clean
     end
   end
 end

data/app/services/concerns/foreman_cve_scanner/profiles_uploader.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ForemanCveScanner
+  module ProfilesUploader
+    def upload
+      result = super
+      return result unless result && Setting[:run_cve_scan_after_host_profiles_upload]
+
+      begin
+        composer = ::JobInvocationComposer.for_feature(
+          :run_cve_scan,
+          @host,
+          scanner: Setting[:preferred_cve_scanner]
+        )
+        composer.trigger!
+      rescue StandardError => e
+        Rails.logger.error(
+          "Failed to schedule CVE scan after host profiles upload: #{e.class}: #{e.message}"
+        )
+      end
+
+      result
+    end
+  end
+end

data/app/services/foreman_cve_scanner/cve_report_scanner.rb

@@ -2,7 +2,6 @@
 
 module ForemanCveScanner
   # Parses raw CVE scanner reports and produces unified logs/metrics.
-  # rubocop:disable Metrics/ClassLength
   class CveReportScanner
     SEVERITY_ORDER = %w[CRITICAL HIGH MEDIUM LOW UNKNOWN].freeze
 
@@ -42,8 +41,7 @@ module ForemanCveScanner
     end
 
     def metrics
-      known = %w[critical high medium low]
-      res = @status.slice(*known)
+      res = @status.slice(*::ForemanCveScanner::CveScan::SEVERITY_LEVELS)
       res['total'] = res.values.sum
       res
     end
@@ -81,7 +79,7 @@ module ForemanCveScanner
       {
         'name' => entry['artifact']['name'],
         'version' => entry['artifact']['version'],
-        'title' => entry['vulnerability']['description'].gsub(/[\[\]"\\]/, ''),
+        'title' => entry['vulnerability']['description'].to_s.gsub(/[\[\]"\\]/, ''),
         'severity' => entry['vulnerability']['severity'],
         'url' => entry['vulnerability']['dataSource'],
       }
@@ -91,7 +89,7 @@ module ForemanCveScanner
       unified = {
         'name' => entry['PkgName'],
         'version' => entry['InstalledVersion'],
-        'title' => entry['Title'].gsub(/[\[\]"\\]/, ''),
+        'title' => entry['Title'].to_s.gsub(/[\[\]"\\]/, ''),
         'severity' => entry['Severity'],
         'url' => entry['PrimaryURL'],
         'status' => entry['Status'],
@@ -101,7 +99,7 @@ module ForemanCveScanner
       unified
     end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def generate_unified_vuls
       raise ::Foreman::Exception, _('Invalid CVE scanner report') unless @raw_data.key?('scan')
 
@@ -126,7 +124,6 @@ module ForemanCveScanner
 
       vuls
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/app/services/foreman_cve_scanner/scan_cleanup.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ForemanCveScanner
+  class ScanCleanup
+    SETTING_NAME = :cve_scan_delete_after_days
+
+    def initialize(scope: ::ForemanCveScanner::CveScan.all, days: nil)
+      @scope = scope
+      @days = days
+    end
+
+    def cleanup!
+      return 0 unless retention_days.positive?
+
+      deleted = @scope.where('scanned_at < ?', retention_cutoff).delete_all
+      Rails.logger.info("Deleted #{deleted} CVE scans older than #{retention_days} days") if deleted.positive?
+      deleted
+    end
+
+    private
+
+    def retention_days
+      @retention_days ||= configured_days.to_i
+    end
+
+    def configured_days
+      @days.nil? ? Setting[SETTING_NAME] : @days
+    end
+
+    def retention_cutoff
+      retention_days.days.ago
+    end
+  end
+end

data/app/services/foreman_cve_scanner/scan_comparison.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module ForemanCveScanner
+  class ScanComparison
+    DIFF_FIELDS = %w[severity version fixed status title published url].freeze
+
+    def self.compare(first_scan, second_scan)
+      new(first_scan, second_scan).compare
+    end
+
+    def initialize(first_scan, second_scan)
+      @first_scan = first_scan
+      @second_scan = second_scan
+    end
+
+    def compare
+      rows = comparison_rows
+
+      {
+        previous: scan_payload(@first_scan),
+        current: scan_payload(@second_scan),
+        summary: summarize(rows),
+        results: rows,
+      }
+    end
+
+    private
+
+    def comparison_rows
+      identities.map do |identity|
+        previous_finding = previous_map[identity]
+        current_finding = current_map[identity]
+        current_values = current_finding || previous_finding
+        diff = diff_for(previous_finding, current_finding)
+
+        {
+          key: identity,
+          status: comparison_status_for(previous_finding, current_finding, diff),
+          id: value_for(current_values, 'id'),
+          name: value_for(current_values, 'name'),
+          title: value_for(current_values, 'title'),
+          published: value_for(current_values, 'published'),
+          severity: value_for(current_values, 'severity'),
+          version: value_for(current_values, 'version'),
+          fixed: value_for(current_values, 'fixed'),
+          scan_status: normalized_value_for(current_values, 'status'),
+          url: value_for(current_values, 'url'),
+          diff: diff,
+        }
+      end
+    end
+
+    def summarize(rows)
+      rows.each_with_object(default_summary) do |row, summary|
+        summary[row[:status]] += 1
+      end
+    end
+
+    def default_summary
+      {
+        'new' => 0,
+        'resolved' => 0,
+        'updated' => 0,
+        'unchanged' => 0,
+      }
+    end
+
+    def comparison_status_for(previous_finding, current_finding, diff)
+      return 'new' if previous_finding.nil?
+      return 'resolved' if current_finding.nil?
+      return 'updated' if diff.any?
+
+      'unchanged'
+    end
+
+    def diff_for(previous_finding, current_finding)
+      return {} if previous_finding.nil? || current_finding.nil?
+
+      DIFF_FIELDS.each_with_object({}) do |field, diff|
+        old_value = normalized_value_for(previous_finding, field)
+        new_value = normalized_value_for(current_finding, field)
+        next if old_value == new_value
+
+        diff[response_field_name(field)] = {
+          old: old_value,
+          new: new_value,
+        }
+      end
+    end
+
+    def previous_map
+      @previous_map ||= findings_map(@first_scan)
+    end
+
+    def current_map
+      @current_map ||= findings_map(@second_scan)
+    end
+
+    def identities
+      @identities ||= (previous_map.keys + current_map.keys).uniq
+    end
+
+    def findings_map(scan)
+      Array(scan.findings).index_by { |finding| finding_identity(finding) }
+    end
+
+    def finding_identity(finding)
+      "#{finding['id']}::#{finding['name']}"
+    end
+
+    def normalize_status(status)
+      status.presence || 'open'
+    end
+
+    def value_for(finding, field)
+      finding&.[](field).to_s
+    end
+
+    def normalized_value_for(finding, field)
+      return normalize_status(finding&.[]('status')) if field == 'status'
+
+      value_for(finding, field)
+    end
+
+    def response_field_name(field)
+      field == 'status' ? 'scan_status' : field
+    end
+
+    def scan_payload(scan)
+      {
+        id: scan.id,
+        host_id: scan.host_id,
+        scanner: scan.scanner,
+        source: scan.source,
+        scanned_at: scan.scanned_at,
+        total: scan.total,
+        critical: scan.critical,
+        high: scan.high,
+        medium: scan.medium,
+        low: scan.low,
+        summary: scan.summary,
+      }
+    end
+  end
+end