vangrail 0.1.0

data/lib/vangrail/rails/markup.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Removes markup that does something when the answer is rendered.
+    #
+    # An answer is text until a client renders it, and most clients render
+    # markdown by pulling in a library that passes raw HTML straight through.
+    # At that point a script tag in the answer is a script tag in the page, and
+    # the model wrote it because a retrieved document told it to. That is a
+    # cross-site scripting bug with a language model in the middle of it, and
+    # the fact that the model is the delivery mechanism does not make it a
+    # different class of bug.
+    #
+    # The application's own sanitiser is the real defence and this does not
+    # replace it. What this covers is the case where there is no sanitiser,
+    # which is most of them, and where the answer is passed to a renderer that
+    # was chosen for how its tables look.
+    #
+    # Removes rather than blocks. An answer with a script tag in it is an answer
+    # with one bad span, the same as an answer with a credential in it.
+    #
+    # Not on by default. A desk whose client renders markdown as text, or which
+    # escapes before rendering, does not need it, and a rail that strips markup
+    # nobody was going to execute is noise in the result.
+    class Markup < Rail
+      PATTERNS = {
+        # Executes on load.
+        'script' => /<script\b[^>]*>.*?<\/script>|<script\b[^>]*\/?>/mi,
+        # Loads and executes something else.
+        'frame' => /<(?:iframe|frame|embed|object|applet)\b[^>]*>(?:.*?<\/(?:iframe|frame|embed|object|applet)>)?/mi,
+        # Runs on an event, which is how a lone img tag becomes an exploit.
+        'event_handler' => /\son[a-z]{3,20}\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/i,
+        # A scheme that executes rather than fetches.
+        'active_scheme' => /(?:javascript|vbscript|data)\s*:\s*[^\s"'<>)]+/i,
+        # Rewrites where a form or a link goes, or what the page loads next.
+        'meta_refresh' => /<meta\b[^>]*http-equiv\s*=\s*["']?refresh["']?[^>]*>/i,
+        '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
+      }.freeze
+
+      attr_reader :patterns
+
+      def initialize(patterns: PATTERNS, name: 'markup', sides: [:output])
+        super(name: name, sides: sides)
+        @patterns = patterns
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, _context)
+        text
+      end
+
+      def call(text, _context)
+        body = text.to_s
+        found = []
+        cleaned = patterns.reduce(body) do |acc, (label, pattern)|
+          acc.gsub(pattern) do
+            found << label
+            ''
+          end
+        end
+        return pass if found.empty?
+
+        modify(cleaned, categories: found.uniq,
+                        reason: "removed #{found.uniq.join(', ')} from the answer")
+      end
+    end
+  end
+end

data/lib/vangrail/rails/missing.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Stands in for a rail that was asked for and could not be built.
+    #
+    # Without this, a configuration asking for a model-backed rail against an
+    # endpoint that is down produces an engine holding only its offline rails.
+    # Those rails pass, the engine reports passed and certain, and the answer is
+    # a lie: the check the operator configured never ran.
+    #
+    # A placeholder that always returns unchecked keeps the arithmetic right.
+    # The turn is allowed, the engine's result is uncertain, and the reason
+    # names what is missing and why.
+    class Missing < Rail
+      attr_reader :reason
+
+      def initialize(reason:, name: 'missing', sides: Rail::SIDES)
+        super(name: name, sides: sides)
+        @reason = reason
+      end
+
+      def offline?
+        true
+      end
+
+      def placeholder?
+        true
+      end
+
+      def call(_text, _context)
+        unchecked(reason)
+      end
+    end
+  end
+end

data/lib/vangrail/rails/obfuscation.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative '../confusables'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Runs other rails again over the text an attacker actually meant.
+    #
+    # Every pattern rail reads what is written. An attacker who knows that
+    # writes it differently: base64 the paragraph and ask the model to decode
+    # it, rot13 it, spell it with Cyrillic letters that look like Latin ones,
+    # put zero-width joiners between the letters of "ignore", or set a
+    # right-to-left override so the rendered page and the byte sequence say
+    # different things. The model reads through all of it, because that is what
+    # models do, and the regexps see nothing.
+    #
+    # The answer is not more patterns. It is to undo the encoding and run the
+    # rails that already exist over the result, which is why this takes a rail
+    # list rather than defining checks of its own:
+    #
+    #   Rails::Obfuscation.new(rails: [Rails::InjectedInstructions.new,
+    #                                  Rails::Jailbreak.new])
+    #
+    # Each transform is applied on its own, and a variant identical to the
+    # 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.
+    #
+    # 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
+    # joiner inside a word has no honest use in a handbook, and removing it
+    # costs a reader nothing while denying the cheapest bypass there is.
+    #
+    # What this does not do is guess. There is no scoring, no entropy
+    # threshold, no "this looks encoded" heuristic that would fire on the base64
+    # blobs and hashes a cluster handbook is full of. A blob either decodes to
+    # text a rail objects to, or it does not.
+    class Obfuscation < Rail
+      # 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 = /[​-‍⁠᠎‪-‮⁦-⁩]/
+
+      # 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
+      # alphabet.
+      #
+      # Bounded by lookaround rather than \b, because + and / are not word
+      # characters: a blob ending in one had its last character trimmed off the
+      # match, and a base64 string one character short decodes to a sentence
+      # with its tail missing. That cost the corpus a case, and the case it
+      # cost was an HTML comment, whose pattern needs the closing marker.
+      BASE64 = /(?<![A-Za-z0-9+\/=])[A-Za-z0-9+\/]{24,}={0,2}(?![A-Za-z0-9+\/=])/
+
+      attr_reader :rails, :transforms
+
+      def initialize(rails:, transforms: %i[invisible confusables confusables_all rot13 base64 nfkc],
+                     name: 'obfuscation', sides: %i[input context])
+        super(name: name, sides: sides)
+        @rails = Array(rails)
+        @transforms = Array(transforms).map(&:to_sym)
+      end
+
+      # Only if everything it delegates to is. A wrapper around a model rail
+      # inherits the model rail's posture.
+      def offline?
+        rails.all?(&:offline?)
+      end
+
+      def cache_key(text, _context)
+        text if offline?
+      end
+
+      def call(text, context)
+        body = text.to_s
+        stripped = body.gsub(INVISIBLE, '')
+
+        hit = first_objection(body, stripped, context)
+        return hit if hit
+
+        return pass if stripped == body
+
+        modify(stripped, categories: ['invisible_characters'],
+                         reason: 'removed zero-width or bidi control characters')
+      end
+
+      # The decoded forms of a text, labelled. Public because an application
+      # that logs a blocked page wants to show what it decoded to.
+      def variants(text)
+        body = text.to_s
+        transforms.filter_map do |name|
+          decoded = apply(name, body)
+          next if decoded.nil? || decoded == body || decoded.strip.empty?
+
+          [name, decoded]
+        end
+      end
+
+      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.
+      def first_objection(body, stripped, context)
+        candidates = []
+        # The stripped text is a variant in its own right when anything was
+        # removed: "i<zwj>gnore previous instructions" is the whole attack, and
+        # every other transform runs after the removal rather than instead of it.
+        candidates << [:invisible, stripped] unless stripped == body
+        candidates.concat(variants(stripped))
+
+        candidates.each do |name, decoded|
+          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})")
+          end
+        end
+        nil
+      end
+
+      def apply(name, body)
+        case name
+        when :invisible then body.gsub(INVISIBLE, '')
+        when :confusables then defold(body)
+        when :confusables_all then Confusables.fold_all(body)
+        when :rot13 then body.tr('A-Za-z', 'N-ZA-Mn-za-m')
+        when :base64 then decode_base64(body)
+        when :nfkc then normalise(body)
+        end
+      end
+
+      # Two readings of the same text, because the policies fail in opposite
+      # directions and a variant costs one comparison.
+      #
+      # :confusables folds only words that mix ASCII with imitators, which is
+      # what an imitation attack looks like and what leaves a page of Russian
+      # alone. It misses a word converted character for character, where
+      # nothing ASCII is left to mix with.
+      #
+      # :confusables_all folds everything and catches that, at the price of
+      # turning genuine Cyrillic into noise. The noise is never shown to
+      # anybody: a variant exists to be read by a pattern, and the corpus
+      # asserts that ordinary non-Latin prose does not match one.
+      def defold(body)
+        Confusables.fold(body)
+      end
+
+      # Every long base64 run in the text, decoded and joined. A run that is not
+      # valid base64, or that decodes to bytes rather than text, contributes
+      # nothing rather than failing the whole pass: a handbook page carrying one
+      # hash and one payload should still have the payload read.
+      def decode_base64(body)
+        pieces = body.scan(BASE64).filter_map { |run| readable(run) }
+        pieces.empty? ? nil : pieces.join("\n")
+      end
+
+      def readable(run)
+        decoded = run.unpack1('m')
+        return nil if decoded.nil? || decoded.empty?
+
+        decoded.force_encoding(Encoding::UTF_8)
+        return nil unless decoded.valid_encoding?
+        # Printable enough to be a sentence rather than a compressed blob.
+        return nil if decoded.count("^ -~\n\t").positive?
+
+        decoded
+      rescue ArgumentError
+        nil
+      end
+
+      # Compatibility normalisation folds the fullwidth and mathematical
+      # alphabets, which is the other cheap way to write a word a regexp will
+      # not recognise.
+      def normalise(body)
+        body.unicode_normalize(:nfkc)
+      rescue ArgumentError, Encoding::CompatibilityError
+        nil
+      end
+    end
+  end
+end

