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
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 2a56a08cba76ca63cc79cf13b4bce8b677330ef3858bc8392db2eea4d4b739cf
|
|
4
|
+
data.tar.gz: 6a1ee3893e3032a6d4bf793def687129eccf60eb1a9acd8dd3150b9c9b13c09c
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 24743f3b35250fb57889c25bfe8540e44d1993ca6b7bb580341f5ab5a20f27d03bf8ac25c89f5dc118bd331fb4694a4edf193125c1040de0a45f78c694df47a6
|
|
7
|
+
data.tar.gz: 743118b44641afefa870501451b74beab030bfd0d7f8f93c32d2ffe89061d508377fefd52cd52ed8ae3a5fd81e142300a80e1236e5e3e9fc75b86cac64228d61
|
data/.gitignore
ADDED
data/Gemfile
ADDED
data/LICENSE
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
Business Source License 1.1
|
|
2
|
+
|
|
3
|
+
Licensor: Duncan Ndegwa / DevFortress
|
|
4
|
+
devfortress.net
|
|
5
|
+
Nairobi, Kenya
|
|
6
|
+
|
|
7
|
+
Licensed Work: DevFortress SDK for Ruby
|
|
8
|
+
The Licensed Work is (c) 2026 Duncan Ndegwa
|
|
9
|
+
|
|
10
|
+
Change Date: Four years from the date each version of the
|
|
11
|
+
Licensed Work is first publicly distributed.
|
|
12
|
+
For devfortress-sdk@0.1.0 (RubyGems), the
|
|
13
|
+
Change Date is 2030-01-01.
|
|
14
|
+
|
|
15
|
+
Change License: Apache License, Version 2.0
|
|
16
|
+
|
|
17
|
+
Additional Use Grant: You may use the Licensed Work to monitor,
|
|
18
|
+
observe, and protect your own applications,
|
|
19
|
+
APIs, and AI agents for security threats,
|
|
20
|
+
provided that you do not use the Licensed Work
|
|
21
|
+
to provide a competing commercial security
|
|
22
|
+
monitoring service or platform to third parties.
|
|
23
|
+
|
|
24
|
+
For commercial licensing, enterprise use, or questions:
|
|
25
|
+
support@devfortress.net
|
|
26
|
+
|
|
27
|
+
-----------------------------------------------------------------------------
|
|
28
|
+
|
|
29
|
+
Business Source License 1.1
|
|
30
|
+
|
|
31
|
+
Terms
|
|
32
|
+
|
|
33
|
+
The Licensor hereby grants you the right to copy, modify, create
|
|
34
|
+
derivative works, redistribute, and make non-production use of the
|
|
35
|
+
Licensed Work. The Licensor may make an Additional Use Grant, above,
|
|
36
|
+
permitting limited production use.
|
|
37
|
+
|
|
38
|
+
Effective on the Change Date, or the fourth anniversary of the first
|
|
39
|
+
publicly available distribution of a specific version of the Licensed
|
|
40
|
+
Work under this License, whichever comes first, the Licensor hereby
|
|
41
|
+
grants you rights under the terms of the Change License, and the
|
|
42
|
+
rights granted in the paragraph above terminate.
|
|
43
|
+
|
|
44
|
+
If your use of the Licensed Work does not comply with the requirements
|
|
45
|
+
currently in effect as described in this License, you must purchase a
|
|
46
|
+
commercial license from the Licensor, refrain from using the Licensed
|
|
47
|
+
Work, or make arrangements with the Licensor for a separate license.
|
|
48
|
+
|
|
49
|
+
For avoidance of doubt, a "Competing Service" means any commercial
|
|
50
|
+
product or service that provides API security monitoring, application
|
|
51
|
+
security monitoring, AI agent security monitoring, session threat
|
|
52
|
+
detection, automated threat response, or credential isolation
|
|
53
|
+
functionality to third parties.
|
|
54
|
+
|
|
55
|
+
Notice
|
|
56
|
+
|
|
57
|
+
The Business Source License (this document, or the "License") is not
|
|
58
|
+
an Open Source license. However, the Licensed Work will eventually be
|
|
59
|
+
made available under an Open Source License, as stated in this License.
|
|
60
|
+
|
|
61
|
+
License text copyright (c) 2017 MariaDB Corporation Ab, All Rights
|
|
62
|
+
Reserved. "Business Source License" is a trademark of MariaDB
|
|
63
|
+
Corporation Ab.
|
data/README.md
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# devfortress-sdk (Ruby)
|
|
2
|
+
|
|
3
|
+
Event reporting client for DevFortress (external mode). Pre-release, not published.
|
|
4
|
+
|
|
5
|
+
Requires Ruby 3.0 or newer. There are no runtime dependencies outside the standard library (`net/http`, `openssl`, `digest`, `json`, `securerandom`, `ipaddr`). A Rack middleware adapter (`devfortress-sdk-rails`, gem name proposed — Duncan's call) lives at `../devfortress-ruby-rails`.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Not published to RubyGems yet. Until it is, reference the local path in your `Gemfile`:
|
|
10
|
+
|
|
11
|
+
```ruby
|
|
12
|
+
gem "devfortress-sdk", path: "../devfortress-ruby"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## The DevFortress Textbook
|
|
16
|
+
|
|
17
|
+
DevFortress implements 34 novel security inventions. Patent Pending.
|
|
18
|
+
|
|
19
|
+
These 34 inventions are documented in depth across 5 volumes.
|
|
20
|
+
|
|
21
|
+
**"Credential Isolation Closed-Loop Security"**
|
|
22
|
+
_Duncan Ndungu Ndegwa — DevFortress, 2026_
|
|
23
|
+
|
|
24
|
+
→ Available on Gumroad: [https://devfortress.gumroad.com/l/master-edition]
|
|
25
|
+
|
|
26
|
+
## Quick start
|
|
27
|
+
|
|
28
|
+
```ruby
|
|
29
|
+
require "devfortress"
|
|
30
|
+
|
|
31
|
+
client = DevFortress::Client.new(ENV.fetch("DEVFORTRESS_API_KEY"))
|
|
32
|
+
|
|
33
|
+
client.track_event(
|
|
34
|
+
"eventType" => "auth_failure",
|
|
35
|
+
"ip" => "203.0.113.7",
|
|
36
|
+
"method" => "POST",
|
|
37
|
+
"path" => "/login",
|
|
38
|
+
"severity" => "MEDIUM",
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
client.close # flushes whatever is still queued
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`track_event` and `track_events` queue events in memory; the queue also flushes itself (synchronously, on the caller's thread) once it reaches the batch size. `flush` sends whatever is queued and `close` flushes on shutdown. `test_connection` sends one test event and reports whether the platform accepts the key.
|
|
45
|
+
|
|
46
|
+
`Client.new(api_key, endpoint = DEFAULT_ENDPOINT, **options)` takes `timeout:` (15s), `retries:` (3 attempts), `batch_size:` (25), `defaults:`, `privacy:` (`"standard"` or `"strict"`), `logger:` (anything responding to `#log(level, message, fields)`), `transport:`, `flush_interval:` (a background `Thread` that flushes on that cadence; `nil`, the default, disables it — callers then flush explicitly), and `mode:` (see below).
|
|
47
|
+
|
|
48
|
+
Delivery never raises into your application. A failed delivery is returned as a `DeliveryResult` from `#flush` and logged through the optional `logger:`. Failed deliveries are retried automatically on network errors and 5xx responses; a 3xx or 4xx response is never retried. Only a missing API key raises, at construction.
|
|
49
|
+
|
|
50
|
+
## Closed-loop mode
|
|
51
|
+
|
|
52
|
+
`mode:` selects the closed-loop delivery mode: `"external"` (default — every event ships to the platform, no behavior change for existing callers), `"internal"` (decisions are made locally, nothing leaves your infrastructure), or `"hybrid"` (local-first, with automatic cloud enrichment and failover). Internal/hybrid require Team tier or above.
|
|
53
|
+
|
|
54
|
+
```ruby
|
|
55
|
+
client = DevFortress::Client.new(
|
|
56
|
+
ENV.fetch("DEVFORTRESS_API_KEY"),
|
|
57
|
+
mode: ENV.fetch("DEVFORTRESS_CL_MODE", "external"),
|
|
58
|
+
)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Reading the mode from a `DEVFORTRESS_CL_MODE` env var (`external`, `internal`, or `hybrid`) is the convention this SDK's demo apps use so the same process can be started in any mode without a code change.
|
|
62
|
+
|
|
63
|
+
## Rack / framework adapters: use `Observer.observe_and_flush`, not `Observer.observe`
|
|
64
|
+
|
|
65
|
+
`DevFortress::Observer` is the shared "classify this request/response, queue an event for it" logic every Ruby adapter should build on (the same role the Go SDK's `Observe`/`ObserveAndFlush` plays for its `net/http` and `gin` adapters):
|
|
66
|
+
|
|
67
|
+
```ruby
|
|
68
|
+
DevFortress::Observer.observe_and_flush(client, DevFortress::Observer::Input.new(
|
|
69
|
+
method: request.request_method,
|
|
70
|
+
path: request.path,
|
|
71
|
+
raw_query: request.query_string,
|
|
72
|
+
status_code: response_status,
|
|
73
|
+
latency_ms: latency_ms,
|
|
74
|
+
user_agent: request.user_agent,
|
|
75
|
+
forwarded_for: request.get_header("HTTP_X_FORWARDED_FOR"),
|
|
76
|
+
real_ip: request.get_header("HTTP_X_REAL_IP"),
|
|
77
|
+
remote_addr: request.get_header("REMOTE_ADDR"),
|
|
78
|
+
))
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`.observe_and_flush` classifies, queues **and delivers** the event in one detached `Thread`, after the response has already gone out, so a single request's event is delivered even under sparse traffic. **`.observe` alone only queues** — without something else to flush the queue (a steady stream of other requests reaching the batch size, `flush_interval:`, or an explicit `#flush`/`#close`), a lone event can sit undelivered indefinitely. This is exactly the gap the Go SDK's gin adapter and `demos/go-non-agentic` had before Brief 10.2 fixed it (enqueued events that never reached the platform under normal, non-bursty traffic) — ported here as `.observe_and_flush` from the start so the Ruby adapter never ships with the same gap. `devfortress-sdk-rails`'s Rack middleware calls `.observe_and_flush`.
|
|
82
|
+
|
|
83
|
+
## Request signing
|
|
84
|
+
|
|
85
|
+
Every request is signed with your API key (contract v2). The key itself is never sent — only a non-secret key ID derived from it.
|
|
86
|
+
|
|
87
|
+
## Webhook verification
|
|
88
|
+
|
|
89
|
+
```ruby
|
|
90
|
+
result = DevFortress::WebhookVerifier.verify(
|
|
91
|
+
raw_body: body, # the bytes exactly as received
|
|
92
|
+
signature: headers["X-DevFortress-Signature"],
|
|
93
|
+
timestamp: headers["X-DevFortress-Timestamp"],
|
|
94
|
+
secret: ENV.fetch("DEVFORTRESS_WEBHOOK_SECRET"),
|
|
95
|
+
nonce_check: ->(nonce) { remember_nonce(nonce) }, # true the first time only
|
|
96
|
+
)
|
|
97
|
+
unless result.valid?
|
|
98
|
+
status = result.reason == "replay_detected" ? 409 : 401
|
|
99
|
+
# ...
|
|
100
|
+
end
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Stale timestamps are rejected. `nonce_check:` is optional; the library keeps no state, so replay tracking is yours.
|
|
104
|
+
|
|
105
|
+
## Request classification
|
|
106
|
+
|
|
107
|
+
`DevFortress::Classifier.build_event` turns a response status plus the request path and query into an event Hash, or `nil` when nothing is worth reporting. It flags suspicious patterns in the path and query string (one percent-decoding pass; a double-encoded payload is a known, deliberate limitation shared with every other SDK — see `contracts/`). `DevFortress::ClientIp.resolve` picks the end-user IP the same way the middleware does: `X-Forwarded-For`, then `X-Real-IP`, then the socket address.
|
|
108
|
+
|
|
109
|
+
## Other modules
|
|
110
|
+
|
|
111
|
+
`DevFortress::UnifiedAuditTrail` merges internal and external closed-loop audit events into one in-memory timeline. `DevFortress::GraduatedRateLimiter` applies alias-scoped rate limiting with multi-stage escalation (observe, warn, soft-limit, hard-block, revoke).
|
|
112
|
+
|
|
113
|
+
## Tests
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
rake test
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
The signing and webhook tests read the shared cross-language vector files from `../../contracts` (set `DEVFORTRESS_CONTRACTS_DIR` to override).
|
|
120
|
+
|
|
121
|
+
License: BUSL-1.1
|
data/Rakefile
ADDED
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
|
|
5
|
+
module DevFortress
|
|
6
|
+
AGENT_ID_MAX_LENGTH = 128
|
|
7
|
+
AGENT_ID_PATTERN = /\A[a-zA-Z0-9_\-.:@]+\z/.freeze
|
|
8
|
+
|
|
9
|
+
# Validate agent ID to prevent injection and ensure safe usage as cache
|
|
10
|
+
# keys and pseudo-URL path segments.
|
|
11
|
+
def self.validate_agent_id(agent_id)
|
|
12
|
+
raise ArgumentError, "agent_id is required and must be a non-empty string" if agent_id.nil? || !agent_id.is_a?(String) || agent_id.empty?
|
|
13
|
+
raise ArgumentError, "agent_id must be at most #{AGENT_ID_MAX_LENGTH} characters" if agent_id.length > AGENT_ID_MAX_LENGTH
|
|
14
|
+
unless AGENT_ID_PATTERN.match?(agent_id)
|
|
15
|
+
raise ArgumentError, "agent_id may only contain alphanumeric characters, hyphens, underscores, dots, colons, and @"
|
|
16
|
+
end
|
|
17
|
+
end
|
|
18
|
+
|
|
19
|
+
# DevFortress Agent Security Adapter (IP-C1).
|
|
20
|
+
#
|
|
21
|
+
# Wraps Client#track_event for AI agent tool invocations. Intercepts
|
|
22
|
+
# agent_id, tool_name, and input_summary from LangChain/LangGraph tool
|
|
23
|
+
# calls, OpenAI function calling, or raw HTTP-based agent tool
|
|
24
|
+
# invocations.
|
|
25
|
+
#
|
|
26
|
+
# Unlike the Node SDK's synchronous df.observe() (which can return a
|
|
27
|
+
# server-decided flagged verdict on the same call), Ruby's Tier 1 Client
|
|
28
|
+
# queues events asynchronously (#track_event/#flush) — there is no
|
|
29
|
+
# per-call server round trip here to carry a flagged verdict back, so
|
|
30
|
+
# this adapter has no on_flagged callback, matching the Go SDK's same
|
|
31
|
+
# adaptation for the same reason. The event shape (agent_id, tool_name,
|
|
32
|
+
# input_summary, framework, session tracking) matches the Node SDK
|
|
33
|
+
# field-for-field.
|
|
34
|
+
class AgentAdapter
|
|
35
|
+
MAX_TRACKED_SESSIONS = 10_000
|
|
36
|
+
|
|
37
|
+
def initialize(client, agent_id:, agent_name: nil, agent_ip: "127.0.0.1",
|
|
38
|
+
max_input_summary_length: 256, sanitize_inputs: true)
|
|
39
|
+
DevFortress.validate_agent_id(agent_id)
|
|
40
|
+
@client = client
|
|
41
|
+
@agent_id = agent_id
|
|
42
|
+
@agent_name = agent_name || agent_id
|
|
43
|
+
@agent_ip = agent_ip
|
|
44
|
+
@max_input_summary_length = max_input_summary_length
|
|
45
|
+
@sanitize_inputs = sanitize_inputs
|
|
46
|
+
@session_tool_counts = {}
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# Queue an observation of an AI agent tool invocation.
|
|
50
|
+
def observe_tool_call(tool:, input: nil, duration_ms: nil, model: nil, framework: "custom", meta: nil, session_id: nil)
|
|
51
|
+
summary = summarize_input(input)
|
|
52
|
+
|
|
53
|
+
sid = session_id || "default"
|
|
54
|
+
@session_tool_counts[sid] = (@session_tool_counts[sid] || 0) + 1
|
|
55
|
+
count = @session_tool_counts[sid]
|
|
56
|
+
|
|
57
|
+
metadata = {
|
|
58
|
+
"agent_id" => @agent_id,
|
|
59
|
+
"agent_name" => @agent_name,
|
|
60
|
+
"tool_name" => tool,
|
|
61
|
+
"input_summary" => summary,
|
|
62
|
+
"duration_ms" => duration_ms,
|
|
63
|
+
"model" => model,
|
|
64
|
+
"framework" => framework || "custom",
|
|
65
|
+
"session_tool_count" => count,
|
|
66
|
+
"session_id" => session_id,
|
|
67
|
+
"event_category" => "agent_tool_call",
|
|
68
|
+
}
|
|
69
|
+
metadata.merge!(meta) if meta
|
|
70
|
+
|
|
71
|
+
@client.track_event(
|
|
72
|
+
"eventType" => "custom",
|
|
73
|
+
"method" => "TOOL_CALL",
|
|
74
|
+
"path" => "/agent/#{@agent_id}/tool/#{tool}",
|
|
75
|
+
"ip" => @agent_ip,
|
|
76
|
+
"userAgent" => "DevFortress-Agent/#{@agent_name}",
|
|
77
|
+
"severity" => "LOW",
|
|
78
|
+
"metadata" => metadata,
|
|
79
|
+
)
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# Convenience wrapper for a LangChain/LangGraph tool call.
|
|
83
|
+
def observe_lang_chain_tool(tool_name, tool_input, session_id: nil, model: nil, duration_ms: nil)
|
|
84
|
+
observe_tool_call(tool: tool_name, input: tool_input, framework: "langchain", model: model,
|
|
85
|
+
duration_ms: duration_ms, session_id: session_id)
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# Convenience wrapper extracting from an OpenAI tool_calls entry.
|
|
89
|
+
def observe_openai_tool_call(function_name, arguments_json, session_id: nil, model: nil, duration_ms: nil)
|
|
90
|
+
parsed = begin
|
|
91
|
+
JSON.parse(arguments_json)
|
|
92
|
+
rescue JSON::ParserError
|
|
93
|
+
{ "raw" => arguments_json }
|
|
94
|
+
end
|
|
95
|
+
observe_tool_call(tool: function_name, input: parsed, framework: "openai", model: model,
|
|
96
|
+
duration_ms: duration_ms, session_id: session_id)
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
# Observe a raw HTTP tool call (e.g. an agent calling an external API).
|
|
100
|
+
def observe_http_tool_call(url, method, status_code: nil, duration_ms: nil, session_id: nil, meta: nil)
|
|
101
|
+
observe_tool_call(
|
|
102
|
+
tool: "http:#{method.to_s.upcase}",
|
|
103
|
+
input: { "url" => url, "status_code" => status_code },
|
|
104
|
+
framework: "raw_http",
|
|
105
|
+
duration_ms: duration_ms,
|
|
106
|
+
meta: meta,
|
|
107
|
+
session_id: session_id,
|
|
108
|
+
)
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
# Track the start of an agent session (task/conversation).
|
|
112
|
+
def track_session_start(session_id, task_description: nil)
|
|
113
|
+
if @session_tool_counts.size >= MAX_TRACKED_SESSIONS
|
|
114
|
+
@session_tool_counts.delete(@session_tool_counts.first[0])
|
|
115
|
+
end
|
|
116
|
+
@session_tool_counts[session_id] = 0
|
|
117
|
+
|
|
118
|
+
@client.track_event(
|
|
119
|
+
"eventType" => "custom",
|
|
120
|
+
"method" => "SESSION_START",
|
|
121
|
+
"path" => "/agent/#{@agent_id}/session/#{session_id}",
|
|
122
|
+
"ip" => @agent_ip,
|
|
123
|
+
"userAgent" => "DevFortress-Agent/#{@agent_name}",
|
|
124
|
+
"severity" => "LOW",
|
|
125
|
+
"metadata" => {
|
|
126
|
+
"agent_id" => @agent_id, "session_id" => session_id,
|
|
127
|
+
"task_description" => task_description, "event_category" => "agent_session_start",
|
|
128
|
+
},
|
|
129
|
+
)
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
# Track the end of an agent session with summary metrics.
|
|
133
|
+
def track_session_end(session_id, total_tools: nil, duration_ms: nil, success: nil)
|
|
134
|
+
tool_count = @session_tool_counts.delete(session_id) || 0
|
|
135
|
+
|
|
136
|
+
@client.track_event(
|
|
137
|
+
"eventType" => "custom",
|
|
138
|
+
"method" => "SESSION_END",
|
|
139
|
+
"path" => "/agent/#{@agent_id}/session/#{session_id}",
|
|
140
|
+
"ip" => @agent_ip,
|
|
141
|
+
"userAgent" => "DevFortress-Agent/#{@agent_name}",
|
|
142
|
+
"severity" => "LOW",
|
|
143
|
+
"metadata" => {
|
|
144
|
+
"agent_id" => @agent_id, "session_id" => session_id,
|
|
145
|
+
"total_tools" => total_tools || tool_count, "total_duration_ms" => duration_ms,
|
|
146
|
+
"success" => success, "event_category" => "agent_session_end",
|
|
147
|
+
},
|
|
148
|
+
)
|
|
149
|
+
end
|
|
150
|
+
|
|
151
|
+
def session_tool_count(session_id)
|
|
152
|
+
@session_tool_counts[session_id] || 0
|
|
153
|
+
end
|
|
154
|
+
|
|
155
|
+
private
|
|
156
|
+
|
|
157
|
+
def summarize_input(input)
|
|
158
|
+
return "{}" unless input
|
|
159
|
+
|
|
160
|
+
summary = {}
|
|
161
|
+
input.each do |key, val|
|
|
162
|
+
summary[key.to_s] =
|
|
163
|
+
if val.nil?
|
|
164
|
+
"null"
|
|
165
|
+
elsif val.is_a?(String)
|
|
166
|
+
key_str = key.to_s.downcase
|
|
167
|
+
if @sanitize_inputs && (key_str.include?("key") || key_str.include?("token") || key_str.include?("secret") || key_str.include?("password"))
|
|
168
|
+
"[REDACTED]"
|
|
169
|
+
else
|
|
170
|
+
val.length > 64 ? "#{val[0, 61]}..." : val
|
|
171
|
+
end
|
|
172
|
+
elsif val.is_a?(Numeric) || val == true || val == false
|
|
173
|
+
val.to_s
|
|
174
|
+
elsif val.is_a?(Array)
|
|
175
|
+
"Array(#{val.length})"
|
|
176
|
+
else
|
|
177
|
+
"{...}"
|
|
178
|
+
end
|
|
179
|
+
end
|
|
180
|
+
|
|
181
|
+
str = JSON.generate(summary)
|
|
182
|
+
str.length > @max_input_summary_length ? "#{str[0, @max_input_summary_length - 3]}..." : str
|
|
183
|
+
end
|
|
184
|
+
end
|
|
185
|
+
end
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
|
|
5
|
+
module DevFortress
|
|
6
|
+
# Agent Loop Detector (A10).
|
|
7
|
+
#
|
|
8
|
+
# Instruments the SDK to track agent execution cycles and token
|
|
9
|
+
# consumption. Detects infinite loops via cycle count, time budget, and
|
|
10
|
+
# token budget thresholds. Implements an automatic circuit breaker: pause
|
|
11
|
+
# agent, alert owner. Distinguishes legitimate long operations from
|
|
12
|
+
# runaway loops via progress metrics. Mirrors
|
|
13
|
+
# packages/devfortress-sdk/src/agent-loop-detector.ts.
|
|
14
|
+
class AgentLoopDetector
|
|
15
|
+
def initialize(max_cycles: 20, max_duration_ms: 120_000, max_tokens: 100_000,
|
|
16
|
+
progress_threshold: { unique_tools: 2, window_cycles: 5 }, max_sessions: 50_000)
|
|
17
|
+
@max_cycles = max_cycles
|
|
18
|
+
@max_duration_ms = max_duration_ms
|
|
19
|
+
@max_tokens = max_tokens
|
|
20
|
+
@progress_threshold = progress_threshold
|
|
21
|
+
@max_sessions = max_sessions
|
|
22
|
+
@sessions = {}
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
# Record a new execution cycle for an agent session.
|
|
26
|
+
def record_cycle(agent_id, session_id, tokens_used: 0, tool_name: nil, tool_args: nil, progress_metric: nil)
|
|
27
|
+
session = get_or_create_session(agent_id, session_id)
|
|
28
|
+
now = now_ms
|
|
29
|
+
|
|
30
|
+
return build_result(session, now, true, "agent_paused", "TERMINATE") if session[:paused]
|
|
31
|
+
|
|
32
|
+
session[:cycles] += 1
|
|
33
|
+
session[:total_tokens] += tokens_used || 0
|
|
34
|
+
session[:tool_history] << tool_name if tool_name
|
|
35
|
+
session[:arg_hashes] << hash_args(tool_args) if tool_args
|
|
36
|
+
session[:progress_metrics] << progress_metric unless progress_metric.nil?
|
|
37
|
+
|
|
38
|
+
elapsed_ms = now - session[:started_at]
|
|
39
|
+
making_progress = check_progress(session)
|
|
40
|
+
repetition_score = compute_repetition_score(session)
|
|
41
|
+
|
|
42
|
+
if session[:cycles] >= @max_cycles && !making_progress
|
|
43
|
+
session[:paused] = true
|
|
44
|
+
return build_result(session, now, true, "max_cycles", "PAUSE_AGENT")
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
if elapsed_ms >= @max_duration_ms
|
|
48
|
+
session[:paused] = true
|
|
49
|
+
return build_result(session, now, true, "max_duration", "PAUSE_AGENT")
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
if session[:total_tokens] >= @max_tokens
|
|
53
|
+
session[:paused] = true
|
|
54
|
+
return build_result(session, now, true, "max_tokens", "PAUSE_AGENT")
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
if repetition_score > 0.8 && session[:cycles] > 5 && !making_progress
|
|
58
|
+
session[:paused] = true
|
|
59
|
+
return build_result(session, now, true, "repetitive_pattern", "PAUSE_AGENT")
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
if session[:cycles] >= @max_cycles * 0.8 || elapsed_ms >= @max_duration_ms * 0.8 || session[:total_tokens] >= @max_tokens * 0.8
|
|
63
|
+
return build_result(session, now, false, "approaching_limit", "WARN")
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
build_result(session, now, false, "within_limits", "CONTINUE")
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
def clear_session(agent_id_or_session_id, session_id = nil)
|
|
70
|
+
key = session_id ? "#{agent_id_or_session_id}:#{session_id}" : agent_id_or_session_id
|
|
71
|
+
@sessions.delete(key)
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
def release_agent(session_id)
|
|
75
|
+
session = @sessions[session_id]
|
|
76
|
+
return false unless session
|
|
77
|
+
|
|
78
|
+
session[:paused] = false
|
|
79
|
+
session[:cycles] = 0
|
|
80
|
+
session[:total_tokens] = 0
|
|
81
|
+
session[:tool_history] = []
|
|
82
|
+
session[:arg_hashes] = []
|
|
83
|
+
true
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def paused?(session_id)
|
|
87
|
+
@sessions[session_id]&.[](:paused) || false
|
|
88
|
+
end
|
|
89
|
+
|
|
90
|
+
def metrics(session_id)
|
|
91
|
+
session = @sessions[session_id]
|
|
92
|
+
return { exists: false, cycles: 0, tokens: 0, elapsed_ms: 0, paused: false } unless session
|
|
93
|
+
|
|
94
|
+
{ exists: true, cycles: session[:cycles], tokens: session[:total_tokens],
|
|
95
|
+
elapsed_ms: now_ms - session[:started_at], paused: session[:paused] }
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
def destroy
|
|
99
|
+
@sessions.clear
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
private
|
|
103
|
+
|
|
104
|
+
def get_or_create_session(agent_id, session_id)
|
|
105
|
+
session = @sessions[session_id]
|
|
106
|
+
unless session
|
|
107
|
+
@sessions.delete(@sessions.first[0]) if @sessions.size >= @max_sessions
|
|
108
|
+
session = { agent_id: agent_id, started_at: now_ms, cycles: 0, total_tokens: 0, tool_history: [],
|
|
109
|
+
arg_hashes: [], progress_metrics: [], paused: false }
|
|
110
|
+
@sessions[session_id] = session
|
|
111
|
+
end
|
|
112
|
+
session
|
|
113
|
+
end
|
|
114
|
+
|
|
115
|
+
def check_progress(session)
|
|
116
|
+
unique_tools = @progress_threshold[:unique_tools]
|
|
117
|
+
window_cycles = @progress_threshold[:window_cycles]
|
|
118
|
+
recent_tools = session[:tool_history].last(window_cycles)
|
|
119
|
+
return true if recent_tools.uniq.length >= unique_tools
|
|
120
|
+
|
|
121
|
+
if session[:progress_metrics].length >= 2
|
|
122
|
+
recent = session[:progress_metrics].last(3)
|
|
123
|
+
increasing = recent.each_cons(2).all? { |a, b| b > a }
|
|
124
|
+
return true if increasing
|
|
125
|
+
end
|
|
126
|
+
|
|
127
|
+
false
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
def compute_repetition_score(session)
|
|
131
|
+
return 0 if session[:arg_hashes].length < 3
|
|
132
|
+
|
|
133
|
+
recent = session[:arg_hashes].last(10)
|
|
134
|
+
unique_hashes = recent.uniq.length
|
|
135
|
+
1 - (unique_hashes.to_f / recent.length)
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
def hash_args(args)
|
|
139
|
+
sorted_keys = args.keys.sort_by(&:to_s)
|
|
140
|
+
sorted = sorted_keys.to_h { |k| [k, args[k]] }
|
|
141
|
+
str = JSON.generate(sorted)
|
|
142
|
+
hash = 0
|
|
143
|
+
str.each_byte do |byte|
|
|
144
|
+
hash = ((hash << 5) - hash + byte) & 0xFFFFFFFF
|
|
145
|
+
end
|
|
146
|
+
# Mirror JS's `| 0` (32-bit signed wraparound) before base-36 encoding.
|
|
147
|
+
hash -= 0x100000000 if hash >= 0x80000000
|
|
148
|
+
hash.to_s(36)
|
|
149
|
+
end
|
|
150
|
+
|
|
151
|
+
def build_result(session, now, loop_detected, reason, action)
|
|
152
|
+
elapsed_ms = now - session[:started_at]
|
|
153
|
+
making_progress = check_progress(session)
|
|
154
|
+
repetition_score = compute_repetition_score(session)
|
|
155
|
+
|
|
156
|
+
{
|
|
157
|
+
loop: loop_detected, reason: reason, action: action, cycles: session[:cycles],
|
|
158
|
+
total_tokens: session[:total_tokens], elapsed_ms: elapsed_ms, making_progress: making_progress,
|
|
159
|
+
repetition_score: repetition_score,
|
|
160
|
+
}
|
|
161
|
+
end
|
|
162
|
+
|
|
163
|
+
def now_ms
|
|
164
|
+
(Time.now.to_f * 1000).to_i
|
|
165
|
+
end
|
|
166
|
+
end
|
|
167
|
+
end
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module DevFortress
|
|
4
|
+
# Agent Output Exfiltration Detector (B7).
|
|
5
|
+
#
|
|
6
|
+
# Monitors AI agent outputs for potential data exfiltration patterns.
|
|
7
|
+
# Detects when agent responses contain sensitive data that shouldn't be
|
|
8
|
+
# included in outputs (PII, credentials, internal system info). Mirrors
|
|
9
|
+
# packages/devfortress-sdk/src/agent-output-exfiltration-detector.ts.
|
|
10
|
+
class AgentOutputExfiltrationDetector
|
|
11
|
+
AgentOutput = Struct.new(:agent_id, :output_content, :output_type, :destination_type, :timestamp,
|
|
12
|
+
keyword_init: true)
|
|
13
|
+
|
|
14
|
+
DEFAULT_SENSITIVE_PATTERNS = [
|
|
15
|
+
# Credit cards
|
|
16
|
+
'\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})\b',
|
|
17
|
+
# SSN
|
|
18
|
+
'\b\d{3}-\d{2}-\d{4}\b',
|
|
19
|
+
# Email addresses in unexpected contexts
|
|
20
|
+
'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b',
|
|
21
|
+
# API keys / tokens (high entropy strings)
|
|
22
|
+
'(?:api[_-]?key|token|secret|password|credential)[\s:=]+["\']?[A-Za-z0-9+/=_-]{20,}["\']?',
|
|
23
|
+
# AWS keys
|
|
24
|
+
'(?:AKIA|ASIA)[A-Z0-9]{16}',
|
|
25
|
+
# Private keys
|
|
26
|
+
'-----BEGIN (?:RSA |EC )?PRIVATE KEY-----',
|
|
27
|
+
# Internal IPs
|
|
28
|
+
'\b(?:10\.|172\.(?:1[6-9]|2[0-9]|3[01])\.|192\.168\.)[0-9.]+\b',
|
|
29
|
+
].freeze
|
|
30
|
+
|
|
31
|
+
def initialize(sensitive_patterns: nil, max_output_size_bytes: 1_048_576, entropy_detection: true,
|
|
32
|
+
entropy_threshold: 4.5)
|
|
33
|
+
@sensitive_patterns = sensitive_patterns || DEFAULT_SENSITIVE_PATTERNS
|
|
34
|
+
@max_output_size_bytes = max_output_size_bytes
|
|
35
|
+
@entropy_detection = entropy_detection
|
|
36
|
+
@entropy_threshold = entropy_threshold
|
|
37
|
+
@compiled_patterns = @sensitive_patterns.map { |p| Regexp.new(p, Regexp::IGNORECASE) }
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
# output: an AgentOutput (or any object responding to #output_content).
|
|
41
|
+
def analyze(output)
|
|
42
|
+
if ENV["FEATURE_PLATFORM_INTEL"] == "false"
|
|
43
|
+
return { detected: false, threat_type: "none", confidence: 0, matched_patterns: [], recommendation: "allow" }
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
if output.output_content.bytesize > @max_output_size_bytes
|
|
47
|
+
return { detected: true, threat_type: "oversized-output", confidence: 0.7, matched_patterns: [],
|
|
48
|
+
recommendation: "warn" }
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
matched_patterns = []
|
|
52
|
+
@compiled_patterns.each_with_index do |pattern, i|
|
|
53
|
+
matched_patterns << @sensitive_patterns[i] if pattern.match?(output.output_content)
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
if matched_patterns.any?
|
|
57
|
+
threat_type =
|
|
58
|
+
if matched_patterns.any? { |p| p.include?("PRIVATE KEY") || p.include?("AKIA") }
|
|
59
|
+
"credential-leak"
|
|
60
|
+
elsif matched_patterns.any? { |p| p.include?("SSN") || p.include?("credit") }
|
|
61
|
+
"pii-leak"
|
|
62
|
+
else
|
|
63
|
+
"system-info-leak"
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
return {
|
|
67
|
+
detected: true,
|
|
68
|
+
threat_type: threat_type,
|
|
69
|
+
confidence: [1, 0.5 + (matched_patterns.length * 0.15)].min,
|
|
70
|
+
matched_patterns: matched_patterns,
|
|
71
|
+
recommendation: threat_type == "credential-leak" ? "block" : "redact",
|
|
72
|
+
redacted_output: redact(output.output_content),
|
|
73
|
+
}
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Entropy detection for unknown secrets
|
|
77
|
+
if @entropy_detection
|
|
78
|
+
high_entropy_segments = find_high_entropy_segments(output.output_content)
|
|
79
|
+
if high_entropy_segments.any?
|
|
80
|
+
return { detected: true, threat_type: "high-entropy-secret", confidence: 0.6,
|
|
81
|
+
matched_patterns: high_entropy_segments, recommendation: "warn" }
|
|
82
|
+
end
|
|
83
|
+
end
|
|
84
|
+
|
|
85
|
+
{ detected: false, threat_type: "none", confidence: 0, matched_patterns: [], recommendation: "allow" }
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
private
|
|
89
|
+
|
|
90
|
+
def redact(content)
|
|
91
|
+
redacted = content
|
|
92
|
+
@compiled_patterns.each { |pattern| redacted = redacted.gsub(pattern, "[REDACTED]") }
|
|
93
|
+
redacted
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
def find_high_entropy_segments(content)
|
|
97
|
+
segments = []
|
|
98
|
+
candidates = content.scan(%r{[A-Za-z0-9+/=_-]{32,}})
|
|
99
|
+
candidates.each do |candidate|
|
|
100
|
+
segments << "#{candidate[0, 20]}..." if shannon_entropy(candidate) > @entropy_threshold
|
|
101
|
+
end
|
|
102
|
+
segments
|
|
103
|
+
end
|
|
104
|
+
|
|
105
|
+
def shannon_entropy(str)
|
|
106
|
+
freq = Hash.new(0)
|
|
107
|
+
str.each_char { |c| freq[c] += 1 }
|
|
108
|
+
len = str.length
|
|
109
|
+
-freq.values.reduce(0.0) do |sum, count|
|
|
110
|
+
p = count.to_f / len
|
|
111
|
+
sum + (p * Math.log2(p))
|
|
112
|
+
end
|
|
113
|
+
end
|
|
114
|
+
end
|
|
115
|
+
end
|