vangrail 0.1.0 → 0.2.0

data/lib/vangrail/rails/guard_model.rb

@@ -44,6 +44,10 @@ module Vangrail
         @chat = chat || build_chat(provider, max_tokens, chat_options)
       end
 
+      def offline?
+        false
+      end
+
       # The verdict depends on the text and, on the output side, on the user
       # turn sent with it.
       def cache_key(text, context)
@@ -52,13 +56,12 @@ module Vangrail
         "#{context[:user_input]} #{text}"
       end
 
-      def call(text, context)
+      def decide(text, context)
         answer = chat.ask(messages_for(text, context))
         parsed = preset == :apriel_guard ? Parsers.apriel_guard(answer.text) : Parsers.llama_guard(answer.text)
         unless parsed[:decided]
-          return Result.new(status: :passed, rail: name, certain: false, model: model,
-                            latency_ms: answer.latency_ms, raw: answer.raw,
-                            reason: "unparsed guard response: #{parsed[:reason]}")
+          return unchecked("unparsed guard response: #{parsed[:reason]}",
+                           model: model, latency_ms: answer.latency_ms, raw: answer.raw)
         end
 
         return pass(model: model, latency_ms: answer.latency_ms, raw: answer.raw) unless parsed[:violated]

data/lib/vangrail/rails/hidden.rb

@@ -25,7 +25,8 @@ module Vangrail
     # found rather than what it says. A hidden span with ordinary content in it
     # passes: pages carry meta descriptions and alt text for good reasons, and
     # a rail that objected to invisible text as such would reject most of the
-    # web.
+    # web. A child that rewrites a span (a key in a comment) replaces that
+    # span inside the page. The rest of the page is still the page.
     #
     # Only useful where documents arrive as HTML. A retrieval step that
     # converts to markdown before storing has usually dropped most of these
@@ -57,7 +58,7 @@ module Vangrail
         'hidden_attribute' => /<(\w+)\b[^>]*\bhidden\b[^>]*>(.*?)<\/\1>/mi,
         # Markdown carries two of its own: a link title, and image alt text.
         'link_title' => /\[[^\]]*\]\([^)\s]+\s+["']([^"']{12,})["']\)/,
-        'image_alt' => /!\[([^\]]{12,})\]\(/
+        'image_alt' => /!\[([^\]]{12,})\]\(/,
       }.freeze
 
       attr_reader :rails, :carriers
@@ -76,16 +77,46 @@ module Vangrail
         text if offline?
       end
 
-      def call(text, context)
-        spans(text).each do |carrier, span|
-          rails.each do |rail|
-            result = rail.call(span, context)
-            next unless result.blocked?
+      def decide(text, context)
+        rewritten = text.to_s
+        modified = nil
+        uncertain = nil
 
-            return block(categories: (result.categories || []) + ["hidden:#{carrier}"],
-                         reason: "#{result.reason} (hidden in #{carrier.tr('_', ' ')})")
+        blocked = catch(:blocked) do
+          carriers.each do |carrier, pattern|
+            rewritten = rewritten.gsub(pattern) do |full|
+              span = captured_span(Regexp.last_match)
+              next full if span.empty?
+
+              current = span
+              rails.each do |rail|
+                result = rail.call(current, context)
+                extra = ["hidden:#{carrier}"]
+                if result.blocked?
+                  throw :blocked, wrapped_block(result, extra, carrier)
+                end
+
+                if result.modified?
+                  current = result.content.to_s
+                  modified = [result, extra, carrier]
+                elsif !result.certain?
+                  uncertain ||= result
+                end
+              end
+              current == span ? full : full.sub(span) { current }
+            end
           end
+          nil
         end
+        return blocked if blocked
+
+        if modified
+          result, extra, carrier = modified
+          return modify(rewritten, categories: (result.categories || []) + extra,
+                        reason: "#{result.reason} (hidden in #{carrier.tr('_', ' ')})")
+        end
+        return unchecked(uncertain.reason) if uncertain
+
         pass
       end
 
@@ -100,6 +131,18 @@ module Vangrail
           end
         end
       end
+
+      private
+
+      def captured_span(match)
+        captures = match.captures.compact
+        (captures.max_by(&:length) || match[0]).to_s.strip
+      end
+
+      def wrapped_block(result, extra, carrier)
+        block(categories: (result.categories || []) + extra,
+              reason: "#{result.reason} (hidden in #{carrier.tr('_', ' ')})")
+      end
     end
   end
 end

data/lib/vangrail/rails/injected_instructions.rb