data/lib/vangrail/rails/pattern.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Blocks text matching any of a list of patterns.
+    #
+    # A guardrail stack that is only a language model has no floor: when the
+    # endpoint is slow, cold, or down, every check degrades at once. A pattern
+    # rail decides in microseconds, offline, and identically every time, so the
+    # cases you can state exactly stay covered no matter what the network does.
+    #
+    #   Pattern.new(patterns: { 'instruction_override' => /ignore (all )?previous instructions/i })
+    class Pattern < Rail
+      attr_reader :patterns
+
+      def initialize(patterns:, name: 'pattern', sides: Rail::SIDES, reason: nil)
+        super(name: name, sides: sides)
+        @patterns = normalize(patterns)
+        @reason = reason
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, _context)
+        text
+      end
+
+      def call(text, _context)
+        hit = patterns.find { |_label, pattern| pattern.match?(text.to_s) }
+        return pass unless hit
+
+        label = hit.first
+        block(categories: [label], reason: @reason || "matched #{label}")
+      end
+
+      private
+
+      def normalize(patterns)
+        case patterns
+        when Hash then patterns.to_h { |k, v| [k.to_s, to_regexp(v)] }
+        when Array then patterns.each_with_index.to_h { |v, i| ["pattern_#{i + 1}", to_regexp(v)] }
+        else { 'pattern_1' => to_regexp(patterns) }
+        end
+      end
+
+      def to_regexp(value)
+        return value if value.is_a?(Regexp)
+
+        Regexp.new(Regexp.escape(value.to_s), Regexp::IGNORECASE)
+      end
+    end
+  end
+end

