normalize: HTML escape

Author: azi-acceis

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unisec (0.0.5)
+    unisec (0.0.6)
       ctf-party (~> 3.0)
       dry-cli (~> 1.0)
       paint (~> 2.3)

README.md

@@ -26,7 +26,7 @@ A CLI tool and library to play with Unicode security.
 - **Hexdump**
   - UTF-8, UTF-16, UTF-32 hexadecimal dumps
 - **Normalization**
-  - NFC, NFKC, NFD, NFKD normalization forms
+  - NFC, NFKC, NFD, NFKD normalization forms, HTML escape bypass for XSS
 - **Properties**
   - Get all properties of a given Unicode character
   - List code points matching a Unicode property

docs/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [unreleased]
 
+## [0.0.6]
+
+**Features**
+
+- _Prepare a XSS payload for HTML escape bypass (HTML escape followed by NFKC / NFKD normalization)_
+  - Rename CLI command `normalize` into `normalize all`
+  - Add a new method `replace_bypass` in the class `Unisec::Normalization`
+  - Add a new CLI command `normalize replace` (using the new `replace_bypass` method)
+
 ## [0.0.5]
 
 **Features**

docs/pages/usage.md

@@ -58,7 +58,9 @@ Options:
   - [Randomize](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Confusables/Randomize)
 - [Grep](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Grep)
 - [Hexdump](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Hexdump)
