kiosk-redteam 0.5.20

data/lib/kiosk/redteam/battery.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Kiosk
+  module Redteam
+    # One ledger and one exit status for a red-team run, filing hand-written
+    # beats and library Scenarios alike. #report! answers 0 only when at least one
+    # attack was blocked, none breached, every attack was tested, and the skips are
+    # exactly the expected ones.
+    class Battery
+      # state is :blocked, :breach, :untested or :skipped.
+      Entry = Data.define(:name, :state, :detail)
+
+      def initialize(io: $stdout)
+        @io      = io
+        @entries = []
+      end
+
+      # untested: a setup step failed, so the attack never reached its gate.
+      def record(name, blocked, detail = '', untested: false)
+        state = blocked ? :blocked : :breach
+        file(Entry.new(name: name.to_s, state: untested ? :untested : state, detail: detail.to_s))
+      end
+
+      # on_skip: :breach when this origin has the surface, so a skip is a harness defect.
+      def scenario(scenario, client:, profile:, on_skip: :skip)
+        verdict = scenario.call(client, profile)
+        absorb_verdict(scenario.name, verdict, on_skip: on_skip)
+      end
+
+      # Runner#run has already printed each line, hence echo: false.
+      def absorb(results, on_skip: :skip)
+        Array(results).map do |r|
+          absorb_verdict(r[:scenario].name, r[:verdict], on_skip: on_skip, echo: false)
+        end
+      end
+
+      def blocked = @entries.select { |e| e.state == :blocked }
+
+      def breaches = @entries.select { |e| e.state == :breach }
+
+      def skipped = @entries.select { |e| e.state == :skipped }
+
+      def untested = @entries.select { |e| e.state == :untested }
+
+      # Returns the exit status: 0 green, 1 breach, untested attack or no proof, 2 skip set differs from expected_skips.
+      def report!(expected_skips: [])
+        actual   = skipped.map(&:name).sort
+        expected = Array(expected_skips).map(&:to_s).sort
+
+        print_summary
+        status = outcome_status
+        status = 2 if skips_differ?(actual, expected) && status.zero?
+        print_json(actual, status)
+        status
+      end
+
+      private
+
+      def print_summary
+        @io.puts "\n── Summary ──"
+        @io.puts(*[blocked, skipped, untested, breaches].flatten.map { line(it, summary: true) })
+        @io.puts ''
+      end
+
+      def line(entry, summary: false)
+        case entry.state
+        when :blocked  then "  BLOCKED ✓ #{entry.name}#{" — #{entry.detail}" unless summary || entry.detail.empty?}"
+        when :skipped  then "  SKIP    — #{entry.name} (#{entry.detail})"
+        when :untested then "  UNTESTED ! #{entry.name} — #{entry.detail}"
+        else                "  BREACH  ✗ #{entry.name} — #{entry.detail}"
+        end
+      end
+
+      # Prints the tally line and answers 0 when every attack was blocked, else 1.
+      def outcome_status
+        return tally(1, "  #{@entries.size} scenarios, 0 BLOCKED — this run proved NOTHING, which is not a pass.") if blocked.empty?
+        unless breaches.empty?
+          return tally(1, "#{counts} #{breaches.size} BREACH — FIX REQUIRED",
+                       '  BREACH means a real hole in the provider — fix the app, not the scenario.')
+        end
+        return tally(0, all_blocked_line) if untested.empty?
+
+        tally(1, "#{counts} 0 BREACH — NOT A PASS",
+              '  UNTESTED means a setup step or the environment failed, and the attack never reached its gate. ' \
+              'Fix the step it names, then run again.')
+      end
+
+      def counts = "  #{blocked.size} BLOCKED, #{skipped.size} SKIPPED, #{untested.size} UNTESTED,"
+
+      def all_blocked_line
+        "  #{blocked.size} BLOCKED, #{skipped.size} SKIPPED, 0 BREACH — all attacks blocked."
+      end
+
+      def tally(status, *lines)
+        @io.puts(*lines)
+        status
+      end
+
+      # Prints the mismatch and answers true when the skip set is not the expected one.
+      def skips_differ?(actual, expected)
+        return false if actual == expected
+
+        @io.puts ''
+        @io.puts '  EXPECTED-APPLICABLE ASSERTION FAILED:'
+        @io.puts "    Expected skips: #{expected.inspect}"
+        @io.puts "    Actual skips:   #{actual.inspect}"
+        @io.puts '  A profile key may have been set to nil, disabling a gate scenario.'
+        true
+      end
+
+      def print_json(actual, status)
+        @io.puts JSON.generate(scenarios: @entries.size, blocked: blocked.size, skipped: actual,
+                               breaches: breaches.map(&:name), untested: untested.map(&:name), exit: status)
+      end
+
+      def absorb_verdict(name, verdict, on_skip:, echo: true)
+        entry = entry_for(name, verdict, on_skip)
+        return file(entry) if echo
+
+        @entries << entry
+        entry
+      end
+
+      def entry_for(name, verdict, on_skip)
+        return skip_entry(name, verdict, on_skip) if verdict.skipped
+        return Entry.new(name: name, state: :blocked, detail: "HTTP #{verdict.status}") if verdict.blocked
+        return Entry.new(name: name, state: :untested, detail: verdict.detail.to_s) if verdict.untested
+
+        Entry.new(name: name, state: :breach, detail: verdict.detail.to_s)
+      end
+
+      def skip_entry(name, verdict, on_skip)
+        reason = verdict.detail.to_s.delete_prefix('SKIP — ')
+        return Entry.new(name: name, state: :skipped, detail: reason) unless on_skip == :breach
+
+        Entry.new(name: name, state: :breach, detail: "SKIPPED, which this origin must never do — #{reason}")
+      end
+
+      def file(entry)
+        @entries << entry
+        @io.puts line(entry)
+        entry
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/leak_scan.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Kiosk
+  module Redteam
+    # Finds runtime vocabulary (a Ruby class, a PostgreSQL error) in an error
+    # body without counting the probe's own echoed value as a leak. A needle is
+    # discounted only when it lies wholly inside one span of bytes the probe
+    # supplied; discounted needles are reported in Result#note.
+    module LeakScan
+      Result = Data.define(:leak, :echoed) do
+        def leak? = !leak.nil?
+
+        def note
+          return '' if echoed.empty?
+
+          " [echoed, not leaked: #{echoed.join(', ')} — these bytes came back " \
+            "from the probe's own value, so they are not the runtime speaking]"
+        end
+      end
+
+      module_function
+
+      # +supplied+ is what the probe put on the wire; nil discounts nothing.
+      def scan(body, needles, supplied: nil)
+        raw = body.is_a?(String) ? body : JSON.generate(body)
+        echoed, leaked = sightings(raw, needles, echo_spans(raw, supplied)).partition(&:last)
+        Result.new(leak: leaked.first&.first, echoed: echoed.map(&:first).freeze)
+      end
+
+      # [needle, echoed?] for each needle found in +raw+, in needle order.
+      def sightings(raw, needles, spans)
+        needles.filter_map do |needle|
+          next if needle.nil? || needle.empty?
+
+          hits = occurrences(raw, needle)
+          [needle, hits.all? { |at| inside_one_span?(at, needle.length, spans) }] unless hits.empty?
+        end
+      end
+
+      def leak(body, needles, supplied: nil)
+        scan(body, needles, supplied: supplied).leak
+      end
+
+      def echo_spans(raw, supplied)
+        spellings(supplied).flat_map do |spelling|
+          occurrences(raw, spelling).map { |at| [at, at + spelling.length] }
+        end
+      end
+
+      # Every form a supplied value can take in a serialized body: JSON, the bare
+      # JSON string content, Ruby `inspect`, and that `inspect` JSON-escaped.
+      def spellings(value, acc = [])
+        nested_values(value).each { |element| spellings(element, acc) }
+        acc.concat(own_spellings(value))
+        acc.reject! { |spelling| spelling.nil? || spelling.empty? }
+        acc.uniq!
+        acc
+      end
+
+      def nested_values(value)
+        case value
+        when Array then value
+        when Hash  then value.flat_map { |key, element| [key, element] }
+        else []
+        end
+      end
+
+      def own_spellings(value)
+        json      = json_fragment(value)
+        inspected = value.inspect
+        [json, bare_string(json, value), inspected, json_fragment(inspected)&.slice(1..-2)]
+      end
+
+      # The JSON string content without its quotes, or nil when +value+ is not a String.
+      def bare_string(json, value)
+        json[1..-2] if json && value.is_a?(String) && json.length > 2
+      end
+
+      def json_fragment(value)
+        JSON.generate([value])[1..-2]
+      rescue StandardError
+        nil
+      end
+
+      def occurrences(haystack, needle)
+        found = []
+        at    = 0
+        while (at = haystack.index(needle, at))
+          found << at
+          at += 1
+        end
+        found
+      end
+
+      # One span, not their union: two adjacent echoes must not cover a needle between them.
+      def inside_one_span?(at, length, spans)
+        finish = at + length
+        spans.any? { |from, to| from <= at && finish <= to }
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/profile.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Redteam
+    # What an origin tells the generic scenarios about itself. A nil field skips
+    # the scenarios that need that surface.
+    #
+    #   pow_difficulty        >0 when /register is gated by a PoW toll; 0 skips RegistrationWithoutPow
+    #   declared_roles        the roles the origin declares; DeviceGrantRoleSelfSelection needs a real one
+    #   requires_kyc          whether the gated action needs a KYC attestation
+    #   currency              the ISO 4217 code the origin prices in, lower case (WrongCurrencyCart)
+    #   per_user_query        query returning the caller's own rows (CrossTenantRead)
+    #   row_id_key            key of a row's id in query results
+    #   result_id_key         key of the new resource's id in forge_action's result
+    #   create_owned          (client, principal) -> Hash with at least :id
+    #   forge_action          action whose caller-supplied user_id the server must ignore
+    #   forge_args            (client, principal_a, principal_b) -> Hash, without user_id
+    #   gated_action          action gated behind payment (and KYC when requires_kyc)
+    #   gated_action_consumes false when calling gated_action twice is correct (skips SpentResourceReuse)
+    #   gated_args            (owned_ref) -> Hash
+    #   pay_for               (client, principal, owned_ref) -> { intent:, cart: }
+    #   kyc_valid             (user_id) -> a valid attestation JWS
+    #   kyc_expired           (user_id) -> an expired attestation JWS
+    #   kyc_forged            (user_id) -> an attestation with a wrong issuer or signature
+    class Profile
+      DEFAULTS = {
+        pow_difficulty: 0,
+        declared_roles: [],
+        currency: nil,
+        requires_kyc: false,
+        per_user_query: nil,
+        row_id_key: 'id',
+        result_id_key: nil,
+        create_owned: nil,
+        forge_action: nil,
+        forge_args: nil,
+        gated_action: nil,
+        gated_action_consumes: true,
+        gated_args: nil,
+        pay_for: nil,
+        kyc_valid: nil,
+        kyc_expired: nil,
+        kyc_forged: nil
+      }.freeze
+
+      attr_reader(*DEFAULTS.keys)
+
+      def initialize(**fields)
+        unknown = fields.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+        DEFAULTS.merge(fields).each { |field, value| instance_variable_set(:"@#{field}", value) }
+        @declared_roles = Array(declared_roles).map(&:to_s).reject(&:empty?).uniq
+        @result_id_key ||= row_id_key
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/runner.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Redteam
+    # Runs scenarios, prints a BLOCKED / SKIP / UNTESTED / BREACH line for each and returns
+    # the `{ scenario:, verdict: }` results; `Battery#absorb` scores them.
+    class Runner
+      def initialize(base_url:, profile:)
+        @client  = Kiosk::TestHelpers::Assistant.new(base_url:)
+        @profile = profile
+      end
+
+      def run(scenarios)
+        scenarios.map do |scenario|
+          verdict = scenario.call(@client, @profile)
+          print_line(scenario, verdict)
+          { scenario:, verdict: }
+        end
+      end
+
+      private
+
+      def print_line(scenario, verdict)
+        if verdict.skipped
+          puts "  SKIP    — #{scenario.name} (#{verdict.detail.delete_prefix('SKIP — ')})"
+        elsif verdict.blocked
+          # The status says which gate answered.
+          puts "  BLOCKED ✓ #{scenario.name} (HTTP #{verdict.status})"
+        elsif verdict.untested
+          puts "  UNTESTED ! #{scenario.name} — #{verdict.detail}"
+        else
+          puts "  BREACH  ✗ #{scenario.name} — #{verdict.detail}"
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/scenario.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'kiosk/redteam/token_claims'
+require 'kiosk/redteam/verdicts'
+require 'kiosk/redteam/staging'
+
+module Kiosk
+  module Redteam
+    # Base class for adversarial scenarios. Subclasses implement #call and
+    # return a Verdict: blocked when the origin refused the attack, skipped
+    # when the profile lacks the surface the scenario needs.
+    class Scenario
+      include Verdicts
+      include Staging
+
+      attr_reader :name
+
+      def initialize(name:)
+        @name = name
+      end
+
+      def call(client, profile)
+        raise NotImplementedError, "#{self.class}#call is not implemented"
+      end
+
+      private
+
+      # Changes a payload claim and keeps the original signature.
+      def tamper_token(token)
+        TokenClaims.tamper(token)
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/scenarios/cross_tenant_read.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Redteam
+    module Scenarios
+      # B's per_user_query must answer 200 without A's row, and A's own query
+      # must return it: without that control, an empty answer proves nothing.
+      class CrossTenantRead < Scenario
+        def initialize
+          super(name: 'CrossTenantRead')
+        end
+
+        def call(client, profile)
+          skip_unless(profile, per_user_query: 'no per_user_query', create_owned: 'no create_owned') ||
+            attack(client, profile)
+        end
+
+        private
+
+        def attack(client, profile)
+          a = client.register!
+          owned_id = profile.create_owned.call(client, a)[:id].to_s
+          control_failure(client.query(a, name: profile.per_user_query), profile, owned_id) ||
+            isolation_verdict(client.query(client.register!, name: profile.per_user_query), profile, owned_id)
+        end
+
+        def control_failure(control, profile, owned_id)
+          return nil if control.status == 200 && rows_contain?(control, profile.row_id_key, owned_id)
+
+          breach_verdict(
+            control.status,
+            "CONTROL FAILED: A's own #{profile.per_user_query} must answer 200 and list " \
+            "A's own resource id=#{owned_id} under row_id_key=" \
+            "#{profile.row_id_key.inspect} — got HTTP #{control.status} " \
+            "#{control.body.inspect}. Until it does, B seeing nothing proves nothing."
+          )
+        end
+
+        def isolation_verdict(resp, profile, owned_id)
+          # An unanswered query is not isolation: an error envelope also reads as no rows.
+          unless resp.status == 200
+            return breach_verdict(resp.status,
+                                  "B's #{profile.per_user_query} was not answered (HTTP #{resp.status}: " \
+                                  "#{resp.body.inspect}); an unanswered query is not proof of isolation")
+          end
+          return blocked_verdict(resp.status) unless rows_contain?(resp, profile.row_id_key, owned_id)
+
+          breach_verdict(resp.status, "A's resource id=#{owned_id} visible in B's #{profile.per_user_query} result")
+        end
+
+        def rows_contain?(response, row_id_key, owned_id)
+          rows_from(response).any? { |row| row[row_id_key].to_s == owned_id }
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/scenarios/device_grant_role_self_selection.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Kiosk
+  module Redteam
+    module Scenarios
+      # The unauthenticated device_authorization request must refuse a
+      # client-chosen role or scope. Probed with roles the origin actually
+      # declares, since a vulnerable origin refuses an undeclared one too; the
+      # role-less request must still open the ceremony.
+      class DeviceGrantRoleSelfSelection < Scenario
+        # Refused by a vulnerable origin too; probed only to show both filters in the detail.
+        UNDECLARED_ROLE = 'master'
+
+        # RFC 8628 §3.2 user codes as this engine mints them.
+        USER_CODE = /\A[A-Z0-9]{4}-[A-Z0-9]{4}\z/
+
+        def initialize
+          super(name: 'DeviceGrantRoleSelfSelection')
+        end
+
+        def call(client, profile)
+          wire_role, setup = wire_declared_role(client)
+          return setup if setup
+
+          declared = (profile.declared_roles + [wire_role]).compact.uniq
+          return skip_verdict(no_declared_role_reason) if declared.empty?
+
+          probes = probe(client, declared)
+          control_ok, control_detail = control(client)
+          refused = probes.all?(&:first)
+          Verdict.new(blocked: refused && control_ok, skipped: false, status: refused ? 400 : 200,
+                      detail: summary(probes, control_detail, declared, wire_role))
+        end
+
+        private
+
+        # [refused?, detail] for each role or scope the request names.
+        def probe(client, declared)
+          pem = OpenSSL::PKey::RSA.generate(2048).public_key.to_pem
+          probe_labels(declared).map do |label, param, value|
+            resp = client.device_authorization(
+              client_id: 'redteam-device-grant-role', public_key: pem, param => value
+            )
+            [resp.status == 400 && body_field(resp, 'error') == 'invalid_request',
+             "#{label} -> HTTP #{resp.status} error=#{body_field(resp, 'error').inspect}"]
+          end
+        end
+
+        def summary(probes, control_detail, declared, wire_role)
+          "#{probes.map(&:last).join('; ')}; #{control_detail} " \
+            "[declared roles probed: #{declared.inspect} " \
+            "(#{wire_role.inspect} read off this origin's own registration token); " \
+            'want every role/scope refused 400 invalid_request AND the role-less ' \
+            'ceremony still opening]'
+        end
+
+        def body_field(resp, key)
+          resp.body.is_a?(Hash) ? resp.body[key] : nil
+        end
+
+        def probe_labels(declared)
+          declared.flat_map do |role|
+            %i[role scope].map do |param|
+              ["#{param}=#{role} (DECLARED by this origin — the escalation itself)", param, role]
+            end
+          end + %i[role scope].map do |param|
+            ["#{param}=#{UNDECLARED_ROLE} (undeclared; refused by the vulnerable code too, " \
+             'so it proves nothing alone)', param, UNDECLARED_ROLE]
+          end
+        end
+
+        def control(client)
+          key  = OpenSSL::PKey::RSA.generate(2048)
+          resp = client.device_authorization(
+            client_id: 'redteam-device-grant-role', public_key: key.public_key.to_pem
+          )
+          code = resp.body.is_a?(Hash) ? resp.body['user_code'].to_s : ''
+          [resp.status == 200 && code.match?(USER_CODE),
+           "CONTROL role-less request -> HTTP #{resp.status} user_code=#{code.inspect}"]
+        end
+
+        # The `role` claim of a token this origin mints at registration.
+        def wire_declared_role(client)
+          resp = client.register_raw
+          failure = (registration_failure(resp) unless resp.status == 201)
+          return [nil, failure] if failure
+
+          [token_role(body_field(resp, 'access_token')), nil]
+        end
+
+        def registration_failure(resp)
+          setup_failure(
+            resp,
+            step: 'the CONTROL registration this scenario reads a declared role from',
+            because: 'without a role the origin actually declares, the only probe left is an ' \
+                     'invented one — which even a vulnerable origin refuses, so the battery ' \
+                     'would print BLOCKED without testing anything.'
+          )
+        end
+
+        def no_declared_role_reason
+          'this origin declares no role — `declared_roles` is empty in the profile AND the ' \
+            'token it minted at registration carries no `role` claim, so a client-chosen ' \
+            'DECLARED role has nothing to name here'
+        end
+
+        # Unverified: only what the server put there matters.
+        def token_role(token)
+          role = TokenClaims.claims(token)&.fetch('role', nil)
+          role.nil? || role.to_s.empty? ? nil : role.to_s
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/scenarios/expired_kyc.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'kiosk/redteam/scenarios/kyc_attack'
+
+module Kiosk
+  module Redteam
+    module Scenarios
+      # An attestation whose exp is past must be refused, either at /kyc or at the gated action.
+      class ExpiredKyc < Scenario
+        include KycAttack
+
+        def initialize
+          super(name: 'ExpiredKyc')
+        end
+
+        def call(client, profile)
+          skip_unless(profile, requires_kyc: 'requires_kyc is false', kyc_expired: 'no kyc_expired callable',
+                               gated_action: 'no gated_action', create_owned: 'no create_owned',
+                               pay_for: 'no pay_for') ||
+            # kyc_required or unauthenticated, depending on where the origin checks exp.
+            kyc_attack(client, profile, attestation: profile.kyc_expired, kind: 'expired',
+                                        check: 'KYC expiry check')
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/scenarios/forged_kyc.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'kiosk/redteam/scenarios/kyc_attack'
+
+module Kiosk
+  module Redteam
+    module Scenarios
+      # An attestation from an untrusted issuer must be refused, at /kyc or at the gated action.
+      class ForgedKyc < Scenario
+        include KycAttack
+
+        def initialize
+          super(name: 'ForgedKyc')
+        end
+
+        def call(client, profile)
+          skip_unless(profile, requires_kyc: 'requires_kyc is false', kyc_forged: 'no kyc_forged callable',
+                               gated_action: 'no gated_action', create_owned: 'no create_owned',
+                               pay_for: 'no pay_for') ||
+            # kyc_required or unauthenticated, depending on the origin.
+            kyc_attack(client, profile, attestation: profile.kyc_forged, kind: 'forged',
+                                        check: 'KYC issuer check')
+        end
+      end
+    end
+  end
+end