data/lib/vangrail/rails/personal_data.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Redacts a reader's own details before the question leaves the building.
+    #
+    # This is a privacy rail rather than a security one, and it exists because
+    # of where the text goes next. A question typed into a documentation desk
+    # is about to be sent to a model endpoint, which may be a third party, may
+    # log, and may sit in another jurisdiction. A reader pasting a support
+    # thread into it has not thought about any of that, and nothing in the
+    # answer needs their phone number.
+    #
+    # Redacts rather than blocks, for the same reason the secrets rail does: the
+    # question is answerable, and one span in it should not have been sent.
+    #
+    # The hard part on a cluster desk is not detection. It is that
+    # `ssh rgoswami@snellius.example.org` is an email address by every
+    # syntactic measure, and redacting it destroys the answer to the most
+    # commonly asked question there is. So an address is left alone when it is
+    # inside backticks or a fence, when its line carries a command that takes a
+    # user@host argument or an ssh config keyword, or when a remote path
+    # follows it. All three are in the corpus, because a rail that eats login
+    # examples is worse for a handbook than no rail at all.
+    #
+    # Deliberately not included: national identity numbers. The Dutch BSN is
+    # nine digits with a checksum, a Slurm job id is six to eight digits, and
+    # one in eleven job ids passes the checksum by accident. A rail that
+    # redacts job ids from a cluster support question is unusable, and the
+    # trade is not close.
+    class PersonalData < Rail
+      PLACEHOLDER = '[redacted]'
+
+      # Commands whose argument is a login target rather than a mailbox. Read
+      # over the line rather than the character before the match: scp puts a
+      # source path in between, and an ssh config line has no command on it at
+      # all, only the User keyword.
+      HOST_COMMANDS = /\b(?:ssh|scp|sftp|rsync|mosh|ssh-copy-id|ssh:\/\/|sftp:\/\/|User)\b/i
+
+      # The other half of scp and rsync syntax: an address followed by a remote
+      # path is a target, not a mailbox.
+      REMOTE_PATH = /\A:[~\/\w.]/
+
+      # Local parts that are documentation rather than a person.
+      PLACEHOLDER_USERS = /\A(?:user|username|your[._-]?name|login|account|me|example|
+                              firstname|lastname|name|admin|root)\z/xi
+
+      PATTERNS = {
+        'email' => /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
+        # International or national, with a separator, long enough to be a
+        # phone number and not a job id: a leading + or 00, or a leading zero
+        # with grouping.
+        'phone' => /(?:\+|\b00)[1-9]\d{0,2}[\s.-]?(?:\(?\d{1,4}\)?[\s.-]?){2,5}\d{2,4}\b
+                    |\b0\d{1,3}[\s.-]\d{3}[\s.-]?\d{3,4}\b/x,
+        'iban' => /\b[A-Z]{2}\d{2}\s?(?:[A-Z0-9]{4}\s?){2,7}[A-Z0-9]{1,4}\b/,
+        'card' => /\b(?:\d[ -]?){13,19}\b/
+      }.freeze
+
+      attr_reader :patterns, :placeholder
+
+      def initialize(patterns: PATTERNS, placeholder: PLACEHOLDER,
+                     name: 'personal_data', sides: [:input])
+        super(name: name, sides: sides)
+        @patterns = patterns
+        @placeholder = placeholder
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, _context)
+        text
+      end
+
+      def call(text, _context)
+        body = text.to_s
+        found = []
+        redacted = patterns.reduce(body) do |acc, (label, pattern)|
+          replace(acc, label, pattern, found)
+        end
+        return pass if found.empty?
+
+        modify(redacted, categories: found.uniq,
+                         reason: "redacted #{found.uniq.join(', ')} before sending")
+      end
+
+      private
+
+      def replace(body, label, pattern, found)
+        body.gsub(pattern) do |match|
+          m = Regexp.last_match
+          next match unless redact?(label, match, m.pre_match, m.post_match)
+
+          found << label
+          placeholder
+        end
+      end
+
+      def redact?(label, match, before, after)
+        return false if in_code?(before)
+
+        case label
+        when 'email' then mailbox?(match, before, after)
+        when 'card' then card?(match)
+        else true
+        end
+      end
+
+      # An address is a mailbox unless it is a login target or a placeholder in
+      # documentation.
+      def mailbox?(match, before, after)
+        return false if after.match?(REMOTE_PATH)
+        return false if before[/[^\n]*\z/].match?(HOST_COMMANDS)
+
+        !match.split('@').first.match?(PLACEHOLDER_USERS)
+      end
+
+      # Digits alone are not a card number. A cluster question is full of long
+      # numbers, so the check has to be the one the issuers use.
+      def card?(match)
+        digits = match.gsub(/\D/, '')
+        return false unless digits.length.between?(13, 19)
+
+        luhn?(digits)
+      end
+
+      def luhn?(digits)
+        sum = digits.reverse.chars.each_with_index.sum do |c, i|
+          n = c.to_i
+          next n if i.even?
+
+          n * 2 > 9 ? (n * 2) - 9 : n * 2
+        end
+        (sum % 10).zero?
+      end
+
+      # Inside backticks or a fence, the text is a command rather than a
+      # person's details, and rewriting a command is how a guardrail becomes
+      # the thing the reader has to work around.
+      def in_code?(before)
+        before.count('`').odd? || fenced?(before)
+      end
+
+      def fenced?(before)
+        before.scan(/^```/).size.odd?
+      end
+    end
+  end
+end

data/lib/vangrail/rails/remote.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../client'
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # A NeMo Guardrails server as one rail among the local ones.
+    #
+    # Wrapping the client in the rail protocol is what keeps the two paths from
+    # becoming two designs. A team migrating off the Python service can put this
+    # rail and a local one in the same ordered list, compare them on live
+    # traffic, and drop the remote one when the local rails cover it.
+    class Remote < Rail
+      attr_reader :client
+
+      def initialize(client: nil, base_url: nil, config_id: nil, api_key: nil,
+                     name: 'remote', sides: Rail::SIDES)
+        super(name: name, sides: sides)
+        @client = client || Client.new(base_url: base_url, config_id: config_id, api_key: api_key)
+      end
+
+      def cache_key(text, context)
+        return text if context[:side] == :input
+
+        "#{context[:user_input]} #{text}"
+      end
+
+      def call(text, context)
+        result =
+          if context[:side] == :output
+            client.check_output(text, user_input: context[:user_input])
+          else
+            client.check_input(text)
+          end
+        result.with_rail(name)
+      end
+    end
+  end
+end

data/lib/vangrail/rails/secrets.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative '../rail'
+
+module Vangrail
+  module Rails
+    # Redacts credentials, returning :modified rather than blocking.
+    #
+    # This is the rail that justifies having three statuses. An answer that
+    # quotes a config file with a live token is a useful answer with one bad
+    # span in it: blocking it throws away the help, and passing it leaks the
+    # token. Replacing the span keeps both halves honest, and the caller can see
+    # from the status that what it is about to show has been edited.
+    #
+    # Patterns cover shapes that are unambiguous on sight. Anything needing
+    # judgement belongs in a policy rail, not here: a false positive silently
+    # corrupts an answer, which is worse than a missed match a later rail can
+    # still catch.
+    class Secrets < Rail
+      PLACEHOLDER = '[redacted]'
+
+      DEFAULT_PATTERNS = {
+        'private_key' => /-----BEGIN[A-Z ]*PRIVATE KEY-----.*?-----END[A-Z ]*PRIVATE KEY-----/m,
+        'openai_key' => /\bsk-[A-Za-z0-9_-]{20,}\b/,
+        'anthropic_key' => /\bsk-ant-[A-Za-z0-9_-]{20,}\b/,
+        'github_token' => /\bgh[pousr]_[A-Za-z0-9]{30,}\b/,
+        'slack_token' => /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/,
+        'aws_access_key' => /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/,
+        'jwt' => /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+        'bearer_header' => /\b(?i:authorization)\s*:\s*(?i:bearer)\s+\S{12,}/,
+        'inline_password' => /\b(?i:password|passwd|api[_-]?key|secret)\s*[=:]\s*(?!\[redacted\])\S{6,}/
+      }.freeze
+
+      attr_reader :patterns, :placeholder
+
+      def initialize(patterns: DEFAULT_PATTERNS, placeholder: PLACEHOLDER, name: 'secrets',
+                     sides: [:output])
+        super(name: name, sides: sides)
+        @patterns = patterns
+        @placeholder = placeholder
+      end
+
+      def offline?
+        true
+      end
+
+      def cache_key(text, _context)
+        text
+      end
+
+      def call(text, _context)
+        body = text.to_s
+        found = []
+        redacted = patterns.reduce(body) do |acc, (label, pattern)|
+          acc.gsub(pattern) do |match|
+            found << label
+            replacement(label, match)
+          end
+        end
+        return pass if found.empty?
+
+        modify(redacted, categories: found.uniq, reason: "redacted #{found.uniq.join(', ')}")
+      end
+
+      private
+
+      # Keeps the key name visible so the reader still learns which setting the
+      # answer was talking about, and loses only the value.
+      def replacement(label, match)
+        return "#{match[/\A[^=:]*[=:]\s*/]}#{placeholder}" if label == 'inline_password'
+        return "#{match[/\A\S+\s*:\s*\S+\s/]}#{placeholder}" if label == 'bearer_header' && match =~ /\s/
+
+        placeholder
+      end
+    end
+  end
+end