typosquatting 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59d9c744171a8ac32d88c7218078d24ce9a27da2822b03c5127569a9cf91be46
-  data.tar.gz: eb928d00e9d2f3eb5c195628c9a7bc8eaf33e02bc04ce07eab98449b48e3f12c
+  metadata.gz: 1b77954d544fc39b144352e1dfa75ab18f52701b1c8e9d7b49f940158c10f38f
+  data.tar.gz: 3dec0264d6573615efebeb2a6d21e42a1c610e36a5e62449f35d5cee653bc748
 SHA512:
-  metadata.gz: ef4a6f706d3bd5a53d603c1c7d124fd317241ecff5ec898dea1df810ae5e65173986ab3d329ddb7300c89c2608c797b99369425eeb7910cb40f7574de99dfd00
-  data.tar.gz: 93643869152bc1c8ee092a0289c5c49d8615f69adb849f1f5343d8f11748b425f48b6a1e6028223432cf1eecb725fae24181e9d218297657a9fa61e1309675ef
+  metadata.gz: bd100e0d02cda3102f1a65c971a9466deb707f3fc54dc277e188a55d0b8bc91990088469c766f3fa1105950e289152295f0980d392070f8b6eac29f985787b25
+  data.tar.gz: cd6b58996822828dc412f8c88baddc792ff80e8ae3b69247f0b1e9481738c2718e630495e7ec4d1b9c8023eaf497c8aafe7f1b4b5b6f3ce866e66d4fbf928a06

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-01-04
+
+- Add bulk lookup for SBOM checking to reduce API calls
+- Test against Ruby 3.4 and 4.0 in CI
+
+## [0.4.0] - 2026-01-02
+
+- Skip intra-namespace typosquats for scoped packages (npm, composer, golang) since namespace owners control all packages under their namespace
+- Add Dockerfile for running without Ruby installed
+
 ## [0.3.0] - 2025-12-17
 
 - Add `discover` command to find existing similar packages by edit distance using prefix/postfix API

data/Dockerfile

@@ -0,0 +1,5 @@
+FROM ruby:3.4-alpine
+
+RUN gem install typosquatting
+
+ENTRYPOINT ["typosquatting"]

data/README.md

@@ -31,6 +31,19 @@ Or add to your Gemfile:
 gem "typosquatting"
 ```
 
+Or run with Docker:
+
+```bash
+docker build -t typosquatting .
+docker run --rm typosquatting generate requests -e pypi
+```
+
+For commands that read local files (like `sbom`), mount your directory:
+
+```bash
+docker run --rm -v $PWD:/src typosquatting sbom /src/bom.json
+```
+
 ## CLI Usage
 
 ```bash