-- [Normalize](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Normalize)
+- **Normalize**
+  - [All](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Normalize/All)
+  - [Replace](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Normalize/Replace)
 - **Properties**
   - [Char](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Properties/Char)
   - [Codepoints](https://acceis.github.io/unisec/yard/Unisec/CLI/Commands/Properties/Codepoints)

lib/unisec/cli/cli.rb

@@ -24,7 +24,8 @@ module Commands
       register 'confusables randomize', Confusables::Randomize
       register 'grep', Grep
       register 'hexdump', Hexdump
-      register 'normalize', Normalize
+      register 'normalize all', Normalize::All
+      register 'normalize replace', Normalize::Replace
       register 'properties char', Properties::Char
       register 'properties codepoints', Properties::Codepoints
       register 'properties list', Properties::List

lib/unisec/cli/normalization.rb

@@ -8,45 +8,77 @@ module Unisec
   module CLI
     module Commands
       # CLI sub-commands `unisec normalize xxx` for the class {Unisec::Normalization} from the lib.
-      #
-      # Command `unisec normalize "example"`
-      #
-      # Example:
-      #
-      # ```plaintext
-      # ➜ unisec normalize ẛ̣
-      # Original: ẛ̣
-      #   U+1E9B U+0323
-      # NFC: ẛ̣
-      #   U+1E9B U+0323
-      # NFKC: ṩ
-      #   U+1E69
-      # NFD: ẛ̣
-      #   U+017F U+0323 U+0307
-      # NFKD: ṩ
-      #   U+0073 U+0323 U+0307
-      #
-      # ➜ unisec normalize ẛ̣  --form nfkd
-      # ṩ
-      # ```
-      class Normalize < Dry::CLI::Command
-        desc 'Normalize in all forms'
-
-        argument :input, required: true,
-                         desc: 'String input. Read from STDIN if equal to -.'
-
-        option :form, default: nil, values: %w[nfc nfkc nfd nfkd],
-                      desc: 'Output only in the specified normalization form.'
-
-        # Normalize in all forms
-        # @param input [String] Input string to normalize
-        def call(input: nil, **options)
-          input = $stdin.read.chomp if input == '-'
-          if options[:form].nil?
-            puts Unisec::Normalization.new(input).display
-          else
-            # using send() is safe here thanks to the value whitelist
-            puts Unisec::Normalization.send(options[:form], input)
+      module Normalize
+        # Command `unisec normalize all "example"`
+        #
+        # Example:
+        #
+        # ```plaintext
+        # ➜ unisec normalize all ẛ̣
+        # Original: ẛ̣
+        #   U+1E9B U+0323
+        # NFC: ẛ̣
+        #   U+1E9B U+0323
+        # NFKC: ṩ
+        #   U+1E69
+        # NFD: ẛ̣
+        #   U+017F U+0323 U+0307
+        # NFKD: ṩ
+        #   U+0073 U+0323 U+0307
+        #
+        # ➜ unisec normalize all ẛ̣  --form nfkd
+        # ṩ
+        # ```
+        class All < Dry::CLI::Command
+          desc 'Normalize in all forms'
+
+          argument :input, required: true,
+                           desc: 'String input. Read from STDIN if equal to -.'
+
+          option :form, default: nil, values: %w[nfc nfkc nfd nfkd],
+                        desc: 'Output only in the specified normalization form.'
+
+          # Normalize in all forms
+          # @param input [String] Input string to normalize
+          def call(input: nil, **options)
+            input = $stdin.read.chomp if input == '-'
+            if options[:form].nil?
+              puts Unisec::Normalization.new(input).display
+            else
+              # using send() is safe here thanks to the value whitelist
+              puts Unisec::Normalization.send(options[:form], input)
+            end
+          end
+        end
+
+        # Command `unisec normalize replace "example"`
+        #
+        # Example:
+        #
+        # ```plaintext
+        # ➜ unisec normalize replace "<svg onload=\"alert('XSS')\">"
+        # Original: <svg onload="alert('XSS')">
+        #   U+003C U+0073 U+0076 U+0067 U+0020 U+006F U+006E U+006C U+006F U+0061 U+0064 U+003D U+0022 U+0061 U+006C U+0065 U+0072 U+0074 U+0028 U+0027 U+0058 U+0053 U+0053 U+0027 U+0029 U+0022 U+003E
+        # Bypass payload: ﹤svg onload=＂alert(＇XSS＇)＂﹥
+        #   U+FE64 U+0073 U+0076 U+0067 U+0020 U+006F U+006E U+006C U+006F U+0061 U+0064 U+003D U+FF02 U+0061 U+006C U+0065 U+0072 U+0074 U+0028 U+FF07 U+0058 U+0053 U+0053 U+FF07 U+0029 U+FF02 U+FE65
+        # NFKC: <svg onload="alert('XSS')">
+        #   U+003C U+0073 U+0076 U+0067 U+0020 U+006F U+006E U+006C U+006F U+0061 U+0064 U+003D U+0022 U+0061 U+006C U+0065 U+0072 U+0074 U+0028 U+0027 U+0058 U+0053 U+0053 U+0027 U+0029 U+0022 U+003E
+        # NFKD: <svg onload="alert('XSS')">
+        #   U+003C U+0073 U+0076 U+0067 U+0020 U+006F U+006E U+006C U+006F U+0061 U+0064 U+003D U+0022 U+0061 U+006C U+0065 U+0072 U+0074 U+0028 U+0027 U+0058 U+0053 U+0053 U+0027 U+0029 U+0022 U+003E
+        #
+        # ➜ echo -n "<svg onload=\"alert('XSS')\">" | unisec normalize replace -
+        # ```
+        class Replace < Dry::CLI::Command
+          desc 'Prepare a XSS payload for HTML escape bypass (HTML escape followed by NFKC / NFKD normalization)'
+
+          argument :input, required: true,
+                           desc: 'String input. Read from STDIN if equal to -.'
+
+          # Prepare a XSS payload for HTML escape bypass (HTML escape followed by NFKC / NFKD normalization)
+          # @param input [String] Input string to normalize
+          def call(input: nil, **_options)
+            input = $stdin.read.chomp if input == '-'
+            puts Unisec::Normalization.new(input).display_replace
           end
         end
       end

lib/unisec/normalization.rb

@@ -5,6 +5,16 @@
 module Unisec
   # Normalization Forms
   class Normalization
+    # HTML escapable characters mapped with their Unicode counterparts that will
+    # cast to themself after applying normalization forms using compatibility mode.
+    HTML_ESCAPE_BYPASS = {
+      '<' => ['﹤', '＜'],
+      '>' => ['﹥', '＞'],
+      '"' => ['＂'],
+      "'" => ['＇'],
+      '&' => ['﹠', '＆']
+    }.freeze
+
     # Original input
     # @return [String] untouched input
     attr_reader :original
@@ -64,6 +74,25 @@ def self.nfkd(str)
       str.unicode_normalize(:nfkd)
     end
 
+    # Replace HTML escapable characters with their Unicode counterparts that will
+    # cast to themself after applying normalization forms using compatibility mode.
+    # Usefull for XSS, to bypass HTML escape.
+    # If several values are possible, one is picked randomly.
+    # @param str [String] the target string
+    # @return [String] escaped input
+    def self.replace_bypass(str)
+      str = str.dup
+      HTML_ESCAPE_BYPASS.each do |k, v|
+        str.gsub!(k, v.sample)
+      end
+      str
+    end
+
+    # Instance version of {Normalization.replace_bypass}.
+    def replace_bypass
+      Normalization.replace_bypass(@original)
+    end
+
     # Display a CLI-friendly output summurizing all normalization forms
     # @return [String] CLI-ready output
     # @example
@@ -90,5 +119,19 @@ def display
         colorize.call('NFD', @nfd) +
         colorize.call('NFKD', @nfkd)
     end
+
+    # Display a CLI-friendly output of the XSS payload to bypass HTML escape and
+    # what it does once normalized in NFKC & NFKD.
+    def display_replace
+      colorize = lambda { |form_title, form_attr|
+        "#{Paint[form_title.to_s, :underline,
+                 :bold]}: #{form_attr}\n  #{Paint[Unisec::Properties.chars2codepoints(form_attr), :red]}\n"
+      }
+      payload = replace_bypass
+      colorize.call('Original', @original) +
+        colorize.call('Bypass payload', payload) +
+        colorize.call('NFKC', Normalization.nfkc(payload)) +
+        colorize.call('NFKD', Normalization.nfkd(payload))
+    end
   end
 end

lib/unisec/version.rb

@@ -2,5 +2,5 @@
 
 module Unisec
   # Version of unisec library and app
-  VERSION = '0.0.5'
+  VERSION = '0.0.6'
 end

test/test_normalization.rb

@@ -10,5 +10,8 @@ def test_unisec_normalization
     assert_equal("\u{017F 0323 0307}", Unisec::Normalization.nfd("\u{1E9B 0323}"))
     assert_equal("\u{0073 0323 0307}", Unisec::Normalization.nfkd("\u{1E9B 0323}"))
     assert_equal("\u{2126}", Unisec::Normalization.new("\u{2126}").original)
+
+    payload = "<svg onload=\"alert('XSS')\">"
+    assert_equal(payload, Unisec::Normalization.replace_bypass(payload).unicode_normalize(:nfkc))
   end
 end