query_guard 0.4.2 → 0.5.1

data/lib/query_guard/cli/source_metadata_collector.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  class CLI
+    # Collects source and CI environment metadata for SaaS dashboards and PR views.
+    #
+    # Captures:
+    # - Git information (SHA, branch, repository name)
+    # - CI provider detection (GitHub Actions, CircleCI, Jenkins, etc.)
+    # - Pull request information when available
+    # - Graceful fallbacks for local development
+    #
+    # Design:
+    # - Modular detection for each CI provider
+    # - Fails gracefully (returns what's available)
+    # - No external dependencies (pure stdlib)
+    # - Suitable for SaaS platform ingestion
+    #
+    # Example:
+    #   collector = QueryGuard::CLI::SourceMetadataCollector.new
+    #   metadata = collector.collect
+    #   # => { git: { sha: '...' }, ci: { provider: 'github_actions', ... } }
+    class SourceMetadataCollector
+      def initialize
+        @env = ENV.to_h
+      end
+
+      # Collect all available source and CI metadata
+      # Returns: Hash with git and ci information
+      def collect
+        {
+          git: collect_git_metadata,
+          ci: collect_ci_metadata
+        }.compact
+      end
+
+      private
+
+      # Collect git information
+      # SHA, branch, repository name
+      def collect_git_metadata
+        git_info = {}
+
+        # Git SHA (commit hash)
+        git_info[:sha] = read_git_sha
+        git_info[:branch] = read_git_branch
+        git_info[:repository] = read_git_repository
+
+        # Only include if we found at least the SHA
+        git_info.empty? ? nil : git_info.compact
+      end
+
+      # Detect CI provider and collect CI-specific metadata
+      def collect_ci_metadata
+        case ci_provider
+        when :github_actions
+          detect_github_actions_metadata
+        when :circle_ci
+          detect_circle_ci_metadata
+        when :jenkins
+          detect_jenkins_metadata
+        when :gitlab_ci
+          detect_gitlab_ci_metadata
+        when :travis_ci
+          detect_travis_ci_metadata
+        when :bitbucket_ci
+          detect_bitbucket_ci_metadata
+        else
+          # Local development or unknown CI
+          nil
+        end
+      end
+
+      # Detect which CI provider is running
+      def ci_provider
+        return :github_actions if @env['GITHUB_ACTIONS'] == 'true'
+        return :circle_ci if @env['CIRCLECI'] == 'true'
+        return :jenkins if @env['JENKINS_HOME']
+        return :gitlab_ci if @env['GITLAB_CI'] == 'true'
+        return :travis_ci if @env['TRAVIS'] == 'true'
+        return :bitbucket_ci if @env['BITBUCKET_BUILD_NUMBER']
+
+        nil
+      end
+
+      # Github Actions metadata
+      def detect_github_actions_metadata
+        metadata = {
+          provider: 'github_actions',
+          ci: true
+        }
+
+        # Repository
+        if @env['GITHUB_REPOSITORY']
+          owner, repo = @env['GITHUB_REPOSITORY'].split('/')
+          metadata[:repository_owner] = owner
+          metadata[:repository_name] = repo
+        end
+
+        # Pull request information
+        if @env['GITHUB_EVENT_NAME'] == 'pull_request'
+          metadata[:pull_request_number] = @env['GITHUB_REF']&.match(/refs\/pull\/(\d+)\/merge/)&.captures&.first&.to_i
+          metadata[:pull_request] = true
+        elsif @env['GITHUB_REF']
+          metadata[:branch] = @env['GITHUB_REF'].sub('refs/heads/', '')
+        end
+
+        # Run information
+        metadata[:run_id] = @env['GITHUB_RUN_ID']
+        metadata[:run_number] = @env['GITHUB_RUN_NUMBER']
+        metadata[:actor] = @env['GITHUB_ACTOR']
+        metadata[:workflow] = @env['GITHUB_WORKFLOW']
+
+        metadata.compact
+      end
+
+      # CircleCI metadata
+      def detect_circle_ci_metadata
+        metadata = {
+          provider: 'circle_ci',
+          ci: true
+        }
+
+        # Repository
+        metadata[:repository_owner] = @env['CIRCLE_PROJECT_USERNAME']
+        metadata[:repository_name] = @env['CIRCLE_PROJECT_REPONAME']
+
+        # Branch
+        metadata[:branch] = @env['CIRCLE_BRANCH']
+
+        # Pull request information
+        if @env['CIRCLE_PULL_REQUEST']
+          metadata[:pull_request_number] = @env['CIRCLE_PULL_REQUEST'].match(/\/(\d+)$/)&.captures&.first&.to_i
+          metadata[:pull_request] = true
+        end
+
+        # Run information
+        metadata[:build_number] = @env['CIRCLE_BUILD_NUM']
+        metadata[:job_number] = @env['CIRCLE_JOB']
+
+        metadata.compact
+      end
+
+      # Jenkins metadata
+      def detect_jenkins_metadata
+        metadata = {
+          provider: 'jenkins',
+          ci: true
+        }
+
+        # Repository and branch
+        metadata[:repository_url] = @env['GIT_URL']
+        metadata[:branch] = @env['GIT_BRANCH']&.sub('origin/', '')
+
+        # Pull request information (from GitHub Plugin)
+        if @env['ghprbPullId']
+          metadata[:pull_request_number] = @env['ghprbPullId'].to_i
+          metadata[:pull_request] = true
+        end
+
+        # Build information
+        metadata[:build_number] = @env['BUILD_NUMBER']
+        metadata[:build_id] = @env['BUILD_ID']
+        metadata[:job_name] = @env['JOB_NAME']
+
+        metadata.compact
+      end
+
+      # GitLab CI metadata
+      def detect_gitlab_ci_metadata
+        metadata = {
+          provider: 'gitlab_ci',
+          ci: true
+        }
+
+        # Repository
+        metadata[:repository_url] = @env['CI_PROJECT_URL']
+        metadata[:repository_name] = @env['CI_PROJECT_NAME']
+
+        # Branch and merge request
+        if @env['CI_MERGE_REQUEST_IID']
+          metadata[:pull_request_number] = @env['CI_MERGE_REQUEST_IID'].to_i
+          metadata[:pull_request] = true
+        else
+          metadata[:branch] = @env['CI_COMMIT_BRANCH']
+        end
+
+        # Pipeline information
+        metadata[:pipeline_id] = @env['CI_PIPELINE_ID']
+        metadata[:job_name] = @env['CI_JOB_NAME']
+
+        metadata.compact
+      end
+
+      # Travis CI metadata
+      def detect_travis_ci_metadata
+        metadata = {
+          provider: 'travis_ci',
+          ci: true
+        }
+
+        # Repository
+        metadata[:repository] = @env['TRAVIS_REPO_SLUG']
+
+        # Branch and pull request
+        if @env['TRAVIS_PULL_REQUEST'] && @env['TRAVIS_PULL_REQUEST'] != 'false'
+          metadata[:pull_request_number] = @env['TRAVIS_PULL_REQUEST'].to_i
+          metadata[:pull_request] = true
+        else
+          metadata[:branch] = @env['TRAVIS_BRANCH']
+        end
+
+        # Build information
+        metadata[:build_number] = @env['TRAVIS_BUILD_NUMBER']
+        metadata[:build_id] = @env['TRAVIS_BUILD_ID']
+
+        metadata.compact
+      end
+
+      # Bitbucket Pipelines metadata
+      def detect_bitbucket_ci_metadata
+        metadata = {
+          provider: 'bitbucket_ci',
+          ci: true
+        }
+
+        # Repository
+        metadata[:repository_full_name] = @env['BITBUCKET_REPO_FULL_NAME']
+
+        # Branch
+        metadata[:branch] = @env['BITBUCKET_BRANCH']
+
+        # Pull request information
+        if @env['BITBUCKET_PR_ID']
+          metadata[:pull_request_number] = @env['BITBUCKET_PR_ID'].to_i
+          metadata[:pull_request] = true
+        end
+
+        # Build information
+        metadata[:build_number] = @env['BITBUCKET_BUILD_NUMBER']
+
+        metadata.compact
+      end
+
+      # Read git SHA (commit hash)
+      # Returns: String (40-char hex) or nil
+      def read_git_sha
+        read_git_config('rev-parse', 'HEAD')
+      end
+
+      # Read current git branch
+      # Returns: String branch name or nil
+      def read_git_branch
+        # Try to get from detached HEAD first
+        ref = read_git_config('symbolic-ref', '--short', 'HEAD')
+        return ref if ref
+
+        # Fallback: try to get from rev-parse
+        read_git_config('rev-parse', '--abbrev-ref', 'HEAD')
+      end
+
+      # Read repository name from git remote
+      # Returns: String repository name or nil
+      def read_git_repository
+        url = read_git_config('remote', 'get-url', 'origin')
+        return nil unless url
+
+        # Extract repo name from URL
+        # Handles: https://github.com/owner/repo.git, git@github.com:owner/repo.git, etc.
+        url.match(%r{(?:https://|git@)?(?:.*?)[:/](.+?)(?:\.git)?/?$})&.captures&.first
+      end
+
+      # Execute git command and return output
+      # Fails silently if git not available or not a git repo
+      def read_git_config(*git_args)
+        require 'open3'
+
+        # Check if we're in a git repository
+        return nil unless Dir.exist?('.git') || system('git rev-parse --git-dir > /dev/null 2>&1')
+
+        begin
+          stdout, status = Open3.capture2('git', *git_args)
+          return nil unless status.success?
+
+          output = stdout.strip
+          output.empty? ? nil : output
+        rescue Errno::ENOENT
+          # git command not found
+          nil
+        rescue StandardError
+          # Any other error (permission denied, etc.)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/query_guard/cli.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  # Main CLI entry point handling command routing and argument parsing
+  class CLI
+    def self.run(args)
+      cli = new(args)
+      cli.execute
+    end
+
+    def initialize(args)
+      @args = args
+      @command = nil
+      @options = {}
+      @path = '.'
+    end
+
+    def execute
+      parse_arguments
+
+      case @command
+      when 'analyze'
+        execute_analyze
+      when 'check'
+        execute_check
+      when 'help', '--help', '-h', nil
+        print_help
+        exit 0
+      when 'version', '--version', '-v'
+        print_version
+        exit 0
+      else
+        puts "Unknown command: #{@command}"
+        print_help
+        exit 1
+      end
+    end
+
+    private
+
+    # Parse command line arguments
+    def parse_arguments
+      @command = @args.shift&.downcase
+
+      # Parse remaining arguments (options and path)
+      while @args.any?
+        arg = @args.shift
+
+        case arg
+        when '--help', '-h'
+          @options[:help] = true
+        when '--verbose', '-v'
+          @options[:verbose] = true
+        when '--json'
+          @options[:json] = true
+          @options[:format] = 'json'
+        when '--format'
+          format_value = @args.shift
+          @options[:format] = format_value
+          @options[:json] = true if format_value == 'json'
+        when '--threshold'
+          @options[:threshold] = @args.shift
+        when '--config'
+          @options[:config] = @args.shift
+        when /^-/
+          puts "Unknown option: #{arg}"
+          exit 1
+        else
+          # Assume it's a path
+          @path = arg
+        end
+      end
+    end
+
+    def execute_analyze
+      if @options[:help]
+        print_command_help('analyze')
+        exit 0
+      end
+
+      command = Commands::Analyze.new(@path, @options)
+      command.execute
+    end
+
+    def execute_check
+      if @options[:help]
+        print_command_help('check')
+        exit 0
+      end
+
+      command = Commands::Check.new(@path, @options)
+      exit_code = command.execute
+
+      # Exit with appropriate code for check command
+      exit exit_code
+    end
+
+    def print_help
+      puts <<~HELP
+        QueryGuard CLI v#{QueryGuard::VERSION}
+
+        A developer-friendly tool for analyzing query risk and migration safety.
+
+        USAGE:
+          queryguard COMMAND [OPTIONS] [PATH]
+
+        COMMANDS:
+          analyze     Analyze a file or project for query and migration risks
+          check       Check if risks are below configured threshold (for CI/CD)
+          help        Show this help message
+          version     Show version information
+
+        OPTIONS:
+          --help, -h           Show help for command
+          --verbose, -v        Show detailed output
+          --json              Output results as JSON
+          --threshold LEVEL    Set severity threshold (info, warn, error, critical)
+          --config FILE       Load configuration from file
+
+        EXAMPLES:
+          queryguard analyze                 # Analyze current directory
+          queryguard analyze app/models      # Analyze specific directory
+          queryguard check db/migrate        # Check migrations against threshold
+          queryguard check --threshold error # Check with custom threshold
+
+        For more information, visit: https://github.com/your-org/query_guard
+      HELP
+    end
+
+    def print_command_help(command)
+      case command
+      when 'analyze'
+        puts <<~HELP
+          QueryGuard Analyze
+
+          Analyzes files for query and migration risks, printing a report.
+
+          USAGE:
+            queryguard analyze [OPTIONS] [PATH]
+
+          OPTIONS:
+            --help, -h     Show this help message
+            --verbose, -v  Show detailed information about each finding
+            --json        Output results as JSON
+
+          EXIT CODES:
+            0  No errors (risks found may still exist)
+            1  Analysis failed or invalid arguments
+
+          EXAMPLES:
+            queryguard analyze
+            queryguard analyze --verbose
+            queryguard analyze db/migrate
+            queryguard analyze --json app/ > results.json
+        HELP
+      when 'check'
+        puts <<~HELP
+          QueryGuard Check
+
+          Checks if migration/query risks exceed configured threshold.
+          Useful for CI/CD pipelines.
+
+          USAGE:
+            queryguard check [OPTIONS] [PATH]
+
+          OPTIONS:
+            --help, -h           Show this help message
+            --threshold LEVEL    Set severity threshold (default: warn)
+                                 Levels: info, warn, error, critical
+            --verbose, -v       Show detailed output
+            --json              Output results as JSON
+
+          EXIT CODES:
+            0  No findings above threshold (clear to deploy)
+            1  Findings exceed threshold (block deployment)
+            2  Check failed or invalid arguments
+
+          EXAMPLES:
+            queryguard check db/migrate              # Check with default threshold
+            queryguard check --threshold error       # Only fail on :error or :critical
+            queryguard check --threshold critical    # Only fail on :critical
+            queryguard check db/migrate --verbose    # Show all findings details
+        HELP
+      end
+    end
+
+    def print_version
+      puts "QueryGuard v#{QueryGuard::VERSION}"
+    end
+  end
+end
+
+# Require command modules
+require 'query_guard/cli/formatter'
+require 'query_guard/cli/command'
+require 'query_guard/cli/commands/analyze'
+require 'query_guard/cli/commands/check'

data/lib/query_guard/client.rb

@@ -8,17 +8,17 @@ module QueryGuard
     DEFAULT_TIMEOUT = 5 # seconds
 
     def initialize(base_url:, api_key:, project:, env:)
-      @base_url = base_url.sub(%r{/\z}, "") rescue ''
+      @base_url = base_url&.sub(%r{/\z}, "") || ""
       @api_key  = api_key
       @project  = project
       @env      = env
     end
 
-    # Example call used by your Subscriber/Middleware
+    # Bulk events POST
     def post(path, payload)
       uri = URI.parse("#{@base_url}#{path}")
       req = Net::HTTP::Post.new(uri)
-      req["Content-Type"] = "application/json"
+      req["Content-Type"]  = "application/json"
       req["Authorization"] = "Bearer #{@api_key}" if @api_key
       req.body = JSON.generate(payload.merge(project: @project, env: @env))
 
@@ -28,9 +28,7 @@ module QueryGuard
       http.read_timeout = DEFAULT_TIMEOUT
 
       res = http.request(req)
-      unless res.is_a?(Net::HTTPSuccess)
-        warn "[QueryGuard] POST #{uri} -> #{res.code} #{res.body}"
-      end
+      warn "[QueryGuard] POST #{uri} -> #{res.code} #{res.body}" unless res.is_a?(Net::HTTPSuccess)
       res
     rescue => e
       warn "[QueryGuard] HTTP error: #{e.class}: #{e.message}"

data/lib/query_guard/config.rb

@@ -1,23 +1,162 @@
 # frozen_string_literal: true
+require "query_guard/analyzers/base"
+require "query_guard/analyzers/registry"
+require "query_guard/analyzers/slow_query_analyzer"
+require "query_guard/analyzers/query_count_analyzer"
+require "query_guard/analyzers/select_star_analyzer"
+require "query_guard/analyzers/query_risk_analyzer"
+require_relative "budget"
+
 module QueryGuard
   class Config
-    attr_accessor :enabled_environments, :max_queries_per_request,
-                  :max_duration_ms_per_query, :block_select_star,
-                  :ignored_sql, :raise_on_violation, :log_prefix,
-                  :base_url, :api_key, :project, :env
+    # User-facing configuration
+    attr_accessor :migrations_directory, :enabled_environments
+
+    # Analyzer control
+    attr_accessor :disabled_analyzers
+
+    # Severity levels for analyzers
+    attr_accessor :slow_query_severity, :query_count_severity,
+                  :select_star_severity, :migration_risk_severity
+
+    # Query monitoring (optional, defaults disabled)
+    attr_accessor :max_queries_per_request, :max_duration_ms_per_query,
+                  :block_select_star, :raise_on_violation,
+                  :analyze_query_risks,  # Enable/disable query risk analysis
+                  :use_explain_plans,    # Use EXPLAIN plans for query analysis
+                  :explain_enricher,     # Custom EXPLAIN enricher
+                  :ignored_sql           # SQL patterns to ignore in analysis
+
+    # Uploader configuration (SaaS ingestion, future feature)
+    attr_accessor :uploader_type, :api_base_url, :project_key, :api_token
+
+    attr_reader :analyzer_registry
+
+    # --- Security features ---
+    attr_accessor :enable_security
+    attr_accessor :detect_sql_injection
+    attr_accessor :sql_injection_patterns
+
+    attr_accessor :detect_unusual_query_pattern
+    attr_accessor :max_queries_per_minute_per_actor
+    attr_accessor :max_unique_query_fingerprints_per_minute_per_actor
+
+    attr_accessor :detect_data_exfiltration
+    attr_accessor :max_response_bytes_per_request
+    attr_accessor :exfiltration_path_regex
+
+    attr_accessor :detect_mass_assignment
+    attr_accessor :sensitive_param_keys
+
+    # Actor resolver for rate limiting (ip/user/token)
+    attr_accessor :actor_resolver
+
+    # Storage for rolling counters (defaults to in-memory)
+    attr_accessor :store
+
+    # Budget system
+    attr_reader :budget
 
     def initialize
+      # User-facing configuration - simplified for new users
+      @migrations_directory     = "db/migrate"
       @enabled_environments     = %i[development test]
+
+      # Query monitoring thresholds
       @max_queries_per_request  = 100
-      @max_duration_ms_per_query = 100.0   # ms; set to nil to disable
+      @max_duration_ms_per_query = 100.0
       @block_select_star        = false
-      @ignored_sql              = [/^PRAGMA /i, /^BEGIN/i, /^COMMIT/i]
       @raise_on_violation       = false
+      @ignored_sql              = [/^PRAGMA /i, /^BEGIN/i, /^COMMIT/i]
       @log_prefix               = "[QueryGuard]"
+
+      # Analyzer registry and control
+      @disabled_analyzers       = []
+      @analyzer_registry        = Analyzers::Registry.new
+      @analyze_query_risks      = true
+      @use_explain_plans        = false
+      @explain_enricher         = nil
+
+      # Analyzer severity levels
+      @slow_query_severity      = :warn
+      @query_count_severity     = :warn
+      @select_star_severity     = :warn
+      @migration_risk_severity  = :error
+
+      # --- Security defaults (safe, low noise) ---
+      @enable_security          = true
+      @detect_sql_injection     = true
+      @sql_injection_patterns   = [
+        /(\bor\b|\band\b)\s+\d+\s*=\s*\d+/i,   # OR 1=1
+        /\bunion\s+select\b/i,
+        /--|\/\*|\*\//,                         # comment tokens
+        /;\s*(drop|alter|truncate)\b/i,
+        /\b(pg_sleep|sleep)\s*\(/i,
+        /\binformation_schema\b/i
+      ]
+
+      @detect_unusual_query_pattern = true
+      @max_queries_per_minute_per_actor = 300
+      @max_unique_query_fingerprints_per_minute_per_actor = 80
+
+      @detect_data_exfiltration = true
+      @max_response_bytes_per_request = 2_000_000 # ~2MB
+      @exfiltration_path_regex = %r{/(export|download|reports|dump)\b}i
+
+      @detect_mass_assignment   = true
+      @sensitive_param_keys     = %w[
+        admin is_admin role roles permissions permission account_id user_id
+        plan_id price amount balance credit debit status state
+      ]
+
+      @actor_resolver = lambda do |env|
+        env["query_guard.actor"] ||
+          env["action_dispatch.remote_ip"]&.to_s ||
+          env["REMOTE_ADDR"]&.to_s ||
+          "unknown"
+      end
+
+      @store = nil # will default to QueryGuard::Store.new
+
+      @export_mode              = :async
+      @export_queries           = :all
+      @max_query_events_per_req = 200
+      @origin_app               = nil
+
+      # Budget system
+      @budget = Budget.new
+
+      # Uploader configuration (SaaS ingestion, future feature)
+      @uploader_type            = 'no-op'
+      @api_base_url             = nil
+      @project_key              = nil
+      @api_token                = nil
+
+      # Register default analyzers
+      @analyzer_registry.register(:slow_query, Analyzers::SlowQueryAnalyzer.new)
+      @analyzer_registry.register(:query_count, Analyzers::QueryCountAnalyzer.new)
+      @analyzer_registry.register(:select_star, Analyzers::SelectStarAnalyzer.new)
+      @analyzer_registry.register(:query_risk, Analyzers::QueryRiskAnalyzer.new)
     end
 
     def enabled?(env)
       @enabled_environments.map(&:to_sym).include?(env.to_sym)
     end
+
+    # Disable a specific analyzer by name
+    def disable_analyzer(name)
+      analyzer_sym = name.to_sym
+      @disabled_analyzers << analyzer_sym unless @disabled_analyzers.include?(analyzer_sym)
+    end
+
+    # Enable a previously disabled analyzer
+    def enable_analyzer(name)
+      @disabled_analyzers.delete(name.to_sym)
+    end
+
+    # Register a custom analyzer
+    def register_analyzer(name, analyzer)
+      @analyzer_registry.register(name, analyzer)
+    end
   end
 end