kiosk-redteam 0.5.20

data/lib/kiosk/redteam/token_claims.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'base64'
+
+module Kiosk
+  module Redteam
+    # Reads and edits the payload of a compact JWS. Nothing here verifies a signature.
+    module TokenClaims
+      module_function
+
+      # The payload claims as a Hash, or nil when the token does not decode to one.
+      def claims(token)
+        payload_b64 = token.to_s.split('.')[1]
+        return nil if payload_b64.nil?
+
+        parsed = decode(payload_b64)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue StandardError
+        nil
+      end
+
+      # Changes one payload claim and keeps the original signature.
+      def tamper(token)
+        header, payload_b64, sig = token.split('.', 3)
+        return token if payload_b64.nil?
+
+        new_payload = Base64.urlsafe_encode64(JSON.generate(flip(decode(payload_b64))), padding: false)
+        [header, new_payload, sig].join('.')
+      end
+
+      def decode(payload_b64)
+        padded = payload_b64 + ('=' * ((4 - (payload_b64.length % 4)) % 4))
+        JSON.parse(Base64.urlsafe_decode64(padded))
+      end
+
+      def flip(claims)
+        if claims.key?('role')
+          claims['role'] = claims['role'] == 'admin' ? 'superadmin' : 'admin'
+        elsif claims.key?('sub')
+          claims['sub'] = "#{claims['sub']}-tampered"
+        elsif claims.key?('exp')
+          claims['exp'] = (claims['exp'].to_i + 999_999)
+        else
+          claims['__tamper__'] = true
+        end
+        claims
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/verdict.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Redteam
+    # BLOCKED: blocked. UNTESTED: the attack never reached the gate under test,
+    # because a setup step or the environment failed. BREACH: none of these.
+    # SKIPPED: the profile lacks the surface, which is not a pass. status is 0
+    # for a skip.
+    Verdict = Data.define(:blocked, :skipped, :status, :detail, :untested) do
+      def initialize(untested: false, **) = super
+    end
+  end
+end

data/lib/kiosk/redteam/verdicts.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Redteam
+    # Builds the Verdict a Scenario returns. Mixed into Scenario as private methods.
+    module Verdicts
+      private
+
+      def skip_verdict(reason)
+        Verdict.new(blocked: false, skipped: true, status: 0, detail: "SKIP — #{reason}")
+      end
+
+      # The first profile field that is unset, as a skip verdict; nil when every field is set.
+      def skip_unless(profile, reasons)
+        _field, reason = reasons.find { |field, _| !profile.public_send(field) }
+        reason && skip_verdict(reason)
+      end
+
+      def blocked_verdict(status, detail = '')
+        Verdict.new(blocked: true, skipped: false, status: status, detail: detail)
+      end
+
+      def breach_verdict(status, detail)
+        Verdict.new(blocked: false, skipped: false, status: status, detail: detail)
+      end
+
+      def untested_verdict(status, detail)
+        Verdict.new(blocked: false, skipped: false, status: status, detail: detail, untested: true)
+      end
+
+      # The verdict of a beat that sends several probes: a breach when a probe
+      # failed, untested when none failed but one was answered before the origin
+      # evaluated it, and blocked otherwise.
+      def probes_verdict(status, failures, unevaluated)
+        return breach_verdict(status, failures.join(' | ')) unless failures.empty?
+        return untested_verdict(status, "COULD NOT TEST: #{unevaluated.join(' | ')}") unless unevaluated.empty?
+
+        blocked_verdict(status)
+      end
+
+      # +expect+ / +expect_code+ name the gate that must refuse; with neither,
+      # any status or code Kiosk::Redteam.blocked? accepts counts. An answer given
+      # before the attack was evaluated is untested unless +expect_code+ names it.
+      def verdict_from(response, expect: nil, expect_code: nil, detail: nil)
+        return any_gate_verdict(response, detail) if expect.nil? && expect_code.nil?
+        return payment_required_stall(response) if unevaluated_unnamed?(response, expect_code)
+
+        misses = gate_misses(response, expect, expect_code)
+        return blocked_verdict(response.status) if misses.empty?
+
+        named_gate_breach(response, misses, detail)
+      end
+
+      def named_gate_breach(response, misses, detail)
+        breach_verdict(response.status,
+                       "#{detail || 'attack was not refused by the named gate'} " \
+                       "[#{misses.join('; ')}; got HTTP #{response.status} " \
+                       "code=#{error_code(response).inspect}, body=#{response.body.inspect}]")
+      end
+
+      def unevaluated_unnamed?(response, expect_code)
+        Kiosk::Redteam.unevaluated?(response) && !Array(expect_code).include?(error_code(response))
+      end
+
+      def any_gate_verdict(response, detail)
+        stall = payment_required_stall(response)
+        return stall if stall
+        return blocked_verdict(response.status) if Kiosk::Redteam.blocked?(response)
+
+        breach_verdict(response.status, detail || "HTTP #{response.status}: #{response.body.inspect}")
+      end
+
+      def gate_misses(response, expect, expect_code)
+        [
+          status_miss(response.status, expect),
+          code_miss(error_code(response), expect_code),
+          ('5xx is never a block' if response.status >= 500),
+          (unpinned_payment_miss if response.status == 402 && expect_code.nil?)
+        ].compact
+      end
+
+      def status_miss(status, expect)
+        return nil if expect.nil? || Array(expect).include?(status)
+
+        "want status #{Array(expect).join('/')}"
+      end
+
+      def code_miss(code, expect_code)
+        return nil if expect_code.nil? || Array(expect_code).include?(code)
+
+        "want error.code #{Array(expect_code).map(&:inspect).join('/')}"
+      end
+
+      def unpinned_payment_miss
+        'HTTP 402 is conclusive only with an explicit expect_code — ' \
+          "#{Kiosk::Redteam::PAYMENT_REQUIRED_CODES.keys.join('/')} all ride that status"
+      end
+
+      # A payment-required answer proves no refusal. It is untested when it came
+      # before the attack was evaluated, and a breach otherwise.
+      def payment_required_stall(response, step: nil)
+        reason = Kiosk::Redteam.payment_required_reason(response)
+        return nil unless reason
+
+        answered = "#{step || 'the attack under test'} was answered #{reason}."
+        return breach_verdict(response.status, "#{answered} No gate refused the attack.") unless Kiosk::Redteam.unevaluated?(response)
+
+        untested_verdict(
+          response.status,
+          "COULD NOT TEST: #{answered} That is neither a refusal of this attack nor a breach — nothing was proved " \
+          'either way. A provider that means a payment gate HERE must have the scenario ' \
+          'name the code it accepts (verdict_from expect_code:).'
+        )
+      end
+
+      # A failed setup step must not let a later refusal from another gate pass as this one's.
+      def setup_failure(response, step:, because:)
+        return nil if response.nil? || response.status == 200
+
+        untested_verdict(response.status,
+                         "SETUP FAILED: #{step} returned HTTP #{response.status} " \
+                         "#{response.body.inspect}. #{because}")
+      end
+
+      def error_code(response)
+        Kiosk::Redteam.error_code(response)
+      end
+    end
+  end
+end

