Class: Vangrail::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/vangrail/session.rb

Overview

The posterior over a session rather than over a message.

Every check in this gem, and every detector in the published work, judges one string and forgets it. That is the wrong shape for the attack family that actually gets through a desk: ask something harmless, ask for more detail about the part of the answer that helped, keep going. No message in that sequence is an attack, which is why per-message detection is blind to it, and Rails::Escalation only catches the crude version where a refusal is followed by a retry.

Read as evidence, the sequence is the obvious case. Three turns that each move the odds by two bits have moved them by six, and a reader whose every question is unremarkable but slightly odd looks exactly like what they are: unlikely, three times over. Nothing about that needs a new detector. It needs the arithmetic to carry across turns, which is one multiplication.

Two things keep it from becoming a session that eventually blocks everyone.

Evidence decays. Between turns the excess over the prior is multiplied by decay, so a session's posture reflects recent behaviour rather than everything since login. This is the standard forgetting factor of sequential inference with drift, and the drift here is real: the person asking is allowed to change what they are doing, and a reader who asked one odd question an hour ago is not a suspect.

Ordinary turns push back. A clean turn contributes the silence of every rail that ran, which is negative evidence, so a session recovers rather than only ratcheting. A reader who trips one rail and then asks twenty normal questions ends where they started.

session = Vangrail::Session.new(engine: engine, prior: 1e-3)
session.observe(question)          # => Judgement for the turn
session.posterior                  # => the session's, not the turn's
session.action                     # => :allow, :review, :block

The per-turn judgement is still returned, because both numbers are real and they answer different questions. "Is this message an attack" is what a request path routes on. "Is this session an attack" is what a desk wants before it decides whether a reader is probing it.

Defined Under Namespace

Classes: Track

Constant Summary collapse

DEFAULT_DECAY =

How much of the accumulated excess survives to the next turn. At 0.6, two bits of suspicion are worth about one and a quarter after one ordinary turn and a third of a bit after four, so a single odd question fades in a handful of turns while a pattern of them does not.

0.6

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(engine:, prior:, decay: DEFAULT_DECAY, policy: Policy::DEFAULT, alpha: 0.01, beta: 0.05) ⇒ Session

alpha and beta are the error rates a sequential test is allowed: how often it may call an ordinary reader an attacker, and how often it may miss one. Given those two numbers the thresholds are not a choice, which is the whole appeal of the sequential test.

Raises:

  • (ArgumentError) 


83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/vangrail/session.rb', line 83

def initialize(engine:, prior:, decay: DEFAULT_DECAY, policy: Policy::DEFAULT,
               alpha: 0.01, beta: 0.05)
  raise ArgumentError, 'prior must be strictly between 0 and 1' unless prior.positive? && prior < 1
  raise ArgumentError, 'decay must be in (0, 1]' unless decay.positive? && decay <= 1
  raise ArgumentError, 'alpha and beta must be in (0, 1)' unless [alpha, beta].all? { |v| v.positive? && v < 1 }

  @engine = engine
  @prior = prior
  @decay = decay
  @policy = policy
  @alpha = alpha
  @beta = beta
  base = Math.log2(Posterior.to_odds(prior))
  @attack = Track.new(base)
  @contamination = Track.new(base)
  @channel = nil
end

Instance Attribute Details

#alpha ⇒ Object (readonly)

Returns the value of attribute alpha.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def alpha
  @alpha
end

#attack ⇒ Object (readonly)

Returns the value of attribute attack.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def attack
  @attack
end

#beta ⇒ Object (readonly)

Returns the value of attribute beta.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def beta
  @beta
end

#channel ⇒ Object (readonly)

Returns the value of attribute channel.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def channel
  @channel
end

#contamination ⇒ Object (readonly)

Returns the value of attribute contamination.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def contamination
  @contamination
end

#decay ⇒ Object (readonly)

Returns the value of attribute decay.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def decay
  @decay
end

#engine ⇒ Object (readonly)

Returns the value of attribute engine.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def engine
  @engine
end

#policy ⇒ Object (readonly)

Returns the value of attribute policy.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def policy
  @policy
end

#prior ⇒ Object (readonly)

Returns the value of attribute prior.



76
77
78
 
# File 'lib/vangrail/session.rb', line 76

def prior
  @prior
end

Instance Method Details

#action ⇒ Object 



159
160
161
 
# File 'lib/vangrail/session.rb', line 159

def action
  policy.action_for(posterior)
end

#allow? ⇒ Boolean

Returns:

  • (Boolean) 


171
172
173
 
# File 'lib/vangrail/session.rb', line 171

def allow?
  action == :allow
end

#bits ⇒ Object

How far the session sits from where it started, in bits. The readable summary: zero is an ordinary session, and positive is a reader who keeps doing things that ordinary readers do not.



155
156
157
 
# File 'lib/vangrail/session.rb', line 155

def bits
  log_odds - Math.log2(Posterior.to_odds(prior))
end

#bits_to_decide ⇒ Object

How much more evidence the test needs before it can decide, in bits.



210
211
212
213
214
 
# File 'lib/vangrail/session.rb', line 210

def bits_to_decide
  return 0.0 unless verdict == :undecided

  [upper_threshold - bits, bits - lower_threshold].min
end

#block? ⇒ Boolean

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/vangrail/session.rb', line 163

def block?
  action == :block
end

#certain? ⇒ Boolean

False as soon as any turn was judged without every rail reaching a decision, because the session's number inherits every gap in the turns that built it.

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/vangrail/session.rb', line 226

def certain?
  attack.turns.all?(&:certain?) && contamination.turns.all?(&:certain?)
end

#cusum ⇒ Object 



138
139
140
 
# File 'lib/vangrail/session.rb', line 138

def cusum
  primary.cusum
end

#fold(judgement) ⇒ Object

Folds a judgement computed elsewhere, for a caller that already ran one.



123
124
125
126
127
128
 
# File 'lib/vangrail/session.rb', line 123

def fold(judgement)
  origin = judgement.origin || Origin.default_for(judgement.side || :input)
  @channel ||= origin.channel
  apply(track_for(origin.channel), judgement)
  self
end

#log_odds ⇒ Object 



130
131
132
 
# File 'lib/vangrail/session.rb', line 130

def log_odds
  primary.log_odds
end

#lower_threshold ⇒ Object 



205
206
207
 
# File 'lib/vangrail/session.rb', line 205

def lower_threshold
  Math.log2(beta / (1 - alpha))
end

#observe(text, side: :input, origin: nil, **context) ⇒ Object

Judges one turn and folds it into the session.

The turn's own judgement is computed against the session's prior rather than against the session's current posterior, deliberately. Feeding the running posterior back in as the prior would compound the same evidence every turn and reach certainty on a reader who did nothing new; the accumulation belongs in the session's state, not in each turn's premise.

origin defaults from the side: a question is a user span, a retrieved page is data. Privileged origin updates the attack track. Untrusted origin updates contamination. The two numbers never add: a poisoned wiki page cannot accuse a reader, and a reader cannot contaminate a document they did not write.



114
115
116
117
118
119
120
 
# File 'lib/vangrail/session.rb', line 114

def observe(text, side: :input, origin: nil, **context)
  origin = Origin.coerce(origin || Origin.default_for(side))
  judgement = engine.assess(text, side: side, prior: prior, policy: policy,
                                  origin: origin, **context)
  fold(judgement)
  judgement
end

#posterior ⇒ Object 



148
149
150
 
# File 'lib/vangrail/session.rb', line 148

def posterior
  Posterior.from_odds(2**log_odds)
end

#quarantined ⇒ Object

Turns that landed on the other rank. They still moved that rank's posterior; they did not move this one.



144
145
146
 
# File 'lib/vangrail/session.rb', line 144

def quarantined
  other.turns
end

#review? ⇒ Boolean

Returns:

  • (Boolean) 


167
168
169
 
# File 'lib/vangrail/session.rb', line 167

def review?
  action == :review
end

#shift? ⇒ Boolean

True when the recent burst of attack-direction evidence has reached the same bar Wald uses for the accumulated total. A change of behaviour, not a lifetime score.

Returns:

  • (Boolean) 


219
220
221
 
# File 'lib/vangrail/session.rb', line 219

def shift?
  cusum >= upper_threshold
end

#to_h ⇒ Object 



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/vangrail/session.rb', line 230

def to_h
  {
    'prior' => prior,
    'posterior' => posterior.round(6),
    'bits' => bits.round(2),
    'decay' => decay,
    'turns' => turns.size,
    'channel' => channel&.to_s,
    'quarantined' => (quarantined.size unless quarantined.empty?),
    'attack' => track_h(attack),
    'contamination' => track_h(contamination),
    'action' => action.to_s,
    'verdict' => verdict.to_s,
    'cusum' => cusum.round(2),
    'shift' => shift?,
    'certain' => certain?,
  }.compact
end

#to_s ⇒ Object 



249
250
251
252
 
# File 'lib/vangrail/session.rb', line 249

def to_s
  format('session %<action>s p=%<posterior>.4f over %<turns>d turn(s), %<bits>+.1f bits',
         action: action, posterior: posterior, turns: turns.size, bits: bits)
end

#turns ⇒ Object 



134
135
136
 
# File 'lib/vangrail/session.rb', line 134

def turns
  primary.turns
end

#upper_threshold ⇒ Object 



201
202
203
 
# File 'lib/vangrail/session.rb', line 201

def upper_threshold
  Math.log2((1 - beta) / alpha)
end

#verdict ⇒ Object

Wald's sequential test over the same accumulated evidence.

The posterior answers "how likely is this"; the sequential test answers a question an operator often prefers: "have I seen enough to decide, at error rates I chose in advance". It is the older machinery, it is what the network-detection work uses for exactly this shape of problem, and it costs nothing extra here because the log-likelihood ratio is already being accumulated.

Two thresholds, both fixed by alpha and beta rather than by taste: accumulate until the evidence passes log((1 - beta) / alpha) and call it an attack, or falls below log(beta / (1 - alpha)) and call it ordinary. In between, the honest answer is that the session has not said enough yet.

Reported beside the posterior rather than instead of it. They answer different questions and disagreeing is informative: a session that the test calls undecided while the policy says review is a session where the cost argument and the error-rate argument point different ways, and somebody should know that.



194
195
196
197
198
199
 
# File 'lib/vangrail/session.rb', line 194

def verdict
  return :attack if bits >= upper_threshold
  return :benign if bits <= lower_threshold

  :undecided
end