devfortress-sdk 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +4 -0
  3. data/Gemfile +7 -0
  4. data/LICENSE +63 -0
  5. data/README.md +121 -0
  6. data/Rakefile +11 -0
  7. data/lib/devfortress/agent_adapter.rb +185 -0
  8. data/lib/devfortress/agent_loop_detector.rb +167 -0
  9. data/lib/devfortress/agent_output_exfiltration_detector.rb +115 -0
  10. data/lib/devfortress/agent_security.rb +431 -0
  11. data/lib/devfortress/alias_verify.rb +87 -0
  12. data/lib/devfortress/api_key_aliasing.rb +240 -0
  13. data/lib/devfortress/bounded_map.rb +80 -0
  14. data/lib/devfortress/circuit_breaker.rb +149 -0
  15. data/lib/devfortress/classifier.rb +133 -0
  16. data/lib/devfortress/client.rb +380 -0
  17. data/lib/devfortress/client_ip.rb +28 -0
  18. data/lib/devfortress/clock_drift_detector.rb +71 -0
  19. data/lib/devfortress/credential_isolation.rb +340 -0
  20. data/lib/devfortress/credential_vault.rb +93 -0
  21. data/lib/devfortress/delivery_result.rb +9 -0
  22. data/lib/devfortress/graduated_rate_limiter.rb +270 -0
  23. data/lib/devfortress/internal_closed_loop_engine.rb +658 -0
  24. data/lib/devfortress/license_manager.rb +297 -0
  25. data/lib/devfortress/observer.rb +62 -0
  26. data/lib/devfortress/prompt_injection_filter.rb +73 -0
  27. data/lib/devfortress/response_webhook_client.rb +165 -0
  28. data/lib/devfortress/shadow_agent_registry.rb +123 -0
  29. data/lib/devfortress/signer.rb +134 -0
  30. data/lib/devfortress/telemetry.rb +407 -0
  31. data/lib/devfortress/tier_gate.rb +294 -0
  32. data/lib/devfortress/tool_call_sequence_validator.rb +126 -0
  33. data/lib/devfortress/transport.rb +31 -0
  34. data/lib/devfortress/unified_audit_trail.rb +213 -0
  35. data/lib/devfortress/version.rb +5 -0
  36. data/lib/devfortress/webhook_verification.rb +9 -0
  37. data/lib/devfortress/webhook_verifier.rb +93 -0
  38. data/lib/devfortress.rb +96 -0
  39. metadata +110 -0
@@ -0,0 +1,658 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "bounded_map"
4
+
5
+ module DevFortress
6
+ # Internal Closed-Loop Protection Engine.
7
+ #
8
+ # Port of the Node SDK's `internal-closed-loop-engine.ts`
9
+ # (`InternalClosedLoopEngine`), following the same structure as this
10
+ # session's Python port
11
+ # (devfortress-python/src/devfortress/internal_closed_loop_engine.py).
12
+ #
13
+ # Three tiers:
14
+ #
15
+ # Tier 1: Deterministic rule engine (<1ms) — regex, scanner signature,
16
+ # sensitive-file, credential-stuffing, and agent-tool rules.
17
+ # Tier 2: Optional custom scorer — anything responding to `#call`
18
+ # (a Proc/lambda or any object). Unimplemented by default: no
19
+ # scorer is wired in unless the caller passes one; #evaluate
20
+ # simply skips Tier 2 in that case (same as Node's behaviour
21
+ # when `tier2Scorer` is unset, and Python's when
22
+ # `tier2_scorer` is `None`). This engine does not build a Ruby
23
+ # equivalent of Node's MLClassifier adapter — that is
24
+ # Node-specific and out of scope here.
25
+ # Tier 3: Relay — fires the `on_relay` callable for non-'allow'
26
+ # decisions when `enable_external_relay` is true (hybrid mode
27
+ # only). This engine has no HTTP client or platform
28
+ # credentials of its own by design; the caller's relay
29
+ # callback does the actual platform call (see client.rb's
30
+ # `_relay_internal_decision_to_platform`).
31
+ #
32
+ # State (blocked IPs/users/sessions, quarantined agents, rate-limiter
33
+ # entries, audit log) is bounded in-memory, lives for the engine
34
+ # instance's lifetime, and is never persisted — reusing this SDK's own
35
+ # BoundedMap, exactly like Node's and Python's engines.
36
+ #
37
+ # Ruby's Onigmo regex engine was independently verified against Node's
38
+ # V8/ECMA regex for every Tier 1 pattern below (see this session's
39
+ # report). One real divergence was found and fixed: Ruby's `$` anchor
40
+ # matches at the end of *any line* (there is no non-multiline mode for
41
+ # `^`/`$` in Ruby), whereas JS's bare `$` (no `/m` flag) matches only at
42
+ # the end of the *string*. The `path_traversal` rule's
43
+ # "ends with ..\\" pattern relied on `$` meaning absolute string end, so
44
+ # it is anchored with `\z` here instead of `$` to preserve Node's exact
45
+ # semantics (a multi-line request path containing "..\\" mid-string,
46
+ # followed by a line break and more content, would otherwise match in
47
+ # Ruby but not in Node). No other pattern in this engine is affected:
48
+ # every other `$`/`^` use already has a `\s`-based alternative that
49
+ # already covers embedded newlines on both engines, so the two engines'
50
+ # line-vs-string anchor difference produces no observable behavioural
51
+ # difference there.
52
+ class InternalClosedLoopEngine
53
+ # ── Default Attack Pattern Rules (Tier 1) ──────────────────────────
54
+ # Copied as literally as possible from internal-closed-loop-engine.ts;
55
+ # Ruby's /pattern/ literal syntax accepts the TS source's own escaping
56
+ # of internal slashes unchanged. See the class comment above for the
57
+ # one anchor fix (`$` -> `\z`) found necessary by direct verification.
58
+
59
+ SQL_INJECTION_STRICT = [
60
+ /(?:^|\s)(?:UNION\s+(?:ALL\s+)?SELECT|DROP\s+TABLE|INSERT\s+INTO|UPDATE\s+[a-zA-Z0-9_]+\s+SET|DELETE\s+FROM)(?:\s|\z)/i,
61
+ /(?:'|")\s*OR\s+(?:\d+\s*=\s*\d+|'[^']*'\s*=\s*'[^']*'|"[^"]*"\s*=\s*"[^"]*")/i,
62
+ /(?:'|")\s*;\s*(?:--|\/\*)/,
63
+ /(\bxp_\w+)/i,
64
+ ].freeze
65
+
66
+ SQL_INJECTION_MODERATE = [/(\/\*.*\*\/)/, /(\bEXEC\b|\bEXECUTE\b)\s*\(/i].freeze
67
+
68
+ XSS_PATTERNS = [
69
+ /<script[\s>]/i,
70
+ /javascript\s*:/i,
71
+ /on(load|error|click|mouseover|submit|focus|blur)\s*=/i,
72
+ /(<iframe|<object|<embed|<applet)/i,
73
+ /(document\.(cookie|write|location))/i,
74
+ /(window\.(location|open))/i,
75
+ ].freeze
76
+
77
+ PATH_TRAVERSAL_PATTERNS = [
78
+ /\.\.\//,
79
+ /\.\.%2[fF]/,
80
+ /\.\.\\\z/, # was `$` in Node; `\z` here is the Ruby-exact equivalent (see class comment)
81
+ /%2e%2e[%\/\\]/i,
82
+ /\/etc\/(passwd|shadow|hosts)/,
83
+ /\/proc\/self/,
84
+ /(\/\.env|\/\.git|\/\.ssh)/,
85
+ ].freeze
86
+
87
+ SCANNER_SIGNATURES = %w[sqlmap nikto nmap dirbuster gobuster].map { |p| Regexp.new(p, Regexp::IGNORECASE) } +
88
+ [Regexp.new('wpscan', Regexp::IGNORECASE),
89
+ Regexp.new('burp\s*suite', Regexp::IGNORECASE),
90
+ Regexp.new('acunetix', Regexp::IGNORECASE),
91
+ Regexp.new('nessus', Regexp::IGNORECASE),
92
+ Regexp.new('masscan', Regexp::IGNORECASE),
93
+ Regexp.new('zgrab', Regexp::IGNORECASE),
94
+ Regexp.new('nuclei', Regexp::IGNORECASE)].freeze
95
+
96
+ SENSITIVE_FILE_PATTERNS = [
97
+ /\/\.env/,
98
+ /\/\.git/,
99
+ /\/\.ssh/,
100
+ /\/wp-admin/,
101
+ /\/wp-login/,
102
+ /\/phpmyadmin/i,
103
+ /\/admin\.php/,
104
+ /\/\.htaccess/,
105
+ /\/\.htpasswd/,
106
+ /\/server-status/,
107
+ /\/actuator/,
108
+ /\/debug\//,
109
+ ].freeze
110
+
111
+ AUTH_PATHS = ["/login", "/signin", "/auth", "/api/auth", "/api/login", "/oauth/token"].freeze
112
+ DANGEROUS_TOOLS = %w[shell_exec eval exec rm sudo chmod kill].freeze
113
+
114
+ # ── Request / Result value objects ─────────────────────────────────
115
+
116
+ Request = Struct.new(
117
+ :ip, :method, :path, :user_agent, :user_id, :session_id, :body, :query,
118
+ :headers, :agent_id, :tool_name, :timestamp,
119
+ keyword_init: true
120
+ ) do
121
+ def initialize(**kwargs)
122
+ super
123
+ self.headers ||= {}
124
+ end
125
+ end
126
+
127
+ Action = Struct.new(:type, :target, :reason, :ttl_seconds, :timestamp, :event_id, keyword_init: true)
128
+ Result = Struct.new(:decision, :score, :tier, :matched_rules, :evaluation_time_us, :actions, :event_id, keyword_init: true)
129
+ AuditEntry = Struct.new(
130
+ :event_id, :timestamp, :ip, :decision, :score, :tier, :matched_rules, :user_id, :agent_id, :path, :method,
131
+ keyword_init: true
132
+ )
133
+ Rule = Struct.new(:name, :description, :severity, :score, :decision, :match, :enabled, keyword_init: true)
134
+
135
+ BlockEntry = Struct.new(:expires_at, :reason, keyword_init: true)
136
+ QuarantineEntry = Struct.new(:reason, :timestamp, keyword_init: true)
137
+ RateLimitEntry = Struct.new(:timestamps, :blocked, keyword_init: true) do
138
+ def initialize(**kwargs)
139
+ super
140
+ self.timestamps ||= []
141
+ end
142
+ end
143
+
144
+ attr_reader :fail_mode, :enable_external_relay
145
+
146
+ def initialize(
147
+ fail_mode: :closed,
148
+ enable_external_relay: false,
149
+ max_blocked_entries: 10_000,
150
+ max_rate_limit_entries: 50_000,
151
+ max_audit_entries: 100_000,
152
+ default_block_ttl_seconds: 3600,
153
+ tier2_scorer: nil,
154
+ block_threshold: 85,
155
+ rate_limit_threshold: 60,
156
+ rate_limit_max: 100,
157
+ rate_limit_window_seconds: 60.0,
158
+ debug: false,
159
+ on_action: nil,
160
+ on_relay: nil,
161
+ logger: nil
162
+ )
163
+ @fail_mode = fail_mode.to_sym
164
+ @enable_external_relay = enable_external_relay
165
+ @max_audit_entries = max_audit_entries
166
+ @default_block_ttl_seconds = default_block_ttl_seconds
167
+ @tier2_scorer = tier2_scorer
168
+ @block_threshold = block_threshold
169
+ @rate_limit_threshold = rate_limit_threshold
170
+ @rate_limit_max = rate_limit_max
171
+ @rate_limit_window_seconds = rate_limit_window_seconds
172
+ @debug = debug
173
+ @on_action = on_action
174
+ @on_relay = on_relay
175
+ @logger = logger
176
+
177
+ @blocked_ips = BoundedMap.new(max_blocked_entries)
178
+ @blocked_users = BoundedMap.new(max_blocked_entries)
179
+ @blocked_sessions = BoundedMap.new(max_blocked_entries)
180
+ @quarantined_agents = BoundedMap.new(max_blocked_entries)
181
+ @rate_limiter = BoundedMap.new(max_rate_limit_entries)
182
+ @audit_log = []
183
+ @audit_mutex = Mutex.new
184
+ @rules = []
185
+ @event_counter = 0
186
+ @event_counter_mutex = Mutex.new
187
+
188
+ register_default_rules
189
+ log(:info, "Internal Closed-Loop Engine initialized (fail_mode=#{@fail_mode})")
190
+ end
191
+
192
+ # ── Public API ──────────────────────────────────────────────────
193
+
194
+ # Evaluates +req+ (an InternalCLEngine::Request) through the 3-tier
195
+ # engine. Call this for every inbound request, before it reaches the
196
+ # application. Never raises: an uncaught error inside a rule or
197
+ # Tier 2/3 is contained and falls back to +fail_mode+.
198
+ def evaluate(req)
199
+ start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
200
+ now = req.timestamp || Time.now.to_f
201
+ event_id = generate_event_id
202
+
203
+ begin
204
+ pre_check = check_blocked(req, now)
205
+ if pre_check
206
+ decision, reason = pre_check
207
+ result = Result.new(
208
+ decision: decision, score: 100, tier: 1, matched_rules: [reason],
209
+ evaluation_time_us: elapsed_us(start), actions: [], event_id: event_id
210
+ )
211
+ record_audit(result, req)
212
+ return result
213
+ end
214
+
215
+ tier1_decision, tier1_score, tier1_rules = evaluate_tier1(req)
216
+ if tier1_decision != :allow
217
+ actions = execute_actions(tier1_decision, tier1_rules, req, event_id, now)
218
+ result = Result.new(
219
+ decision: tier1_decision, score: tier1_score, tier: 1, matched_rules: tier1_rules,
220
+ evaluation_time_us: elapsed_us(start), actions: actions, event_id: event_id
221
+ )
222
+ record_audit(result, req)
223
+ relay_to_external(result, req) if @enable_external_relay
224
+ return result
225
+ end
226
+
227
+ if check_rate_limit(req.ip, now)
228
+ actions = execute_actions(:rate_limit, ["rate_limit_exceeded"], req, event_id, now)
229
+ result = Result.new(
230
+ decision: :rate_limit, score: 65, tier: 1, matched_rules: ["rate_limit_exceeded"],
231
+ evaluation_time_us: elapsed_us(start), actions: actions, event_id: event_id
232
+ )
233
+ record_audit(result, req)
234
+ return result
235
+ end
236
+
237
+ record_request(req.ip, now)
238
+
239
+ # ── Tier 2: optional custom scorer — unimplemented/pass-through
240
+ # by default. Skipped entirely when no scorer is configured. ──
241
+ if @tier2_scorer
242
+ score = @tier2_scorer.call(req).to_f
243
+
244
+ if score >= @block_threshold
245
+ actions = execute_actions(:block, ["tier2_ml_score"], req, event_id, now)
246
+ result = Result.new(
247
+ decision: :block, score: score, tier: 2, matched_rules: ["tier2_ml_score"],
248
+ evaluation_time_us: elapsed_us(start), actions: actions, event_id: event_id
249
+ )
250
+ record_audit(result, req)
251
+ relay_to_external(result, req) if @enable_external_relay
252
+ return result
253
+ elsif score >= @rate_limit_threshold
254
+ result = Result.new(
255
+ decision: :rate_limit, score: score, tier: 2, matched_rules: ["tier2_ml_elevated"],
256
+ evaluation_time_us: elapsed_us(start), actions: [], event_id: event_id
257
+ )
258
+ record_audit(result, req)
259
+ return result
260
+ end
261
+ end
262
+
263
+ Result.new(decision: :allow, score: 0, tier: 1, matched_rules: [], evaluation_time_us: elapsed_us(start),
264
+ actions: [], event_id: event_id)
265
+ rescue StandardError => e
266
+ log(:error, "Evaluation error: #{e.message}")
267
+ if @fail_mode == :closed
268
+ Result.new(decision: :block, score: 100, tier: 1, matched_rules: ["fail_closed_error"],
269
+ evaluation_time_us: elapsed_us(start), actions: [], event_id: event_id)
270
+ else
271
+ Result.new(decision: :allow, score: 0, tier: 1, matched_rules: ["fail_open_error"],
272
+ evaluation_time_us: elapsed_us(start), actions: [], event_id: event_id)
273
+ end
274
+ end
275
+ end
276
+
277
+ def block_ip(ip, reason, ttl_seconds: nil)
278
+ ttl = ttl_seconds || @default_block_ttl_seconds
279
+ @blocked_ips.set(ip, BlockEntry.new(expires_at: Time.now.to_f + ttl, reason: reason))
280
+ log(:info, "IP blocked: #{ip} — #{reason} (TTL: #{ttl}s)")
281
+ end
282
+
283
+ def unblock_ip(ip)
284
+ existed = @blocked_ips.has?(ip)
285
+ @blocked_ips.delete(ip)
286
+ log(:info, "IP unblocked: #{ip}") if existed
287
+ existed
288
+ end
289
+
290
+ def block_user(user_id, reason, ttl_seconds: nil)
291
+ ttl = ttl_seconds || @default_block_ttl_seconds
292
+ @blocked_users.set(user_id, BlockEntry.new(expires_at: Time.now.to_f + ttl, reason: reason))
293
+ log(:info, "User blocked: #{user_id} — #{reason}")
294
+ end
295
+
296
+ def block_session(session_id, reason, ttl_seconds: nil)
297
+ ttl = ttl_seconds || @default_block_ttl_seconds
298
+ @blocked_sessions.set(session_id, BlockEntry.new(expires_at: Time.now.to_f + ttl, reason: reason))
299
+ log(:info, "Session blocked: #{session_id} — #{reason}")
300
+ end
301
+
302
+ def quarantine_agent(agent_id, reason)
303
+ @quarantined_agents.set(agent_id, QuarantineEntry.new(reason: reason, timestamp: Time.now.to_f))
304
+ log(:info, "Agent quarantined: #{agent_id} — #{reason}")
305
+ end
306
+
307
+ def unquarantine_agent(agent_id)
308
+ existed = @quarantined_agents.has?(agent_id)
309
+ @quarantined_agents.delete(agent_id)
310
+ log(:info, "Agent unquarantined: #{agent_id}") if existed
311
+ existed
312
+ end
313
+
314
+ # Ruby-idiomatic equivalent of Node's isIPBlocked / Python's
315
+ # is_ip_blocked (dropping the redundant "is_" prefix, matching this
316
+ # SDK's own convention elsewhere, e.g. PlatformCircuitBreaker#rules_stale?).
317
+ def ip_blocked?(ip)
318
+ entry = @blocked_ips.get(ip)
319
+ return false unless entry
320
+ if Time.now.to_f > entry.expires_at
321
+ @blocked_ips.delete(ip)
322
+ return false
323
+ end
324
+ true
325
+ end
326
+
327
+ def agent_quarantined?(agent_id)
328
+ @quarantined_agents.has?(agent_id)
329
+ end
330
+
331
+ def add_rule(rule)
332
+ @rules << rule
333
+ log(:debug, "Rule added: #{rule.name}")
334
+ end
335
+
336
+ def remove_rule(name)
337
+ idx = @rules.find_index { |r| r.name == name }
338
+ return false unless idx
339
+
340
+ @rules.delete_at(idx)
341
+ log(:debug, "Rule removed: #{name}")
342
+ true
343
+ end
344
+
345
+ def rules
346
+ @rules.map do |r|
347
+ { name: r.name, description: r.description, severity: r.severity, score: r.score, decision: r.decision,
348
+ enabled: r.enabled }
349
+ end
350
+ end
351
+
352
+ def audit_log(limit: 100)
353
+ @audit_mutex.synchronize { @audit_log.last(limit) }
354
+ end
355
+
356
+ def stats
357
+ {
358
+ blocked_ips: @blocked_ips.size,
359
+ blocked_users: @blocked_users.size,
360
+ blocked_sessions: @blocked_sessions.size,
361
+ quarantined_agents: @quarantined_agents.size,
362
+ rate_limit_entries: @rate_limiter.size,
363
+ audit_log_size: @audit_mutex.synchronize { @audit_log.length },
364
+ rules_count: @rules.length,
365
+ fail_mode: @fail_mode,
366
+ }
367
+ end
368
+
369
+ def import_blocked_ips(entries)
370
+ count = 0
371
+ entries.each do |entry|
372
+ block_ip(entry[:ip], entry[:reason], ttl_seconds: entry[:ttl_seconds])
373
+ count += 1
374
+ end
375
+ count
376
+ end
377
+
378
+ # Resets all state. For testing.
379
+ def reset!
380
+ @blocked_ips.clear
381
+ @blocked_users.clear
382
+ @blocked_sessions.clear
383
+ @quarantined_agents.clear
384
+ @rate_limiter.clear
385
+ @audit_mutex.synchronize { @audit_log = [] }
386
+ @event_counter_mutex.synchronize { @event_counter = 0 }
387
+ end
388
+
389
+ private
390
+
391
+ def elapsed_us(start)
392
+ (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1_000_000
393
+ end
394
+
395
+ def check_blocked(req, now)
396
+ ip_block = @blocked_ips.get(req.ip)
397
+ if ip_block
398
+ if now > ip_block.expires_at
399
+ @blocked_ips.delete(req.ip)
400
+ else
401
+ return [:block, "ip_blocked:#{ip_block.reason}"]
402
+ end
403
+ end
404
+
405
+ if req.user_id
406
+ user_block = @blocked_users.get(req.user_id)
407
+ if user_block
408
+ if now > user_block.expires_at
409
+ @blocked_users.delete(req.user_id)
410
+ else
411
+ return [:block, "user_blocked:#{user_block.reason}"]
412
+ end
413
+ end
414
+ end
415
+
416
+ if req.session_id
417
+ session_block = @blocked_sessions.get(req.session_id)
418
+ if session_block
419
+ if now > session_block.expires_at
420
+ @blocked_sessions.delete(req.session_id)
421
+ else
422
+ return [:block, "session_blocked:#{session_block.reason}"]
423
+ end
424
+ end
425
+ end
426
+
427
+ if req.agent_id && @quarantined_agents.has?(req.agent_id)
428
+ return [:quarantine, "agent_quarantined:#{req.agent_id}"]
429
+ end
430
+
431
+ nil
432
+ end
433
+
434
+ def evaluate_tier1(req)
435
+ matched_rules = []
436
+ max_score = 0.0
437
+ decision = :allow
438
+
439
+ @rules.each do |rule|
440
+ next unless rule.enabled
441
+
442
+ begin
443
+ if rule.match.call(req)
444
+ matched_rules << rule.name
445
+ if rule.score > max_score
446
+ max_score = rule.score
447
+ decision = rule.decision
448
+ end
449
+ end
450
+ rescue StandardError
451
+ # An individual rule's error must not crash the whole engine.
452
+ log(:error, "Rule #{rule.name} raised an error")
453
+ end
454
+ end
455
+
456
+ [decision, max_score, matched_rules]
457
+ end
458
+
459
+ def check_rate_limit(ip, now)
460
+ entry = @rate_limiter.get(ip)
461
+ return false unless entry
462
+
463
+ window_start = now - @rate_limit_window_seconds
464
+ entry.timestamps = entry.timestamps.select { |t| t > window_start }
465
+ if entry.timestamps.length >= @rate_limit_max
466
+ entry.blocked = true
467
+ return true
468
+ end
469
+ false
470
+ end
471
+
472
+ def record_request(ip, now)
473
+ entry = @rate_limiter.get(ip) || RateLimitEntry.new
474
+ entry.timestamps << now
475
+ @rate_limiter.set(ip, entry)
476
+ end
477
+
478
+ def execute_actions(decision, matched_rules, req, event_id, now)
479
+ actions = []
480
+ ttl = @default_block_ttl_seconds
481
+ reason = matched_rules.join(", ")
482
+
483
+ if decision == :block || decision == :quarantine
484
+ @blocked_ips.set(req.ip, BlockEntry.new(expires_at: now + ttl, reason: reason))
485
+ actions << Action.new(type: :block_ip, target: req.ip, reason: reason, ttl_seconds: ttl, timestamp: now,
486
+ event_id: event_id)
487
+
488
+ if req.session_id
489
+ @blocked_sessions.set(req.session_id, BlockEntry.new(expires_at: now + ttl, reason: reason))
490
+ actions << Action.new(type: :block_session, target: req.session_id, reason: reason, ttl_seconds: ttl,
491
+ timestamp: now, event_id: event_id)
492
+ end
493
+
494
+ if req.agent_id
495
+ @quarantined_agents.set(req.agent_id, QuarantineEntry.new(reason: reason, timestamp: now))
496
+ actions << Action.new(type: :quarantine_agent, target: req.agent_id, reason: reason, ttl_seconds: 0,
497
+ timestamp: now, event_id: event_id)
498
+ end
499
+ end
500
+
501
+ if @on_action
502
+ actions.each do |action|
503
+ begin
504
+ @on_action.call(action)
505
+ rescue StandardError
506
+ log(:error, "on_action callback error for #{action.type}")
507
+ end
508
+ end
509
+ end
510
+
511
+ actions
512
+ end
513
+
514
+ def record_audit(result, req)
515
+ @audit_mutex.synchronize do
516
+ if @audit_log.length >= @max_audit_entries
517
+ @audit_log.shift([1, (@max_audit_entries * 0.1).to_i].max)
518
+ end
519
+
520
+ @audit_log << AuditEntry.new(
521
+ event_id: result.event_id,
522
+ timestamp: req.timestamp || Time.now.to_f,
523
+ ip: req.ip,
524
+ decision: result.decision,
525
+ score: result.score,
526
+ tier: result.tier,
527
+ matched_rules: result.matched_rules,
528
+ user_id: req.user_id,
529
+ agent_id: req.agent_id,
530
+ path: req.path,
531
+ method: req.method,
532
+ )
533
+ end
534
+ end
535
+
536
+ def relay_to_external(result, req)
537
+ # Tier 3: relay via the caller-supplied on_relay callable. This
538
+ # engine has no HTTP client or platform credentials of its own by
539
+ # design — the caller does the actual platform call.
540
+ log(:debug, "Tier 3 relay: #{result.event_id} -> external platform")
541
+ return unless @on_relay
542
+
543
+ begin
544
+ @on_relay.call(result, req)
545
+ rescue StandardError => e
546
+ log(:error, "on_relay callback error for #{result.event_id}: #{e.message}")
547
+ end
548
+ end
549
+
550
+ def generate_event_id
551
+ counter = @event_counter_mutex.synchronize { @event_counter += 1 }
552
+ ts = (Time.now.to_f * 1000).to_i.to_s(16)
553
+ counter_hex = counter.to_s(16).rjust(4, "0")
554
+ rand_hex = rand(0x10000).to_s(16).rjust(4, "0")
555
+ "icl_#{ts}_#{counter_hex}_#{rand_hex}"
556
+ end
557
+
558
+ # Mirrors Node's `.filter(Boolean)` / Python's `if t` filtering: drops
559
+ # both nil and empty-string values, so an absent/empty query string or
560
+ # body never gets regex-matched against (it never would match, but
561
+ # this keeps behaviour identical rather than merely equivalent).
562
+ def present(*values)
563
+ values.reject { |v| v.nil? || v.empty? }
564
+ end
565
+
566
+ def register_default_rules
567
+ @rules << Rule.new(
568
+ name: "sql_injection",
569
+ description: "Detects SQL injection patterns context-aware (strict on path/query, moderate on body)",
570
+ severity: "critical", score: 95, decision: :block, enabled: true,
571
+ match: lambda do |req|
572
+ strict_targets = present(req.path, req.query)
573
+ next true if strict_targets.any? { |t| SQL_INJECTION_STRICT.any? { |p| p.match?(t) } }
574
+ next true if strict_targets.any? { |t| SQL_INJECTION_MODERATE.any? { |p| p.match?(t) } }
575
+
576
+ body_targets = present(req.body, *req.headers.values)
577
+ body_targets.any? { |t| SQL_INJECTION_STRICT.any? { |p| p.match?(t) } }
578
+ end
579
+ )
580
+
581
+ @rules << Rule.new(
582
+ name: "xss_attempt",
583
+ description: "Detects cross-site scripting patterns",
584
+ severity: "high", score: 90, decision: :block, enabled: true,
585
+ match: lambda do |req|
586
+ targets = present(req.path, req.query, req.body)
587
+ targets.any? { |t| XSS_PATTERNS.any? { |p| p.match?(t) } }
588
+ end
589
+ )
590
+
591
+ @rules << Rule.new(
592
+ name: "path_traversal",
593
+ description: "Detects directory traversal attempts",
594
+ severity: "high", score: 90, decision: :block, enabled: true,
595
+ match: lambda do |req|
596
+ targets = present(req.path, req.query)
597
+ targets.any? { |t| PATH_TRAVERSAL_PATTERNS.any? { |p| p.match?(t) } }
598
+ end
599
+ )
600
+
601
+ @rules << Rule.new(
602
+ name: "scanner_detected",
603
+ description: "Detects known vulnerability scanner user agents",
604
+ severity: "medium", score: 75, decision: :block, enabled: true,
605
+ match: lambda do |req|
606
+ next false unless req.user_agent
607
+
608
+ SCANNER_SIGNATURES.any? { |p| p.match?(req.user_agent) }
609
+ end
610
+ )
611
+
612
+ @rules << Rule.new(
613
+ name: "sensitive_file_access",
614
+ description: "Detects access to sensitive files (.env, .git, wp-admin, etc.)",
615
+ severity: "high", score: 85, decision: :block, enabled: true,
616
+ match: ->(req) { SENSITIVE_FILE_PATTERNS.any? { |p| p.match?(req.path) } }
617
+ )
618
+
619
+ @rules << Rule.new(
620
+ name: "credential_stuffing_pattern",
621
+ description: "Detects credential stuffing via POST to auth endpoints",
622
+ severity: "high", score: 80, decision: :rate_limit, enabled: true,
623
+ match: lambda do |req|
624
+ next false unless req.method == "POST"
625
+
626
+ path_lower = req.path.downcase
627
+ AUTH_PATHS.any? { |p| path_lower.include?(p) }
628
+ end
629
+ )
630
+
631
+ @rules << Rule.new(
632
+ name: "agent_unsanctioned_tool",
633
+ description: "Detects agent attempting to use dangerous tools",
634
+ severity: "critical", score: 95, decision: :quarantine, enabled: true,
635
+ match: lambda do |req|
636
+ next false unless req.agent_id && req.tool_name
637
+
638
+ DANGEROUS_TOOLS.include?(req.tool_name.downcase)
639
+ end
640
+ )
641
+ end
642
+
643
+ def log(level, message)
644
+ return if !@debug && level == :debug
645
+
646
+ prefix = "[DevFortress ICL]"
647
+ if @logger
648
+ begin
649
+ @logger.log(level.to_s, "#{prefix} #{message}")
650
+ rescue StandardError
651
+ # A failing logger must not reach the host application either.
652
+ end
653
+ elsif level == :error || level == :warn || @debug
654
+ warn("#{prefix} #{message}")
655
+ end
656
+ end
657
+ end
658
+ end