data/lib/kiosk/redteam/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Redteam
+    VERSION = '0.5.20'
+  end
+end

data/lib/kiosk/redteam.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'kiosk/test_helpers/assistant'
+require 'kiosk/redteam/version'
+require 'kiosk/redteam/verdict'
+require 'kiosk/redteam/leak_scan'
+require 'kiosk/redteam/scenario'
+require 'kiosk/redteam/runner'
+require 'kiosk/redteam/profile'
+require 'kiosk/redteam/battery'
+
+require 'kiosk/redteam/scenarios/cross_tenant_read'
+require 'kiosk/redteam/scenarios/forged_user_id'
+require 'kiosk/redteam/scenarios/mandate_principal_swap'
+require 'kiosk/redteam/scenarios/mandate_replay'
+require 'kiosk/redteam/scenarios/token_tampering'
+require 'kiosk/redteam/scenarios/registration_without_pow'
+require 'kiosk/redteam/scenarios/privilege_self_selection'
+require 'kiosk/redteam/scenarios/device_grant_role_self_selection'
+require 'kiosk/redteam/scenarios/unpaid_gated_action'
+require 'kiosk/redteam/scenarios/missing_kyc'
+require 'kiosk/redteam/scenarios/expired_kyc'
+require 'kiosk/redteam/scenarios/forged_kyc'
+require 'kiosk/redteam/scenarios/spent_resource_reuse'
+require 'kiosk/redteam/scenarios/pay_for_other_use_self'
+require 'kiosk/redteam/scenarios/wrong_currency_cart'
+
+module Kiosk
+  # Adversarial regression harness: drives hostile HTTP scenarios against a
+  # Kiosk origin and asserts each attack is refused.
+  module Redteam
+    # 402 is absent: see PAYMENT_REQUIRED_CODES.
+    BLOCKED_STATUSES = [401, 403].freeze
+
+    # The three codes kiosk-server maps onto HTTP 402, each with why it is not a refusal.
+    PAYMENT_REQUIRED_CODES = {
+      'pow_required' =>
+        'a toll was DEMANDED, not a refusal — the request was deferred until a proof is ' \
+        'supplied. This harness PAYS that toll on every verb, so seeing this code here ' \
+        'means the demand survived a paid retry (or arrived with no challenges to ' \
+        'solve); either way the attack itself was never evaluated',
+      'payment_setup_required' =>
+        "the principal has no payment instrument on file — a gap in the ATTACKER's setup, " \
+        'not a decision about the attack',
+      'payment_failed' =>
+        'the payment rail declined the charge AFTER the mandate trail verified — every ' \
+        'authorization gate the request passed through said yes; a declined card is not a gate'
+    }.freeze
+
+    # The 402 codes kiosk-server answers before it evaluates the request.
+    UNEVALUATED_CODES = %w[pow_required payment_setup_required].freeze
+
+    # A validation error (bad_request) is not evidence of an authorization gate.
+    BLOCKED_ERROR_CODES = %w[forbidden unauthenticated rls_denied].freeze
+
+    # A successful query answers a bare Array, so the body may not be a Hash.
+    def self.error_code(response)
+      body = response.body
+      return nil unless body.is_a?(Hash)
+
+      body['code']
+    end
+
+    # Why a payment-required answer cannot settle a verdict, or nil when it is not one.
+    def self.payment_required_reason(response)
+      code = error_code(response)
+      return nil unless response.status == 402 || PAYMENT_REQUIRED_CODES.key?(code)
+
+      why = PAYMENT_REQUIRED_CODES[code] ||
+            "kiosk-server maps three codes onto 402 — #{PAYMENT_REQUIRED_CODES.keys.join(', ')} — " \
+            'and this answer named none of them, so which gate fired (if any did) is unknowable'
+      "HTTP #{response.status} code=#{code.inspect}:#{paid_retry_note(response)} #{why}"
+    end
+
+    def self.paid_retry_note(response)
+      return '' unless response.pow_retried?
+
+      ' [the harness already solved every issued challenge and re-sent the identical request once]'
+    end
+
+    # True when the origin answered before it evaluated the request: a toll it
+    # demands, or a payment refused before the mandates are read.
+    def self.unevaluated?(response) = UNEVALUATED_CODES.include?(error_code(response))
+
+    def self.blocked?(response)
+      # Status first: a crash whose body carries `forbidden` is not a block. 0 is a connection error.
+      return false if response.status >= 500 || response.status.zero?
+      return false if payment_required_reason(response)
+      return true if BLOCKED_STATUSES.include?(response.status)
+
+      BLOCKED_ERROR_CODES.include?(error_code(response))
+    end
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: kiosk-redteam
+version: !ruby/object:Gem::Version
+  version: 0.5.20
+platform: ruby
+authors:
+- Phil Pirozhkov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: kiosk-test-support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+description: |
+  kiosk-redteam drives hostile HTTP scenarios against any Kiosk provider
+  and asserts each attack is correctly blocked — a deliberate refusal, never
+  a crash and never a toll the harness could not settle.  A scenario that
+  finds a real breach fails loudly.
+
+  Ships a Scenario/Verdict/Runner framework and a library of generic attack
+  scenarios parameterised by a per-provider Profile. It attacks through the
+  assistant client kiosk-test-support ships.
+
+  No dependency on Rails.
+email:
+- hello@fili.pp.ru
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/kiosk/redteam.rb
+- lib/kiosk/redteam/battery.rb
+- lib/kiosk/redteam/leak_scan.rb
+- lib/kiosk/redteam/profile.rb
+- lib/kiosk/redteam/runner.rb
+- lib/kiosk/redteam/scenario.rb
+- lib/kiosk/redteam/scenarios/cross_tenant_read.rb
+- lib/kiosk/redteam/scenarios/device_grant_role_self_selection.rb
+- lib/kiosk/redteam/scenarios/expired_kyc.rb
+- lib/kiosk/redteam/scenarios/forged_kyc.rb
+- lib/kiosk/redteam/scenarios/forged_user_id.rb
+- lib/kiosk/redteam/scenarios/kyc_attack.rb
+- lib/kiosk/redteam/scenarios/mandate_principal_swap.rb
+- lib/kiosk/redteam/scenarios/mandate_replay.rb
+- lib/kiosk/redteam/scenarios/missing_kyc.rb
+- lib/kiosk/redteam/scenarios/pay_for_other_use_self.rb
+- lib/kiosk/redteam/scenarios/privilege_self_selection.rb
+- lib/kiosk/redteam/scenarios/registration_without_pow.rb
+- lib/kiosk/redteam/scenarios/spent_resource_reuse.rb
+- lib/kiosk/redteam/scenarios/token_tampering.rb
+- lib/kiosk/redteam/scenarios/unpaid_gated_action.rb
+- lib/kiosk/redteam/scenarios/wrong_currency_cart.rb
+- lib/kiosk/redteam/staging.rb
+- lib/kiosk/redteam/token_claims.rb
+- lib/kiosk/redteam/verdict.rb
+- lib/kiosk/redteam/verdicts.rb
+- lib/kiosk/redteam/version.rb
+homepage: https://kiosk.tech
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://kiosk.tech
+  source_code_uri: https://github.com/kiosk-hq/kiosk
+  changelog_uri: https://github.com/kiosk-hq/kiosk/blob/main/kiosk-redteam/CHANGELOG.md
+  bug_tracker_uri: https://github.com/kiosk-hq/kiosk/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Adversarial regression harness for Kiosk providers
+test_files: []