ace-git-secrets 0.13.0

data/lib/ace/git/secrets/organisms/release_gate.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Secrets
+      module Organisms
+        # Pre-release security gate
+        # Blocks releases if tokens are detected in history
+        #
+        # Requires gitleaks to be installed: brew install gitleaks
+        class ReleaseGate
+          attr_reader :scanner, :strict_mode
+
+          # @param repository_path [String] Path to git repository
+          # @param gitleaks_config [String, nil] Path to gitleaks config file
+          # @param strict [Boolean] Fail on medium confidence matches too
+          # @param exclusions [Array<String>, nil] Glob patterns for files to exclude
+          def initialize(repository_path: ".", gitleaks_config: nil, strict: false, exclusions: nil)
+            @scanner = Molecules::HistoryScanner.new(
+              repository_path: repository_path,
+              gitleaks_config: gitleaks_config,
+              exclusions: exclusions
+            )
+            @strict_mode = strict
+          end
+
+          # Run pre-release security check
+          # @return [Hash] Result with :passed, :message, :report keys
+          def check
+            min_confidence = strict_mode ? "medium" : "high"
+
+            report = scanner.scan(min_confidence: min_confidence)
+
+            if report.clean?
+              {
+                passed: true,
+                exit_code: 0,
+                message: "Pre-release security check: PASSED",
+                summary: "No authentication tokens detected in Git history.",
+                report: report
+              }
+            else
+              {
+                passed: false,
+                exit_code: 1,
+                message: "Pre-release security check: FAILED",
+                summary: failure_summary(report),
+                report: report,
+                remediation: remediation_steps(report)
+              }
+            end
+          end
+
+          # Format result for CI output
+          # @param result [Hash] Check result
+          # @param format [String] Output format (table, json)
+          # @return [String]
+          def format_result(result, format: "table")
+            case format
+            when "json"
+              require "json"
+              JSON.pretty_generate({
+                passed: result[:passed],
+                message: result[:message],
+                token_count: result[:report].token_count,
+                tokens: result[:report].tokens.map { |t| t.to_h }
+              })
+            else
+              format_table_result(result)
+            end
+          end
+
+          private
+
+          def failure_summary(report)
+            lines = []
+            lines << "#{report.token_count} authentication token(s) detected in Git history."
+            lines << ""
+            lines << "Summary by type:"
+
+            report.token_types.each do |type|
+              count = report.tokens.count { |t| t.token_type == type }
+              lines << "  - #{type}: #{count}"
+            end
+
+            lines << ""
+            lines << "Release blocked until tokens are removed."
+
+            lines.join("\n")
+          end
+
+          def remediation_steps(report)
+            <<~STEPS
+              To fix this issue:
+
+              1. Review detected tokens:
+                 ace-git-secrets scan
+
+              2. Revoke compromised tokens immediately:
+                 ace-git-secrets revoke
+
+              3. Remove tokens from Git history:
+                 ace-git-secrets rewrite-history
+
+              4. Force push cleaned history:
+                 git push --force-with-lease
+
+              5. Re-run this check:
+                 ace-git-secrets check-release
+            STEPS
+          end
+
+          def format_table_result(result)
+            lines = []
+            lines << "=" * 60
+            lines << result[:message]
+            lines << "=" * 60
+            lines << ""
+            lines << result[:summary]
+
+            unless result[:passed]
+              lines << ""
+              lines << "-" * 60
+              lines << result[:remediation]
+            end
+
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/secrets/organisms/security_auditor.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Secrets
+      module Organisms
+        # Orchestrates security scanning and reporting
+        # High-level workflow for detecting tokens in repositories
+        #
+        # Uses gitleaks for token detection with whitelist filtering,
+        # formatted reporting, and actionable next steps.
+        #
+        # Requires gitleaks to be installed: brew install gitleaks
+        class SecurityAuditor
+          attr_reader :scanner, :output_format, :whitelist, :whitelisted_count, :whitelist_audit_log
+
+          # @param repository_path [String] Path to git repository
+          # @param gitleaks_config [String, nil] Path to gitleaks config file
+          # @param output_format [String] Output format (table, json, yaml)
+          # @param whitelist [Array<Hash>] Patterns/files to whitelist
+          # @param exclusions [Array<String>, nil] Glob patterns for files to exclude
+          def initialize(repository_path: ".", gitleaks_config: nil, output_format: "table",
+            whitelist: [], exclusions: nil)
+            @scanner = Molecules::HistoryScanner.new(
+              repository_path: repository_path,
+              gitleaks_config: gitleaks_config,
+              exclusions: exclusions
+            )
+            @output_format = output_format
+            @whitelist = whitelist || []
+            @whitelisted_count = 0
+            @whitelist_audit_log = []
+          end
+
+          # Run full security audit on repository
+          # @param since [String, nil] Start commit or date
+          # @param min_confidence [String] Minimum confidence level
+          # @param output_path [String, nil] Path to save report
+          # @param verbose [Boolean] Enable verbose output
+          # @return [Models::ScanReport]
+          def audit(since: nil, min_confidence: "low", output_path: nil, verbose: false)
+            puts "Scanning Git history for authentication tokens..." if verbose
+
+            start_time = Time.now
+
+            report = scanner.scan(
+              since: since,
+              min_confidence: min_confidence
+            )
+
+            scan_duration = Time.now - start_time
+
+            # Apply whitelist filtering
+            report = apply_whitelist(report) if whitelist.any?
+
+            # Add timing metadata to report
+            report = add_timing_metadata(report, scan_duration)
+
+            # Output results
+            output_report(report, output_path)
+
+            report
+          end
+
+          # Audit only current files (no history)
+          # @param min_confidence [String] Minimum confidence level
+          # @param output_path [String, nil] Path to save report
+          # @return [Models::ScanReport]
+          def audit_files(min_confidence: "low", output_path: nil)
+            report = scanner.scan_files(min_confidence: min_confidence)
+            output_report(report, output_path)
+            report
+          end
+
+          # Get formatted output
+          # @param report [Models::ScanReport]
+          # @return [String]
+          def format_report(report)
+            case output_format
+            when "json"
+              report.to_json
+            when "yaml"
+              report.to_yaml
+            else
+              report.to_table
+            end
+          end
+
+          # Print actionable next steps
+          # @param report [Models::ScanReport]
+          # @return [String]
+          def next_steps(report)
+            return "No tokens detected. Repository is clean." if report.clean?
+
+            steps = []
+            steps << "SECURITY ALERT: #{report.token_count} token(s) detected in repository"
+            steps << ""
+            steps << "Recommended next steps:"
+            steps << "1. Review detected tokens to confirm they are real (not false positives)"
+            steps << "2. Revoke tokens immediately: ace-git-secrets revoke"
+            steps << "3. Remove tokens from history: ace-git-secrets rewrite-history"
+            steps << "4. Force push the cleaned history: git push --force-with-lease"
+            steps << "5. Notify affected team members to re-clone"
+            steps << ""
+
+            if report.revocable_tokens.any?
+              steps << "Tokens that can be revoked via API: #{report.revocable_tokens.size}"
+            end
+
+            manual = report.tokens.reject(&:revocable?)
+            if manual.any?
+              steps << "Tokens requiring manual revocation: #{manual.size}"
+              steps << "  Visit provider dashboards to revoke these manually."
+            end
+
+            steps.join("\n")
+          end
+
+          private
+
+          # Output report to file or stdout
+          def output_report(report, output_path)
+            formatted = format_report(report)
+
+            if output_path
+              File.write(output_path, formatted)
+              puts "Report saved to: #{output_path}"
+            end
+
+            formatted
+          end
+
+          # Apply whitelist filtering to scan report
+          # @param report [Models::ScanReport] Original report
+          # @return [Models::ScanReport] Filtered report
+          def apply_whitelist(report)
+            whitelisted_tokens = []
+            filtered_tokens = report.tokens.reject do |token|
+              is_whitelisted = whitelisted?(token)
+              whitelisted_tokens << token if is_whitelisted
+              is_whitelisted
+            end
+
+            # Track whitelisted count for display
+            @whitelisted_count = whitelisted_tokens.size
+
+            # Return new report with filtered tokens
+            Models::ScanReport.new(
+              tokens: filtered_tokens,
+              repository_path: report.repository_path,
+              scanned_at: report.scanned_at,
+              scan_options: report.scan_options,
+              commits_scanned: report.commits_scanned,
+              detection_method: report.detection_method
+            )
+          end
+
+          # Check if a token matches any whitelist entry
+          # @param token [Models::DetectedToken] Token to check
+          # @return [Boolean] true if whitelisted
+          def whitelisted?(token)
+            whitelist.any? do |entry|
+              if matches_whitelist_entry?(token, entry)
+                # Audit log for security review: track what was whitelisted and why
+                @whitelist_audit_log << {
+                  token_masked: token.masked_value,
+                  token_type: token.token_type,
+                  file_path: token.file_path,
+                  matched_entry: entry,
+                  reason: entry["reason"]
+                }
+                true
+              else
+                false
+              end
+            end
+          end
+
+          # Check if token matches a specific whitelist entry
+          # @param token [Models::DetectedToken]
+          # @param entry [Hash] Whitelist entry with :pattern or :file key
+          # @return [Boolean]
+          def matches_whitelist_entry?(token, entry)
+            # Match by pattern (exact token value match)
+            if entry["pattern"]
+              return true if token.raw_value == entry["pattern"]
+            end
+
+            # Match by file path (glob pattern)
+            # FNM_EXTGLOB enables ** to match across directories
+            # FNM_DOTMATCH enables matching dotfiles like .env, .claude*
+            if entry["file"]
+              pattern = entry["file"]
+              flags = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH
+              return true if File.fnmatch?(pattern, token.file_path, flags)
+            end
+
+            false
+          end
+
+          # Add timing metadata to report
+          # @param report [Models::ScanReport] Original report
+          # @param scan_duration [Float] Scan duration in seconds
+          # @return [Models::ScanReport] Report with timing metadata
+          def add_timing_metadata(report, scan_duration)
+            Models::ScanReport.new(
+              tokens: report.tokens,
+              repository_path: report.repository_path,
+              scanned_at: report.scanned_at,
+              scan_options: report.scan_options,
+              commits_scanned: report.commits_scanned,
+              detection_method: report.detection_method,
+              scan_duration: scan_duration
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/secrets/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Git
+    module Secrets
+      VERSION = "0.13.0"
+    end
+  end
+end

data/lib/ace/git/secrets.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "secrets/version"
+
+# Load ace-config for configuration cascade management
+require "ace/support/config"
+
+# Models
+require_relative "secrets/models/detected_token"
+require_relative "secrets/models/revocation_result"
+require_relative "secrets/models/scan_report"
+
+# Atoms
+require_relative "secrets/atoms/gitleaks_runner"
+require_relative "secrets/atoms/service_api_client"
+
+# Molecules
+require_relative "secrets/molecules/history_scanner"
+require_relative "secrets/molecules/git_rewriter"
+require_relative "secrets/molecules/token_revoker"
+
+# Organisms
+require_relative "secrets/organisms/security_auditor"
+require_relative "secrets/organisms/history_cleaner"
+require_relative "secrets/organisms/release_gate"
+
+# Commands
+require_relative "secrets/commands/scan_command"
+require_relative "secrets/commands/rewrite_command"
+require_relative "secrets/commands/revoke_command"
+require_relative "secrets/commands/check_release_command"
+
+# CLI
+require_relative "secrets/cli"
+
+module Ace
+  module Git
+    module Secrets
+      class Error < StandardError; end
+      class GitRewriteError < Error; end
+      class RevocationError < Error; end
+
+      # Mutex for thread-safe config loading
+      @config_mutex = Mutex.new
+
+      # Load ace-git-secrets configuration using ace-config cascade
+      # Follows ADR-022: Load defaults from .ace-defaults/, merge user overrides from .ace/
+      # Uses Ace::Support::Config.create() for configuration cascade resolution
+      #
+      # @note Thread Safety: This method is thread-safe via Mutex synchronization.
+      #   The config is loaded once and cached for subsequent calls.
+      #   IMPORTANT: Config MUST be preloaded via CLI.start before parallel operations
+      #   begin. When using ace-git-secrets as a library (not via CLI), call
+      #   Ace::Git::Secrets.config explicitly before spawning any threads that
+      #   perform scanning or revocation. Failure to preload may result in race
+      #   conditions during config initialization under concurrent load.
+      #
+      # @return [Hash] Configuration hash
+      def self.config
+        @config_mutex.synchronize do
+          @config ||= begin
+            gem_root = Gem.loaded_specs["ace-git-secrets"]&.gem_dir ||
+              File.expand_path("../../..", __dir__)
+
+            resolver = Ace::Support::Config.create(
+              config_dir: ".ace",
+              defaults_dir: ".ace-defaults",
+              gem_path: gem_root
+            )
+
+            # Resolve config for git-secrets namespace
+            config = resolver.resolve_namespace("git-secrets")
+
+            # Extract git-secrets section if present
+            config.data["git-secrets"] || config.data
+          rescue => e
+            warn "Warning: Could not load ace-git-secrets config: #{e.message}"
+            fallback_defaults
+          end
+        end
+      end
+
+      # Fallback defaults when config loading fails
+      # Note: Should rarely be used - .ace-defaults/ should always be present
+      # @return [Hash] Minimal fallback configuration
+      def self.fallback_defaults
+        {
+          "exclusions" => [],
+          "whitelist" => [],
+          "output" => {
+            "format" => "table",
+            "mask_tokens" => true
+          }
+        }
+      end
+
+      # Get file exclusions from config
+      # ADR-022: Exclusions come from .ace-defaults/, merged with user config
+      # @return [Array<String>] Glob patterns for files to exclude
+      def self.exclusions
+        config["exclusions"] || []
+      end
+
+      # Resolve gitleaks config path with cascade
+      # Checks: .ace/git-secrets/gitleaks.toml -> .ace-defaults/git-secrets/gitleaks.toml
+      #
+      # @note Thread Safety: This method uses the same mutex as config to ensure
+      #   thread-safe initialization. Like config, it should be preloaded before
+      #   spawning threads (the CLI does this automatically via CLI.start).
+      # @note Environment Variable: Set ACE_GITLEAKS_CONFIG_PATH to override
+      #   automatic config discovery (useful for testing).
+      # @return [String, nil] Path to gitleaks config, or nil if not found
+      def self.gitleaks_config_path
+        @config_mutex.synchronize do
+          @gitleaks_config_path ||= begin
+            # Check environment variable override first (useful for testing)
+            env_path = ENV["ACE_GITLEAKS_CONFIG_PATH"]
+            if env_path && File.exist?(env_path)
+              env_path
+            else
+              # Check user config first (project .ace/)
+              user_path = find_user_gitleaks_config
+              if user_path && File.exist?(user_path)
+                user_path
+              else
+                # Fall back to gem defaults
+                gem_root = File.expand_path("../../..", __dir__)
+                example_path = File.join(gem_root, ".ace-defaults", "git-secrets", "gitleaks.toml")
+                File.exist?(example_path) ? example_path : nil
+              end
+            end
+          end
+        end
+      end
+
+      # Find user gitleaks config in project .ace/ directory
+      # @return [String, nil] Path to user gitleaks config
+      def self.find_user_gitleaks_config
+        # Search from current dir upward for .ace/git-secrets/gitleaks.toml
+        dir = Dir.pwd
+        while dir != "/"
+          config_path = File.join(dir, ".ace", "git-secrets", "gitleaks.toml")
+          return config_path if File.exist?(config_path)
+          dir = File.dirname(dir)
+        end
+        nil
+      end
+
+      # Check if gitleaks is available in PATH
+      # @return [Boolean] true if gitleaks is available
+      def self.gitleaks_available?
+        @gitleaks_available ||= system("which gitleaks > /dev/null 2>&1")
+      end
+
+      # Reset config cache
+      # Useful for testing to ensure clean state between tests.
+      # Thread-safe - uses mutex to reset all cached values atomically.
+      # @return [void]
+      def self.reset_config!
+        @config_mutex.synchronize do
+          @config = nil
+          @gitleaks_config_path = nil
+        end
+        @gitleaks_available = nil
+      end
+    end
+  end
+end