envhunter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6513ca7b1df51f0df7e896ab8df2f0da17924fd273238cbbd63cfd9e8378c54
+  data.tar.gz: 18d191b73c700d8ab5bc711fe83241e6fc9dbc8d80890125f8293c7e88f2be7d
+SHA512:
+  metadata.gz: '0984b505d2ef371ced06a63ae796ed84432299def562606f2915ca5724290e77c567f58968a205141384d7b0bdb4a07bdde96f252150e6be694e8c4766f30288'
+  data.tar.gz: 461c02d75e68f804460fe34ae459b8a5feff104b148c42faca9b0f18341d8b2a95009548601814d5c837eadb31090879d39efd9e8a2d946b105d7222c92f6f61

data/README.md

@@ -0,0 +1,73 @@
+# EnvHunter 🔍
+
+**EnvHunter** is a Ruby-based CLI tool that searches GitHub repositories or gists for `.env` files containing potentially sensitive high-entropy secrets like API keys or tokens.
+
+## ⚙️ Features
+
+- 🔎 Searches GitHub repos or gists for `.env` files
+- 🧪 Detects `.env` variables with names containing `KEY` or `TOKEN`
+- 📈 Filters secrets based on entropy (Shannon entropy)
+- 💬 Outputs results in `terminal`, `json`, or `csv` formats
+- 🔐 Uses GitHub API (requires a Personal Access Token)
+
+## 🧰 Installation
+
+### As a Ruby Gem
+
+```bash
+gem install envhunter
+```
+
+Or clone and build locally:
+
+```bash
+git clone https://github.com/yourusername/envhunter.git
+cd envhunter
+gem build envhunter.gemspec
+gem install envhunter-1.0.0.gem
+```
+
+## 🐳 Docker
+
+```bash
+docker build -t envhunter .
+docker run --rm -e GITHUB_TOKEN=your_token_here envhunter scan --mode gists --format json
+```
+
+## 🚀 Usage
+
+```bash
+envhunter scan [options]
+```
+
+### Options
+
+| Option     | Description                  |
+| ---------- | ---------------------------- |
+| `--mode`   | `repos` (default) or `gists` |
+| `--format` | `terminal`, `json`, or `csv` |
+
+## 🔐 Authentication
+
+Set your GitHub token:
+
+```bash
+export GITHUB_TOKEN=your_token_here
+```
+
+## 📊 Output Example
+
+```plaintext
+=== High Entropy Keys Found ===
+
+User: johndoe
+Repo/Gist: johndoe/myrepo
+File: .env
+Match:
+  API_TOKEN=abcd123...
+----------------------------------------
+```
+
+## 📝 License
+
+MIT License © 2025 Dave Williams <dave@dave.io>

data/bin/envhunter

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+# Try to load from the installed gem first
+begin
+  require "envhunter"
+rescue LoadError
+  # If not found, add the lib directory to the load path (for development)
+  $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+  require "envhunter"
+end
+
+# Run the CLI
+EnvHunter.run_cli

data/lib/envhunter.rb

