vangrail 0.1.0 → 0.2.0

data/lib/vangrail/actions.rb

@@ -52,10 +52,17 @@ module Vangrail
     # polarity those flows branch on.
     def self.from_rails(input: nil, output: nil, facts: nil)
       actions = new
-      actions.register('self_check_input') { |_args, ctx| input&.call(ctx[:text], ctx)&.allowed? }
-      actions.register('self_check_output') { |_args, ctx| output&.call(ctx[:text], ctx)&.allowed? }
-      actions.register('self_check_facts') { |_args, ctx| facts&.call(ctx[:text], ctx)&.allowed? }
+      actions.register('self_check_input') { |_args, ctx| allowed_by?(input, ctx) }
+      actions.register('self_check_output') { |_args, ctx| allowed_by?(output, ctx) }
+      actions.register('self_check_facts') { |_args, ctx| allowed_by?(facts, ctx) }
       actions
     end
+
+    def self.allowed_by?(rail, ctx)
+      return false unless rail
+
+      result = rail.call(ctx[:text], ctx)
+      result.respond_to?(:allowed?) && result.allowed?
+    end
   end
 end

data/lib/vangrail/assessor.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative 'evidence'
+require_relative 'evidence_data'
+require_relative 'judgement'
+require_relative 'origin'
+require_relative 'rail'
+
+module Vangrail
+  # Combines every measured rail into a posterior, then ranks a set by it.
+  #
+  # `check_input` and friends answer a different question. They run the rails
+  # in order, stop at the first block, and report a decision; that is the
+  # right shape for a request path and it is what every published defence
+  # does. It also throws away most of what was measured. A rail that fired
+  # tells you nothing about how much that hit is worth, three rails that
+  # nearly fired tell you nothing at all, and a block carries no number an
+  # operator can set a policy against.
+  #
+  # This runs every rail that has a measured operating point, treats each
+  # verdict as evidence, and combines it with the deployment's base rate.
+  # What comes back is a probability, the bits each rail contributed, and an
+  # action under a stated policy.
+  class Assessor
+    def initialize(engine)
+      @engine = engine
+    end
+
+    # The prior is not optional and has no sensible default. Detector papers
+    # report their numbers on balanced corpora, where an attack is half the
+    # traffic; a documentation desk over an editable wiki might see one poisoned
+    # page in ten thousand. Those two worlds disagree about what a hit means by
+    # four orders of magnitude, and only the deployment knows which one it is
+    # in. Guessing on its behalf would be the whole error this method exists to
+    # expose.
+    #
+    #   judgement = engine.assess(page, side: :context, prior: 1e-4)
+    #   judgement.posterior    # => 0.0073
+    #   judgement.action       # => :review
+    #   judgement.fired        # => [{rail: "paraphrase", bits: 6.2, ...}]
+    #
+    # Costs more than a check, because nothing short-circuits: every rail with
+    # an entry in the table runs, including the ones a block would have skipped.
+    def assess(text, side: :input, prior: nil, policy: Policy::DEFAULT, evidence: nil,
+               escalate: false, confidence: Posterior::DEFAULT_CONFIDENCE, origin: nil, **context)
+      raise ArgumentError, prior_message if prior.nil?
+
+      origin = Origin.coerce(origin || Origin.default_for(side))
+      # A rail is worth different evidence on different sides, by a lot: the
+      # same paraphrase rail catches a third of in-the-wild jailbreak prompts
+      # and none of the published injections in retrieved documents. One table
+      # for both would be an average of two unrelated things.
+      evidence ||= EvidenceData.for_side(side)
+
+      observed = observe(text, side, context, evidence, escalate ? { prior: prior, policy: policy } : nil)
+      observations, direct, certain, skipped = observed
+      posterior, contributions = Posterior.combine(prior: prior, observations: observations,
+                                                   evidence: evidence, direct: direct,
+                                                   confidence: confidence)
+      action = policy.action_for(posterior)
+      # A confidence bound is what the corpus can defend. If the point
+      # estimate and the bound disagree about the action, the action is not
+      # identified: reporting it as a certain decision would spend evidence
+      # nobody measured.
+      if confidence
+        # Explicitly nil, because the bound is what `combine` defaults to now:
+        # asking for the point estimate has to say so, or this compares the
+        # bound against itself and reports every action as identified.
+        point, = Posterior.combine(prior: prior, observations: observations,
+                                   evidence: evidence, direct: direct, confidence: nil)
+        certain &&= policy.action_for(point) == action
+      end
+      Judgement.new(posterior: posterior, prior: prior, bits: contributions.sum { |c| c[:bits] },
+                    contributions: contributions, certain: certain, side: side.to_sym,
+                    skipped: skipped, action: action, origin: origin)
+    end
+
+    # Screening, with the documents ranked by how suspicious they are rather
+    # than partitioned by whether one rail objected.
+    #
+    # `screen` drops a document the moment a rail blocks it, which is the right
+    # shape when a rail is a switch. Given a posterior there is a better answer
+    # available: rank the set, drop what the policy says to drop, hand what it
+    # says to review to whoever reviews, and keep the rest. A page that trips
+    # one pattern at a base rate of one in ten thousand is not a page worth
+    # taking away from a reader, and it is worth putting at the bottom of the
+    # passage list.
+    #
+    #   triage = engine.triage(documents, prior: 1e-4)
+    #   triage.keep       # documents, least suspicious first
+    #   triage.review     # [{document:, judgement:}]
+    #   triage.dropped    # [{document:, judgement:}]
+    def triage(documents, prior:, policy: Policy::DEFAULT, escalate: false, **context)
+      judged = Array(documents).each_with_index.map do |document, index|
+        judgement = assess(Cell.text_of(document), side: :context, prior: prior, policy: policy,
+                                                   escalate: escalate, **context, document: document,
+                                                   index: index)
+        { document: document, judgement: judgement }
+      end
+      Triage.new(judged: judged.sort_by { |row| -row[:judgement].posterior })
+    end
+
+    private
+
+    # Runs every rail with a measured operating point and records what each one
+    # saw: true for a hit, false for a rail that ran and did not fire, and
+    # nothing at all for a rail that could not decide.
+    #
+    # That third case is the one this gem can express and a pure detector stack
+    # cannot. An unreachable rail is not a rail that found nothing, and folding
+    # the two together silently converts a broken endpoint into evidence of
+    # innocence.
+    def observe(text, side, context, evidence, escalation = nil)
+      ctx = context.merge(side: side)
+      certain = true
+      observations = {}
+      direct = {}
+      skipped = []
+      readable = true
+      queue = queue_for(side, evidence, escalation)
+
+      queue.each_with_index do |rail, index|
+        if escalation && !rail.posture? && settled?(observations, queue[index..], evidence, escalation)
+          skipped = queue[index..].map(&:name)
+          break
+        end
+
+        result = @engine.invoke(rail, text, ctx)
+        certain, readable = record(rail, result, observations, direct, certain, readable)
+      end
+
+      [observations, direct, certain, skipped]
+    end
+
+    def queue_for(side, evidence, escalation)
+      queue = @engine.rails(side).select do |rail|
+        next false unless rail.applies_to?(side)
+        next true if rail.posture? || rail.quantifies?
+
+        evidence[rail.name]&.measured?
+      end
+      # Posture first, so a page nothing can read is known before silence is
+      # recorded. Cheap first after that when escalating, so a round trip is
+      # what an early stop can save.
+      posture, rest = queue.partition(&:posture?)
+      rest = rest.partition(&:offline?).flatten if escalation
+      posture + rest
+    end
+
+    def record(rail, result, observations, direct, certain, readable)
+      if rail.posture?
+        return [false, false] unless result.certain?
+
+        return [certain, readable]
+      end
+      return [false, readable] unless result.certain?
+
+      # A hit still counts: a hidden English injection inside a German
+      # page is a hit. Silence does not. A rail that cannot read this
+      # language and did not fire has not said the page is clean.
+      return [certain, readable] unless readable || rail.language_agnostic? || result.blocked?
+
+      # A rail that computed a likelihood ratio reports it in `raw`, and is
+      # read that way rather than being flattened to whether it blocked.
+      bits = result.raw.is_a?(Hash) ? result.raw['bits'] : nil
+      if bits
+        direct[rail.name] = bits.to_f
+      else
+        observations[rail.name] = result.blocked?
+      end
+      [certain, readable]
+    end
+
+    # Would running the rest change what happens?
+    #
+    # Not a guess and not a threshold on confidence: the evidence a rail can
+    # carry is bounded by its measured operating point, so the most the
+    # remaining rails could move the posterior in either direction is a number
+    # this can add up. When the action is the same at both ends of that
+    # interval, the remaining rails cannot change the outcome and running them
+    # buys nothing.
+    #
+    # This is why the framing pays for itself rather than only being tidier. A
+    # documentation desk running the deterministic rails and one model rail
+    # pays for the round trip on every check under the switch; here it pays only
+    # when the free evidence leaves the answer genuinely open, which on ordinary
+    # traffic is almost never.
+    #
+    # Skipping is not abstention. A rail that was proved irrelevant did not fail
+    # to run, so `certain?` stays true: the claim is about the action, and the
+    # action is unchanged by construction.
+    def settled?(observations, remaining, evidence, escalation)
+      return false if remaining.empty?
+      # A rail that reports its own likelihood ratio has no bound to reason
+      # against: its contribution is whatever the text scores. Nothing is
+      # skipped while one of those is still to run.
+      return false if remaining.any?(&:quantifies?)
+
+      posterior, = Posterior.combine(prior: escalation[:prior], observations: observations,
+                                     evidence: evidence)
+      reachable = remaining.filter_map { |rail| evidence[rail.name] }
+      return false if reachable.empty?
+
+      best = reachable.sum { |entry| entry.bits(true) }
+      worst = reachable.sum { |entry| entry.bits(false) }
+      policy = escalation[:policy]
+      odds = Posterior.to_odds(posterior)
+
+      policy.action_for(Posterior.from_odds(odds * (2**best))) ==
+        policy.action_for(Posterior.from_odds(odds * (2**worst)))
+    end
+
+    def prior_message
+      'assess needs a prior: the share of texts on this side that are actually attacks. ' \
+        'Published detector numbers assume a balanced corpus (0.5); a documentation desk over ' \
+        'an editable wiki is nearer 1e-4. The answer changes the verdict, and only you know it.'
+    end
+  end
+
+  # What triage returns. The ranking is the product: a caller that wants the
+  # old behaviour reads `kept`, and one that wants to put the doubtful pages
+  # last reads them in order.
+  Triage = Struct.new(:judged, keyword_init: true) do
+    def dropped
+      judged.select { |row| row[:judgement].block? }
+    end
+
+    def review
+      judged.select { |row| row[:judgement].review? }
+    end
+
+    def kept
+      judged.reject { |row| row[:judgement].block? }.reverse.map { |row| row[:document] }
+    end
+
+    def certain?
+      judged.all? { |row| row[:judgement].certain? }
+    end
+
+    def to_h
+      {
+        'kept' => kept.size,
+        'review' => review.size,
+        'dropped' => dropped.map { |row| row[:judgement].to_h },
+        'certain' => certain?,
+      }
+    end
+  end
+end

