ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/text/erb/mixin.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'erb'
+
+module Ronin
+  module Support
+    module Text
+      module ERB
+        module Mixin
+          #
+          # Renders the ERB template file.
+          #
+          # @param [String] path
+          #   The path to the ERB template file.
+          #
+          # @return [String]
+          #   The rendered result.
+          #
+          def erb(path)
+            erb = ::ERB.new(File.read(path), trim_mode: '-')
+
+            return erb.result(binding)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/text/erb.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/text/erb/mixin'

data/lib/ronin/support/text/homoglyph/core_ext/string.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/text/homoglyph'
+
+class String
+
+  #
+  # Returns a random homoglyph substitution of the String.
+  #
+  # @param [Hash{Symbol => Object}] kwargs
+  #   Additional keyword arguments.
+  #
+  # @option kwargs [:ascii, :greek, :cyrillic, :punctuation, :latin_numbers,
+  #                 :full_width, nil] char_set
+  #   The character set to use.
+  #
+  # @return [String]
+  #   A random homoglyphic variation of the String.
+  #
+  # @raise [ArgumentError]
+  #   Could not find any matching characters to replace in the String.
+  #
+  # @raise [Ronin::Support::Text::Homoglyph::NotViable]
+  #   No homoglyph replaceable characters were found in the String.
+  #
+  # @see Ronin::Support::Text::Homoglyph.substitute
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def homoglyph(**kwargs)
+    Ronin::Support::Text::Homoglyph.substitute(self,**kwargs)
+  end
+
+  #
+  # Enumerates over every homoglyph variation of the String.
+  #
+  # @param [Hash{Symbol => Object}] kwargs
+  #   Additional keyword arguments.
+  #
+  # @option kwargs [:ascii, :greek, :cyrillic, :punctuation, :latin_numbers,
+  #                 :full_width, nil] char_set
+  #   The character set to use.
+  #
+  # @yield [homoglyph]
+  #   The given block will be passed each homoglyph variation of the String.
+  #
+  # @yieldparam [String] homoglyph
+  #   A variation of the String.
+  #
+  # @return [Enumerator]
+  #   If no block is given, an Enumerator object will be returned.
+  #
+  # @see Ronin::Support::Text::Homoglyph.each_substitution
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def each_homoglyph(**kwargs,&block)
+    Ronin::Support::Text::Homoglyph.each_substitution(self,**kwargs,&block)
+  end
+
+  #
+  # Returns every homoglyph variation of the String.
+  #
+  # @param [Hash{Symbol => Object}] kwargs
+  #   Additional keyword arguments.
+  #
+  # @option kwargs [:ascii, :greek, :cyrillic, :punctuation, :latin_numbers,
+  #                 :full_width, nil] char_set
+  #   The character set to use.
+  #
+  # @yield [homoglyph]
+  #   The given block will be passed each homoglyph variation of the given
+  #   word.
+  #
+  # @return [Array<String>]
+  #   All variation of the given String.
+  #
+  # @see Ronin::Support::Text::Homoglyph.each_substitution
+  #
+  # @api public
+  #
+  # @since 1.0.0
+  #
+  def homoglyphs(**kwargs)
+    Ronin::Support::Text::Homoglyph.each_substitution(self,**kwargs).to_a
+  end
+
+end

data/lib/ronin/{formatting/digest.rb → support/text/homoglyph/core_ext.rb}

@@ -1,20 +1,19 @@
+# frozen_string_literal: true
 #
-# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
-# This file is part of Ronin Support.
-#
-# Ronin Support is free software: you can redistribute it and/or modify
+# ronin-support is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
 # by the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 #
-# Ronin Support is distributed in the hope that it will be useful,
+# ronin-support is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU Lesser General Public License for more details.
 #
 # You should have received a copy of the GNU Lesser General Public License
-# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
-require 'ronin/formatting/extensions/digest'
+require 'ronin/support/text/homoglyph/core_ext/string'

data/lib/ronin/{network/http/exceptions/unknown_request.rb → support/text/homoglyph/exceptions.rb}

@@ -1,26 +1,27 @@
+# frozen_string_literal: true
 #
-# Copyright (c) 2006-2012 Hal Brodigan (postmodern.mod3 at gmail.com)
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
-# This file is part of Ronin Support.
-#
-# Ronin Support is free software: you can redistribute it and/or modify
+# ronin-support is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Lesser General Public License as published
 # by the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 #
-# Ronin Support is distributed in the hope that it will be useful,
+# ronin-support is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU Lesser General Public License for more details.
 #
 # You should have received a copy of the GNU Lesser General Public License
-# along with Ronin Support.  If not, see <http://www.gnu.org/licenses/>.
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
 #
 
 module Ronin
-  module Network
-    module HTTP
-      class UnknownRequest < StandardError
+  module Support
+    module Text
+      module Homoglyph
+        class NotViable < RuntimeError
+        end
       end
     end
   end