@@ -0,0 +1,181 @@
+require 'commander/import'
+require 'httparty'
+require 'json'
+require 'csv'
+require 'uri'
+require 'yaml'
+
+module EnvHunter
+  extend self
+
+  GITHUB_TOKEN = ENV['GITHUB_TOKEN'] || abort("Error: GITHUB_TOKEN environment variable is not set.")
+  ENTROPY_THRESHOLD = 4.0
+  KEYWORDS = /KEY|TOKEN/
+
+  def entropy(str)
+    return 0.0 if str.nil? || str.empty?
+    chars = str.each_char.group_by(&:itself).transform_values(&:count)
+    probs = chars.values.map { |c| c.to_f / str.length }
+    -probs.map { |p| p * Math.log2(p) }.reduce(:+) || 0.0
+  end
+
+  def extract_env_keys(content)
+    results = {}
+    content.each_line do |line|
+      next unless line =~ /^\s*[\w\-]+=(.+)$/
+      key, value = line.strip.split('=', 2)
+      next unless key =~ KEYWORDS
+      next if value.nil?
+      ent = entropy(value.gsub(/['"]/, ''))
+      results[key] = value if ent > ENTROPY_THRESHOLD
+    end
+    results
+  end
+
+  def github_search(query, mode, page = 1, per_page = 30)
+    url = if mode == 'gists'
+      "https://api.github.com/gists/public?page=#{page}&per_page=#{per_page}"
+    else
+      "https://api.github.com/search/code?q=#{URI.encode_www_form_component(query)}&page=#{page}&per_page=#{per_page}"
+    end
+    headers = {
+      "Authorization" => "token #{GITHUB_TOKEN}",
+      "User-Agent" => "EnvHunter"
+    }
+    response = HTTParty.get(url, headers: headers)
+    JSON.parse(response.body)
+  end
+
+  def process_results(data, mode, output_file)
+    items = mode == 'gists' ? (data.is_a?(Array) ? data : []) : data['items'] || []
+    found_count = 0
+    results = []
+
+    items.each do |item|
+      raw_url, user, repo, file = if mode == 'gists'
+        next unless item['files']
+        file_obj = item['files'].values.find { |f| f['filename'] =~ /\.env$/ }
+        next unless file_obj
+        [file_obj['raw_url'], item['owner']['login'], "Gist: #{item['id']}", file_obj['filename']]
+      else
+        raw_url = item['html_url'].gsub('github.com', 'raw.githubusercontent.com').gsub('/blob/', '/')
+        [raw_url, item['repository']['owner']['login'], item['repository']['full_name'], item['name']]
+      end
+
+      # Skip files that are likely not of interest
+      next if file.downcase.include?('example')
+      next if file.downcase.include?('sample')
+      next if file.downcase.include?('template')
+      next if file.downcase.include?('.ex.')
+      next if file.downcase.include?('.bak')
+      next if file.downcase.include?('.bkp')
+      next if file.downcase.include?('staging')
+      next if file.downcase.include?('copy')
+      next if file.downcase.include?('backup')
+      next if file.downcase.include?('old')
+      next if file.downcase.include?('archive')
+
+      begin
+        raw = HTTParty.get(raw_url).body
+        matches = extract_env_keys(raw)
+        if matches.any?
+          result = {
+            user: user,
+            repo: repo,
+            file: file,
+            matches: matches
+          }
+          found_count += 1
+
+          # Always output to terminal
+          key_names = result[:matches].keys.join(', ')
+          puts "#{result[:repo]} (#{result[:file]}) - Found: #{key_names}"
+
+          # Store result for YAML output if needed
+          results << result if output_file
+        end
+      rescue => e
+        warn "Error fetching #{raw_url}: #{e}"
+      end
+    end
+
+    [found_count, results]
+  end
+
+  def write_yaml_file(results, filename)
+    # Transform matches into a dictionary with env keys as keys and values as values
+    yaml_results = results.map do |result|
+      {
+        repo: result[:repo],
+        file: result[:file],
+        matches: result[:matches]
+      }
+    end
+
+    # Custom YAML dump to avoid colons before keys
+    yaml_content = "---\n"
+    yaml_results.each do |result|
+      yaml_content += "- repo: #{result[:repo]}\n"
+      yaml_content += "  file: #{result[:file]}\n"
+      yaml_content += "  matches:\n"
+      result[:matches].each do |key, value|
+        yaml_content += "    #{key}: #{value}\n"
+      end
+    end
+
+    File.write(filename, yaml_content)
+    puts "\nResults written to #{filename}"
+  end
+
+  def run_cli
+    program :name, 'EnvHunter'
+    program :version, '1.0.0'
+    program :description, 'Search GitHub for secrets in .env files'
+
+    command :scan do |c|
+      c.syntax = 'envhunter scan [options]'
+      c.description = 'Scan GitHub code or gists for secrets'
+      c.option '--mode MODE', String, 'Search mode: repos or gists (default: repos)'
+      c.option '--output OUTPUT', String, 'Output YAML file (optional)'
+      c.option '--limit LIMIT', Integer, 'Maximum number of responses to process (default: 100)'
+      c.action do |args, options|
+        mode = options.mode == 'gists' ? 'gists' : 'code'
+        output_file = options.output
+        limit = options.limit || 100
+        query = 'filename:.env'
+
+        page = 1
+        total_found = 0
+        all_results = []
+
+        begin
+          loop do
+            data = github_search(query, mode, page)
+            break if data.nil? || (mode == 'gists' ? data.empty? : data['items'].empty?)
+
+            found_in_page, page_results = process_results(data, mode, output_file)
+            total_found += found_in_page
+            all_results.concat(page_results) if output_file
+
+            if limit && total_found >= limit
+              break
+            end
+
+            page += 1
+            print "." # Progress indicator
+            STDOUT.flush
+          end
+        rescue Interrupt
+          puts "\nSearch interrupted by user"
+        end
+
+        puts "\nSearch completed. Found #{total_found} matches."
+
+        # Write YAML file if output file is specified
+        write_yaml_file(all_results, output_file) if output_file && all_results.any?
+      end
+    end
+  end
+end
+
+EnvHunter.run_cli

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: envhunter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Dave Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: commander
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.10'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: Search GitHub code or gists for .env files containing high-entropy secrets
+  like tokens and keys.
+email:
+- dave@dave.io
+executables:
+- envhunter
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/envhunter
+- lib/envhunter.rb
+homepage: https://github.com/daveio/envhunter
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: CLI tool to hunt for secrets in GitHub .env files
+test_files: []