guardrail-middleware 0.1.0__py3-none-any.whl
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.
- guardrail_middleware/__init__.py +43 -0
- guardrail_middleware/audit.py +88 -0
- guardrail_middleware/detectors.py +336 -0
- guardrail_middleware/engine.py +136 -0
- guardrail_middleware/fastapi.py +139 -0
- guardrail_middleware/models.py +143 -0
- guardrail_middleware/policy.py +117 -0
- guardrail_middleware-0.1.0.dist-info/METADATA +160 -0
- guardrail_middleware-0.1.0.dist-info/RECORD +12 -0
- guardrail_middleware-0.1.0.dist-info/WHEEL +5 -0
- guardrail_middleware-0.1.0.dist-info/licenses/LICENSE +21 -0
- guardrail_middleware-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""guardrail-middleware — runtime authorization for AI agent tool calls.
|
|
2
|
+
|
|
3
|
+
GuardRail sits between an AI agent and its tools. Every proposed action is
|
|
4
|
+
checked against a policy — authorization, prompt-injection and taint
|
|
5
|
+
detectors, financial and bulk limits — *before* it executes, and every
|
|
6
|
+
decision is written to a tamper-evident, hash-chained audit log.
|
|
7
|
+
|
|
8
|
+
Quick start::
|
|
9
|
+
|
|
10
|
+
from guardrail_middleware import Guardrail
|
|
11
|
+
|
|
12
|
+
guard = Guardrail()
|
|
13
|
+
decision = guard.evaluate({
|
|
14
|
+
"tool": "payments", "operation": "payment",
|
|
15
|
+
"target_resource": "vendor/acme",
|
|
16
|
+
"parameters": {"amount": 42000},
|
|
17
|
+
"agent_role": "support",
|
|
18
|
+
})
|
|
19
|
+
print(decision.verdict) # ESCALATE_TO_HUMAN
|
|
20
|
+
|
|
21
|
+
Extracted from the GuardRail project (Infosys Ignite EngNext 2026, special
|
|
22
|
+
recognition) so any agent stack can use the same enforcement core.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from .audit import AuditLog
|
|
26
|
+
from .engine import Guardrail
|
|
27
|
+
from .models import ActionRequest, Decision, Finding, TriggeredBy, Verdict
|
|
28
|
+
from .policy import DEFAULT_POLICY, Policy
|
|
29
|
+
|
|
30
|
+
__version__ = "0.1.0"
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"Guardrail",
|
|
34
|
+
"Policy",
|
|
35
|
+
"DEFAULT_POLICY",
|
|
36
|
+
"AuditLog",
|
|
37
|
+
"ActionRequest",
|
|
38
|
+
"Decision",
|
|
39
|
+
"Finding",
|
|
40
|
+
"Verdict",
|
|
41
|
+
"TriggeredBy",
|
|
42
|
+
"__version__",
|
|
43
|
+
]
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"""Append-only, hash-chained audit log.
|
|
2
|
+
|
|
3
|
+
Every decision GuardRail makes is recorded as one JSON line. Each entry
|
|
4
|
+
carries the SHA-256 hash of the previous entry, so any later edit, deletion,
|
|
5
|
+
or reordering of the log breaks the chain and is detectable with
|
|
6
|
+
:meth:`AuditLog.verify`.
|
|
7
|
+
|
|
8
|
+
The log is deliberately boring: a file on disk, one line per decision, no
|
|
9
|
+
database required. Point it at shared storage if several processes write.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import hashlib
|
|
15
|
+
import json
|
|
16
|
+
import threading
|
|
17
|
+
from datetime import datetime, timezone
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
from typing import Any, Optional, Union
|
|
20
|
+
|
|
21
|
+
_GENESIS = "0" * 64
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _entry_hash(payload: dict[str, Any]) -> str:
|
|
25
|
+
canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
|
|
26
|
+
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class AuditLog:
|
|
30
|
+
"""Thread-safe append-only audit log with a SHA-256 hash chain."""
|
|
31
|
+
|
|
32
|
+
def __init__(self, path: Union[str, Path]) -> None:
|
|
33
|
+
self._path = Path(path)
|
|
34
|
+
self._lock = threading.Lock()
|
|
35
|
+
self._last_hash = self._read_last_hash()
|
|
36
|
+
|
|
37
|
+
def _read_last_hash(self) -> str:
|
|
38
|
+
if not self._path.exists():
|
|
39
|
+
return _GENESIS
|
|
40
|
+
last = _GENESIS
|
|
41
|
+
with open(self._path, "r", encoding="utf-8") as fh:
|
|
42
|
+
for line in fh:
|
|
43
|
+
line = line.strip()
|
|
44
|
+
if line:
|
|
45
|
+
try:
|
|
46
|
+
last = json.loads(line)["entry_hash"]
|
|
47
|
+
except (json.JSONDecodeError, KeyError):
|
|
48
|
+
continue
|
|
49
|
+
return last
|
|
50
|
+
|
|
51
|
+
def record(self, *, action: dict[str, Any], decision: dict[str, Any]) -> str:
|
|
52
|
+
"""Append one decision; returns the new entry's hash."""
|
|
53
|
+
with self._lock:
|
|
54
|
+
payload = {
|
|
55
|
+
"ts": datetime.now(timezone.utc).isoformat(),
|
|
56
|
+
"prev_hash": self._last_hash,
|
|
57
|
+
"action": action,
|
|
58
|
+
"decision": decision,
|
|
59
|
+
}
|
|
60
|
+
entry_hash = _entry_hash(payload)
|
|
61
|
+
entry = {**payload, "entry_hash": entry_hash}
|
|
62
|
+
self._path.parent.mkdir(parents=True, exist_ok=True)
|
|
63
|
+
with open(self._path, "a", encoding="utf-8") as fh:
|
|
64
|
+
fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
|
|
65
|
+
self._last_hash = entry_hash
|
|
66
|
+
return entry_hash
|
|
67
|
+
|
|
68
|
+
def verify(self) -> dict[str, Any]:
|
|
69
|
+
"""Recompute the whole chain. Returns {ok, entries, broken_at}."""
|
|
70
|
+
prev = _GENESIS
|
|
71
|
+
count = 0
|
|
72
|
+
if not self._path.exists():
|
|
73
|
+
return {"ok": True, "entries": 0, "broken_at": None}
|
|
74
|
+
with open(self._path, "r", encoding="utf-8") as fh:
|
|
75
|
+
for idx, line in enumerate(fh):
|
|
76
|
+
line = line.strip()
|
|
77
|
+
if not line:
|
|
78
|
+
continue
|
|
79
|
+
try:
|
|
80
|
+
entry = json.loads(line)
|
|
81
|
+
except json.JSONDecodeError:
|
|
82
|
+
return {"ok": False, "entries": count, "broken_at": idx}
|
|
83
|
+
payload = {k: v for k, v in entry.items() if k != "entry_hash"}
|
|
84
|
+
if entry.get("prev_hash") != prev or _entry_hash(payload) != entry.get("entry_hash"):
|
|
85
|
+
return {"ok": False, "entries": count, "broken_at": idx}
|
|
86
|
+
prev = entry["entry_hash"]
|
|
87
|
+
count += 1
|
|
88
|
+
return {"ok": True, "entries": count, "broken_at": None}
|
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
"""Deterministic detectors for guardrail-middleware.
|
|
2
|
+
|
|
3
|
+
Each detector inspects one :class:`ActionRequest` and returns zero or more
|
|
4
|
+
:class:`Finding` objects. Detectors are pure functions of (action, policy) —
|
|
5
|
+
no network, no LLM — so a decision is reproducible and fast enough to sit in
|
|
6
|
+
front of every tool call.
|
|
7
|
+
|
|
8
|
+
The set mirrors the attack classes from the GuardRail red-team benchmark:
|
|
9
|
+
prompt injection, taint/PII exfiltration, unauthorized or destructive actions,
|
|
10
|
+
financial-limit abuse, and bulk-operation abuse.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import re
|
|
16
|
+
from typing import Any, Callable, Iterable, Optional
|
|
17
|
+
|
|
18
|
+
from .models import ActionRequest, Finding
|
|
19
|
+
from .policy import Policy
|
|
20
|
+
|
|
21
|
+
# ---------------------------------------------------------------------------
|
|
22
|
+
# Operation classification
|
|
23
|
+
# ---------------------------------------------------------------------------
|
|
24
|
+
|
|
25
|
+
_READ = {"read", "get", "list", "fetch", "search", "query", "select", "view"}
|
|
26
|
+
_WRITE = {"write", "create", "update", "insert", "upsert", "patch", "post"}
|
|
27
|
+
_DELETE = {"delete", "drop", "purge", "truncate", "wipe", "erase", "destroy", "remove"}
|
|
28
|
+
_PAYMENT = {"payment", "pay", "transfer", "wire", "charge", "send money"}
|
|
29
|
+
_REFUND = {"refund", "reimburse", "chargeback"}
|
|
30
|
+
_SEND = {"send", "email", "post message", "publish", "webhook", "notify"}
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def classify_operation(operation: str) -> str:
|
|
34
|
+
"""Map a free-form operation string to a policy class."""
|
|
35
|
+
op = operation.strip().lower()
|
|
36
|
+
if op in _READ:
|
|
37
|
+
return "read"
|
|
38
|
+
if op in _DELETE:
|
|
39
|
+
return "delete"
|
|
40
|
+
if op in _PAYMENT:
|
|
41
|
+
return "payment"
|
|
42
|
+
if op in _REFUND:
|
|
43
|
+
return "refund"
|
|
44
|
+
if op in _SEND:
|
|
45
|
+
return "external_send"
|
|
46
|
+
if op in _WRITE:
|
|
47
|
+
return "write"
|
|
48
|
+
return "other"
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
# ---------------------------------------------------------------------------
|
|
52
|
+
# Parameter helpers
|
|
53
|
+
# ---------------------------------------------------------------------------
|
|
54
|
+
|
|
55
|
+
_AMOUNT_KEYS = ("amount", "total", "total_amount", "price", "value", "sum")
|
|
56
|
+
_COUNT_KEYS = ("count", "records", "num_records", "batch_size", "limit", "quantity")
|
|
57
|
+
_LIST_KEYS = ("ids", "recipients", "targets", "items", "records", "users")
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def extract_amount(params: dict[str, Any]) -> Optional[float]:
|
|
61
|
+
for key in _AMOUNT_KEYS:
|
|
62
|
+
val = params.get(key)
|
|
63
|
+
if isinstance(val, (int, float)) and not isinstance(val, bool):
|
|
64
|
+
return float(val)
|
|
65
|
+
return None
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def extract_record_count(params: dict[str, Any]) -> Optional[int]:
|
|
69
|
+
for key in _COUNT_KEYS:
|
|
70
|
+
val = params.get(key)
|
|
71
|
+
if isinstance(val, int) and not isinstance(val, bool):
|
|
72
|
+
return val
|
|
73
|
+
for key in _LIST_KEYS:
|
|
74
|
+
val = params.get(key)
|
|
75
|
+
if isinstance(val, list):
|
|
76
|
+
return len(val)
|
|
77
|
+
return None
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _flatten_keys(obj: Any, prefix: str = "") -> Iterable[str]:
|
|
81
|
+
if isinstance(obj, dict):
|
|
82
|
+
for key, value in obj.items():
|
|
83
|
+
path = f"{prefix}.{key}" if prefix else str(key)
|
|
84
|
+
yield path
|
|
85
|
+
yield from _flatten_keys(value, path)
|
|
86
|
+
elif isinstance(obj, list):
|
|
87
|
+
for item in obj:
|
|
88
|
+
yield from _flatten_keys(item, prefix)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def _present_fields(params: dict[str, Any], wanted: set[str]) -> set[str]:
|
|
92
|
+
found = set()
|
|
93
|
+
for path in _flatten_keys(params):
|
|
94
|
+
leaf = path.rsplit(".", 1)[-1].lower()
|
|
95
|
+
if leaf in wanted:
|
|
96
|
+
found.add(leaf)
|
|
97
|
+
return found
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def is_external_destination(resource: str, policy: Policy) -> bool:
|
|
101
|
+
"""A resource is external if it looks like a URL/host outside the internal list."""
|
|
102
|
+
res = (resource or "").lower()
|
|
103
|
+
if not res:
|
|
104
|
+
return False
|
|
105
|
+
if not any(marker in res for marker in ("://", ".com", ".io", ".net", ".org", "@")):
|
|
106
|
+
return False # internal path / table / id
|
|
107
|
+
return not any(host in res for host in policy.internal_hosts)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
# ---------------------------------------------------------------------------
|
|
111
|
+
# 1. Prompt-injection detector
|
|
112
|
+
# ---------------------------------------------------------------------------
|
|
113
|
+
|
|
114
|
+
_INJECTION_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
|
|
115
|
+
("instruction override", re.compile(r"ignore (all )?(previous|prior|above) instructions", re.I)),
|
|
116
|
+
("instruction override", re.compile(r"disregard (the )?(system|previous|prior)", re.I)),
|
|
117
|
+
("role hijack", re.compile(r"you are now (a|an|in)\b", re.I)),
|
|
118
|
+
("role hijack", re.compile(r"\bdeveloper mode\b|\bjailbreak\b|\bDAN mode\b", re.I)),
|
|
119
|
+
("secret extraction", re.compile(r"(reveal|print|show|leak|dump).{0,30}(system prompt|api key|password|secret|credentials)", re.I)),
|
|
120
|
+
("policy bypass", re.compile(r"without (telling|notifying|alerting|logging|approval)", re.I)),
|
|
121
|
+
("policy bypass", re.compile(r"(skip|bypass|override) (the )?(approval|check|verification|guardrail|policy)", re.I)),
|
|
122
|
+
("urgency pressure", re.compile(r"(urgent|immediately).{0,40}(transfer|send|pay|delete)", re.I)),
|
|
123
|
+
]
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def detect_injection(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
127
|
+
texts = [action.source_text or "", action.stated_reason or ""]
|
|
128
|
+
hits = set()
|
|
129
|
+
for text in texts:
|
|
130
|
+
for label, pattern in _INJECTION_PATTERNS:
|
|
131
|
+
if pattern.search(text):
|
|
132
|
+
hits.add(label)
|
|
133
|
+
if not hits:
|
|
134
|
+
return []
|
|
135
|
+
labels = ", ".join(sorted(hits))
|
|
136
|
+
if action.triggered_by.untrusted:
|
|
137
|
+
return [Finding(
|
|
138
|
+
detector="injection",
|
|
139
|
+
severity="critical",
|
|
140
|
+
message=f"Prompt-injection pattern(s) in untrusted {action.triggered_by.value} content: {labels}. "
|
|
141
|
+
"Untrusted content is data, never instructions.",
|
|
142
|
+
effect="block",
|
|
143
|
+
)]
|
|
144
|
+
return [Finding(
|
|
145
|
+
detector="injection",
|
|
146
|
+
severity="medium",
|
|
147
|
+
message=f"Injection-like phrasing in the action rationale: {labels}.",
|
|
148
|
+
effect="conditions",
|
|
149
|
+
)]
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
# ---------------------------------------------------------------------------
|
|
153
|
+
# 2. Authorization detector
|
|
154
|
+
# ---------------------------------------------------------------------------
|
|
155
|
+
|
|
156
|
+
def detect_unauthorized(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
157
|
+
op_class = classify_operation(action.operation)
|
|
158
|
+
allowed = policy.role_allowed(op_class, action.agent_role)
|
|
159
|
+
if allowed is False:
|
|
160
|
+
return [Finding(
|
|
161
|
+
detector="authorization",
|
|
162
|
+
severity="critical",
|
|
163
|
+
message=f"Role '{action.agent_role}' is not permitted to perform '{op_class}' operations.",
|
|
164
|
+
effect="block",
|
|
165
|
+
)]
|
|
166
|
+
return []
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
# ---------------------------------------------------------------------------
|
|
170
|
+
# 3. Financial-limit detector
|
|
171
|
+
# ---------------------------------------------------------------------------
|
|
172
|
+
|
|
173
|
+
def detect_financial(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
174
|
+
op_class = classify_operation(action.operation)
|
|
175
|
+
if op_class not in ("payment", "refund"):
|
|
176
|
+
return []
|
|
177
|
+
amount = extract_amount(action.parameters)
|
|
178
|
+
if amount is None:
|
|
179
|
+
return [Finding(
|
|
180
|
+
detector="financial_limits",
|
|
181
|
+
severity="high",
|
|
182
|
+
message=f"{op_class} action carries no amount in its parameters; the value cannot be verified.",
|
|
183
|
+
effect="escalate",
|
|
184
|
+
)]
|
|
185
|
+
findings: list[Finding] = []
|
|
186
|
+
hard_block = policy.get("hard_block_amount")
|
|
187
|
+
if hard_block is not None and amount > float(hard_block):
|
|
188
|
+
findings.append(Finding(
|
|
189
|
+
detector="financial_limits",
|
|
190
|
+
severity="critical",
|
|
191
|
+
message=f"Amount {amount:,.0f} exceeds the hard block ceiling of {float(hard_block):,.0f}.",
|
|
192
|
+
effect="block",
|
|
193
|
+
))
|
|
194
|
+
return findings
|
|
195
|
+
limits = policy.get("approval_limits", op_class, default={}) or {}
|
|
196
|
+
block_above = limits.get("block_above")
|
|
197
|
+
auto_max = limits.get("auto_approve_max")
|
|
198
|
+
if block_above is not None and amount > float(block_above):
|
|
199
|
+
findings.append(Finding(
|
|
200
|
+
detector="financial_limits",
|
|
201
|
+
severity="critical",
|
|
202
|
+
message=f"{op_class} of {amount:,.0f} exceeds the policy block threshold of {float(block_above):,.0f}.",
|
|
203
|
+
effect="block",
|
|
204
|
+
))
|
|
205
|
+
elif auto_max is not None and amount > float(auto_max):
|
|
206
|
+
findings.append(Finding(
|
|
207
|
+
detector="financial_limits",
|
|
208
|
+
severity="high",
|
|
209
|
+
message=f"{op_class} of {amount:,.0f} exceeds the auto-approve limit of {float(auto_max):,.0f}; a human must approve.",
|
|
210
|
+
effect="escalate",
|
|
211
|
+
))
|
|
212
|
+
return findings
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
# ---------------------------------------------------------------------------
|
|
216
|
+
# 4. Bulk-operation detector
|
|
217
|
+
# ---------------------------------------------------------------------------
|
|
218
|
+
|
|
219
|
+
def detect_bulk(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
220
|
+
count = extract_record_count(action.parameters)
|
|
221
|
+
if count is None:
|
|
222
|
+
return []
|
|
223
|
+
auto_max = policy.get("bulk_operation", "auto_approve_max_records", default=50)
|
|
224
|
+
escalate_above = policy.get("bulk_operation", "escalate_above_records", default=500)
|
|
225
|
+
if count > int(escalate_above):
|
|
226
|
+
return [Finding(
|
|
227
|
+
detector="bulk_operation",
|
|
228
|
+
severity="high",
|
|
229
|
+
message=f"Bulk operation touches {count} records, above the escalation threshold of {escalate_above}.",
|
|
230
|
+
effect="escalate",
|
|
231
|
+
)]
|
|
232
|
+
if count > int(auto_max):
|
|
233
|
+
return [Finding(
|
|
234
|
+
detector="bulk_operation",
|
|
235
|
+
severity="medium",
|
|
236
|
+
message=f"Bulk operation touches {count} records (auto-approve max {auto_max}); batch it and dry-run first.",
|
|
237
|
+
effect="conditions",
|
|
238
|
+
)]
|
|
239
|
+
return []
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
# ---------------------------------------------------------------------------
|
|
243
|
+
# 5. Taint / exfiltration detector
|
|
244
|
+
# ---------------------------------------------------------------------------
|
|
245
|
+
|
|
246
|
+
def detect_taint(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
247
|
+
findings: list[Finding] = []
|
|
248
|
+
pii = _present_fields(action.parameters, policy.pii_fields)
|
|
249
|
+
secrets = _present_fields(action.parameters, policy.secret_fields)
|
|
250
|
+
external = is_external_destination(action.target_resource, policy)
|
|
251
|
+
op_class = classify_operation(action.operation)
|
|
252
|
+
outbound = op_class in ("external_send", "payment", "refund", "write")
|
|
253
|
+
|
|
254
|
+
if secrets:
|
|
255
|
+
findings.append(Finding(
|
|
256
|
+
detector="taint",
|
|
257
|
+
severity="critical",
|
|
258
|
+
message=f"Action parameters contain secret field(s): {', '.join(sorted(secrets))}. "
|
|
259
|
+
"Secrets must never travel inside tool-call parameters.",
|
|
260
|
+
effect="block",
|
|
261
|
+
))
|
|
262
|
+
if pii and external and outbound:
|
|
263
|
+
findings.append(Finding(
|
|
264
|
+
detector="taint",
|
|
265
|
+
severity="critical",
|
|
266
|
+
message=f"PII field(s) {', '.join(sorted(pii))} would flow to external destination "
|
|
267
|
+
f"'{action.target_resource}'. Possible exfiltration chain.",
|
|
268
|
+
effect="block",
|
|
269
|
+
))
|
|
270
|
+
elif pii and action.triggered_by.untrusted:
|
|
271
|
+
findings.append(Finding(
|
|
272
|
+
detector="taint",
|
|
273
|
+
severity="high",
|
|
274
|
+
message=f"Action touches PII field(s) {', '.join(sorted(pii))} and was triggered by untrusted "
|
|
275
|
+
f"{action.triggered_by.value} content; a human should confirm it matches the user's intent.",
|
|
276
|
+
effect="escalate",
|
|
277
|
+
))
|
|
278
|
+
return findings
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
# ---------------------------------------------------------------------------
|
|
282
|
+
# 6. Destructive / irreversibility detector
|
|
283
|
+
# ---------------------------------------------------------------------------
|
|
284
|
+
|
|
285
|
+
def detect_destructive(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
286
|
+
op = action.operation.strip().lower()
|
|
287
|
+
if op not in policy.irreversible_operations and classify_operation(op) != "delete":
|
|
288
|
+
return []
|
|
289
|
+
params = action.parameters
|
|
290
|
+
confirmed = params.get("confirmed") is True or params.get("dry_run") is True
|
|
291
|
+
backed_up = params.get("backup_taken") is True or params.get("snapshot_id")
|
|
292
|
+
if classify_operation(op) == "delete" and not action.target_resource:
|
|
293
|
+
return [Finding(
|
|
294
|
+
detector="destructive",
|
|
295
|
+
severity="high",
|
|
296
|
+
message="Delete operation has no target resource — scope is unbounded.",
|
|
297
|
+
effect="escalate",
|
|
298
|
+
)]
|
|
299
|
+
if not confirmed and not backed_up:
|
|
300
|
+
return [Finding(
|
|
301
|
+
detector="destructive",
|
|
302
|
+
severity="medium",
|
|
303
|
+
message=f"'{action.operation}' is irreversible and carries no backup/confirmation marker.",
|
|
304
|
+
effect="conditions",
|
|
305
|
+
)]
|
|
306
|
+
return []
|
|
307
|
+
|
|
308
|
+
|
|
309
|
+
# ---------------------------------------------------------------------------
|
|
310
|
+
# 7. Untrusted-source escalation detector
|
|
311
|
+
# ---------------------------------------------------------------------------
|
|
312
|
+
|
|
313
|
+
def detect_untrusted_source(action: ActionRequest, policy: Policy) -> list[Finding]:
|
|
314
|
+
if not action.triggered_by.untrusted:
|
|
315
|
+
return []
|
|
316
|
+
op_class = classify_operation(action.operation)
|
|
317
|
+
if op_class in ("payment", "refund", "delete", "external_send"):
|
|
318
|
+
return [Finding(
|
|
319
|
+
detector="untrusted_source",
|
|
320
|
+
severity="high",
|
|
321
|
+
message=f"A {op_class} action was triggered by {action.triggered_by.value} content, not by the user. "
|
|
322
|
+
"Untrusted content must never originate money movement, deletion, or external sends.",
|
|
323
|
+
effect="escalate",
|
|
324
|
+
)]
|
|
325
|
+
return []
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
ALL_DETECTORS: list[Callable[[ActionRequest, Policy], list[Finding]]] = [
|
|
329
|
+
detect_injection,
|
|
330
|
+
detect_unauthorized,
|
|
331
|
+
detect_financial,
|
|
332
|
+
detect_bulk,
|
|
333
|
+
detect_taint,
|
|
334
|
+
detect_destructive,
|
|
335
|
+
detect_untrusted_source,
|
|
336
|
+
]
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
"""The GuardRail decision engine.
|
|
2
|
+
|
|
3
|
+
Runs every detector over a proposed action, folds the findings into a single
|
|
4
|
+
verdict, and (optionally) writes the decision to the hash-chained audit log.
|
|
5
|
+
|
|
6
|
+
Verdict rules, in priority order — earlier rules win:
|
|
7
|
+
|
|
8
|
+
1. Any finding with effect ``block`` → BLOCK
|
|
9
|
+
2. Any finding with effect ``escalate`` → ESCALATE_TO_HUMAN
|
|
10
|
+
3. Any finding with effect ``conditions`` → APPROVE_WITH_CONDITIONS
|
|
11
|
+
4. No findings → APPROVE
|
|
12
|
+
|
|
13
|
+
The engine is deterministic and LLM-free by design: the same action under the
|
|
14
|
+
same policy always gets the same verdict, in well under a millisecond.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from typing import Any, Optional, Union
|
|
20
|
+
|
|
21
|
+
from .audit import AuditLog
|
|
22
|
+
from .detectors import ALL_DETECTORS
|
|
23
|
+
from .models import ActionRequest, Decision, Finding, Verdict
|
|
24
|
+
from .policy import Policy
|
|
25
|
+
|
|
26
|
+
_SEVERITY_WEIGHT = {"low": 5, "medium": 15, "high": 35, "critical": 60}
|
|
27
|
+
|
|
28
|
+
_CONDITIONS: dict[str, str] = {
|
|
29
|
+
"bulk_operation": "Process in batches with a dry-run preview before the full run",
|
|
30
|
+
"destructive": "Take a verified backup or snapshot before executing",
|
|
31
|
+
"injection": "Re-state the instruction in your own words and confirm it matches the user's request",
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class Guardrail:
|
|
36
|
+
"""Evaluate agent actions against a policy before they execute.
|
|
37
|
+
|
|
38
|
+
Usage::
|
|
39
|
+
|
|
40
|
+
guard = Guardrail() # default policy
|
|
41
|
+
decision = guard.evaluate({
|
|
42
|
+
"tool": "payments", "operation": "payment",
|
|
43
|
+
"parameters": {"amount": 42000}, "agent_role": "support",
|
|
44
|
+
})
|
|
45
|
+
if decision.allowed:
|
|
46
|
+
run_the_tool()
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
def __init__(
|
|
50
|
+
self,
|
|
51
|
+
policy: Optional[Union[Policy, dict[str, Any]]] = None,
|
|
52
|
+
audit_log: Optional[AuditLog] = None,
|
|
53
|
+
*,
|
|
54
|
+
fail_closed: bool = True,
|
|
55
|
+
) -> None:
|
|
56
|
+
if policy is None:
|
|
57
|
+
policy = Policy()
|
|
58
|
+
elif isinstance(policy, dict):
|
|
59
|
+
policy = Policy(policy)
|
|
60
|
+
self.policy = policy
|
|
61
|
+
self.audit_log = audit_log
|
|
62
|
+
self.fail_closed = fail_closed
|
|
63
|
+
|
|
64
|
+
# ------------------------------------------------------------------ API
|
|
65
|
+
|
|
66
|
+
def evaluate(self, action: Union[ActionRequest, dict[str, Any]]) -> Decision:
|
|
67
|
+
if isinstance(action, dict):
|
|
68
|
+
action = ActionRequest.from_dict(action)
|
|
69
|
+
try:
|
|
70
|
+
findings: list[Finding] = []
|
|
71
|
+
for detector in ALL_DETECTORS:
|
|
72
|
+
findings.extend(detector(action, self.policy))
|
|
73
|
+
decision = self._decide(action, findings)
|
|
74
|
+
except Exception as exc: # never let the guard itself crash the caller
|
|
75
|
+
if not self.fail_closed:
|
|
76
|
+
raise
|
|
77
|
+
decision = Decision(
|
|
78
|
+
action_id=action.action_id,
|
|
79
|
+
verdict=Verdict.ESCALATE_TO_HUMAN,
|
|
80
|
+
risk_score=100,
|
|
81
|
+
findings=[Finding(
|
|
82
|
+
detector="engine",
|
|
83
|
+
severity="high",
|
|
84
|
+
message=f"GuardRail evaluation failed ({exc!r}); failing closed.",
|
|
85
|
+
effect="escalate",
|
|
86
|
+
)],
|
|
87
|
+
explanation="Evaluation error — escalated to a human (fail-closed).",
|
|
88
|
+
)
|
|
89
|
+
if self.audit_log is not None:
|
|
90
|
+
decision.audit_hash = self.audit_log.record(
|
|
91
|
+
action=action.to_dict(), decision=decision.to_dict()
|
|
92
|
+
)
|
|
93
|
+
return decision
|
|
94
|
+
|
|
95
|
+
# -------------------------------------------------------------- internals
|
|
96
|
+
|
|
97
|
+
@staticmethod
|
|
98
|
+
def _decide(action: ActionRequest, findings: list[Finding]) -> Decision:
|
|
99
|
+
effects = {f.effect for f in findings}
|
|
100
|
+
if "block" in effects:
|
|
101
|
+
verdict = Verdict.BLOCK
|
|
102
|
+
elif "escalate" in effects:
|
|
103
|
+
verdict = Verdict.ESCALATE_TO_HUMAN
|
|
104
|
+
elif "conditions" in effects:
|
|
105
|
+
verdict = Verdict.APPROVE_WITH_CONDITIONS
|
|
106
|
+
else:
|
|
107
|
+
verdict = Verdict.APPROVE
|
|
108
|
+
|
|
109
|
+
risk = min(100, sum(_SEVERITY_WEIGHT.get(f.severity, 5) for f in findings))
|
|
110
|
+
if verdict is Verdict.BLOCK:
|
|
111
|
+
risk = max(risk, 80)
|
|
112
|
+
elif verdict is Verdict.ESCALATE_TO_HUMAN:
|
|
113
|
+
risk = max(risk, 50)
|
|
114
|
+
|
|
115
|
+
conditions = []
|
|
116
|
+
for f in findings:
|
|
117
|
+
if verdict in (Verdict.APPROVE_WITH_CONDITIONS, Verdict.ESCALATE_TO_HUMAN) \
|
|
118
|
+
and f.effect == "conditions" and f.detector in _CONDITIONS:
|
|
119
|
+
text = _CONDITIONS[f.detector]
|
|
120
|
+
if text not in conditions:
|
|
121
|
+
conditions.append(text)
|
|
122
|
+
|
|
123
|
+
if not findings:
|
|
124
|
+
explanation = f"{action.operation} on {action.target_resource or action.tool}: no policy issues found."
|
|
125
|
+
else:
|
|
126
|
+
top = max(findings, key=lambda f: _SEVERITY_WEIGHT.get(f.severity, 0))
|
|
127
|
+
explanation = f"{verdict.value}: {top.message}"
|
|
128
|
+
|
|
129
|
+
return Decision(
|
|
130
|
+
action_id=action.action_id,
|
|
131
|
+
verdict=verdict,
|
|
132
|
+
risk_score=risk,
|
|
133
|
+
findings=findings,
|
|
134
|
+
conditions=conditions,
|
|
135
|
+
explanation=explanation,
|
|
136
|
+
)
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
"""FastAPI / Starlette integration.
|
|
2
|
+
|
|
3
|
+
Two ways to protect an app:
|
|
4
|
+
|
|
5
|
+
1. **Middleware** — guard specific routes that execute agent tool calls. The
|
|
6
|
+
request body is read as an action (``tool``, ``operation``,
|
|
7
|
+
``target_resource``, ``parameters``, ...). Blocked or escalated actions
|
|
8
|
+
never reach your handler::
|
|
9
|
+
|
|
10
|
+
from guardrail_middleware.fastapi import GuardrailMiddleware
|
|
11
|
+
app.add_middleware(GuardrailMiddleware, paths=["/tools/execute"])
|
|
12
|
+
|
|
13
|
+
Verdicts are exposed to handlers and clients via response headers
|
|
14
|
+
``X-Guardrail-Verdict`` and ``X-Guardrail-Risk``. A stopped action returns
|
|
15
|
+
HTTP 403 with the full decision as JSON.
|
|
16
|
+
|
|
17
|
+
2. **Decorator** — guard a plain Python function that performs a tool call::
|
|
18
|
+
|
|
19
|
+
@guard_tool(guard)
|
|
20
|
+
def send_payment(amount: int, to: str): ...
|
|
21
|
+
|
|
22
|
+
The wrapped function's arguments become the action parameters; a BLOCK or
|
|
23
|
+
ESCALATE verdict raises :class:`GuardrailBlocked` instead of running.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
import functools
|
|
29
|
+
import json
|
|
30
|
+
from typing import Any, Callable, Optional
|
|
31
|
+
|
|
32
|
+
from starlette.middleware.base import BaseHTTPMiddleware
|
|
33
|
+
from starlette.requests import Request
|
|
34
|
+
from starlette.responses import JSONResponse, Response
|
|
35
|
+
|
|
36
|
+
from .engine import Guardrail
|
|
37
|
+
from .models import ActionRequest, Decision
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class GuardrailBlocked(Exception):
|
|
41
|
+
"""Raised by @guard_tool when GuardRail stops an action."""
|
|
42
|
+
|
|
43
|
+
def __init__(self, decision: Decision) -> None:
|
|
44
|
+
super().__init__(f"GuardRail {decision.verdict.value}: {decision.explanation}")
|
|
45
|
+
self.decision = decision
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class GuardrailMiddleware(BaseHTTPMiddleware):
|
|
49
|
+
"""Starlette middleware that vets tool-call requests before execution."""
|
|
50
|
+
|
|
51
|
+
def __init__(
|
|
52
|
+
self,
|
|
53
|
+
app,
|
|
54
|
+
guard: Optional[Guardrail] = None,
|
|
55
|
+
*,
|
|
56
|
+
paths: Optional[list[str]] = None,
|
|
57
|
+
path_prefix: Optional[str] = None,
|
|
58
|
+
) -> None:
|
|
59
|
+
super().__init__(app)
|
|
60
|
+
self.guard = guard or Guardrail()
|
|
61
|
+
self.paths = set(paths or [])
|
|
62
|
+
self.path_prefix = path_prefix
|
|
63
|
+
|
|
64
|
+
def _guarded(self, path: str) -> bool:
|
|
65
|
+
if self.paths:
|
|
66
|
+
return path in self.paths
|
|
67
|
+
if self.path_prefix:
|
|
68
|
+
return path.startswith(self.path_prefix)
|
|
69
|
+
return True
|
|
70
|
+
|
|
71
|
+
async def dispatch(self, request: Request, call_next: Callable) -> Response:
|
|
72
|
+
if request.method not in ("POST", "PUT", "PATCH", "DELETE") or not self._guarded(request.url.path):
|
|
73
|
+
return await call_next(request)
|
|
74
|
+
|
|
75
|
+
raw = await request.body()
|
|
76
|
+
try:
|
|
77
|
+
payload = json.loads(raw) if raw else {}
|
|
78
|
+
if not isinstance(payload, dict):
|
|
79
|
+
raise ValueError("action body must be a JSON object")
|
|
80
|
+
action = ActionRequest.from_dict(payload)
|
|
81
|
+
except Exception:
|
|
82
|
+
# Not an action-shaped body — not ours to judge; pass through.
|
|
83
|
+
return await call_next(request)
|
|
84
|
+
|
|
85
|
+
if not action.tool and not action.operation:
|
|
86
|
+
return await call_next(request)
|
|
87
|
+
|
|
88
|
+
decision = self.guard.evaluate(action)
|
|
89
|
+
if not decision.allowed:
|
|
90
|
+
return JSONResponse(
|
|
91
|
+
status_code=403,
|
|
92
|
+
content={
|
|
93
|
+
"error": "guardrail_stopped",
|
|
94
|
+
"decision": decision.to_dict(),
|
|
95
|
+
},
|
|
96
|
+
headers={
|
|
97
|
+
"X-Guardrail-Verdict": decision.verdict.value,
|
|
98
|
+
"X-Guardrail-Risk": str(decision.risk_score),
|
|
99
|
+
},
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
response = await call_next(request)
|
|
103
|
+
response.headers["X-Guardrail-Verdict"] = decision.verdict.value
|
|
104
|
+
response.headers["X-Guardrail-Risk"] = str(decision.risk_score)
|
|
105
|
+
return response
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def guard_tool(
|
|
109
|
+
guard: Guardrail,
|
|
110
|
+
*,
|
|
111
|
+
tool: str,
|
|
112
|
+
operation: str,
|
|
113
|
+
agent_role: str = "agent",
|
|
114
|
+
target_param: Optional[str] = None,
|
|
115
|
+
):
|
|
116
|
+
"""Decorator: vet a function's arguments as an action before it runs."""
|
|
117
|
+
|
|
118
|
+
def decorator(fn: Callable) -> Callable:
|
|
119
|
+
@functools.wraps(fn)
|
|
120
|
+
def wrapper(*args, **kwargs):
|
|
121
|
+
import inspect
|
|
122
|
+
|
|
123
|
+
bound = inspect.signature(fn).bind_partial(*args, **kwargs).arguments
|
|
124
|
+
params = {k: v for k, v in bound.items() if k != target_param}
|
|
125
|
+
action = ActionRequest(
|
|
126
|
+
tool=tool,
|
|
127
|
+
operation=operation,
|
|
128
|
+
target_resource=str(bound.get(target_param, "")) if target_param else "",
|
|
129
|
+
parameters=params,
|
|
130
|
+
agent_role=agent_role,
|
|
131
|
+
)
|
|
132
|
+
decision = guard.evaluate(action)
|
|
133
|
+
if not decision.allowed:
|
|
134
|
+
raise GuardrailBlocked(decision)
|
|
135
|
+
return fn(*args, **kwargs)
|
|
136
|
+
|
|
137
|
+
return wrapper
|
|
138
|
+
|
|
139
|
+
return decorator
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
"""Core data models for guardrail-middleware.
|
|
2
|
+
|
|
3
|
+
An *action* is one proposed tool call by an AI agent: which tool, which
|
|
4
|
+
operation, on what resource, with what parameters, and where the instruction
|
|
5
|
+
came from. GuardRail evaluates the action *before* it executes and returns a
|
|
6
|
+
:class:`Decision`.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import uuid
|
|
12
|
+
from dataclasses import dataclass, field
|
|
13
|
+
from enum import Enum
|
|
14
|
+
from typing import Any, Optional
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class Verdict(str, Enum):
|
|
18
|
+
"""Final decision for a proposed action."""
|
|
19
|
+
|
|
20
|
+
APPROVE = "APPROVE"
|
|
21
|
+
APPROVE_WITH_CONDITIONS = "APPROVE_WITH_CONDITIONS"
|
|
22
|
+
ESCALATE_TO_HUMAN = "ESCALATE_TO_HUMAN"
|
|
23
|
+
BLOCK = "BLOCK"
|
|
24
|
+
|
|
25
|
+
@property
|
|
26
|
+
def allowed(self) -> bool:
|
|
27
|
+
"""True when the action may proceed (possibly with conditions)."""
|
|
28
|
+
return self in (Verdict.APPROVE, Verdict.APPROVE_WITH_CONDITIONS)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class TriggeredBy(str, Enum):
|
|
32
|
+
"""Origin of the instruction that produced this action.
|
|
33
|
+
|
|
34
|
+
Anything other than a direct user instruction is *untrusted*: content from
|
|
35
|
+
emails, webpages and tool outputs is data, never instructions.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
USER = "user"
|
|
39
|
+
EMAIL = "email"
|
|
40
|
+
WEBPAGE = "webpage"
|
|
41
|
+
TOOL_OUTPUT = "tool_output"
|
|
42
|
+
OTHER = "other"
|
|
43
|
+
|
|
44
|
+
@property
|
|
45
|
+
def untrusted(self) -> bool:
|
|
46
|
+
return self is not TriggeredBy.USER
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass
|
|
50
|
+
class ActionRequest:
|
|
51
|
+
"""A single proposed agent action, submitted for pre-execution validation."""
|
|
52
|
+
|
|
53
|
+
tool: str
|
|
54
|
+
operation: str
|
|
55
|
+
target_resource: str = ""
|
|
56
|
+
parameters: dict[str, Any] = field(default_factory=dict)
|
|
57
|
+
agent_id: str = "agent"
|
|
58
|
+
agent_role: str = "agent"
|
|
59
|
+
stated_reason: str = ""
|
|
60
|
+
task_context: str = ""
|
|
61
|
+
triggered_by: TriggeredBy = TriggeredBy.USER
|
|
62
|
+
source_text: Optional[str] = None
|
|
63
|
+
action_id: str = field(default_factory=lambda: f"act-{uuid.uuid4().hex[:8]}")
|
|
64
|
+
|
|
65
|
+
@classmethod
|
|
66
|
+
def from_dict(cls, data: dict[str, Any]) -> "ActionRequest":
|
|
67
|
+
triggered = data.get("triggered_by", TriggeredBy.USER)
|
|
68
|
+
if isinstance(triggered, str):
|
|
69
|
+
triggered = TriggeredBy(triggered.lower())
|
|
70
|
+
return cls(
|
|
71
|
+
tool=str(data.get("tool", "")),
|
|
72
|
+
operation=str(data.get("operation", "")),
|
|
73
|
+
target_resource=str(data.get("target_resource", "")),
|
|
74
|
+
parameters=dict(data.get("parameters") or {}),
|
|
75
|
+
agent_id=str(data.get("agent_id", "agent")),
|
|
76
|
+
agent_role=str(data.get("agent_role", "agent")),
|
|
77
|
+
stated_reason=str(data.get("stated_reason", "")),
|
|
78
|
+
task_context=str(data.get("task_context", "")),
|
|
79
|
+
triggered_by=triggered,
|
|
80
|
+
source_text=data.get("source_text"),
|
|
81
|
+
action_id=str(data.get("action_id") or f"act-{uuid.uuid4().hex[:8]}"),
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
def to_dict(self) -> dict[str, Any]:
|
|
85
|
+
return {
|
|
86
|
+
"action_id": self.action_id,
|
|
87
|
+
"agent_id": self.agent_id,
|
|
88
|
+
"agent_role": self.agent_role,
|
|
89
|
+
"tool": self.tool,
|
|
90
|
+
"operation": self.operation,
|
|
91
|
+
"target_resource": self.target_resource,
|
|
92
|
+
"parameters": self.parameters,
|
|
93
|
+
"stated_reason": self.stated_reason,
|
|
94
|
+
"task_context": self.task_context,
|
|
95
|
+
"triggered_by": self.triggered_by.value,
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
@dataclass
|
|
100
|
+
class Finding:
|
|
101
|
+
"""One detector hit: what fired, how bad it is, and what to do about it."""
|
|
102
|
+
|
|
103
|
+
detector: str
|
|
104
|
+
severity: str # "low" | "medium" | "high" | "critical"
|
|
105
|
+
message: str
|
|
106
|
+
effect: str = "warn" # "warn" | "conditions" | "escalate" | "block"
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
@dataclass
|
|
110
|
+
class Decision:
|
|
111
|
+
"""The verdict on an action, with the evidence behind it."""
|
|
112
|
+
|
|
113
|
+
action_id: str
|
|
114
|
+
verdict: Verdict
|
|
115
|
+
risk_score: int # 0 (safe) .. 100 (certain harm)
|
|
116
|
+
findings: list[Finding] = field(default_factory=list)
|
|
117
|
+
conditions: list[str] = field(default_factory=list)
|
|
118
|
+
explanation: str = ""
|
|
119
|
+
audit_hash: Optional[str] = None
|
|
120
|
+
|
|
121
|
+
@property
|
|
122
|
+
def allowed(self) -> bool:
|
|
123
|
+
return self.verdict.allowed
|
|
124
|
+
|
|
125
|
+
def to_dict(self) -> dict[str, Any]:
|
|
126
|
+
return {
|
|
127
|
+
"action_id": self.action_id,
|
|
128
|
+
"verdict": self.verdict.value,
|
|
129
|
+
"allowed": self.allowed,
|
|
130
|
+
"risk_score": self.risk_score,
|
|
131
|
+
"findings": [
|
|
132
|
+
{
|
|
133
|
+
"detector": f.detector,
|
|
134
|
+
"severity": f.severity,
|
|
135
|
+
"message": f.message,
|
|
136
|
+
"effect": f.effect,
|
|
137
|
+
}
|
|
138
|
+
for f in self.findings
|
|
139
|
+
],
|
|
140
|
+
"conditions": self.conditions,
|
|
141
|
+
"explanation": self.explanation,
|
|
142
|
+
"audit_hash": self.audit_hash,
|
|
143
|
+
}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"""Policy configuration for guardrail-middleware.
|
|
2
|
+
|
|
3
|
+
The policy is a plain dict (loaded from YAML if PyYAML is installed, or built
|
|
4
|
+
in code). Every threshold the detectors use lives here, so a team can tighten
|
|
5
|
+
or loosen GuardRail without touching code.
|
|
6
|
+
|
|
7
|
+
The defaults mirror the reference GuardRail policy used in the original
|
|
8
|
+
project's red-team benchmark.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import copy
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any, Optional, Union
|
|
16
|
+
|
|
17
|
+
DEFAULT_POLICY: dict[str, Any] = {
|
|
18
|
+
# Roles allowed to perform each operation class. "*" = any role.
|
|
19
|
+
"role_permissions": {
|
|
20
|
+
"read": ["*"],
|
|
21
|
+
"write": ["*"],
|
|
22
|
+
"delete": ["admin", "operator"],
|
|
23
|
+
"payment": ["admin", "finance"],
|
|
24
|
+
"external_send": ["admin", "operator", "support"],
|
|
25
|
+
},
|
|
26
|
+
# Money limits (in the policy's currency unit, INR by default).
|
|
27
|
+
"approval_limits": {
|
|
28
|
+
"payment": {"auto_approve_max": 5_000, "block_above": 50_000},
|
|
29
|
+
"refund": {"auto_approve_max": 10_000, "block_above": 100_000},
|
|
30
|
+
},
|
|
31
|
+
# Bulk-operation limits, by record count found in parameters.
|
|
32
|
+
"bulk_operation": {"auto_approve_max_records": 50, "escalate_above_records": 500},
|
|
33
|
+
# Parameter keys that count as PII / secrets for taint tracking.
|
|
34
|
+
"pii_fields": [
|
|
35
|
+
"email", "phone", "address", "ssn", "national_id", "passport",
|
|
36
|
+
"credit_card", "bank_account", "date_of_birth", "salary", "medical",
|
|
37
|
+
],
|
|
38
|
+
"secret_fields": ["api_key", "password", "secret", "token", "private_key"],
|
|
39
|
+
# Operations considered irreversible (no undo). The destructive detector
|
|
40
|
+
# attaches backup/confirmation conditions to these. Money movement is
|
|
41
|
+
# governed by approval_limits instead, so payment/refund are not listed.
|
|
42
|
+
"irreversible_operations": ["delete", "drop", "purge", "truncate", "wipe", "send"],
|
|
43
|
+
# Hosts/patterns treated as internal; anything else is an external destination.
|
|
44
|
+
"internal_hosts": ["localhost", "127.0.0.1", "internal", ".local", ".corp", ".internal"],
|
|
45
|
+
# Hard ceiling: a single action may never move more than this, whatever the role.
|
|
46
|
+
"hard_block_amount": 100_000,
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class Policy:
|
|
51
|
+
"""Thin wrapper around the policy dict with typed helpers."""
|
|
52
|
+
|
|
53
|
+
def __init__(self, data: Optional[dict[str, Any]] = None) -> None:
|
|
54
|
+
self._data: dict[str, Any] = copy.deepcopy(DEFAULT_POLICY)
|
|
55
|
+
if data:
|
|
56
|
+
self._deep_merge(self._data, data)
|
|
57
|
+
|
|
58
|
+
# ------------------------------------------------------------------ I/O
|
|
59
|
+
|
|
60
|
+
@classmethod
|
|
61
|
+
def from_yaml(cls, path: Union[str, Path]) -> "Policy":
|
|
62
|
+
try:
|
|
63
|
+
import yaml
|
|
64
|
+
except ImportError as exc: # pragma: no cover
|
|
65
|
+
raise RuntimeError(
|
|
66
|
+
"Loading a YAML policy needs PyYAML: pip install pyyaml"
|
|
67
|
+
) from exc
|
|
68
|
+
with open(path, "r", encoding="utf-8") as fh:
|
|
69
|
+
data = yaml.safe_load(fh) or {}
|
|
70
|
+
if not isinstance(data, dict):
|
|
71
|
+
raise ValueError("Policy YAML must be a mapping at the top level")
|
|
72
|
+
return cls(data)
|
|
73
|
+
|
|
74
|
+
@classmethod
|
|
75
|
+
def from_dict(cls, data: dict[str, Any]) -> "Policy":
|
|
76
|
+
return cls(data)
|
|
77
|
+
|
|
78
|
+
@staticmethod
|
|
79
|
+
def _deep_merge(target: dict[str, Any], source: dict[str, Any]) -> None:
|
|
80
|
+
for key, value in source.items():
|
|
81
|
+
if isinstance(value, dict) and isinstance(target.get(key), dict):
|
|
82
|
+
Policy._deep_merge(target[key], value)
|
|
83
|
+
else:
|
|
84
|
+
target[key] = value
|
|
85
|
+
|
|
86
|
+
# -------------------------------------------------------------- helpers
|
|
87
|
+
|
|
88
|
+
def get(self, *keys: str, default: Any = None) -> Any:
|
|
89
|
+
node: Any = self._data
|
|
90
|
+
for key in keys:
|
|
91
|
+
if not isinstance(node, dict) or key not in node:
|
|
92
|
+
return default
|
|
93
|
+
node = node[key]
|
|
94
|
+
return node
|
|
95
|
+
|
|
96
|
+
def role_allowed(self, operation_class: str, role: str) -> Optional[bool]:
|
|
97
|
+
"""True/False if the policy names this class; None if unlisted."""
|
|
98
|
+
perms = self.get("role_permissions", operation_class)
|
|
99
|
+
if perms is None:
|
|
100
|
+
return None
|
|
101
|
+
return "*" in perms or role in perms
|
|
102
|
+
|
|
103
|
+
@property
|
|
104
|
+
def pii_fields(self) -> set[str]:
|
|
105
|
+
return {str(f).lower() for f in self.get("pii_fields", default=[])}
|
|
106
|
+
|
|
107
|
+
@property
|
|
108
|
+
def secret_fields(self) -> set[str]:
|
|
109
|
+
return {str(f).lower() for f in self.get("secret_fields", default=[])}
|
|
110
|
+
|
|
111
|
+
@property
|
|
112
|
+
def irreversible_operations(self) -> set[str]:
|
|
113
|
+
return {str(o).lower() for o in self.get("irreversible_operations", default=[])}
|
|
114
|
+
|
|
115
|
+
@property
|
|
116
|
+
def internal_hosts(self) -> list[str]:
|
|
117
|
+
return [str(h).lower() for h in self.get("internal_hosts", default=[])]
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: guardrail-middleware
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Runtime authorization middleware for AI agent tool calls — policy checks, injection/taint detectors, and a hash-chained audit log, before any action executes.
|
|
5
|
+
Author: Niraj Sanjay Karnawat
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Niraj21-star/guardrail-middleware
|
|
8
|
+
Project-URL: Source, https://github.com/Niraj21-star/guardrail-middleware
|
|
9
|
+
Keywords: ai-agents,guardrails,llm-security,middleware,fastapi,authorization
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Security
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Provides-Extra: fastapi
|
|
20
|
+
Requires-Dist: starlette>=0.27; extra == "fastapi"
|
|
21
|
+
Requires-Dist: fastapi>=0.100; extra == "fastapi"
|
|
22
|
+
Provides-Extra: yaml
|
|
23
|
+
Requires-Dist: pyyaml>=6; extra == "yaml"
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
26
|
+
Requires-Dist: fastapi>=0.100; extra == "dev"
|
|
27
|
+
Requires-Dist: httpx>=0.24; extra == "dev"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# guardrail-middleware
|
|
31
|
+
|
|
32
|
+
**Runtime authorization for AI agent tool calls.** GuardRail sits between an AI agent and its tools: every proposed action is checked against a policy *before* it executes — and every decision is written to a tamper-evident audit log.
|
|
33
|
+
|
|
34
|
+
An agent that can call tools can also be talked into misusing them — by a prompt injection in an email, a poisoned webpage, or its own overconfidence. GuardRail is the checkpoint that asks, deterministically and in under a millisecond: *is this role allowed to do this, to this resource, with these parameters, on the say-so of this source?*
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
pip install guardrail-middleware # core, zero dependencies
|
|
38
|
+
pip install guardrail-middleware[fastapi] # + FastAPI/Starlette middleware
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Quick start — framework-agnostic
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
from guardrail_middleware import Guardrail
|
|
45
|
+
|
|
46
|
+
guard = Guardrail() # built-in default policy
|
|
47
|
+
|
|
48
|
+
decision = guard.evaluate({
|
|
49
|
+
"tool": "payments",
|
|
50
|
+
"operation": "payment",
|
|
51
|
+
"target_resource": "vendor/acme",
|
|
52
|
+
"parameters": {"amount": 42000},
|
|
53
|
+
"agent_role": "support",
|
|
54
|
+
})
|
|
55
|
+
|
|
56
|
+
decision.verdict # Verdict.BLOCK — role 'support' may not run payments
|
|
57
|
+
decision.allowed # False
|
|
58
|
+
decision.explanation
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Works anywhere an agent proposes an action: LangChain/LangGraph tool wrappers, MCP servers, custom agent loops, job queues.
|
|
62
|
+
|
|
63
|
+
## Quick start — FastAPI / Starlette middleware
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
from fastapi import FastAPI
|
|
67
|
+
from guardrail_middleware import Guardrail, AuditLog
|
|
68
|
+
from guardrail_middleware.fastapi import GuardrailMiddleware
|
|
69
|
+
|
|
70
|
+
app = FastAPI()
|
|
71
|
+
app.add_middleware(
|
|
72
|
+
GuardrailMiddleware,
|
|
73
|
+
guard=Guardrail(audit_log=AuditLog("audit.jsonl")),
|
|
74
|
+
paths=["/tools/execute"],
|
|
75
|
+
)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Requests to guarded paths are read as actions. **Blocked or escalated actions never reach your handler** — the client gets HTTP 403 with the full decision as JSON. Allowed actions pass through with `X-Guardrail-Verdict` and `X-Guardrail-Risk` headers set.
|
|
79
|
+
|
|
80
|
+
## Quick start — decorator
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
from guardrail_middleware.fastapi import guard_tool, GuardrailBlocked
|
|
84
|
+
|
|
85
|
+
@guard_tool(guard, tool="payments", operation="payment", agent_role="support")
|
|
86
|
+
def send_payment(amount: int, to: str):
|
|
87
|
+
... # only runs if GuardRail approves
|
|
88
|
+
|
|
89
|
+
try:
|
|
90
|
+
send_payment(amount=42_000, to="vendor/acme")
|
|
91
|
+
except GuardrailBlocked as stopped:
|
|
92
|
+
print(stopped.decision.explanation)
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Verdicts
|
|
96
|
+
|
|
97
|
+
| Verdict | Meaning |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `APPROVE` | No policy issues — execute. |
|
|
100
|
+
| `APPROVE_WITH_CONDITIONS` | Execute only with the attached conditions (batch it, back up first, dry-run). |
|
|
101
|
+
| `ESCALATE_TO_HUMAN` | A person must approve first (over-limit payment, untrusted source, unbounded delete). |
|
|
102
|
+
| `BLOCK` | Never execute (injection, unauthorized role, PII exfiltration, hard money ceiling). |
|
|
103
|
+
|
|
104
|
+
Priority is fail-safe: any `block` finding wins, then `escalate`, then `conditions`.
|
|
105
|
+
|
|
106
|
+
## What it checks — 7 deterministic detectors
|
|
107
|
+
|
|
108
|
+
No LLM in the decision path: the same action under the same policy always gets the same verdict, reproducibly and fast.
|
|
109
|
+
|
|
110
|
+
1. **Injection** — instruction-override / role-hijack / secret-extraction / policy-bypass patterns in untrusted content (email, webpage, tool output). Untrusted content is data, never instructions.
|
|
111
|
+
2. **Authorization** — role × operation-class permissions (an `intern` role cannot delete, a `support` role cannot pay).
|
|
112
|
+
3. **Financial limits** — per-class auto-approve and block thresholds, plus a hard ceiling no role can exceed; a payment with no verifiable amount escalates.
|
|
113
|
+
4. **Bulk operations** — record-count thresholds: conditions (batch + dry-run) above the auto-approve max, escalation above the bulk ceiling.
|
|
114
|
+
5. **Taint / exfiltration** — PII or secret fields flowing to an external destination is blocked; secrets inside tool-call parameters are blocked outright.
|
|
115
|
+
6. **Destructive actions** — irreversible operations without a backup/confirmation marker get conditions; a delete with no target escalates.
|
|
116
|
+
7. **Untrusted source** — money movement, deletion, or external sends *triggered by* email/webpage/tool-output content escalate to a human.
|
|
117
|
+
|
|
118
|
+
## Policy
|
|
119
|
+
|
|
120
|
+
Every threshold lives in one policy dict — tune it without touching code, or load it from YAML:
|
|
121
|
+
|
|
122
|
+
```python
|
|
123
|
+
from guardrail_middleware import Guardrail, Policy
|
|
124
|
+
|
|
125
|
+
policy = Policy.from_yaml("policy.yaml") # see policy.example.yaml
|
|
126
|
+
guard = Guardrail(policy=policy)
|
|
127
|
+
|
|
128
|
+
# …or inline
|
|
129
|
+
guard = Guardrail(policy={"approval_limits": {"payment": {"auto_approve_max": 500}}})
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Audit log
|
|
133
|
+
|
|
134
|
+
Pass an `AuditLog` and every decision is appended as one JSON line, hash-chained with SHA-256: each entry commits to the previous entry's hash, so editing, deleting, or reordering history breaks the chain.
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from guardrail_middleware import AuditLog
|
|
138
|
+
AuditLog("audit.jsonl").verify() # {'ok': True, 'entries': 128, 'broken_at': None}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Demo & tests
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
python examples/demo.py # 5 scenarios, all four verdicts, audit verification
|
|
145
|
+
pytest # 18 tests: engine, detectors, middleware, decorator, audit tampering
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Where this comes from
|
|
149
|
+
|
|
150
|
+
`guardrail-middleware` is the reusable enforcement core extracted from **[GuardRail](https://github.com/Niraj21-star/guard_ai)** — a runtime action-authorization and behavioral-safety layer for agentic AI built at Infosys Ignite EngNext 2026 (special recognition), where the full system adds multi-step plan validation, an action-passport execution gateway, and a 42-scenario adversarial red-team benchmark. This package packages the single-action checkpoint from that system so any agent stack can adopt it in minutes.
|
|
151
|
+
|
|
152
|
+
## Status & honesty notes
|
|
153
|
+
|
|
154
|
+
- v0.1.0, alpha. The API may still move.
|
|
155
|
+
- Detectors are deterministic heuristics, not a proof of safety — pair them with least-privilege credentials and human review for high-impact tools.
|
|
156
|
+
- Plan-level (multi-step) validation lives in the main GuardRail project, not in this package yet.
|
|
157
|
+
|
|
158
|
+
## License
|
|
159
|
+
|
|
160
|
+
MIT © Niraj Sanjay Karnawat
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
guardrail_middleware/__init__.py,sha256=bblsBe7JKby91ejrzcHllvch6gIQnvUa4xLvUMia3Pk,1241
|
|
2
|
+
guardrail_middleware/audit.py,sha256=3mMdhc_FHdlgFqqmeqy1F8P_s7gZXfo82fJoASWUh7Y,3398
|
|
3
|
+
guardrail_middleware/detectors.py,sha256=J5TIQYrsYSpMql3YgdYGtUxT0W7f3PRNzn4_bWn1jC0,13575
|
|
4
|
+
guardrail_middleware/engine.py,sha256=zH13mi3tEdet9RP2AvK_N3OoMLaWvGqBoyB1lzOAtb4,5072
|
|
5
|
+
guardrail_middleware/fastapi.py,sha256=dgmRFXQ8SFEv5Zuz1IdjU1q3vofvuwVV2--B2rodgHc,4732
|
|
6
|
+
guardrail_middleware/models.py,sha256=NDv18CitqJ3Nca96nplotjoLkdJOtNBiziylCgrlqGk,4619
|
|
7
|
+
guardrail_middleware/policy.py,sha256=e48YUr-vdHjfI079k_ZxEAhdwSghTLFJOyHaLUaoB6U,4666
|
|
8
|
+
guardrail_middleware-0.1.0.dist-info/licenses/LICENSE,sha256=03WQ9QB-hNJKrczHIH2ydPVc4sjNkBlqhL6rfw_O1XA,1078
|
|
9
|
+
guardrail_middleware-0.1.0.dist-info/METADATA,sha256=ZbfLmzzDDyvRnw5mv6irAtOTYwgh5tzt63aywXRv2Jw,7197
|
|
10
|
+
guardrail_middleware-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
11
|
+
guardrail_middleware-0.1.0.dist-info/top_level.txt,sha256=QM0tas-zJLMY2xe68wlpKGEonyu6I_8wm_4Ui6JUB4w,21
|
|
12
|
+
guardrail_middleware-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niraj Sanjay Karnawat
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
guardrail_middleware
|