@@ -25,10 +25,33 @@ module Vangrail
     class InjectedInstructions < Rail
       PATTERNS = {
         # A chat role header inside a document: nothing in prose needs one.
-        'role_header' => /^\s{0,3}(?:###\s*)?(?:system|assistant|user)\s*:\s*\S/i,
+        # The Dutch role names sit beside the English ones because a role
+        # header is a shape rather than a sentence, and a page that writes
+        # "assistent:" mid-paragraph is doing what "assistant:" does.
+        'role_header' => /^\s{0,3}(?:###\s*)?(?:system|systeem|assistant|assistent|user|gebruiker)\s*:\s*\S/i,
         # An override aimed at whatever came before it in the prompt.
-        'override_above' => /\b(?:ignore|disregard|forget|override)\b[^.\n]{0,40}\b
-                             (?:above|previous|prior|earlier|preceding|system\s+prompt|instructions?)\b/xi,
+        #
+        # Three branches rather than one alternation, because a backward
+        # reference on its own is not an attack. "You can ignore the earlier
+        # warning about the toolchain" is a page, and it fell to the single
+        # alternation: the override has to name what it cancels, cancel the lot,
+        # or use the reference as a noun.
+        'override_above' => /
+          \b(?:ignore|disregard|forget|override)\b
+          (?:
+            # Names the standing instruction, in any of its usual words.
+            [^.\n]{0,40}\b(?:instructions?|guidelines?|rules?|directions?|directives?|
+                             system\s+prompt|everything\s+above)\b
+            |
+            # Cancels all of it, which is what an attacker does when they do
+            # not know what they are cancelling.
+            \s+(?:all|any|every|everything|anything)\b[^.\n]{0,20}
+              \b(?:above|previous|prior|earlier|preceding)\b
+            |
+            # The reference used as a noun and nothing after it.
+            \s+(?:the\s+)?(?:above|preceding|foregoing)\s*[.,;:]?\s*$
+          )
+        /xi,
         # A document telling the assistant what it is now.
         'role_assignment' => /\byou\s+(?:are|must\s+now\s+act|will\s+now\s+act)\s+(?:now\s+)?
                               (?:a|an|the)?\s*(?:assistant|ai|model|chatbot|dan)\b/xi,
@@ -56,7 +79,8 @@ module Vangrail
                            (?:system\s+prompt|api[_\s-]?key|token|credentials?|conversation)\b/xi,
         # Hidden text: a marker for content meant for the model and not the
         # reader. HTML comments in a rendered page are the common carrier.
-        'hidden_directive' => /<!--[^>]*\b(?:ignore|instruction|assistant|system|prompt)\b[^>]*-->/im
+        'hidden_directive' => /<!--[^>]*\b(?:ignore|instruction|assistant|system|prompt|
+                                             negeer|instructie|assistent|systeem)\b[^>]*-->/imx,
       }.freeze
 
       attr_reader :patterns
@@ -66,15 +90,11 @@ module Vangrail
         @patterns = patterns
       end
 
-      def offline?
-        true
-      end
-
       def cache_key(text, _context)
         text
       end
 
-      def call(text, _context)
+      def decide(text, _context)
         body = text.to_s
         hits = patterns.select { |_label, pattern| pattern.match?(body) }.keys
         return pass if hits.empty?

data/lib/vangrail/rails/jailbreak.rb

@@ -85,7 +85,7 @@ module Vangrail
           |
           \bthis\s+is\s+(?:the\s+)?[a-z][\w.-]*(?:\s+(?:ai|inc|labs?))?\b[^.\n]{0,30}
           \byou\s+are\s+now\s+(?:permitted|allowed|required|authori[sz]ed)\b
-        /xi
+        /xi,
       }.freeze
 
       attr_reader :patterns
@@ -95,15 +95,11 @@ module Vangrail
         @patterns = patterns
       end
 
-      def offline?
-        true
-      end
-
       def cache_key(text, _context)
         text
       end
 
-      def call(text, _context)
+      def decide(text, _context)
         hits = patterns.select { |_label, pattern| pattern.match?(text.to_s) }.keys
         return pass if hits.empty?
 

data/lib/vangrail/rails/known_answer.rb

@@ -76,13 +76,17 @@ module Vangrail
         end
       end
 
+      def offline?
+        false
+      end
+
       # Never memoizable in the useful sense: the token changes per check, and
       # a cached verdict would be a verdict about a different question.
       def cache_key(_text, _context)
         nil
       end
 
-      def call(text, _context)
+      def decide(text, _context)
         body = text.to_s
         return pass if body.strip.empty?
 
@@ -101,7 +105,7 @@ module Vangrail
       def ask(token, body)
         chat.ask([
                    { 'role' => 'system', 'content' => format(INSTRUCTION, token: token) },
-                   { 'role' => 'user', 'content' => "<<<DOCUMENT\n#{body}\nDOCUMENT>>>" }
+                   { 'role' => 'user', 'content' => "<<<DOCUMENT\n#{body}\nDOCUMENT>>>" },
                  ])
       end
 

data/lib/vangrail/rails/language.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative '../nlp'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Reports that a page or a question is in a language nothing here can read.
+    #
+    # Every other deterministic rail in this gem is a rule about English or
+    # Dutch words. Handed a page in German, all of them return passed, and an
+    # application reading that result cannot tell "checked and clean" from "the
+    # checks do not apply to this text". That is precisely the distinction this
+    # gem promises to keep, so the promise has to hold across languages too,
+    # and on the question as well as on the retrieved page.
+    #
+    # So this rail never blocks. A page in an unsupported language is not an
+    # attack, and refusing it would break a site that has one; what it is, is
+    # unchecked, and `certain? == false` is the word for that. An application
+    # reporting a safety posture can then route the page to a model rail, to a
+    # human, or to nothing, knowing which it is doing.
+    #
+    # Below the floor it says nothing at all. A six-word question is not
+    # evidence of a language, and marking every short turn uncertain would turn
+    # the posture into noise, which is a different way of making it useless.
+    class Language < Rail
+      def initialize(supported: NLP::LANGUAGES, floor: NLP::LANGUAGE_FLOOR,
+                     name: 'language', sides: %i[input context])
+        super(name: name, sides: sides)
+        @supported = Array(supported).map(&:to_sym)
+        @floor = floor
+      end
+
+      attr_reader :supported, :floor
+
+      def posture?
+        true
+      end
+
+      def cache_key(text, _context)
+        "#{supported.join('+')}\n#{text}"
+      end
+
+      def decide(text, _context)
+        reason = unread_reason(text)
+        return unchecked(reason) if reason
+
+        pass
+      end
+
+      private
+
+      # Clause by clause: a German paragraph inside an English page is
+      # unread even when the function words of the page as a whole are
+      # English. The twelve-token floor still applies per clause, so a
+      # short question stays quiet.
+      def unread_reason(text)
+        whole = classify(text)
+        return whole if whole
+
+        spans = NLP.clauses(text)
+        return nil if spans.size <= 1
+
+        spans.each do |span|
+          reason = classify(span)
+          return reason if reason
+        end
+        nil
+      end
+
+      def classify(span)
+        tokens = NLP.words(span)
+        return nil if tokens.size < floor
+
+        found = NLP.language(span)
+        return nil if supported.include?(found)
+        # Named unread (Cavnar-Trenkle) is evidence even in the
+        # twelve-to-twenty-three token band. An unidentified short
+        # handbook sentence is not.
+        return nil if tokens.size < (floor * 2) && !NLP.named_foreign?(span, supported)
+
+        "text is not in a language this engine reads (#{supported.join(', ')}); " \
+          'the deterministic rails do not apply to it'
+      end
+    end
+  end
+end

data/lib/vangrail/rails/linear.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative '../linear_model'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # The fitted classifier, reading a model somebody trained on their own
+    # traffic.
+    #
+    # On the corpus this repository can measure, it is the best detector here by
+    # a wide margin and within two points of a published transformer:
+    #
+    #   hand-written rails                      39.5%
+    #   naive Bayes over n-grams                67.0%
+    #   this rail                               73.7%
+    #   deberta-v3-base-prompt-injection-v2     75.3%
+    #
+    # all at the same false-alarm rate, cross-validated where fitted. Below one
+    # false alarm in a hundred it beats the transformer, 27.0% against 21.1%,
+    # which is the operating point a desk actually wants and the one a rule
+    # stack cannot be asked about at all.
+    #
+    # It ships without a model, deliberately. Weights fitted on somebody else's
+    # traffic are the thing this repository spent a long time measuring the cost
+    # of, and the numbers above are for a model fitted on the corpus it was
+    # scored against. Fit your own:
+    #
+    #   ruby script/train_linear.rb --emit model.json
+    #
+    # With no model configured the rail reports itself unchecked rather than
+    # passing, because a detector that is not there must not look like a
+    # detector that found nothing.
+    class Linear < Rail
+      def initialize(model: nil, path: nil, threshold: nil, name: 'linear', sides: %i[input context])
+        super(name: name, sides: sides)
+        @path = path
+        @model = model || load_model(path)
+        @threshold = threshold || @model&.threshold || 0.0
+      end
+
+      attr_reader :model, :threshold
+
+      def cache_key(text, _context)
+        return nil unless model
+
+        "#{threshold}\n#{text}"
+      end
+
+      def decide(text, _context)
+        return unchecked(missing_reason) unless model
+
+        value = model.score(text)
+        return pass if value <= threshold
+
+        block(categories: ['linear'],
+              reason: format('scores %<value>+.2f against a threshold of %<threshold>+.2f', value: value,
+                                                                                           threshold: threshold))
+      end
+
+      private
+
+      def load_model(path)
+        path ||= ENV.fetch('GUARDRAILS_LINEAR_MODEL', nil)
+        return nil if path.nil? || path.to_s.strip.empty?
+
+        LinearModel.load(path)
+      rescue StandardError => e
+        @load_error = "#{path}: #{e.class.name.split('::').last}: #{e.message}"
+        nil
+      end
+
+      def missing_reason
+        return "linear model could not be read (#{@load_error})" if @load_error
+
+        'no linear model configured: set GUARDRAILS_LINEAR_MODEL, or fit one with script/train_linear.rb'
+      end
+    end
+  end
+end

data/lib/vangrail/rails/many_shot.rb

@@ -43,7 +43,7 @@ module Vangrail
 
       # A role header at the start of a line, which is how a pasted transcript
       # is written when it is not using template tokens.
-      TURN = /^\s{0,3}(?:###\s*)?(?:system|user|human|assistant|ai|bot|q|a)\s*:\s*\S/i
+      TURN = /^\s{0,3}(?:###\s*)?(?:system|user|human|assistant|ai|bot|q|a|systeem|gebruiker|assistent|mens)\s*:\s*\S/i
 
       attr_reader :max_turns, :placeholder
 
@@ -53,15 +53,11 @@ module Vangrail
         @placeholder = placeholder
       end
 
-      def offline?
-        true
-      end
-
       def cache_key(text, _context)
         text
       end
 
-      def call(text, _context)
+      def decide(text, _context)
         body = text.to_s
         turns = body.scan(TURN).size
         if turns > max_turns

data/lib/vangrail/rails/markup.rb

@@ -40,7 +40,7 @@ module Vangrail
         'base_tag' => /<base\b[^>]*>/i,
         'form' => /<form\b[^>]*>.*?<\/form>|<form\b[^>]*>/mi,
         # Styling can position an invisible overlay over the page.
-        'style_block' => /<style\b[^>]*>.*?<\/style>/mi
+        'style_block' => /<style\b[^>]*>.*?<\/style>/mi,
       }.freeze
 
       attr_reader :patterns
@@ -50,7 +50,7 @@ module Vangrail
         @patterns = patterns
       end
 
-      def offline?
+      def language_agnostic?
         true
       end
 
@@ -58,7 +58,7 @@ module Vangrail
         text
       end
 
-      def call(text, _context)
+      def decide(text, _context)
         body = text.to_s
         found = []
         cleaned = patterns.reduce(body) do |acc, (label, pattern)|

data/lib/vangrail/rails/missing.rb

@@ -22,15 +22,11 @@ module Vangrail
         @reason = reason
       end
 
-      def offline?
-        true
-      end
-
       def placeholder?
         true
       end
 
-      def call(_text, _context)
+      def decide(_text, _context)
         unchecked(reason)
       end
     end

data/lib/vangrail/rails/obfuscation.rb

@@ -26,7 +26,10 @@ module Vangrail
     # original is dropped, so ordinary text costs one comparison per transform
     # and nothing else. A hit names both the rail and the encoding it was
     # hiding under, because "blocked" without that is unactionable for whoever
-    # has to look at the page.
+    # has to look at the page. A child that rewrites a variant (a key inside a
+    # decoded blob) is spliced back into the page, or into that variant when
+    # the variant *is* the page (the invisible-character strip). The decoded
+    # form is not published in place of the document.
     #
     # Invisible characters are handled here directly rather than by a delegate:
     # they are stripped, and the strip is reported as a rewrite. A zero-width
@@ -41,7 +44,12 @@ module Vangrail
       # Zero-width and bidi control characters. The first four are the invisible
       # separators; the bidi set is the trojan-source family, where the rendered
       # order and the stored order disagree.
-      INVISIBLE = /[​-‍⁠᠎‪-‮⁦-⁩]/
+      # The last one is the replacement character, which is what a scrub leaves
+      # where an invalid byte was. Garbage bytes inside a keyword are the same
+      # move as a zero-width joiner with a cruder tool: they break a pattern
+      # without changing what a model reads, and scrubbing restores validity
+      # rather than the phrase. Legitimate text does not carry them.
+      INVISIBLE = /[​-‍⁠᠎‪-‮⁦-⁩�]/
 
       # A base64 run long enough to hold a sentence. Below this the decode is
       # noise, and a handbook is full of short tokens that happen to be in the
@@ -73,12 +81,13 @@ module Vangrail
         text if offline?
       end
 
-      def call(text, context)
+      def decide(text, context)
         body = text.to_s
         stripped = body.gsub(INVISIBLE, '')
 
-        hit = first_objection(body, stripped, context)
+        hit, uncertain = first_objection(body, stripped, context)
         return hit if hit
+        return unchecked(uncertain.reason) if uncertain
 
         return pass if stripped == body
 
@@ -100,9 +109,9 @@ module Vangrail
 
       private
 
-      # Stops at the first rail that objects to any variant. Order is the
-      # caller's rail order, then transform order, so the reported reason is
-      # stable rather than whichever regexp happened to be quickest.
+      # Walks every variant. A block stops the pass. A rewrite is spliced into
+      # the page and the remaining encodings are still read, so a redaction
+      # cannot hide a later injection.
       def first_objection(body, stripped, context)
         candidates = []
         # The stripped text is a variant in its own right when anything was
@@ -111,16 +120,75 @@ module Vangrail
         candidates << [:invisible, stripped] unless stripped == body
         candidates.concat(variants(stripped))
 
+        published = stripped
+        modified = nil
+        uncertain = nil
         candidates.each do |name, decoded|
+          viewed = decoded
+          variant_modified = nil
+          extra = ["encoded:#{name}"]
           rails.each do |rail|
-            result = rail.call(decoded, context)
-            next unless result.blocked?
-
-            return block(categories: (result.categories || []) + ["encoded:#{name}"],
-                         reason: "#{result.reason} (hidden with #{name})")
+            result = rail.call(viewed, context)
+            if result.blocked?
+              return [block(categories: (result.categories || []) + extra,
+                            reason: "#{result.reason} (hidden with #{name})"), nil]
+            end
+            if result.modified?
+              viewed = result.content.to_s
+              variant_modified = [result, extra, name]
+            elsif !result.certain?
+              uncertain ||= result
+            end
           end
+          next if variant_modified.nil? || modified
+
+          published = apply_rewrite(published, name, decoded, viewed)
+          modified = variant_modified
         end
-        nil
+        if modified
+          result, extra, name = modified
+          return [modify(published, categories: (result.categories || []) + extra,
+                         reason: "#{result.reason} (hidden with #{name})"), nil]
+        end
+
+        [nil, uncertain]
+      end
+
+      # Puts the child's rewrite back on the page the reader will see.
+      def apply_rewrite(published, name, decoded, rewrite)
+        return splice_base64(published, rewrite) if name == :base64
+        return rewrite if decoded == published
+        return published.sub(decoded) { rewrite } if published.include?(decoded)
+        return splice_aligned(published, decoded, rewrite) if published.length == decoded.length
+
+        published
+      end
+
+      def splice_base64(published, rewrite)
+        runs = published.scan(BASE64)
+        return published if runs.empty?
+        return published.sub(runs.first) { rewrite } unless runs.size > 1
+
+        pieces = rewrite.split("\n")
+        return published.sub(runs.first) { rewrite } unless pieces.size == runs.size
+
+        runs.zip(pieces).reduce(published) { |acc, (run, piece)| acc.sub(run) { piece } }
+      end
+
+      def splice_aligned(published, decoded, rewrite)
+        prefix = 0
+        limit = [decoded.length, rewrite.length].min
+        prefix += 1 while prefix < limit && decoded[prefix] == rewrite[prefix]
+
+        suffix = 0
+        max_suffix = [decoded.length - prefix, rewrite.length - prefix].min
+        while suffix < max_suffix &&
+              decoded[decoded.length - 1 - suffix] == rewrite[rewrite.length - 1 - suffix]
+          suffix += 1
+        end
+
+        replacement = rewrite[prefix, rewrite.length - prefix - suffix]
+        published[0, prefix] + replacement.to_s + published[published.length - suffix, suffix]
       end
 
       def apply(name, body)