data/lib/ronin/support/text/homoglyph/table.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/text/homoglyph/exceptions'
+
+module Ronin
+  module Support
+    module Text
+      module Homoglyph
+        #
+        # Loads a table of characters and their homoglyph characters.
+        #
+        # @since 1.0.0
+        #
+        # @api private
+        #
+        class Table
+
+          # The list of all homoglyph characters in the table.
+          #
+          # @return [Array<String>]
+          attr_reader :homoglyphs
+
+          # The table of ASCII characters and their homoglyph counterparts.
+          #
+          # @return [Hash{String => Array<String>}]
+          attr_reader :table
+
+          #
+          # Initializes an empty homoglyph table.
+          #
+          def initialize
+            @homoglyphs = []
+            @table      = {}
+          end
+
+          #
+          # Loads a table of homoglyphs from the `.txt` file.
+          #
+          # @param [String] path
+          #   The path to the `.txt` file.
+          #
+          # @return [Table]
+          #   The newly loaded homoglyph table.
+          #
+          # @api private
+          #
+          def self.load_file(path)
+            table = new()
+
+            File.open(path) do |file|
+              file.each_line(chomp: true) do |line|
+                char, substitute = line.split(' ',2)
+
+                table[char] = substitute
+              end
+            end
+
+            return table
+          end
+
+          #
+          # Looks up the substitute characters for the given original character.
+          #
+          # @param [String] char
+          #   The ASCII character to lookup in the table.
+          #
+          # @return [Array<String>, nil]
+          #   The homoglyphic equivalent characters for the given ASCII
+          #   character.
+          #
+          # @api public
+          #
+          def [](char)
+            @table[char]
+          end
+
+          #
+          # Adds a homoglyph character for the character.
+          #
+          # @param [String] char
+          #   The ASCII character.
+          #
+          # @param [String] substitute
+          #   The ASCII character's homoglyph counterpart.
+          #
+          # @return [Array<String>]
+          #   All previously added homoglyph substitution characters.
+          #
+          # @api private
+          #
+          def []=(char,substitute)
+            @homoglyphs << substitute
+            (@table[char] ||= []) << substitute
+          end
+
+          #
+          # Enumerates over all characters and their substitutions in the table.
+          #
+          # @yield [char,substitutions]
+          #   If a block is given, it will be passed each ASCII character and a
+          #   homoglyphic equivalent character from the table.
+          #
+          # @yieldparam [String] char
+          #   An ASCII character.
+          #
+          # @yieldparam [String] substitution
+          #   A homoglyphic equivalent for the character.
+          #
+          # @return [Enumerator]
+          #   If no block is given, an Enumerator will be returned.
+          #
+          def each(&block)
+            return enum_for(__method__) unless block
+
+            @table.each do |char,substitutions|
+              substitutions.each do |substitute_char|
+                yield char, substitute_char
+              end
+            end
+          end
+
+          #
+          # Combines the table with another table.
+          #
+          # @param [Table] other_table
+          #   The other table to merge together.
+          #
+          # @return [Table]
+          #   The new merged table.
+          #
+          def merge(other_table)
+            new_table = self.class.new
+
+            each do |char,substitute|
+              new_table[char] = substitute
+            end
+
+            other_table.each do |char,other_substitute|
+              new_table[char] = other_substitute
+            end
+
+            return new_table
+          end
+
+          alias + merge
+
+          #
+          # Performs a random homoglyphic substitution on the given String.
+          #
+          # @param [String] string
+          #   The given String.
+          #
+          # @return [String]
+          #   The random homoglyph string derived from the given String.
+          #
+          # @raise [NotViable]
+          #   No homoglyph replaceable characters were found in the String.
+          #
+          def substitute(string)
+            replaceable_chars = string.chars & @table.keys
+
+            if replaceable_chars.empty?
+              raise(NotViable,"no homoglyph replaceable characters found in String (#{string.inspect})")
+            end
+
+            replaceable_char = replaceable_chars.sample
+            substitute_char  = @table[replaceable_char].sample
+
+            return string.sub(replaceable_char,substitute_char)
+          end
+
+          #
+          # Enumerates over every possible homoglyphic substitution of the
+          # given String.
+          #
+          # @param [String] string
+          #   The original to perform substitutions on.
+          #
+          # @yield [homoglyph]
+          #   If a block is given, it will be passed each homoglyphic
+          #   substitution of the given String.
+          #
+          # @yieldparam [String] homoglyph
+          #   A copy of the given String with one character replaced with it's
+          #   homoglyph equivalent from the table.
+          #
+          # @return [Enumerator]
+          #   If no block is given, an Enumerator will be returned.
+          #
+          def each_substitution(string)
+            return enum_for(__method__,string) unless block_given?
+
+            (string.chars & @table.keys).each do |replaceable_char|
+              @table[replaceable_char].each do |substitute_char|
+                offset = 0
+
+                while (index = string.index(replaceable_char,offset))
+                  homoglyph = string.dup
+                  homoglyph[index] = substitute_char
+
+                  yield homoglyph
+                  offset = index+1
+                end
+              end
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/support/text/homoglyph.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/text/homoglyph/table'
+
+module Ronin
+  module Support
+    module Text
+      #
+      # Generates [homoglyph](http://homoglyphs.net/) typos.
+      #
+      # @since 1.0.0
+      #
+      # @api public
+      #
+      module Homoglyph
+        # Path to the `data/text/homoglyphs/` directory.
+        DATA_DIR = File.expand_path(File.join(__dir__,'..','..','..','..','data','text','homoglyphs'))
+
+        # ASCII only homoglyph rules.
+        ASCII = Table.load_file(File.join(DATA_DIR,'ascii.txt'))
+
+        # Greek homoglyph rules.
+        GREEK = Table.load_file(File.join(DATA_DIR,'greek.txt'))
+
+        # Cyrillic homoglyph rules.
+        CYRILLIC = Table.load_file(File.join(DATA_DIR,'cyrillic.txt'))
+
+        # Punctuation/symbol homoglyph rules.
+        PUNCTUATION = Table.load_file(File.join(DATA_DIR,'punctuation.txt'))
+
+        # Latin numeral homoglyph rules.
+        LATIN_NUMBERS = Table.load_file(File.join(DATA_DIR,'latin_numbers.txt'))
+
+        # Full-width homoglyph rules.
+        FULL_WIDTH = Table.load_file(File.join(DATA_DIR,'full_width.txt'))
+
+        # All homoglyph rules combined.
+        DEFAULT = GREEK + CYRILLIC + PUNCTUATION + LATIN_NUMBERS + FULL_WIDTH
+
+        # Homoglyph rules grouped by character set.
+        CHAR_SETS = {
+          ascii:         ASCII,
+          greek:         GREEK,
+          cyrillic:      CYRILLIC,
+          punctuation:   PUNCTUATION,
+          latin_numbers: LATIN_NUMBERS,
+          full_width:    FULL_WIDTH
+        }
+
+        #
+        # Looks up a homoglyph character set.
+        #
+        # @param [:ascii, :greek, :cyrillic, :punctuation, :latin_numbers,
+        #         :full_width, nil] char_set
+        #   The character set name.
+        #
+        # @return [Table]
+        #   The specific homoglyph character set or {DEFAULT} if no name was
+        #   given.
+        #
+        def self.table(char_set=nil)
+          if char_set
+            CHAR_SETS.fetch(char_set) do
+              raise(ArgumentError,"unknown homoglyph character set (#{char_set.inspect}), must be #{CHAR_SETS.keys.map(&:inspect).join(', ')}")
+            end
+          else
+            DEFAULT
+          end
+        end
+
+        #
+        # Returns a random homoglyph substitution of the given word.
+        #
+        # @param [String] word
+        #   The given word to mutate.
+        #
+        # @param [:ascii, :greek, :cyrillic, :punctuation, :latin_numbers,
+        #         :full_width, nil] char_set
+        #   The character set to use.
+        #
+        # @return [String]
+        #   A random homoglyphic variation of the given word.
+        #
+        # @raise [ArgumentError]
+        #   Could not find any matching characters to replace in the given text.
+        #
+        # @raise [NotViable]
+        #   No homoglyph replaceable characters were found in the String.
+        #
+        # @see Table#substitute
+        #
+        def self.substitute(word, char_set: nil)
+          self.table(char_set).substitute(word)
+        end
+
+        #
+        # Enumerates over every homoglyph variation of the given word.
+        #
+        # @param [String] word
+        #   The given word to mutate.
+        #
+        # @param [:ascii, :greek, :cyrillic, :punctuation, :latin_numbers,
+        #         :full_width, nil] char_set
+        #   The character set to use.
+        #
+        # @yield [homoglyph]
+        #   The given block will be passed each homoglyph variation of the given
+        #   word.
+        #
+        # @yieldparam [String] homoglyph
+        #   A variation of the given word.
+        #
+        # @return [Enumerator]
+        #   If no block is given, an Enumerator object will be returned.
+        #
+        # @see Table#each_substitution
+        #
+        def self.each_substitution(word, char_set: nil, &block)
+          self.table(char_set).each_substitution(word,&block)
+        end
+      end
+    end
+  end
+end
+
+require 'ronin/support/text/homoglyph/core_ext'

data/lib/ronin/support/text/mixin.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2006-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-support is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# ronin-support is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-support.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/support/text/random/mixin'
+require 'ronin/support/text/erb/mixin'
+
+module Ronin
+  module Support
+    module Text
+      module Mixin
+        include Random::Mixin
+        include ERB::Mixin
+      end
+    end
+  end
+end