ronin-support 0.5.1 → 1.0.0.beta1

data/lib/ronin/support/encoding/shell.rb

@@ -0,0 +1,293 @@
+# 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 'strscan'
+
+module Ronin
+  module Support
+    class Encoding < ::Encoding
+      #
+      # Contains methods for encoding/decoding escaping/unescaping Shell data.
+      #
+      # @api public
+      #
+      module Shell
+        # Special shell bytes and their escaped Strings.
+        ESCAPE_BYTES = {
+          0x00 => "\\0",  # $'\0'
+          0x07 => "\\a",  # $'\a'
+          0x08 => "\\b",  # $'\b'
+          0x09 => "\\t",  # $'\t'
+          0x0a => "\\n",  # $'\n'
+          0x0b => "\\v",  # $'\v'
+          0x0c => "\\f",  # $'\f'
+          0x0d => "\\r",  # $'\r'
+          0x1B => "\\e",  # $'\e'
+          0x22 => "\\\"", # \"
+          0x23 => "\\#",  # \#
+          0x5c => "\\\\"  # \\
+        }
+
+        #
+        # Encodes the byte as a shell character.
+        #
+        # @param [Integer] byte
+        #   The byte value to encode.
+        #
+        # @return [String]
+        #   The encoded shell character.
+        #
+        # @raise [RangeError]
+        #   The byte value is negative.
+        #
+        # @example 
+        #   Encoding::Shell.encode_byte(0x41)
+        #   # => "\\x41"
+        #   Encoding::Shell.encode_byte(0x0a)
+        #   # => "\\n"
+        #
+        # @example Encoding unicode characters:
+        #   Encoding::Shell.encode_byte(1001)
+        #   # => "\\u1001"
+        #
+        def self.encode_byte(byte)
+          if byte >= 0x00 && byte <= 0xff
+            "\\x%.2x" % byte
+          elsif byte > 0xff
+            "\\u%x" % byte
+          else
+            raise(RangeError,"#{byte.inspect} out of char range")
+          end
+        end
+
+        #
+        # Escapes the byte as a shell character.
+        #
+        # @param [Integer] byte
+        #   The byte value to escape.
+        #
+        # @return [String]
+        #   The escaped shell character.
+        #
+        # @raise [RangeError]
+        #   The integer value is negative.
+        #
+        # @example 
+        #   Encoding::Shell.escape(0x41)
+        #   # => "A"
+        #   Encoding::Shell.escape(0x08)
+        #   # => "\b"
+        #   Encoding::Shell.escape(0xff)
+        #   # => "\xff"
+        #
+        # @example Escaping unicode characters:
+        #   Encoding::Shell.escape(1001)
+        #   # => "\\u1001"
+        #
+        def self.escape_byte(byte)
+          if byte >= 0x00 && byte <= 0xff
+            ESCAPE_BYTES.fetch(byte) do
+              if byte >= 0x20 && byte <= 0x7e
+                byte.chr
+              else
+                encode_byte(byte)
+              end
+            end
+          else
+            encode_byte(byte)
+          end
+        end
+
+        # Shell characters that must be back-slashed.
+        BACKSLASHED_CHARS = {
+          '0'  => "\0",
+          'a'  => "\a",
+          'b'  => "\b",
+          'e'  => "\e",
+          't'  => "\t",
+          'n'  => "\n",
+          'v'  => "\v",
+          'f'  => "\f",
+          'r'  => "\r",
+          "'"  => "'",
+          '"'  => '"'
+        }
+
+        #
+        # Shell escapes any special characters in the given data.
+        #
+        # @param [String] data
+        #   The data to shell escape.
+        #
+        # @return [String]
+        #   The shell escaped string.
+        #
+        # @example
+        #   Encoding::Shell.escape("hello\nworld")
+        #   # => "hello\\nworld"
+        #
+        def self.escape(data)
+          escaped = String.new
+
+          if data.valid_encoding?
+            data.each_codepoint do |codepoint|
+              escaped << escape_byte(codepoint)
+            end
+          else
+            data.each_byte do |byte|
+              escaped << escape_byte(byte)
+            end
+          end
+
+          return escaped
+        end
+
+        #
+        # Shell unescapes the given data.
+        #
+        # @param [String] data
+        #   The data to shell unescape.
+        #
+        # @return [String]
+        #   The shell unescaped string.
+        #
+        # @example
+        #   "hello\\nworld".shell_unescape
+        #   # => "hello\nworld"
+        #
+        def self.unescape(data)
+          unescaped = String.new
+          scanner   = StringScanner.new(data)
+
+          until scanner.eos?
+            unescaped << if (backslash_char = scanner.scan(/\\[0abetnvfr\'\"]/)) # \n
+                           BACKSLASHED_CHARS[backslash_char[1..]]
+                         elsif (hex_char = scanner.scan(/\\x[0-9a-fA-F]+/)) # \XX
+                           hex_char[2..].to_i(16).chr
+                         elsif (unicode_char = scanner.scan(/\\u[0-9a-fA-F]+/)) # \uXXXX
+                           unicode_char[2..].to_i(16).chr(Encoding::UTF_8)
+                         else
+                           scanner.getch
+                         end
+          end
+
+          return unescaped
+        end
+
+        #
+        # Shell encodes every character in the given data.
+        #
+        # @param [String] data
+        #   The data to shell encode.
+        #
+        # @return [String]
+        #   The shell encoded String.
+        #
+        # @example
+        #   Encoding::Shell.encode("hello world")
+        #   # => "\\x68\\x65\\x6c\\x6c\\x6f\\x0a\\x77\\x6f\\x72\\x6c\\x64"
+        #
+        def self.encode(data)
+          encoded = String.new
+
+          if data.valid_encoding?
+            data.each_codepoint do |codepoint|
+              encoded << encode_byte(codepoint)
+            end
+          else
+            data.each_byte do |byte|
+              encoded << encode_byte(byte)
+            end
+          end
+
+          return encoded
+        end
+
+        #
+        # Alias for {unescape}.
+        #
+        # @param [String] data
+        #   The data to shell unescape.
+        #
+        # @return [String]
+        #   The shell unescaped string.
+        #
+        # @see unescape
+        #
+        def self.decode(data)
+          unescape(data)
+        end
+
+        #
+        # Converts the given data into a double-quoted shell escaped String.
+        #
+        # @param [String] data
+        #   The given data to shell escape and quote.
+        #
+        # @return [String]
+        #   The quoted and escaped shell string.
+        #
+        # @example
+        #   Encoding::Shell.quote("hello world")
+        #   # => "\"hello world\""
+        #   Encoding::Shell.quote("hello\nworld")
+        #   # => "$'hello\\nworld'"
+        #
+        def self.quote(data)
+          if data =~ /[^[:print:]]/
+            "$'#{escape(data)}'"
+          else
+            "\"#{escape(data)}\""
+          end
+        end
+
+        #
+        # Removes the quotes an unescapes a shell string.
+        #
+        # @param [String] data
+        #   The quoted and escaped shell string to unquote and unescape.
+        #
+        # @return [String]
+        #   The un-quoted String if the String begins and ends with quotes, or
+        #   the same String if it is not quoted.
+        #
+        # @example
+        #   Encoding::Shell.unquote("\"hello \\\"world\\\"\"")
+        #   # => "hello \"world\""
+        #   Encoding::Shell.unquote("'hello\\'world'")
+        #   # => "hello'world"
+        #   Encoding::Shell.unquote("$'hello\\nworld'")
+        #   # => "hello\nworld"
+        #
+        def self.unquote(data)
+          if (data[0,2] == "$'" && data[-1] == "'")
+            unescape(data[2..-2])
+          elsif (data[0] == '"' && data[-1] == '"')
+            data[1..-2].gsub("\\\"",'"')
+          elsif (data[0] == "'" && data[-1] == "'")
+            data[1..-2].gsub("\\'","'")
+          else
+            data
+          end
+        end
+      end
+    end
+  end
+end
+
+require 'ronin/support/encoding/shell/core_ext'

data/lib/ronin/{network/extensions → support/encoding}/smtp.rb

@@ -1,20 +1,20 @@
+# 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/network/extensions/smtp/net'
+require 'ronin/support/encoding/base64'
+require 'ronin/support/encoding/quoted_printable'

data/lib/ronin/support/encoding/sql/core_ext/string.rb

@@ -0,0 +1,114 @@
+# 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/encoding/sql'
+
+class String
+
+  #
+  # Escapes an String for SQL.
+  #
+  # @param [Hash{Symbol => Object}] kwargs
+  #   Additional keyword arguments.
+  #
+  # @option kwargs [:single, :double, :tick] :quotes (:single)
+  #   Specifies whether to create a single or double quoted string.
+  #
+  # @return [String]
+  #   The escaped String.
+  #
+  # @raise [ArgumentError]
+  #   The quotes argument was neither `:single`, `:double` nor `:tick`.
+  #
+  # @example
+  #   "O'Brian".sql_escape
+  #   # => "'O''Brian'"
+  #
+  # @example Encode with double-quotes:
+  #   "O'Brian".sql_escape(:double)
+  #   # => "\"O'Brian\""
+  #
+  # @api public
+  #
+  # @see Ronin::Support::Encoding::SQL.escape
+  #
+  def sql_escape(**kwargs)
+    Ronin::Support::Encoding::SQL.escape(self,**kwargs)
+  end
+
+  #
+  # Unescapes a SQL String.
+  #
+  # @return [String]
+  #   The unescaped String.
+  #
+  # @raise [ArgumentError]
+  #   The String was not quoted with single, double or tick-mark quotes.
+  #
+  # @example
+  #   "'O''Brian'".sql_unescape
+  #   # => "O'Brian"
+  #
+  # @api public
+  #
+  # @see Ronin::Support::Encoding::SQL.unescape
+  #
+  # @since 1.0.0
+  #
+  def sql_unescape
+    Ronin::Support::Encoding::SQL.unescape(self)
+  end
+
+  #
+  # Returns the SQL hex-string encoded form of the String.
+  #
+  # @example
+  #   "/etc/passwd".sql_encode
+  #   # => "0x2f6574632f706173737764"
+  #
+  # @api public
+  #
+  # @see Ronin::Support::Encoding::SQL.encode
+  #
+  def sql_encode
+    Ronin::Support::Encoding::SQL.encode(self)
+  end
+
+  #
+  # Returns the SQL decoded form of the String.
+  #
+  # @example
+  #   "'Conan O''Brian'".sql_decode
+  #   # => "Conan O'Brian"
+  #
+  # @example
+  #  "2f6574632f706173737764".sql_decode
+  #  # => "/etc/passwd"
+  #
+  # @raise
+  #   The String is neither hex encoded or SQL escaped.
+  #
+  # @see Ronin::Support::Encoding::SQL.decode
+  #
+  # @api public
+  #
+  def sql_decode
+    Ronin::Support::Encoding::SQL.decode(self)
+  end
+
+end

data/lib/ronin/{formatting/http.rb → support/encoding/sql/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/http'
+require 'ronin/support/encoding/sql/core_ext/string'

data/lib/ronin/support/encoding/sql.rb

@@ -0,0 +1,124 @@
+# 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/>.
+#
+
+module Ronin
+  module Support
+    class Encoding < ::Encoding
+      module SQL
+        # The quote styles and their quote characters.
+        QUOTE_STYLES = {
+          single: "'",
+          double: '"',
+          tick:   '`'
+        }
+
+        #
+        # Escapes a String for SQL.
+        #
+        # @param [String] data
+        #   The String to SQL escape.
+        #
+        # @param [:single, :double, :tick] quotes
+        #   Specifies whether to create a single or double quoted string.
+        #
+        # @return [String]
+        #   The SQL escaped string.
+        #
+        # @raise [ArgumentError]
+        #   The quotes argument was neither `:single`, `:double` nor `:tick`.
+        #
+        def self.escape(data, quotes: :single)
+          char = QUOTE_STYLES.fetch(quotes) do
+                   raise(ArgumentError,"invalid quoting style #{quotes.inspect}")
+                 end
+
+          escaped = data.gsub(char,char * 2)
+
+          return "#{char}#{escaped}#{char}"
+        end
+
+        #
+        # Unescapes a SQL String.
+        #
+        # @param [String] data
+        #   The SQL string to unescape.
+        #
+        # @return [String]
+        #   The unescaped SQL string value.
+        #
+        # @raise [ArgumentError]
+        #   The String was not quoted with single, double or tick-mark quotes.
+        #
+        def self.unescape(data)
+          char = if    (data[0] == "'" && data[-1] == "'") then "'"
+                 elsif (data[0] == '"' && data[-1] == '"') then '"'
+                 elsif (data[0] == '`' && data[-1] == '`') then '`'
+                 else
+                   raise(ArgumentError,"#{data.inspect} is not properly quoted")
+                 end
+
+          return data[1..-2].gsub(char * 2,char)
+        end
+
+        #
+        # Returns the SQL hex-string encoded form of the String.
+        #
+        # @param [String] data
+        #
+        # @return [String]
+        #
+        def self.encode(data)
+          return '' if data.empty?
+
+          hex_string = String.new('0x')
+
+          data.each_byte do |b|
+            hex_string << ('%.2x' % b)
+          end
+
+          return hex_string
+        end
+
+        #
+        # Returns the SQL decoded form of the String.
+        #
+        # @param [String] data
+        #   The SQL string to decode.
+        #
+        # @return [String]
+        #   The decoded String.
+        #
+        def self.decode(data)
+          if (data =~ /^[0-9a-fA-F]{2,}$/ && (data.length % 2 == 0))
+            raw = String.new
+
+            data.scan(/../) do |hex_char|
+              raw << hex_char.to_i(16)
+            end
+
+            return raw
+          else
+            unescape(data)
+          end
+        end
+      end
+    end
+  end
+end
+
+require 'ronin/support/encoding/sql/core_ext'