@@ -242,6 +255,26 @@ Full API documentation: [packages.ecosyste.ms/docs](https://packages.ecosyste.ms
 
 The [ecosyste-ms/typosquatting-dataset](https://github.com/ecosyste-ms/typosquatting-dataset) contains 143 confirmed typosquatting attacks from security research, mapping malicious packages to their targets with classification and source attribution. Useful for testing detection tools and understanding real attack patterns.
 
+## Research
+
+The `research/` directory contains a script to scan "critical" packages (high OpenSSF criticality score) for potential typosquats:
+
+```bash
+# Scan critical RubyGems packages
+ruby research/critical_packages.rb rubygems.org
+
+# Scan npm
+ruby research/critical_packages.rb npmjs.org
+
+# Include all algorithms (default is high-confidence only)
+ruby research/critical_packages.rb rubygems.org --all
+
+# Limit to first N packages for testing
+ruby research/critical_packages.rb rubygems.org --limit=100
+```
+
+The script generates variants using all library algorithms, checks which exist on the registry, and outputs a CSV with download counts, creation dates, repository URLs, and package status. It filters out packages that predate the target (can't be typosquats), packages with high download ratios (likely legitimate), and flags packages that have been removed (confirmed typosquats).
+
 ## Development
 
 ```bash

data/lib/typosquatting/ecosystems/base.rb

@@ -40,6 +40,10 @@ module Typosquatting
         false
       end
 
+      def namespace_controls_members?
+        true
+      end
+
       def parse_namespace(name)
         [nil, name]
       end

data/lib/typosquatting/generator.rb

@@ -85,19 +85,21 @@ module Typosquatting
         end
       end
 
-      name_algorithms.each do |algorithm|
-        name_variants = algorithm.generate(name)
-        name_variants.each do |name_variant|
-          full_name = rebuild_namespaced_name(namespace, name_variant)
-          next if full_name == package_name
-          next unless ecosystem.valid_name?(full_name)
-          next if same_after_normalisation?(package_name, full_name)
-
-          results << Variant.new(
-            name: full_name,
-            algorithm: algorithm.name,
-            original: package_name
-          )
+      unless ecosystem.namespace_controls_members?
+        name_algorithms.each do |algorithm|
+          name_variants = algorithm.generate(name)
+          name_variants.each do |name_variant|
+            full_name = rebuild_namespaced_name(namespace, name_variant)
+            next if full_name == package_name
+            next unless ecosystem.valid_name?(full_name)
+            next if same_after_normalisation?(package_name, full_name)
+
+            results << Variant.new(
+              name: full_name,
+              algorithm: algorithm.name,
+              original: package_name
+            )
+          end
         end
       end
 

data/lib/typosquatting/lookup.rb

@@ -47,20 +47,80 @@ module Typosquatting
       package_names.map { |name| results.find { |n, _| n == name }&.last }
     end
 
+    def bulk_lookup(package_names)
+      return [] if package_names.empty?
+
+      purls = package_names.map { |name| build_purl(name).to_s }
+
+      all_packages = []
+      purls.each_slice(100) do |batch|
+        response = post_json("/packages/bulk_lookup", { purls: batch })
+        all_packages.concat(response || [])
+      end
+
+      packages_by_purl = {}
+      all_packages.each do |pkg|
+        purl = pkg["purl"]
+        next unless purl
+
+        packages_by_purl[purl] ||= []
+        packages_by_purl[purl] << pkg
+      end
+
+      package_names.map do |name|
+        purl = build_purl(name).to_s
+        packages = packages_by_purl[purl] || []
+
+        Result.new(
+          name: name,
+          purl: purl,
+          packages: packages,
+          ecosystem: ecosystem.purl_type
+        )
+      end
+    end
+
     def registries
       response = fetch("/registries?ecosystem=#{URI.encode_www_form_component(ecosystem.purl_type)}")
       response&.map { |r| Registry.new(r) } || []
     end
 
-    def list_names(registry:, prefix: nil, postfix: nil)
+    def list_names(registry:, prefix: nil, postfix: nil, critical: nil, page: nil, per_page: nil)
       params = []
       params << "prefix=#{URI.encode_www_form_component(prefix)}" if prefix
       params << "postfix=#{URI.encode_www_form_component(postfix)}" if postfix
+      params << "critical=true" if critical
+      params << "page=#{page}" if page
+      params << "per_page=#{per_page}" if per_page
       query = params.empty? ? "" : "?#{params.join("&")}"
 
       fetch("/registries/#{URI.encode_www_form_component(registry)}/package_names#{query}") || []
     end
 
+    def list_all_names(registry:, prefix: nil, postfix: nil, critical: nil, per_page: 100)
+      all_names = []
+      page = 1
+
+      loop do
+        names = list_names(
+          registry: registry,
+          prefix: prefix,
+          postfix: postfix,
+          critical: critical,
+          page: page,
+          per_page: per_page
+        )
+        break if names.empty?
+
+        all_names.concat(names)
+        break if names.length < per_page
+
+        page += 1
+      end
+
+      all_names
+    end
+
     def discover(package_name, max_distance: 2)
       registry = registries.first
       return [] unless registry
@@ -219,6 +279,32 @@ module Typosquatting
 
       raise
     end
+
+    def post_json(path, body)
+      uri = URI("#{API_BASE}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request["User-Agent"] = USER_AGENT
+      request["Accept"] = "application/json"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(body)
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPNotFound
+        []
+      else
+        raise APIError, "API request failed: #{response.code} #{response.message}"
+      end
+    rescue StandardError => e
+      raise APIError, "API request failed: #{e.message}" unless e.is_a?(APIError)
+
+      raise
+    end
   end
 
   class APIError < StandardError; end

data/lib/typosquatting/sbom.rb

@@ -79,20 +79,23 @@ module Typosquatting
       lookup = Lookup.new(ecosystem: ecosystem)
 
       variants = generator.generate(package_name)
-      suspicions = []
+      return [] if variants.empty?
 
-      variants.each do |variant|
-        result = lookup.check(variant.name)
-        next unless result.exists?
+      variant_names = variants.map(&:name)
+      results = lookup.bulk_lookup(variant_names)
 
-        suspicions << Suspicion.new(
+      results_by_name = results.to_h { |r| [r.name, r] }
+
+      variants.filter_map do |variant|
+        result = results_by_name[variant.name]
+        next unless result&.exists?
+
+        Suspicion.new(
           name: variant.name,
           algorithm: variant.algorithm,
           registries: result.registries
         )
       end
-
-      suspicions
     end
   end
 end

data/lib/typosquatting/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typosquatting
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/research/README.md

@@ -0,0 +1,74 @@
+# Typosquatting Research Tools
+
+Scripts for analyzing potential typosquats across package registries.
+
+## critical_packages.rb
+
+Scans critical packages (high OpenSSF criticality score) from a registry for potential typosquats using our detection algorithms. Results are written to a timestamped CSV file.
+
+```bash
+# Scan rubygems.org critical packages (high-confidence algorithms only)
+ruby research/critical_packages.rb rubygems.org
+
+# Include all algorithm matches
+ruby research/critical_packages.rb rubygems.org --all
+
+# Limit to first N packages (useful for testing)
+ruby research/critical_packages.rb rubygems.org --limit=100
+```
+
+Supported registries: rubygems.org, npmjs.org, pypi.org, crates.io, packagist.org, hex.pm, pub.dev, proxy.golang.org, repo1.maven.org, nuget.org
+
+## Algorithms
+
+By default, only high-confidence algorithms are used (less likely to produce false positives):
+
+- homoglyph - lookalike characters (l vs 1, O vs 0)
+- repetition - doubled characters (lodash vs llodash)
+- replacement - adjacent keyboard keys (lodash vs lodazh)
+- transposition - swapped adjacent characters (lodash vs lodasj)
+- omission - dropped characters (lodash vs lodas)
+
+Use `--all` to include all 17 algorithms.
+
+## Filters
+
+The script applies several filters to reduce false positives:
+
+- **Short names**: Packages under 5 characters are skipped (too many false positives)
+- **Higher downloads**: Packages with more downloads than the critical package are skipped (not typosquats)
+- **Popular packages**: Packages with >= 1% of the critical package's downloads are skipped (likely legitimate)
+- **Predates target**: Packages created before the critical package are skipped (can't be typosquats)
+
+## CSV Output
+
+Output files are named `{registry}_{timestamp}.csv` with these columns:
+
+| Column | Description |
+|--------|-------------|
+| critical_package | The critical package being checked |
+| critical_downloads | Total downloads of the critical package |
+| critical_created | First release date of the critical package |
+| critical_repo | Repository URL of the critical package |
+| potential_typosquat | A similarly named package that exists |
+| algorithm | Which detection algorithm matched |
+| squat_downloads | Total downloads of the potential typosquat |
+| download_ratio | Squat downloads as percentage of critical downloads |
+| squat_created | First release date of the potential typosquat |
+| squat_status | Package status (empty = active, "removed" = yanked) |
+| squat_repo | Repository URL of the potential typosquat |
+| squat_description | Package description |
+
+## Interpreting Results
+
+Signs of a real typosquat:
+- `squat_status` is "removed" (already yanked by registry)
+- No repository URL
+- Very low download ratio
+- Description is empty or generic
+- Created shortly after the critical package became popular
+
+Signs of a false positive:
+- Has a legitimate repository with real code
+- Description describes unrelated functionality
+- Reasonable download count for its purpose

data/research/critical_packages.rb

@@ -0,0 +1,282 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "typosquatting"
+require "csv"
+
+class CriticalPackageScanner
+  SHORT_NAME_THRESHOLD = 5
+  POPULAR_RATIO_THRESHOLD = 1.0 # Skip squats with >= 1% of critical package downloads
+
+  REGISTRY_MAP = {
+    "rubygems.org" => "rubygems",
+    "npmjs.org" => "npm",
+    "pypi.org" => "pypi",
+    "crates.io" => "cargo",
+    "packagist.org" => "composer",
+    "hex.pm" => "hex",
+    "pub.dev" => "pub",
+    "proxy.golang.org" => "golang",
+    "repo1.maven.org" => "maven",
+    "nuget.org" => "nuget"
+  }.freeze
+
+  # High confidence algorithms that indicate likely intentional typosquatting
+  HIGH_CONFIDENCE_ALGORITHMS = %w[
+    homoglyph
+    repetition
+    replacement
+    transposition
+    omission
+  ].freeze
+
+  attr_reader :registry, :results, :errors, :high_confidence_only, :limit
+
+  def initialize(registry:, high_confidence_only: true, limit: nil)
+    @registry = registry
+    @high_confidence_only = high_confidence_only
+    @limit = limit
+    @results = []
+    @errors = []
+    @prefix_cache = {}
+  end
+
+  def run
+    packages = fetch_critical_packages
+    puts "Found #{packages.length} critical packages for #{registry}"
+    puts
+
+    packages.each_with_index do |package, index|
+      scan_package(package, index + 1, packages.length)
+    end
+
+    write_csv
+    print_summary
+  end
+
+  def fetch_critical_packages
+    packages = lookup.list_all_names(registry: registry, critical: true, per_page: 1000)
+    limit ? packages.first(limit) : packages
+  end
+
+  def scan_package(package_name, current, total)
+    print "\r[#{current}/#{total}] Scanning #{package_name.ljust(40)}"
+
+    # Skip short names - too many false positives
+    return if package_name.length < SHORT_NAME_THRESHOLD
+
+    # Generate typosquatting variants using our algorithms
+    variants = generator.generate(package_name)
+    return if variants.empty?
+
+    # Fetch details for the critical package first (needed for download/date comparison)
+    critical_details = fetch_package_details(package_name)
+    @current_critical_downloads = critical_details&.dig("downloads") || 0
+    @current_critical_created = critical_details&.dig("first_release_published_at")
+
+    # Check which variants exist on the registry
+    existing = check_variants_exist(package_name, variants)
+    return if existing.empty?
+
+    results << {
+      package: package_name,
+      critical_details: critical_details,
+      matches: existing
+    }
+  rescue Typosquatting::APIError => e
+    errors << { package: package_name, error: e.message }
+  rescue StandardError => e
+    errors << { package: package_name, error: e.message }
+  end
+
+  def check_variants_exist(package_name, variants)
+    # Filter to high-confidence algorithms if requested
+    if high_confidence_only
+      variants = variants.select { |v| HIGH_CONFIDENCE_ALGORITHMS.include?(v.algorithm) }
+    end
+
+    # Group variants by prefix for efficient lookup
+    variants_by_prefix = variants.group_by { |v| v.name[0, 3] }
+
+    existing = []
+    variants_by_prefix.each do |prefix, prefix_variants|
+      @prefix_cache[prefix] ||= lookup.list_names(registry: registry, prefix: prefix)
+      existing_set = @prefix_cache[prefix].map(&:downcase).to_set
+
+      prefix_variants.each do |variant|
+        if existing_set.include?(variant.name.downcase) && variant.name.downcase != package_name.downcase
+          # Fetch package details
+          details = fetch_package_details(variant.name)
+          squat_downloads = details&.dig("downloads") || 0
+          squat_created = details&.dig("first_release_published_at")
+
+          # Skip if squat has more downloads than critical package - not a squat
+          next if squat_downloads > @current_critical_downloads
+
+          # Skip if squat is too popular (likely legitimate)
+          if @current_critical_downloads > 0
+            ratio = squat_downloads.to_f / @current_critical_downloads * 100
+            next if ratio >= POPULAR_RATIO_THRESHOLD
+          end
+
+          # Skip if squat predates the critical package (can't be a typosquat)
+          if squat_created && @current_critical_created
+            next if squat_created < @current_critical_created
+          end
+
+          existing << {
+            variant: variant,
+            description: details&.dig("description"),
+            repository_url: details&.dig("repository_url"),
+            downloads: squat_downloads,
+            first_release: squat_created,
+            status: details&.dig("status")
+          }
+        end
+      end
+    end
+
+    existing
+  end
+
+  def fetch_package_details(package_name)
+    result = lookup.check(package_name)
+    result.packages.first
+  rescue StandardError
+    nil
+  end
+
+  def generator
+    @generator ||= Typosquatting::Generator.new(ecosystem: ecosystem_for_registry)
+  end
+
+  def lookup
+    @lookup ||= Typosquatting::Lookup.new(ecosystem: ecosystem_for_registry)
+  end
+
+  def ecosystem_for_registry
+    REGISTRY_MAP[registry] || "rubygems"
+  end
+
+  def output_filename
+    timestamp = Time.now.strftime("%Y%m%d_%H%M%S")
+    "#{registry.gsub(".", "_")}_#{timestamp}.csv"
+  end
+
+  def write_csv
+    return if results.empty?
+
+    filename = output_filename
+    filepath = File.join(__dir__, filename)
+
+    CSV.open(filepath, "w") do |csv|
+      csv << [
+        "critical_package", "critical_downloads", "critical_created", "critical_repo",
+        "potential_typosquat", "algorithm", "squat_downloads", "download_ratio", "squat_created", "squat_status", "squat_repo", "squat_description"
+      ]
+
+      results.each do |result|
+        critical = result[:critical_details]
+        critical_downloads = critical&.dig("downloads") || 0
+        result[:matches].each do |match|
+          squat_downloads = match[:downloads] || 0
+          ratio = critical_downloads > 0 ? (squat_downloads.to_f / critical_downloads * 100).round(4) : 0
+
+          csv << [
+            result[:package],
+            critical_downloads,
+            critical&.dig("first_release_published_at")&.split("T")&.first,
+            critical&.dig("repository_url"),
+            match[:variant].name,
+            match[:variant].algorithm,
+            squat_downloads,
+            "#{ratio}%",
+            match[:first_release]&.split("T")&.first,
+            match[:status],
+            match[:repository_url],
+            match[:description]&.gsub(/\s+/, " ")&.strip
+          ]
+        end
+      end
+    end
+
+    puts "\n\nResults written to #{filepath}"
+  end
+
+  def print_summary
+    puts "\n"
+    puts "=" * 60
+    puts "Results for #{registry}"
+    puts "=" * 60
+    puts
+
+    if results.empty?
+      puts "No potential typosquats found."
+    else
+      puts "Found #{results.length} critical packages with potential typosquats"
+      puts "Total potential typosquats: #{results.sum { |r| r[:matches].length }}"
+
+      # Algorithm breakdown
+      algo_counts = Hash.new(0)
+      results.each do |result|
+        result[:matches].each { |m| algo_counts[m[:variant].algorithm] += 1 }
+      end
+
+      puts "\nBy algorithm:"
+      algo_counts.sort_by { |_, count| -count }.each do |algo, count|
+        puts "  #{algo}: #{count}"
+      end
+
+      # Flag suspicious packages (no repo, low downloads)
+      suspicious = []
+      results.each do |result|
+        result[:matches].each do |match|
+          if match[:repository_url].nil? || match[:repository_url].to_s.empty?
+            suspicious << "#{match[:variant].name} (no repo, #{match[:downloads] || 0} downloads)"
+          end
+        end
+      end
+
+      if suspicious.any?
+        puts "\nSuspicious (no repository):"
+        suspicious.first(10).each { |s| puts "  #{s}" }
+        puts "  ... and #{suspicious.length - 10} more" if suspicious.length > 10
+      end
+
+      # Flag removed/yanked packages (confirmed typosquats)
+      removed = []
+      results.each do |result|
+        result[:matches].each do |match|
+          if match[:status] == "removed"
+            removed << "#{match[:variant].name} (targeting #{result[:package]})"
+          end
+        end
+      end
+
+      if removed.any?
+        puts "\nConfirmed (already yanked):"
+        removed.first(10).each { |s| puts "  #{s}" }
+        puts "  ... and #{removed.length - 10} more" if removed.length > 10
+      end
+    end
+
+    return if errors.empty?
+
+    puts "\n" + "=" * 60
+    puts "Errors (#{errors.length}):"
+    puts "=" * 60
+    errors.each do |error|
+      puts "  #{error[:package]}: #{error[:error]}"
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  registry = ARGV[0] || "rubygems.org"
+  high_confidence_only = !ARGV.include?("--all")
+  limit = ARGV.find { |a| a.start_with?("--limit=") }&.split("=")&.last&.to_i
+
+  scanner = CriticalPackageScanner.new(registry: registry, high_confidence_only: high_confidence_only, limit: limit)
+  scanner.run
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typosquatting
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -49,6 +49,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- Dockerfile
 - LICENSE
 - README.md
 - Rakefile
@@ -89,6 +90,8 @@ files:
 - lib/typosquatting/lookup.rb
 - lib/typosquatting/sbom.rb
 - lib/typosquatting/version.rb
+- research/README.md
+- research/critical_packages.rb
 - sig/typosquatting.rbs
 homepage: https://github.com/andrew/typosquatting
 licenses: