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.
- checksums.yaml +7 -0
- data/.gitignore +4 -0
- data/Gemfile +7 -0
- data/LICENSE +63 -0
- data/README.md +121 -0
- data/Rakefile +11 -0
- data/lib/devfortress/agent_adapter.rb +185 -0
- data/lib/devfortress/agent_loop_detector.rb +167 -0
- data/lib/devfortress/agent_output_exfiltration_detector.rb +115 -0
- data/lib/devfortress/agent_security.rb +431 -0
- data/lib/devfortress/alias_verify.rb +87 -0
- data/lib/devfortress/api_key_aliasing.rb +240 -0
- data/lib/devfortress/bounded_map.rb +80 -0
- data/lib/devfortress/circuit_breaker.rb +149 -0
- data/lib/devfortress/classifier.rb +133 -0
- data/lib/devfortress/client.rb +380 -0
- data/lib/devfortress/client_ip.rb +28 -0
- data/lib/devfortress/clock_drift_detector.rb +71 -0
- data/lib/devfortress/credential_isolation.rb +340 -0
- data/lib/devfortress/credential_vault.rb +93 -0
- data/lib/devfortress/delivery_result.rb +9 -0
- data/lib/devfortress/graduated_rate_limiter.rb +270 -0
- data/lib/devfortress/internal_closed_loop_engine.rb +658 -0
- data/lib/devfortress/license_manager.rb +297 -0
- data/lib/devfortress/observer.rb +62 -0
- data/lib/devfortress/prompt_injection_filter.rb +73 -0
- data/lib/devfortress/response_webhook_client.rb +165 -0
- data/lib/devfortress/shadow_agent_registry.rb +123 -0
- data/lib/devfortress/signer.rb +134 -0
- data/lib/devfortress/telemetry.rb +407 -0
- data/lib/devfortress/tier_gate.rb +294 -0
- data/lib/devfortress/tool_call_sequence_validator.rb +126 -0
- data/lib/devfortress/transport.rb +31 -0
- data/lib/devfortress/unified_audit_trail.rb +213 -0
- data/lib/devfortress/version.rb +5 -0
- data/lib/devfortress/webhook_verification.rb +9 -0
- data/lib/devfortress/webhook_verifier.rb +93 -0
- data/lib/devfortress.rb +96 -0
- metadata +110 -0
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module DevFortress
|
|
4
|
+
# Shadow Agent Registry (B10).
|
|
5
|
+
#
|
|
6
|
+
# Detects and tracks unauthorized ("shadow") AI agents that operate
|
|
7
|
+
# without proper registration. Maintains a registry of known agents and
|
|
8
|
+
# flags unregistered agent-like behavior. Mirrors
|
|
9
|
+
# packages/devfortress-sdk/src/shadow-agent-registry.ts.
|
|
10
|
+
class ShadowAgentRegistry
|
|
11
|
+
DEFAULT_AGENT_PATTERNS = [
|
|
12
|
+
"automated request pattern (>100 req/min)",
|
|
13
|
+
"consistent timing between requests (<50ms variance)",
|
|
14
|
+
"sequential resource enumeration",
|
|
15
|
+
"user-agent indicates bot/automation",
|
|
16
|
+
"no mouse/keyboard entropy in session",
|
|
17
|
+
"API-only access (no page loads)",
|
|
18
|
+
].freeze
|
|
19
|
+
|
|
20
|
+
def initialize(heartbeat_timeout_seconds: 300, agent_patterns: nil, auto_block: false)
|
|
21
|
+
@heartbeat_timeout_seconds = heartbeat_timeout_seconds
|
|
22
|
+
@agent_patterns = agent_patterns || DEFAULT_AGENT_PATTERNS
|
|
23
|
+
@auto_block = auto_block
|
|
24
|
+
@registry = {}
|
|
25
|
+
@shadow_detections = {}
|
|
26
|
+
@stats = { registered_count: 0, active_count: 0, shadow_detections: 0, blocked_shadows: 0 }
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
# Registers a known agent. agent: a Hash with :agent_id, :name, :owner,
|
|
30
|
+
# :permissions (symbol keys) — :registered_at/:last_heartbeat/:active
|
|
31
|
+
# are set here, not supplied by the caller.
|
|
32
|
+
def register(agent)
|
|
33
|
+
if ENV["FEATURE_PLATFORM_INTEL"] == "false"
|
|
34
|
+
return agent.merge(registered_at: 0, last_heartbeat: 0, active: false)
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
registered = agent.merge(registered_at: now_ms, last_heartbeat: now_ms, active: true)
|
|
38
|
+
@registry[agent[:agent_id]] = registered
|
|
39
|
+
@stats[:registered_count] += 1
|
|
40
|
+
@stats[:active_count] += 1
|
|
41
|
+
registered
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
# Records a heartbeat from a registered agent.
|
|
45
|
+
def heartbeat(agent_id)
|
|
46
|
+
agent = @registry[agent_id]
|
|
47
|
+
return false unless agent
|
|
48
|
+
|
|
49
|
+
agent[:last_heartbeat] = now_ms
|
|
50
|
+
agent[:active] = true
|
|
51
|
+
true
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
# Checks whether a request source is a registered agent or a shadow.
|
|
55
|
+
def detect(fingerprint, indicators)
|
|
56
|
+
if ENV["FEATURE_PLATFORM_INTEL"] == "false"
|
|
57
|
+
return { detected: false, agent_fingerprint: fingerprint, indicators: [], confidence: 0,
|
|
58
|
+
recommendation: "monitor", matched_patterns: [] }
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# Check if any registered agent matches this fingerprint
|
|
62
|
+
@registry.each_value do |agent|
|
|
63
|
+
if agent[:agent_id] == fingerprint && agent[:active]
|
|
64
|
+
return { detected: false, agent_fingerprint: fingerprint, indicators: [], confidence: 0,
|
|
65
|
+
recommendation: "monitor", matched_patterns: [] }
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
# Check indicators against known agent patterns
|
|
70
|
+
matched_patterns = @agent_patterns.select do |pattern|
|
|
71
|
+
pattern_key = pattern.split("(").first.strip.downcase
|
|
72
|
+
indicators.any? { |i| i.downcase.include?(pattern_key) }
|
|
73
|
+
end
|
|
74
|
+
|
|
75
|
+
confidence = [1, matched_patterns.length / 3.0].min
|
|
76
|
+
detected = confidence > 0.3
|
|
77
|
+
|
|
78
|
+
if detected
|
|
79
|
+
@stats[:shadow_detections] += 1
|
|
80
|
+
@stats[:blocked_shadows] += 1 if @auto_block && confidence > 0.7
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
result = {
|
|
84
|
+
detected: detected,
|
|
85
|
+
agent_fingerprint: fingerprint,
|
|
86
|
+
indicators: indicators,
|
|
87
|
+
confidence: confidence,
|
|
88
|
+
recommendation: confidence > 0.7 ? (@auto_block ? "block" : "register") : "monitor",
|
|
89
|
+
matched_patterns: matched_patterns,
|
|
90
|
+
}
|
|
91
|
+
@shadow_detections[fingerprint] = result if detected
|
|
92
|
+
result
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
# Prunes inactive agents (no heartbeat within the configured timeout).
|
|
96
|
+
def prune_inactive
|
|
97
|
+
cutoff = now_ms - (@heartbeat_timeout_seconds * 1000)
|
|
98
|
+
pruned = []
|
|
99
|
+
@registry.each do |id, agent|
|
|
100
|
+
if agent[:last_heartbeat] < cutoff
|
|
101
|
+
agent[:active] = false
|
|
102
|
+
@stats[:active_count] -= 1
|
|
103
|
+
pruned << id
|
|
104
|
+
end
|
|
105
|
+
end
|
|
106
|
+
pruned
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
def stats
|
|
110
|
+
@stats.dup
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
def registered
|
|
114
|
+
@registry.values
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
private
|
|
118
|
+
|
|
119
|
+
def now_ms
|
|
120
|
+
(Time.now.to_f * 1000).to_i
|
|
121
|
+
end
|
|
122
|
+
end
|
|
123
|
+
end
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "digest"
|
|
4
|
+
require "openssl"
|
|
5
|
+
require "securerandom"
|
|
6
|
+
|
|
7
|
+
module DevFortress
|
|
8
|
+
# Request integrity headers for every SDK-to-platform call (contract v2).
|
|
9
|
+
#
|
|
10
|
+
# Canonical string: "{METHOD}.{requestTarget}.{timestamp}.{nonce}.{payloadHash}"
|
|
11
|
+
# where METHOD is the uppercase HTTP method, requestTarget is the URL path plus
|
|
12
|
+
# "?query" exactly as sent (no host, no re-encoding), and payloadHash is the
|
|
13
|
+
# lowercase hex SHA-256 of the exact body bytes (the empty string for a request
|
|
14
|
+
# with no body). The signature is the lowercase hex HMAC-SHA256 of that string,
|
|
15
|
+
# keyed with the project API key (UTF-8). The timestamp is Unix epoch
|
|
16
|
+
# milliseconds; the nonce is a dashed UUID v4, fresh for every request attempt.
|
|
17
|
+
# Tolerance is 300 seconds.
|
|
18
|
+
#
|
|
19
|
+
# The API key never travels on a signed request. X-DevFortress-Key-Id is a
|
|
20
|
+
# non-secret identifier derived from the key (first 32 hex characters of its
|
|
21
|
+
# SHA-256); the platform verifies the HMAC with the key it has stored.
|
|
22
|
+
class Signer
|
|
23
|
+
SIGNATURE_VERSION = "2"
|
|
24
|
+
TOLERANCE_SECONDS = 300
|
|
25
|
+
|
|
26
|
+
KEY_ID_HEADER = "X-DevFortress-Key-Id"
|
|
27
|
+
VERSION_HEADER = "X-DevFortress-Signature-Version"
|
|
28
|
+
NONCE_HEADER = "X-DevFortress-Nonce"
|
|
29
|
+
TIMESTAMP_HEADER = "X-DevFortress-Timestamp"
|
|
30
|
+
PAYLOAD_HASH_HEADER = "X-DevFortress-Payload-Hash"
|
|
31
|
+
SIGNATURE_HEADER = "X-DevFortress-Signature"
|
|
32
|
+
|
|
33
|
+
class Error < StandardError; end
|
|
34
|
+
|
|
35
|
+
def initialize(api_key)
|
|
36
|
+
raise Error, "DevFortress: an API key is required" if api_key.nil? || api_key.empty?
|
|
37
|
+
|
|
38
|
+
@api_key = api_key
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# Non-secret key ID: first 32 hex characters of SHA-256 over the UTF-8 key.
|
|
42
|
+
def self.derive_key_id(api_key)
|
|
43
|
+
Digest::SHA256.hexdigest(api_key)[0, 32]
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
def key_id
|
|
47
|
+
self.class.derive_key_id(@api_key)
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# Returns the six signing headers (key ID, version, nonce, timestamp, hash, signature).
|
|
51
|
+
def sign(method, request_target, body, timestamp: nil, nonce: nil)
|
|
52
|
+
ts = timestamp || self.class.now_ms
|
|
53
|
+
n = nonce || self.class.uuid_v4
|
|
54
|
+
digest = self.class.digest(@api_key, method, request_target, ts, n, body)
|
|
55
|
+
|
|
56
|
+
{
|
|
57
|
+
KEY_ID_HEADER => key_id,
|
|
58
|
+
VERSION_HEADER => SIGNATURE_VERSION,
|
|
59
|
+
NONCE_HEADER => n,
|
|
60
|
+
TIMESTAMP_HEADER => ts,
|
|
61
|
+
PAYLOAD_HASH_HEADER => digest[:payload_hash],
|
|
62
|
+
SIGNATURE_HEADER => digest[:signature],
|
|
63
|
+
}
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# Returns "valid", "invalid", "expired", "missing" or "unsupported_version".
|
|
67
|
+
#
|
|
68
|
+
# +headers+ uses the wire header names. Mirrors the platform's check.
|
|
69
|
+
def self.verify(api_key, method, request_target, body, headers, now_ms: nil)
|
|
70
|
+
nonce = headers[NONCE_HEADER]
|
|
71
|
+
ts = headers[TIMESTAMP_HEADER]
|
|
72
|
+
payload_hash = headers[PAYLOAD_HASH_HEADER]
|
|
73
|
+
signature = headers[SIGNATURE_HEADER]
|
|
74
|
+
if blank?(nonce) || blank?(ts) || blank?(payload_hash) || blank?(signature)
|
|
75
|
+
return "missing"
|
|
76
|
+
end
|
|
77
|
+
return "unsupported_version" unless headers[VERSION_HEADER] == SIGNATURE_VERSION
|
|
78
|
+
|
|
79
|
+
expected = digest(api_key, method, request_target, ts, nonce, body)
|
|
80
|
+
hash_ok = secure_compare(expected[:payload_hash], payload_hash.downcase)
|
|
81
|
+
sig_ok = secure_compare(expected[:signature], signature.downcase)
|
|
82
|
+
return "invalid" unless hash_ok && sig_ok
|
|
83
|
+
return "invalid" unless ts.match?(/\A-?[0-9]+\z/)
|
|
84
|
+
|
|
85
|
+
now = now_ms || self.now_ms
|
|
86
|
+
age = (now.to_i - ts.to_i).abs
|
|
87
|
+
age > TOLERANCE_SECONDS * 1000 ? "expired" : "valid"
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
# The request target for a URL: path plus "?query" as written, no scheme,
|
|
91
|
+
# host or fragment, and nothing re-encoded or normalised. An empty path is "/".
|
|
92
|
+
def self.request_target_from_url(url)
|
|
93
|
+
url = url.split("#", 2).first || url
|
|
94
|
+
rest = url.sub(%r{\A[A-Za-z][A-Za-z0-9+.\-]*://[^/?]*}, "")
|
|
95
|
+
return "/#{rest}" if rest.empty? || rest.start_with?("?")
|
|
96
|
+
|
|
97
|
+
rest
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
# A dashed UUID v4 from SecureRandom.
|
|
101
|
+
def self.uuid_v4
|
|
102
|
+
SecureRandom.uuid
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
# Unix epoch milliseconds as a decimal string.
|
|
106
|
+
def self.now_ms
|
|
107
|
+
(Time.now.to_r * 1000).to_i.to_s
|
|
108
|
+
end
|
|
109
|
+
|
|
110
|
+
# Not private: #sign (an instance method) calls this via the explicit
|
|
111
|
+
# `self.class.digest` receiver, which Ruby's `private_class_method`
|
|
112
|
+
# would reject even though both live on this class.
|
|
113
|
+
def self.digest(api_key, method, request_target, timestamp, nonce, body)
|
|
114
|
+
payload_hash = Digest::SHA256.hexdigest(body)
|
|
115
|
+
canonical = "#{method.to_s.upcase}.#{request_target}.#{timestamp}.#{nonce}.#{payload_hash}"
|
|
116
|
+
{
|
|
117
|
+
payload_hash: payload_hash,
|
|
118
|
+
signature: OpenSSL::HMAC.hexdigest("SHA256", api_key, canonical),
|
|
119
|
+
}
|
|
120
|
+
end
|
|
121
|
+
|
|
122
|
+
def self.secure_compare(a, b)
|
|
123
|
+
return false unless a.bytesize == b.bytesize
|
|
124
|
+
|
|
125
|
+
OpenSSL.fixed_length_secure_compare(a, b)
|
|
126
|
+
end
|
|
127
|
+
private_class_method :secure_compare
|
|
128
|
+
|
|
129
|
+
def self.blank?(value)
|
|
130
|
+
value.nil? || value.empty?
|
|
131
|
+
end
|
|
132
|
+
private_class_method :blank?
|
|
133
|
+
end
|
|
134
|
+
end
|
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
require "thread"
|
|
5
|
+
|
|
6
|
+
require_relative "signer"
|
|
7
|
+
require_relative "transport"
|
|
8
|
+
require_relative "version"
|
|
9
|
+
|
|
10
|
+
module DevFortress
|
|
11
|
+
# Telemetry Heartbeat — CV-M2.
|
|
12
|
+
#
|
|
13
|
+
# Sends anonymised usage telemetry to the platform periodically (default
|
|
14
|
+
# every 5 minutes). No PII is transmitted — only aggregate counts and
|
|
15
|
+
# operational metadata.
|
|
16
|
+
#
|
|
17
|
+
# If the heartbeat stops, the platform dashboard shows: "SDK offline —
|
|
18
|
+
# upgrade to Hybrid for guaranteed visibility." Mirrors
|
|
19
|
+
# packages/devfortress-sdk/src/telemetry.ts.
|
|
20
|
+
#
|
|
21
|
+
# A background periodic-heartbeat thread is only started if
|
|
22
|
+
# heartbeat_interval_seconds is given and positive (mirrors Client's own
|
|
23
|
+
# opt-in flush_interval convention) — #send_heartbeat is always callable
|
|
24
|
+
# directly, which is what the test suite uses.
|
|
25
|
+
class TelemetryManager
|
|
26
|
+
DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 5 * 60 # 5 minutes
|
|
27
|
+
DEFAULT_TIMEOUT_SECONDS = 5
|
|
28
|
+
MAX_LATENCY_SAMPLES = 100
|
|
29
|
+
INITIAL_HEARTBEAT_DELAY_SECONDS = 5
|
|
30
|
+
|
|
31
|
+
def initialize(
|
|
32
|
+
api_key:,
|
|
33
|
+
endpoint:,
|
|
34
|
+
heartbeat_interval_seconds: nil,
|
|
35
|
+
debug: false,
|
|
36
|
+
timeout: DEFAULT_TIMEOUT_SECONDS,
|
|
37
|
+
transport: nil
|
|
38
|
+
)
|
|
39
|
+
@api_key = api_key
|
|
40
|
+
@endpoint = endpoint
|
|
41
|
+
@signer = Signer.new(api_key)
|
|
42
|
+
@heartbeat_interval_seconds = heartbeat_interval_seconds
|
|
43
|
+
@debug = debug
|
|
44
|
+
@timeout = timeout
|
|
45
|
+
@transport = transport || Transport.new
|
|
46
|
+
|
|
47
|
+
@event_count = 0
|
|
48
|
+
@block_count = 0
|
|
49
|
+
@rate_limit_count = 0
|
|
50
|
+
@latencies = []
|
|
51
|
+
|
|
52
|
+
@started_at = now_ms
|
|
53
|
+
@snapshot_provider = nil
|
|
54
|
+
|
|
55
|
+
@mutex = Mutex.new
|
|
56
|
+
@heartbeat_thread = nil
|
|
57
|
+
@stop = false
|
|
58
|
+
@stop_cv = ConditionVariable.new
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# Starts sending periodic heartbeats if heartbeat_interval_seconds was
|
|
62
|
+
# configured and positive. snapshot_provider, if given, is a callable
|
|
63
|
+
# (#call) returning a Hash with symbol keys (:cl_mode, :tier,
|
|
64
|
+
# :sdk_version, :model_expired, :license_degraded, :integrity_hash)
|
|
65
|
+
# used to enrich each heartbeat with live SDK state.
|
|
66
|
+
def start(snapshot_provider: nil)
|
|
67
|
+
return if @heartbeat_thread
|
|
68
|
+
|
|
69
|
+
@snapshot_provider = snapshot_provider
|
|
70
|
+
@started_at = now_ms
|
|
71
|
+
return unless @heartbeat_interval_seconds && @heartbeat_interval_seconds.positive?
|
|
72
|
+
|
|
73
|
+
@heartbeat_thread = Thread.new { periodic_heartbeat }
|
|
74
|
+
log(:info, "Telemetry heartbeat started (interval: #{@heartbeat_interval_seconds}s)")
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
def record_event
|
|
78
|
+
@mutex.synchronize { @event_count += 1 }
|
|
79
|
+
end
|
|
80
|
+
|
|
81
|
+
def record_block
|
|
82
|
+
@mutex.synchronize { @block_count += 1 }
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
def record_rate_limit
|
|
86
|
+
@mutex.synchronize { @rate_limit_count += 1 }
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# Records observe latency for p99 calculation (bounded reservoir
|
|
90
|
+
# sampling, matching the Node source).
|
|
91
|
+
def record_latency(latency_ms)
|
|
92
|
+
@mutex.synchronize do
|
|
93
|
+
if @latencies.length >= MAX_LATENCY_SAMPLES
|
|
94
|
+
idx = rand(@latencies.length)
|
|
95
|
+
@latencies[idx] = latency_ms
|
|
96
|
+
else
|
|
97
|
+
@latencies << latency_ms
|
|
98
|
+
end
|
|
99
|
+
end
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
# Sends a heartbeat to the platform. Fire-and-forget — failures are
|
|
103
|
+
# logged, never raised. Public (rather than private, as on the Node
|
|
104
|
+
# source) so it can be called directly in tests without waiting on the
|
|
105
|
+
# background thread's timing.
|
|
106
|
+
def send_heartbeat
|
|
107
|
+
enriched = @snapshot_provider ? (@snapshot_provider.call || {}) : {}
|
|
108
|
+
|
|
109
|
+
snapshot = {
|
|
110
|
+
"eventCount" => @event_count,
|
|
111
|
+
"blockCount" => @block_count,
|
|
112
|
+
"rateLimitCount" => @rate_limit_count,
|
|
113
|
+
"clMode" => enriched[:cl_mode] || "external",
|
|
114
|
+
"tier" => enriched[:tier] || "starter",
|
|
115
|
+
"sdkVersion" => enriched[:sdk_version] || VERSION,
|
|
116
|
+
"modelExpired" => enriched.fetch(:model_expired, false),
|
|
117
|
+
"licenseDegraded" => enriched.fetch(:license_degraded, false),
|
|
118
|
+
"integrityHash" => enriched[:integrity_hash] || "",
|
|
119
|
+
"uptimeSeconds" => ((now_ms - @started_at) / 1000),
|
|
120
|
+
"p99LatencyMs" => compute_p99,
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
url = "#{@endpoint}/api/sdk/heartbeat"
|
|
124
|
+
body = JSON.generate(snapshot.merge("timestamp" => now_ms))
|
|
125
|
+
headers = @signer.sign("POST", Signer.request_target_from_url(url), body)
|
|
126
|
+
headers["Content-Type"] = "application/json"
|
|
127
|
+
|
|
128
|
+
begin
|
|
129
|
+
@transport.send_request("POST", url, headers, body, @timeout)
|
|
130
|
+
log(:debug,
|
|
131
|
+
"Heartbeat sent: events=#{snapshot['eventCount']}, blocks=#{snapshot['blockCount']}, " \
|
|
132
|
+
"uptime=#{snapshot['uptimeSeconds']}s")
|
|
133
|
+
@mutex.synchronize do
|
|
134
|
+
@event_count = 0
|
|
135
|
+
@block_count = 0
|
|
136
|
+
@rate_limit_count = 0
|
|
137
|
+
@latencies = []
|
|
138
|
+
end
|
|
139
|
+
rescue StandardError => e
|
|
140
|
+
log(:debug, "Heartbeat failed: #{e.message}")
|
|
141
|
+
end
|
|
142
|
+
end
|
|
143
|
+
|
|
144
|
+
# Current telemetry state (for diagnostics).
|
|
145
|
+
def state
|
|
146
|
+
@mutex.synchronize do
|
|
147
|
+
{
|
|
148
|
+
event_count: @event_count,
|
|
149
|
+
block_count: @block_count,
|
|
150
|
+
rate_limit_count: @rate_limit_count,
|
|
151
|
+
uptime_seconds: ((now_ms - @started_at) / 1000),
|
|
152
|
+
}
|
|
153
|
+
end
|
|
154
|
+
end
|
|
155
|
+
|
|
156
|
+
# Stops sending heartbeats and clean up. Safe to call more than once.
|
|
157
|
+
def destroy
|
|
158
|
+
@mutex.synchronize do
|
|
159
|
+
@stop = true
|
|
160
|
+
@stop_cv.broadcast
|
|
161
|
+
end
|
|
162
|
+
@heartbeat_thread&.join
|
|
163
|
+
@heartbeat_thread = nil
|
|
164
|
+
end
|
|
165
|
+
|
|
166
|
+
private
|
|
167
|
+
|
|
168
|
+
def periodic_heartbeat
|
|
169
|
+
# Send the first heartbeat after a short delay so #start doesn't
|
|
170
|
+
# block init, then on the configured interval thereafter.
|
|
171
|
+
stop = @mutex.synchronize do
|
|
172
|
+
@stop_cv.wait(@mutex, INITIAL_HEARTBEAT_DELAY_SECONDS)
|
|
173
|
+
@stop
|
|
174
|
+
end
|
|
175
|
+
return if stop
|
|
176
|
+
|
|
177
|
+
send_heartbeat
|
|
178
|
+
|
|
179
|
+
loop do
|
|
180
|
+
stop = @mutex.synchronize do
|
|
181
|
+
@stop_cv.wait(@mutex, @heartbeat_interval_seconds)
|
|
182
|
+
@stop
|
|
183
|
+
end
|
|
184
|
+
break if stop
|
|
185
|
+
|
|
186
|
+
send_heartbeat
|
|
187
|
+
end
|
|
188
|
+
end
|
|
189
|
+
|
|
190
|
+
def compute_p99
|
|
191
|
+
return 0 if @latencies.empty?
|
|
192
|
+
|
|
193
|
+
sorted = @latencies.sort
|
|
194
|
+
idx = (sorted.length * 0.99).floor
|
|
195
|
+
sorted[[idx, sorted.length - 1].min]
|
|
196
|
+
end
|
|
197
|
+
|
|
198
|
+
def now_ms
|
|
199
|
+
(Time.now.to_f * 1000).to_i
|
|
200
|
+
end
|
|
201
|
+
|
|
202
|
+
def log(level, message)
|
|
203
|
+
return if level == :debug && !@debug
|
|
204
|
+
|
|
205
|
+
prefix = "[DevFortress:Telemetry]"
|
|
206
|
+
case level
|
|
207
|
+
when :warn
|
|
208
|
+
warn("#{prefix} #{message}")
|
|
209
|
+
else
|
|
210
|
+
puts("#{prefix} #{message}")
|
|
211
|
+
end
|
|
212
|
+
end
|
|
213
|
+
end
|
|
214
|
+
|
|
215
|
+
# Anomaly-Gated Metering: Aggregate Telemetry Rollup Buffer.
|
|
216
|
+
#
|
|
217
|
+
# Option B (2026-08-27): CLEAN/unflagged traffic no longer gets a full,
|
|
218
|
+
# billed LiveThreatEvent row per request. Instead, this buffer
|
|
219
|
+
# accumulates lightweight per-alias/IP-per-hour counters in memory
|
|
220
|
+
# (request count, unique endpoints seen, error count, latency sum) and
|
|
221
|
+
# flushes them as a small number of upsert-increment rows to
|
|
222
|
+
# /api/events/telemetry-rollup on a short interval — not per request.
|
|
223
|
+
# This is what feeds B1/B10's population-level baseline needs without
|
|
224
|
+
# counting toward the customer's billed event quota (see
|
|
225
|
+
# AliasTelemetryRollup in prisma/schema.prisma and
|
|
226
|
+
# DF-Session-task-report-27-08-26.md, Section 1/4). Mirrors
|
|
227
|
+
# packages/devfortress-sdk/src/telemetry-rollup-buffer.ts.
|
|
228
|
+
#
|
|
229
|
+
# The Node source keys its in-memory buckets on a NUL-byte string
|
|
230
|
+
# concatenation (`"#{aliasOrIpKey}\x00#{periodKey}"`) as a
|
|
231
|
+
# collision-free composite map key. This port uses BucketKey, a frozen
|
|
232
|
+
# Struct of (alias_or_ip_key, period_key), as the Hash key instead — the
|
|
233
|
+
# same collision-free bucketing semantics, without embedding a control
|
|
234
|
+
# character in a string.
|
|
235
|
+
class TelemetryRollupBuffer
|
|
236
|
+
# Bounded per-bucket endpoint tracking — uniqueEndpoints is an
|
|
237
|
+
# approximation (this is non-billing, best-effort aggregate
|
|
238
|
+
# telemetry, not an exact count).
|
|
239
|
+
MAX_ENDPOINTS_TRACKED_PER_BUCKET = 50
|
|
240
|
+
# Matches TelemetryManager's DEFAULT_HEARTBEAT_INTERVAL_SECONDS — this
|
|
241
|
+
# is aggregate, non-billing telemetry, not real-time-critical, so a
|
|
242
|
+
# wider batching window means fewer platform requests.
|
|
243
|
+
DEFAULT_FLUSH_INTERVAL_SECONDS = 5 * 60
|
|
244
|
+
DEFAULT_MAX_BUFFERED_KEYS = 500
|
|
245
|
+
DEFAULT_TIMEOUT_SECONDS = 10
|
|
246
|
+
|
|
247
|
+
BucketKey = Struct.new(:alias_or_ip_key, :period_key)
|
|
248
|
+
|
|
249
|
+
# Hour-bucket period key, e.g. "2026-08-27T14" (UTC) — matches
|
|
250
|
+
# AliasTelemetryRollup.periodKey.
|
|
251
|
+
def self.hourly_period_key(time = Time.now)
|
|
252
|
+
time.utc.strftime("%Y-%m-%dT%H")
|
|
253
|
+
end
|
|
254
|
+
|
|
255
|
+
def initialize(
|
|
256
|
+
api_key:,
|
|
257
|
+
endpoint:,
|
|
258
|
+
flush_interval_seconds: nil,
|
|
259
|
+
max_buffered_keys: DEFAULT_MAX_BUFFERED_KEYS,
|
|
260
|
+
debug: false,
|
|
261
|
+
timeout: DEFAULT_TIMEOUT_SECONDS,
|
|
262
|
+
transport: nil
|
|
263
|
+
)
|
|
264
|
+
@api_key = api_key
|
|
265
|
+
@endpoint = endpoint
|
|
266
|
+
@signer = Signer.new(api_key)
|
|
267
|
+
@flush_interval_seconds = flush_interval_seconds
|
|
268
|
+
@max_buffered_keys = max_buffered_keys || DEFAULT_MAX_BUFFERED_KEYS
|
|
269
|
+
@debug = debug
|
|
270
|
+
@timeout = timeout
|
|
271
|
+
@transport = transport || Transport.new
|
|
272
|
+
|
|
273
|
+
@buckets = {}
|
|
274
|
+
@mutex = Mutex.new
|
|
275
|
+
@flush_thread = nil
|
|
276
|
+
@stop = false
|
|
277
|
+
@stop_cv = ConditionVariable.new
|
|
278
|
+
end
|
|
279
|
+
|
|
280
|
+
# Starts the periodic flush thread, if flush_interval_seconds was
|
|
281
|
+
# configured and positive. Safe to call multiple times (no-op if
|
|
282
|
+
# already started).
|
|
283
|
+
def start
|
|
284
|
+
return if @flush_thread
|
|
285
|
+
return unless @flush_interval_seconds && @flush_interval_seconds.positive?
|
|
286
|
+
|
|
287
|
+
@flush_thread = Thread.new { periodic_flush }
|
|
288
|
+
end
|
|
289
|
+
|
|
290
|
+
# Buffers one clean (non-flagged) request's contribution. Synchronous,
|
|
291
|
+
# no network call — actual delivery happens on the next #flush.
|
|
292
|
+
def add(alias_or_ip_key:, endpoint:, is_error:, latency_ms:)
|
|
293
|
+
period_key = self.class.hourly_period_key
|
|
294
|
+
key = BucketKey.new(alias_or_ip_key, period_key)
|
|
295
|
+
now = now_ms
|
|
296
|
+
force_flush = false
|
|
297
|
+
|
|
298
|
+
@mutex.synchronize do
|
|
299
|
+
bucket = @buckets[key]
|
|
300
|
+
unless bucket
|
|
301
|
+
# Bound total buffered keys so a burst of unique IPs can't grow
|
|
302
|
+
# memory unbounded — force an early flush and drop this one
|
|
303
|
+
# contribution. Acceptable: this is approximate, non-billing
|
|
304
|
+
# aggregate telemetry.
|
|
305
|
+
if @buckets.size >= @max_buffered_keys
|
|
306
|
+
force_flush = true
|
|
307
|
+
else
|
|
308
|
+
bucket = {
|
|
309
|
+
alias_or_ip_key: alias_or_ip_key,
|
|
310
|
+
period_key: period_key,
|
|
311
|
+
request_count: 0,
|
|
312
|
+
endpoints: {},
|
|
313
|
+
error_count: 0,
|
|
314
|
+
latency_sum_ms: 0,
|
|
315
|
+
window_start: now,
|
|
316
|
+
window_end: now,
|
|
317
|
+
}
|
|
318
|
+
@buckets[key] = bucket
|
|
319
|
+
end
|
|
320
|
+
end
|
|
321
|
+
|
|
322
|
+
if bucket
|
|
323
|
+
bucket[:request_count] += 1
|
|
324
|
+
bucket[:endpoints][endpoint] = true if bucket[:endpoints].size < MAX_ENDPOINTS_TRACKED_PER_BUCKET
|
|
325
|
+
bucket[:error_count] += 1 if is_error
|
|
326
|
+
bucket[:latency_sum_ms] += latency_ms
|
|
327
|
+
bucket[:window_end] = now
|
|
328
|
+
end
|
|
329
|
+
end
|
|
330
|
+
|
|
331
|
+
flush if force_flush
|
|
332
|
+
end
|
|
333
|
+
|
|
334
|
+
# Flushes all buffered buckets to the platform in one batch request.
|
|
335
|
+
def flush
|
|
336
|
+
contributions = @mutex.synchronize do
|
|
337
|
+
break nil if @buckets.empty?
|
|
338
|
+
|
|
339
|
+
list = @buckets.values.map do |b|
|
|
340
|
+
{
|
|
341
|
+
"aliasOrIpKey" => b[:alias_or_ip_key],
|
|
342
|
+
"periodKey" => b[:period_key],
|
|
343
|
+
"requestCount" => b[:request_count],
|
|
344
|
+
"uniqueEndpointsInBatch" => b[:endpoints].size,
|
|
345
|
+
"errorCount" => b[:error_count],
|
|
346
|
+
"latencySumMs" => b[:latency_sum_ms],
|
|
347
|
+
"windowStart" => b[:window_start],
|
|
348
|
+
"windowEnd" => b[:window_end],
|
|
349
|
+
}
|
|
350
|
+
end
|
|
351
|
+
@buckets.clear
|
|
352
|
+
list
|
|
353
|
+
end
|
|
354
|
+
return if contributions.nil?
|
|
355
|
+
|
|
356
|
+
post(contributions)
|
|
357
|
+
end
|
|
358
|
+
|
|
359
|
+
# Cleans up the flush thread and drops any unflushed buckets.
|
|
360
|
+
def destroy
|
|
361
|
+
@mutex.synchronize do
|
|
362
|
+
@stop = true
|
|
363
|
+
@stop_cv.broadcast
|
|
364
|
+
@buckets.clear
|
|
365
|
+
end
|
|
366
|
+
@flush_thread&.join
|
|
367
|
+
@flush_thread = nil
|
|
368
|
+
end
|
|
369
|
+
|
|
370
|
+
private
|
|
371
|
+
|
|
372
|
+
def periodic_flush
|
|
373
|
+
loop do
|
|
374
|
+
stop = @mutex.synchronize do
|
|
375
|
+
@stop_cv.wait(@mutex, @flush_interval_seconds)
|
|
376
|
+
@stop
|
|
377
|
+
end
|
|
378
|
+
break if stop
|
|
379
|
+
|
|
380
|
+
flush
|
|
381
|
+
end
|
|
382
|
+
end
|
|
383
|
+
|
|
384
|
+
def post(contributions)
|
|
385
|
+
url = "#{@endpoint}/api/events/telemetry-rollup"
|
|
386
|
+
body = JSON.generate({ "contributions" => contributions })
|
|
387
|
+
headers = @signer.sign("POST", Signer.request_target_from_url(url), body)
|
|
388
|
+
headers["Content-Type"] = "application/json"
|
|
389
|
+
@transport.send_request("POST", url, headers, body, @timeout)
|
|
390
|
+
rescue StandardError => e
|
|
391
|
+
# Best-effort — aggregate telemetry is not billing-relevant, so
|
|
392
|
+
# dropping a batch on transient failure is acceptable (unlike the
|
|
393
|
+
# full event relay path, which retries).
|
|
394
|
+
log(:debug, "telemetry rollup flush failed: #{e.message}")
|
|
395
|
+
end
|
|
396
|
+
|
|
397
|
+
def now_ms
|
|
398
|
+
(Time.now.to_f * 1000).to_i
|
|
399
|
+
end
|
|
400
|
+
|
|
401
|
+
def log(level, message)
|
|
402
|
+
return if level == :debug && !@debug
|
|
403
|
+
|
|
404
|
+
puts("[DevFortress:TelemetryRollup] #{message}")
|
|
405
|
+
end
|
|
406
|
+
end
|
|
407
|
+
end
|