brakeman-llm 0.0.1

data/lib/brakeman-llm.rb

@@ -0,0 +1,226 @@
+require 'brakeman'
+require 'brakeman/warning'
+require 'brakeman/options'
+require 'ruby_llm'
+
+# Override Brakeman::Warning to add LLM analysis of warning
+module Brakeman
+  class Warning
+    attr_accessor :llm_analysis
+
+    alias old_to_hash to_hash
+
+    def to_hash(...)
+      old_to_hash(...).tap do |h|
+        h[:llm_analysis] = self.llm_analysis
+      end
+    end
+  end
+end
+
+module Brakeman
+
+  # Simple wrapper for RubyLLM
+  class LLM
+    attr_accessor :assume_model_exists, :instructions, :model, :prompt, :provider
+    attr_reader :llm
+
+    # Configure RubyLLM
+    def initialize(model:, provider:, instructions: nil, prompt: nil, assume_model_exists: false, **kwargs)
+      @llm = RubyLLM.context do |config|
+        kwargs.each do |k, v|
+          case k
+          when :api_key, :api_base, :use_system_role
+            config.send("#{provider}_#{k}=", v)
+          else
+            config.send("#{k}=", v)
+          end
+        end
+
+        config.log_level = :error unless kwargs.key? :log_level
+      end
+
+      RubyLLM.logger.level = Logger::ERROR if @llm.config.log_level == :error
+
+      @instructions = instructions || 'You are a world-class application security expert with deep expertise in Ruby and Ruby on Rails security.'
+
+      @prompt = prompt || <<~PROMPT
+        Analyze the following security warning resulting from analyzing a Ruby on Rails application with the static analysis security tool Brakeman.
+        Explain the security vulnerability and potential fixes. Jump straight into the explanation, do not have a casual introduction.
+        Do not ask follow-up questions, as this is not an interactive prompt.
+        Keep the explanation to less than 400 words.
+        Ignore 'fingerprint' and 'warning_code' fields and do not explain them.
+      PROMPT
+
+      @model = model
+      @provider = provider
+      @assume_model_exists = assume_model_exists
+    end
+
+    # Analyze single Brakeman warning.
+    # Results analysis as a string.
+    def analyze_warning(warning)
+      chat = @llm.chat(model: @model, provider: @provider, assume_model_exists: @assume_model_exists)
+      chat.with_instructions(@instructions)
+
+      llm_input = <<~INPUT
+        #{@prompt}
+        #{help_doc(warning)}
+
+        The following is a Brakeman security warning in JSON format that describes a potential security vulnerability:
+        #{warning.to_json}
+      INPUT
+
+      response = chat.ask llm_input
+
+      response.content
+    end
+
+    def help_doc(warning)
+      if warning.link.match %r{https://brakemanscanner.org/(.+)/}
+        doc = File.join(__dir__, '..', $1, "index.markdown")
+
+        if File.exist? doc
+          content = File.read doc
+          "Here is background information about this type of vulnerability: #{content}"
+        else
+          puts "No file: #{doc}"
+        end
+      end
+    end
+  end
+
+  module Options
+    class << self
+      alias old_create create_option_parser
+
+      def create_option_parser(options)
+        parser = old_create(options)
+
+        parser.separator ""
+        parser.separator "LLM Options:"
+
+        # Add LLM options
+        parser.on '--llm-model MODEL' do |model|
+          options[:llm] ||= {}
+          options[:llm][:model] = model
+        end
+
+        parser.on '--llm-provider PROVIDER', 'LLM provider (openai, ollama, gemini, etc.)' do |provider|
+          options[:llm] ||= {}
+          options[:llm][:provider] = provider
+        end
+
+        parser.on '--llm-api_key API_KEY', 'LLM provider API key' do |api_key|
+          options[:llm] ||= {}
+          options[:llm][:api_key] = api_key
+        end
+
+        parser.on '--llm-api_base BASE_URL', 'LLM provider base URL' do |url|
+          options[:llm] ||= {}
+          options[:llm][:api_base] = url
+        end
+
+        parser.on '--[no-]llm-disclaimer [DISCLAIMER]', 'Disclaimer to add to each generated message' do |disclaimer|
+          options[:llm] ||= {}
+
+          if disclaimer
+            options[:llm][:disclaimer] = disclaimer
+          else
+            options[:llm][:disclaimer] = :none
+          end
+        end
+
+        parser.separator ""
+
+        parser
+      end
+    end
+  end
+
+  class << self
+    alias old_run run
+
+    def ensure_llm_options(options)
+      return if options[:llm]
+
+      # Check config file, but only grab LLM options
+      config_options = self.load_options(options)
+
+      if config_options[:llm]
+        options[:llm] = config_options[:llm]
+      else
+        raise 'Missing LLM configuration'
+      end
+    end
+
+    def run(options)
+      ensure_llm_options(options)
+
+      # Suppress report output until after analysis
+      output_formats = get_output_formats(options)
+      output_files = options.delete(:output_files)
+      options.delete(:output_format)
+      print_report = options.delete(:print_report)
+
+      # Actually run scan
+      tracker = old_run(options)
+
+      # Set up LLM
+      llm_opts = options.delete(:llm) || {}
+
+      disclaimer = llm_opts.delete(:disclaimer) || '(The above message is auto-generated and may contain errors.)'
+      if disclaimer == :none
+        disclaimer = false
+      end
+
+      llm_opts[:log_level] = :debug if @debug
+      llm = llm_opts.delete(:llm) || Brakeman::LLM.new(**llm_opts)
+
+      set_analysis = output_formats.include? :to_json
+
+      notify 'Asking LLM for extended descriptions...'
+
+      warnings = tracker.warnings
+      total = warnings.length
+
+      # Update warnings with LLM analysis
+      warnings.each_with_index do |warning, index|
+        unless @quiet or options[:report_progress] == false
+          $stderr.print " #{index}/#{total} warnings processed\r"
+        end
+
+        if set_analysis
+          warning.llm_analysis = llm.analyze_warning(warning)
+
+          if disclaimer
+            warning.llm_analysis << "\n\n" << disclaimer
+          end
+        else
+          warning.message << "\n\n" << llm.analyze_warning(warning)
+
+          if disclaimer
+            warning.message << "\n\n" << disclaimer
+          end
+        end
+      end
+
+      # Move message to end of the warning output for text report
+      # because LLMs can be quite wordy
+      tracker.options[:text_fields] ||= [:confidence, :category, :check, :code, :file, :line, :message]
+      tracker.options[:output_formats] = output_formats
+
+      if output_files
+        notify "Generating report..."
+
+        write_report_to_files tracker, output_files
+      elsif print_report
+        notify "Generating report..."
+
+        write_report_to_formats tracker, output_formats
+      end
+
+      tracker
+    end
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: brakeman-llm
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Justin Collins
+bindir: bin
+cert_chain: []
+date: 2025-08-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: brakeman
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+    - - "<="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Brakeman detects security vulnerabilities in Ruby on Rails applications
+  via static analysis.
+email: gem@brakeman.org
+executables:
+- brakeman-llm
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/brakeman-llm
+- docs/warning_types/CVE-2010-3933/index.markdown
+- docs/warning_types/CVE-2011-0446/index.markdown
+- docs/warning_types/CVE-2011-3186/index.markdown
+- docs/warning_types/attribute_restriction/index.markdown
+- docs/warning_types/authentication/index.markdown
+- docs/warning_types/authentication_whitelist/index.markdown
+- docs/warning_types/basic_auth/index.markdown
+- docs/warning_types/basic_authentication/index.markdown
+- docs/warning_types/command_injection/index.markdown
+- docs/warning_types/content_tag/index.markdown
+- docs/warning_types/cross-site_request_forgery/index.markdown
+- docs/warning_types/cross_site_request_forgery/index.markdown
+- docs/warning_types/cross_site_scripting/index.markdown
+- docs/warning_types/cross_site_scripting_to_json/index.markdown
+- docs/warning_types/dangerous_eval/index.markdown
+- docs/warning_types/dangerous_evaluation/index.markdown
+- docs/warning_types/dangerous_send/index.markdown
+- docs/warning_types/default_routes/index.markdown
+- docs/warning_types/denial_of_service/index.markdown
+- docs/warning_types/dynamic_render_path/index.markdown
+- docs/warning_types/dynamic_render_paths/index.markdown
+- docs/warning_types/evaluation/index.markdown
+- docs/warning_types/file_access/index.markdown
+- docs/warning_types/format_validation/index.markdown
+- docs/warning_types/http_verb_confusion/index.markdown
+- docs/warning_types/information_disclosure/index.markdown
+- docs/warning_types/link_to/index.markdown
+- docs/warning_types/link_to_href/index.markdown
+- docs/warning_types/mass_assignment/index.markdown
+- docs/warning_types/model_validation/index.markdown
+- docs/warning_types/path_traversal/index.markdown
+- docs/warning_types/redirect/index.markdown
+- docs/warning_types/remote_code_execution/index.markdown
+- docs/warning_types/remote_code_execution_yaml_load/index.markdown
+- docs/warning_types/session_manipulation/index.markdown
+- docs/warning_types/session_setting/index.markdown
+- docs/warning_types/session_settings/index.markdown
+- docs/warning_types/sql_injection/index.markdown
+- docs/warning_types/ssl_verification_bypass/index.markdown
+- docs/warning_types/unmaintained_dependency/index.markdown
+- docs/warning_types/unsafe_deserialization/index.markdown
+- docs/warning_types/unscoped_find/index.markdown
+- lib/brakeman-llm.rb
+homepage: https://github.com/presidentbeef/brakeman-llm
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/presidentbeef/brakeman-llm
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Enhance Brakeman warnings with LLM-based descriptions
+test_files: []