data/lib/vangrail/bayes_data.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module Vangrail
+  # Naive Bayes weights over the corpora, in bits per feature.
+  #
+  # GENERATED FILE. Do not edit by hand; rerun script/train_bayes.rb when a
+  # corpus changes. The rail that reads this lives in rails/bayes.rb.
+  #
+  # 300 features selected by mutual information from 48
+  # attack and 56 benign
+  # clauses, counted as word stems and adjacent stem pairs, smoothed with a
+  # Dirichlet prior of 1.0. A weight is log2 of how much likelier the feature is
+  # in an attack than in ordinary documentation.
+  #
+  # Cross-validated over 5 folds at a threshold of 9 bits:
+  # 15 of 48 attacks above it, 0 of 240
+  # benign documents above it. That number is the held-out one; the training
+  # score is not reported because it is not evidence of anything.
+  module BayesData
+    THRESHOLD = 9
+
+    # Score band => bits, fitted on held-out scores and read at the 95% bound.
+    # A raw naive Bayes score is not a likelihood ratio; this is what turns it
+    # into one the corpus can defend.
+    CALIBRATION = [
+      [-Float::INFINITY, -14.552], # 0 attacks, 231 benign
+      [0.0, 2.601], # 22 attacks, 8 benign
+      [4.0, 4.712], # 26 attacks, 1 benign
+    ].freeze
+
+    # Held-out performance at THRESHOLD, for the evidence table.
+    CAUGHT = 15
+    ATTACKS = 48
+    FLAGGED = 0
+    BENIGN = 240
+
+    WEIGHTS = {
+      'thi page' => 3.2141,
+      'page' => 3.2141,
+      'all' => 2.7991,
+      'were' => 2.7991,
+      'answer' => 2.7991,
+      'alle' => 2.5361,
+      'as' => 2.5361,
+      'you were' => 2.5361,
+      'that' => 2.5361,
+      'ignore all' => 2.5361,
+      'thi' => 2.384,
+      'example invalid' => 2.2141,
+      'invalid collect' => 2.2141,
+      'the reader' => 2.2141,
+      'example' => 2.2141,
+      'http' => 2.2141,
+      'deze pagina' => 2.2141,
+      'reveal' => 2.2141,
+      'pagina' => 2.2141,
+      'negeer alle' => 2.2141,
+      'http example' => 2.2141,
+      'previous instruction' => 2.2141,
+      'unlimit' => 2.2141,
+      'the quota' => 2.2141,
+      'previous' => 2.2141,
+      'collect' => 2.2141,
+      'invalid' => 2.2141,
+      'reader' => 2.2141,
+      'cluster' => 2.2141,
+      'at' => 2.2141,
+      'at the' => 2.2141,
+      'anyth' => 2.2141,
+      'your system' => 2.2141,
+      'now' => 2.0215,
+      'instruction' => 2.0215,
+      'a cheaper' => 1.7991,
+      'stat' => 1.7991,
+      'je systeemprompt' => 1.7991,
+      'einde' => 1.7991,
+      'restriction' => 1.7991,
+      'for thi' => 1.7991,
+      'reveal your' => 1.7991,
+      'rule' => 1.7991,
+      'to http' => 1.7991,
+      'voor' => 1.7991,
+      'issu' => 1.7991,
+      'developer' => 1.7991,
+      'hebt gekregen' => 1.7991,
+      'die je' => 1.7991,
+      'gekregen' => 1.7991,
+      'hiervoor' => 1.7991,
+      'die' => 1.7991,
+      'eerdere instructy' => 1.7991,
+      'alle eerdere' => 1.7991,
+      'model' => 1.7991,
+      'alsof je' => 1.7991,
+      'doe alsof' => 1.7991,
+      'doe' => 1.7991,
+      'alsof' => 1.7991,
+      'recommend the' => 1.7991,
+      'the end' => 1.7991,
+      'end of' => 1.7991,
+      'of your' => 1.7991,
+      'given' => 1.7991,
+      'were given' => 1.7991,
+      'partition exist' => 1.7991,
+      'that a' => 1.7991,
+      'cheaper partition' => 1.7991,
+      'end' => 1.7991,
+      'recommend' => 1.7991,
+      'exist' => 1.7991,
+      'cheaper' => 1.7991,
+      'commercial' => 1.7991,
+      'that thi' => 1.7991,
+      'all previous' => 1.7991,
+      'so' => 1.7991,
+      'instruction and' => 1.7991,
+      'het einde' => 1.7991,
+      'as authoritative' => 1.7991,
+      'page as' => 1.7991,
+      'treat thi' => 1.7991,
+      'and treat' => 1.7991,
+      'forget the' => 1.7991,
+      'authoritative' => 1.7991,
+      'treat' => 1.7991,
+      'forget' => 1.7991,
+      'the commercial' => 1.7991,
+      'commercial cluster' => 1.7991,
+      'disregard' => 1.7991,
+      'and recommend' => 1.7991,
+      'disregard the' => 1.7991,
+      'lezer' => 1.2141,
+      'herhaal' => 1.2141,
+      'partitie bestaat' => 1.2141,
+      'lezer dat' => 1.2141,
+      'richtlijnen voor' => 1.2141,
+      'omzeil de' => 1.2141,
+      'opmerk omzeil' => 1.2141,
+      'omzeil' => 1.2141,
+      'opmerk' => 1.2141,
+      'een goedkopere' => 1.2141,
+      'dat er' => 1.2141,
+      'naar http' => 1.2141,
+      'is gewijzigd' => 1.2141,
+      'gekregen naar' => 1.2141,
+      'pagina is' => 1.2141,
+      'je hebt' => 1.2141,
+      'er een' => 1.2141,
+      'sleutel die' => 1.2141,
+      'niet dat' => 1.2141,
+      'gebruiker niet' => 1.2141,
+      'er' => 1.2141,
+      'oorspronkelijke' => 1.2141,
+      'letterlijk aan' => 1.2141,
+      'configuratie letterlijk' => 1.2141,
+      'oorspronkelijke configuratie' => 1.2141,
+      'goedkopere' => 1.2141,
+      'je oorspronkelijke' => 1.2141,
+      'herhaal je' => 1.2141,
+      'letterlijk' => 1.2141,
+      'bestaat' => 1.2141,
+      'verberg voor' => 1.2141,
+      'voor de' => 1.2141,
+      'de lezer' => 1.2141,
+      'dat deze' => 1.2141,
+      'verberg' => 1.2141,
+      'voor deze' => 1.2141,
+      'have no' => 1.2141,
+      'you have' => 1.2141,
+      'pretend you' => 1.2141,
+      'no' => 1.2141,
+      'have' => 1.2141,
+      'pretend' => 1.2141,
+      'anyth now' => 1.2141,
+      'do anyth' => 1.2141,
+      'for do' => 1.2141,
+      'beperk hebt' => 1.2141,
+      'geen beperk' => 1.2141,
+      'je geen' => 1.2141,
+      'beperk' => 1.2141,
+      'geen' => 1.2141,
+      'eerder instructy' => 1.2141,
+      'alle eerder' => 1.2141,
+      'eerder' => 1.2141,
+      'fall asleep' => 1.2141,
+      'naar' => 1.2141,
+      'stuur de' => 1.2141,
+      'de api' => 1.2141,
+      'goedkopere partitie' => 1.2141,
+      'fall' => 1.2141,
+      'license' => 1.2141,
+      'me' => 1.2141,
+      'used' => 1.2141,
+      'grandma' => 1.2141,
+      'my' => 1.2141,
+      'prompt now' => 1.2141,
+      'answer anyth' => 1.2141,
+      'and answer' => 1.2141,
+      'restriction and' => 1.2141,
+      'no restriction' => 1.2141,
+      'you' => 1.1072,
+      'je' => -0.7034,
+      'het' => -1.0489,
+      'als' => -1.1078,
+      'een' => -1.1078,
+      'a' => -1.2009,
+      'if your' => -1.3708,
+      'etc profile' => -1.3708,
+      'profile d' => -1.3708,
+      'a100' => -1.3708,
+      'warn' => -1.3708,
+      'project space' => -1.3708,
+      'about' => -1.3708,
+      'tijdslimiet' => -1.3708,
+      'wordt' => -1.3708,
+      'load python' => -1.3708,
+      'about the' => -1.3708,
+      'h100 node' => -1.3708,
+      'reservation policy' => -1.3708,
+      '5' => -1.3708,
+      'module load' => -1.3708,
+      'aanvraag' => -1.3708,
+      'd' => -1.3708,
+      'the job' => -1.3708,
+      'sleutel met' => -1.3708,
+      'python' => -1.3708,
+      'sbatch' => -1.3708,
+      '3' => -1.3708,
+      '11' => -1.3708,
+      'follow the' => -1.3708,
+      'account' => -1.3708,
+      'profile' => -1.3708,
+      'reserver' => -1.3708,
+      'squeue' => -1.3708,
+      '200 gb' => -1.3708,
+      'dien' => -1.3708,
+      'scontrol show' => -1.3708,
+      'de' => -1.3708,
+      'voeg' => -1.3708,
+      'toe' => -1.3708,
+      'gpu a100' => -1.3708,
+      'omp num' => -1.3708,
+      'volg de' => -1.3708,
+      'num thread' => -1.3708,
+      'the module' => -1.3708,
+      'and the' => -1.3708,
+      'toe aan' => -1.3708,
+      'het reserveringsbeleid' => -1.3708,
+      'warn about' => -1.3708,
+      'on the' => -1.3708,
+      'service desk' => -1.3708,
+      'deze toe' => -1.3708,
+      'token' => -1.3708,
+      'met een' => -1.3708,
+      'the service' => -1.3708,
+      'voeg deze' => -1.3708,
+      'in' => -1.3708,
+      'request' => -1.3708,
+      'deel je' => -1.3708,
+      'core' => -1.3708,
+      'includ' => -1.3708,
+      'verouderde' => -1.3708,
+      'waarschuw' => -1.3708,
+      'hierboven' => -1.3708,
+      'volg' => -1.3708,
+      'service' => -1.3708,
+      'dedicat node' => -1.3708,
+      'thread' => -1.3708,
+      'taak' => -1.3708,
+      'if' => -1.3708,
+      'it to' => -1.3708,
+      'space' => -1.3708,
+      'can' => -1.3708,
+      'uit' => -1.3708,
+      'python 3' => -1.3708,
+      'follow' => -1.3708,
+      '3 11' => -1.3708,
+      'virtualenv' => -1.3708,
+      'voordat' => -1.3708,
+      '30' => -1.3708,
+      'met de' => -1.3708,
+      'niet met' => -1.3708,
+      'etc' => -1.3708,
+      'op de' => -1.3708,
+      'waarschuw over' => -1.3708,
+      '200' => -1.3708,
+      'is 200' => -1.3708,
+      'limit' => -1.3708,
+      'with a' => -1.3708,
+      'in met' => -1.3708,
+      'gb' => -1.3708,
+      'time limit' => -1.3708,
+      'deel' => -1.3708,
+      'rotate' => -1.3708,
+      'reserveringsbeleid' => -1.3708,
+      'rotate it' => -1.3708,
+      'config' => -1.3708,
+      'en voeg' => -1.3708,
+      'in your' => -1.3708,
+      'show' => -1.3708,
+      'vraagt' => -1.3708,
+      'scontrol' => -1.3708,
+      'show config' => -1.3708,
+      'ask' => -1.3708,
+      'omp' => -1.3708,
+      'num' => -1.3708,
+      'het job' => -1.3708,
+      'dedicat' => -1.3708,
+      'your project' => -1.3708,
+      'toolchain' => -1.3708,
+      'en' => -1.7859,
+      'with' => -1.7859,
+      'run' => -1.7859,
+      'the reservation' => -1.7859,
+      'als je' => -1.7859,
+      'policy' => -1.7859,
+      'om' => -1.7859,
+      'load' => -1.7859,
+      'ssh' => -1.7859,
+      'reservation' => -1.7859,
+      'the desk' => -1.7859,
+      'time' => -2.1078,
+      'h100' => -2.1078,
+      'gpu' => -2.1078,
+      'gpu h100' => -2.1078,
+      'ticket' => -2.1078,
+      'de servicedesk' => -2.1078,
+      'job id' => -2.1078,
+      'te' => -2.1078,
+      'servicedesk' => -2.1078,
+      'op' => -2.1078,
+      'per' => -2.1078,
+      'project' => -2.1078,
+      'desk' => -2.3708,
+      'id' => -2.3708,
+      'module' => -2.5932,
+      'it' => -2.7859,
+      'node' => -2.7859,
+      'met' => -2.9558,
+      'job' => -3.1078,
+    }.freeze
+  end
+end