typosquatting 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e50bfd6b6ae458a3c588600cf0ae4e3fe7a551bf801d0133dca2c88d5df423d6
+  data.tar.gz: d9f0abe8dd964b970e0f760f807b4b76a2f71d3ad9a05b32dcf5b19ce1438f76
+SHA512:
+  metadata.gz: 9cf712d35089a972dd4b9cd47139cb0b793a901f2665de3027629c0f6f39faa1216ef2df4092ee04bc21c89b5c9e2f44e4b26dcbf95598c9b64a151793b3f6be
+  data.tar.gz: 4bb644fb9af9173051c6de93b5d0b5e88f3dac01ff6873dba102dfb2a72d64e0acda77daf7116597a1a93945e050a04f9603c18a039f6faca0761be51e310142

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-16
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"typosquatting" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["andrewnez@gmail.com"](mailto:"andrewnez@gmail.com").

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Andrew Nesbitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,218 @@
+# Typosquatting
+
+Detect potential typosquatting packages across package ecosystems. Generate typosquat variants of package names and check if they exist on package registries.
+
+Supports PyPI, npm, RubyGems, Cargo, Go, Maven, NuGet, Composer, Hex, and Pub.
+
+## When to use this
+
+**Typosquatting** is when an attacker publishes a malicious package with a name similar to a popular one, hoping developers mistype the name or copy-paste a bad example. This tool generates those similar names and checks if they exist.
+
+**Dependency confusion** is when an attacker publishes a public package with the same name as your private/internal package, hoping your build system fetches the public one. The `confusion` command checks which registries have your package name.
+
+This tool helps you:
+- Find existing typosquats of packages you maintain
+- Audit your dependencies for packages that look like typosquats of popular ones
+- Check if your internal package names are safe from dependency confusion
+
+False positives are common. A package named `request` isn't necessarily a typosquat of `requests`. Use the output as a starting point for investigation, not as a definitive verdict.
+
+## Installation
+
+```bash
+gem install typosquatting
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "typosquatting"
+```
+
+## CLI Usage
+
+```bash
+# Generate typosquat variants for a package
+typosquatting generate requests -e pypi
+
+# Use specific algorithms only
+typosquatting generate requests -e pypi -a omission,homoglyph
+
+# Show which algorithm generated each variant
+typosquatting generate requests -e pypi -v
+
+# Check which variants actually exist on registries
+typosquatting check requests -e pypi
+
+# Only show existing packages
+typosquatting check requests -e pypi --existing-only
+
+# Preview what would be checked without API calls
+typosquatting check requests -e pypi --dry-run
+
+# Check for dependency confusion risks
+typosquatting confusion com.company:internal-lib -e maven
+
+# Check multiple packages from a file
+typosquatting confusion -e maven --file internal-packages.txt
+
+# Scan an SBOM for potential typosquats
+typosquatting sbom bom.json
+
+# Output as JSON
+typosquatting check requests -e pypi -f json
+
+# List available algorithms
+typosquatting algorithms
+```
+
+## Example Output
+
+```bash
+$ typosquatting check lodash -e npm --existing-only -v
+
+Checking 142 variants...
+lodas (omission) - EXISTS
+  registries: npmjs.org
+lodah (omission) - EXISTS
+  registries: npmjs.org
+1odash (homoglyph) - EXISTS
+  registries: npmjs.org
+
+Checked 142 variants, 3 exist
+```
+
+```bash
+$ typosquatting sbom bom.json
+
+Potential typosquats found:
+
+reqests (pypi)
+  Version: 1.0.0
+  PURL: pkg:pypi/reqests@1.0.0
+  Similar to existing packages:
+    - requests (omission)
+      registries: pypi.org
+
+Found 1 suspicious package(s)
+```
+
+## Library Usage
+
+```ruby
+require "typosquatting"
+
+# Generate variants (returns array of names)
+variants = Typosquatting.generate("requests", ecosystem: "pypi")
+# => ["reqests", "requets", "request", "reqeusts", ...]
+
+# Generate with algorithm info
+variants = Typosquatting.generate_with_algorithms("requests", ecosystem: "pypi")
+variants.each do |v|
+  puts "#{v.name} (#{v.algorithm})"
+end
+
+# Check which variants exist on registries
+results = Typosquatting.check("requests", ecosystem: "pypi")
+results.each do |result|
+  puts "#{result.name} - #{result.exists? ? 'EXISTS' : 'available'}"
+  puts "  registries: #{result.registries.map(&:name).join(', ')}" if result.exists?
+end
+
+# Dependency confusion check
+confusion = Typosquatting.check_confusion("my-internal-package", ecosystem: "maven")
+confusion.registries.each do |registry, exists|
+  puts "#{registry}: #{exists ? 'EXISTS' : 'available'}"
+end
+puts "Risk detected!" if confusion.confusion_risk?
+
+# Access ecosystem rules
+ecosystem = Typosquatting::Ecosystem.get("pypi")
+ecosystem.valid_name?("some-package")  # => true
+ecosystem.normalise("Some_Package")    # => "some-package"
+
+# Scan an SBOM
+checker = Typosquatting::SBOMChecker.new("bom.json")
+results = checker.check
+results.each do |result|
+  puts "#{result.name} may be a typosquat of:"
+  result.suspicions.each do |s|
+    puts "  - #{s.name} (#{s.algorithm})"
+  end
+end
+```
+
+## Supported Ecosystems
+
+Use these identifiers with the `-e` / `--ecosystem` flag:
+
+| ID | Registry | Case Sensitive | Delimiters | Notes |
+|----|----------|----------------|------------|-------|
+| `pypi` | PyPI | No | `-` `_` `.` | Normalizes to lowercase, collapses delimiters to `-` |
+| `npm` | npmjs.org | No | `-` `_` `.` | Supports scoped packages (`@scope/name`) |
+| `gem` | RubyGems | Yes | `-` `_` | No dots allowed |
+| `cargo` | crates.io | No | `-` `_` | `_` and `-` are equivalent |
+| `golang` | proxy.golang.org | Yes | `-` `_` `.` `/` | Module paths with `/`, version suffixes |
+| `maven` | Maven Central | Yes | `-` `_` `.` | `groupId:artifactId` format |
+| `nuget` | nuget.org | No | `-` `_` `.` | Dots common in names |
+| `composer` | Packagist | No | `-` `_` `.` | `vendor/package` format |
+| `hex` | hex.pm | No | `_` | Underscore only, no hyphens |
+| `pub` | pub.dev | No | `_` | Underscore only, 2-64 chars |
+
+## Algorithms
+
+Use these names with the `-a` / `--algorithms` flag (comma-separated):
+
+| Name | Description | Example |
+|------|-------------|---------|
+| `omission` | Drop single characters | `requests` -> `reqests` |
+| `repetition` | Double characters | `requests` -> `rrequests` |
+| `replacement` | Adjacent keyboard characters | `requests` -> `requezts` |
+| `transposition` | Swap adjacent characters | `requests` -> `reqeusts` |
+| `addition` | Insert characters at start/end | `requests` -> `arequests` |
+| `homoglyph` | Lookalike characters | `requests` -> `reque5ts` |
+| `vowel_swap` | Swap vowels | `requests` -> `raquests` |
+| `delimiter` | Change/add/remove `-` `_` `.` | `my-package` -> `my_package` |
+| `word_order` | Reorder words | `foo-bar` -> `bar-foo` |
+| `plural` | Singularize/pluralize | `request` -> `requests` |
+| `misspelling` | Common typos | `library` -> `libary` |
+| `numeral` | Number/word swap | `lib2` -> `libtwo` |
+
+## SBOM Support
+
+The `sbom` command parses CycloneDX and SPDX JSON files. It reads the `purl` field from each component to determine the ecosystem and package name.
+
+Supported formats:
+- CycloneDX 1.4+ (JSON)
+- SPDX 2.2+ (JSON)
+
+The checker looks for packages in your SBOM that have names similar to existing popular packages, which could indicate you've installed a typosquat.
+
+## API and Rate Limiting
+
+Package lookups use the [ecosyste.ms](https://packages.ecosyste.ms) API. Requests are made in parallel (10 concurrent by default) to improve performance.
+
+Be mindful when checking many packages. The `--dry-run` flag shows what would be checked without making API calls.
+
+## Development
+
+```bash
+git clone https://github.com/andrew/typosquatting
+cd typosquatting
+bundle install
+bundle exec rake test
+```
+
+Run locally without installing:
+
+```bash
+bundle exec ruby -Ilib exe/typosquatting help
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/andrew/typosquatting.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/exe/typosquatting

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "typosquatting"
+
+Typosquatting::CLI.run(ARGV)

data/lib/typosquatting/algorithms/addition.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Addition < Base
+      CHARS = ("a".."z").to_a + ("0".."9").to_a
+
+      def generate(package_name)
+        variants = []
+
+        CHARS.each do |char|
+          variants << char + package_name
+          variants << package_name + char
+        end
+
+        variants.uniq
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Base
+      attr_reader :name
+
+      def initialize
+        @name = self.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+      end
+
+      def generate(package_name)
+        raise NotImplementedError, "Subclasses must implement #generate"
+      end
+
+      def self.all
+        @all ||= [
+          Omission.new,
+          Repetition.new,
+          Replacement.new,
+          Transposition.new,
+          Addition.new,
+          Homoglyph.new,
+          VowelSwap.new,
+          Delimiter.new,
+          WordOrder.new,
+          Plural.new,
+          Misspelling.new,
+          Numeral.new
+        ]
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/delimiter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Delimiter < Base
+      DELIMITERS = %w[- _ .].freeze
+
+      def generate(package_name)
+        variants = []
+
+        DELIMITERS.each do |from_delim|
+          next unless package_name.include?(from_delim)
+
+          DELIMITERS.each do |to_delim|
+            next if from_delim == to_delim
+
+            variants << package_name.gsub(from_delim, to_delim)
+
+            current = package_name
+            while current.include?(from_delim)
+              current = current.sub(from_delim, to_delim)
+              variants << current unless current == package_name.gsub(from_delim, to_delim)
+            end
+          end
+
+          variants << package_name.gsub(from_delim, "")
+
+          current = package_name
+          while current.include?(from_delim)
+            current = current.sub(from_delim, "")
+            variants << current
+          end
+        end
+
+        DELIMITERS.each do |delim|
+          (1...package_name.length).each do |i|
+            next if DELIMITERS.include?(package_name[i - 1]) || DELIMITERS.include?(package_name[i])
+
+            variant = package_name[0...i] + delim + package_name[i..]
+            variants << variant
+          end
+        end
+
+        variants.uniq
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/homoglyph.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Homoglyph < Base
+      GLYPHS = {
+        "a" => %w[4 @],
+        "b" => %w[8 6],
+        "c" => %w[( {],
+        "e" => %w[3],
+        "g" => %w[9 6],
+        "i" => %w[1 l | !],
+        "l" => %w[1 i | I],
+        "o" => %w[0],
+        "s" => %w[5 $],
+        "t" => %w[7 +],
+        "z" => %w[2],
+        "0" => %w[o O],
+        "1" => %w[l i I |],
+        "2" => %w[z Z],
+        "3" => %w[e E],
+        "4" => %w[a A],
+        "5" => %w[s S],
+        "6" => %w[b g],
+        "7" => %w[t T],
+        "8" => %w[b B],
+        "9" => %w[g q],
+        "rn" => %w[m],
+        "m" => %w[rn nn],
+        "vv" => %w[w],
+        "w" => %w[vv uu],
+        "cl" => %w[d],
+        "d" => %w[cl]
+      }.freeze
+
+      def generate(package_name)
+        variants = []
+
+        package_name.each_char.with_index do |char, i|
+          glyphs = GLYPHS[char.downcase] || []
+          glyphs.each do |glyph|
+            variant = package_name[0...i] + glyph + package_name[(i + 1)..]
+            variants << variant
+          end
+        end
+
+        GLYPHS.each do |pattern, replacements|
+          next if pattern.length == 1
+
+          if package_name.include?(pattern)
+            replacements.each do |replacement|
+              variants << package_name.gsub(pattern, replacement)
+            end
+          end
+        end
+
+        variants.uniq
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/misspelling.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Misspelling < Base
+      COMMON_MISSPELLINGS = {
+        "accommodate" => %w[accomodate acommodate],
+        "achieve" => %w[acheive],
+        "acquire" => %w[aquire],
+        "address" => %w[adress],
+        "argument" => %w[arguement],
+        "calendar" => %w[calender],
+        "category" => %w[catagory],
+        "commit" => %w[comit],
+        "config" => %w[confg],
+        "database" => %w[databse],
+        "debug" => %w[debig],
+        "environment" => %w[enviroment enviornment],
+        "experience" => %w[experiance],
+        "gauge" => %w[guage],
+        "grammar" => %w[grammer],
+        "independent" => %w[independant],
+        "library" => %w[libary libraray],
+        "license" => %w[licence lisense],
+        "necessary" => %w[neccessary necessery],
+        "occurrence" => %w[occurence occurrance],
+        "parallel" => %w[paralel parrallel],
+        "privilege" => %w[priviledge],
+        "queue" => %w[que],
+        "receive" => %w[recieve],
+        "recommend" => %w[recomend reccommend],
+        "reference" => %w[refrence referance],
+        "separate" => %w[seperate],
+        "successful" => %w[succesful succesfull],
+        "async" => %w[asyc asnyc],
+        "util" => %w[utl],
+        "utils" => %w[utls utlis],
+        "helper" => %w[hleper helpr],
+        "client" => %w[clent cleint],
+        "server" => %w[sever servre],
+        "request" => %w[requst reuqest],
+        "response" => %w[respnse responese],
+        "parse" => %w[prase prse],
+        "logger" => %w[loger logge],
+        "handler" => %w[handlr hander],
+        "manager" => %w[manger managr],
+        "controller" => %w[controler controllr],
+        "service" => %w[sevice servce],
+        "module" => %w[modle moduel],
+        "package" => %w[pakage packge],
+        "python" => %w[pyhton pytohn],
+        "ruby" => %w[rubu rby],
+        "javascript" => %w[javscript javasript],
+        "typescript" => %w[typscript tyepscript]
+      }.freeze
+
+      def generate(package_name)
+        variants = []
+
+        COMMON_MISSPELLINGS.each do |correct, misspellings|
+          if package_name.include?(correct)
+            misspellings.each do |misspelling|
+              variants << package_name.gsub(correct, misspelling)
+            end
+          end
+
+          misspellings.each do |misspelling|
+            if package_name.include?(misspelling)
+              variants << package_name.gsub(misspelling, correct)
+            end
+          end
+        end
+
+        variants.uniq
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/numeral.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Numeral < Base
+      NUMERALS = {
+        "0" => %w[zero],
+        "1" => %w[one first],
+        "2" => %w[two second],
+        "3" => %w[three third],
+        "4" => %w[four fourth for],
+        "5" => %w[five fifth],
+        "6" => %w[six sixth],
+        "7" => %w[seven seventh],
+        "8" => %w[eight eighth],
+        "9" => %w[nine ninth],
+        "10" => %w[ten tenth]
+      }.freeze
+
+      def generate(package_name)
+        variants = []
+
+        NUMERALS.each do |digit, words|
+          if package_name.include?(digit)
+            words.each do |word|
+              variants << package_name.gsub(digit, word)
+            end
+          end
+
+          words.each do |word|
+            if package_name.include?(word)
+              variants << package_name.gsub(word, digit)
+
+              (words - [word]).each do |other_word|
+                variants << package_name.gsub(word, other_word)
+              end
+            end
+          end
+        end
+
+        variants.reject { |v| v == package_name }.uniq
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/omission.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Omission < Base
+      def generate(package_name)
+        variants = []
+        package_name.length.times do |i|
+          variant = package_name[0...i] + package_name[(i + 1)..]
+          variants << variant unless variant.empty?
+        end
+        variants.uniq
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/plural.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Plural < Base
+      IRREGULAR_PLURALS = {
+        "child" => "children",
+        "person" => "people",
+        "man" => "men",
+        "woman" => "women",
+        "foot" => "feet",
+        "tooth" => "teeth",
+        "goose" => "geese",
+        "mouse" => "mice",
+        "ox" => "oxen",
+        "index" => "indices",
+        "matrix" => "matrices",
+        "vertex" => "vertices",
+        "analysis" => "analyses",
+        "basis" => "bases",
+        "crisis" => "crises",
+        "datum" => "data",
+        "medium" => "media",
+        "criterion" => "criteria"
+      }.freeze
+
+      def generate(package_name)
+        variants = []
+
+        variants << pluralize(package_name)
+        variants << singularize(package_name)
+
+        variants.compact.reject { |v| v == package_name }.uniq
+      end
+
+      def pluralize(word)
+        return IRREGULAR_PLURALS[word] if IRREGULAR_PLURALS.key?(word)
+
+        case word
+        when /(.*)([^aeiou])y$/
+          "#{$1}#{$2}ies"
+        when /(.*)(ss|x|z|ch|sh)$/
+          "#{word}es"
+        when /(.*)fe$/
+          "#{$1}ves"
+        when /(.*)f$/
+          "#{$1}ves"
+        when /(.*)s$/
+          "#{word}es"
+        else
+          "#{word}s"
+        end
+      end
+
+      def singularize(word)
+        reverse_irregulars = IRREGULAR_PLURALS.invert
+        return reverse_irregulars[word] if reverse_irregulars.key?(word)
+
+        case word
+        when /(.*)ies$/
+          "#{$1}y"
+        when /(.*)ves$/
+          "#{$1}f"
+        when /(.*)(ses|xes|zes|ches|shes)$/
+          word[0..-3]
+        when /(.*)s$/
+          $1
+        else
+          word
+        end
+      end
+    end
+  end
+end

data/lib/typosquatting/algorithms/repetition.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Typosquatting
+  module Algorithms
+    class Repetition < Base
+      def generate(package_name)
+        variants = []
+        package_name.each_char.with_index do |char, i|
+          variant = package_name[0..i] + char + package_name[(i + 1)..]
+          variants << variant
+        end
+        variants.uniq
+      end
+    end
+  end
+end