llmtap-proxy 0.2.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.
llmtap/guard.py ADDED
@@ -0,0 +1,391 @@
1
+ """Secret / PII firewall for prompts.
2
+
3
+ Scans request bodies for leaked credentials (and optionally PII) before they leave the machine.
4
+ Designed to run on every request: all regexes are precompiled, cheap literal prefilters skip
5
+ patterns that cannot match, and base64 media payloads (images, audio, data: URLs) are skipped.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import bisect
10
+ import json
11
+ import re
12
+ from dataclasses import asdict, dataclass
13
+ from typing import Any, Callable
14
+
15
+ __all__ = ["Finding", "KINDS", "scan_text", "scan_obj", "redact_obj", "apply_guard"]
16
+
17
+ KINDS: dict[str, str] = {
18
+ "aws_access_key": "AWS access key ID (AKIA…/ASIA…)",
19
+ "aws_secret_key": "AWS secret access key",
20
+ "anthropic_key": "Anthropic API key (sk-ant-…)",
21
+ "openai_key": "OpenAI API key (sk-…/sk-proj-…)",
22
+ "github_token": "GitHub token (ghp_/gho_/ghs_/github_pat_…)",
23
+ "slack_token": "Slack token (xoxb-/xoxp-…)",
24
+ "stripe_key": "Stripe live secret key (sk_live_/rk_live_…)",
25
+ "google_api_key": "Google API key (AIza…)",
26
+ "private_key": "PEM private key block",
27
+ "jwt": "JSON Web Token",
28
+ "generic_secret": "Hard-coded password / secret / token assignment",
29
+ "email": "Email address (PII)",
30
+ "phone": "Phone number (PII)",
31
+ "credit_card": "Credit card number (PII, Luhn-validated)",
32
+ }
33
+
34
+ PII_KINDS: frozenset[str] = frozenset({"email", "phone", "credit_card"})
35
+
36
+
37
+ @dataclass
38
+ class Finding:
39
+ """One detected secret. `start`/`end` are offsets into the string located at `path`."""
40
+ kind: str
41
+ path: str
42
+ preview: str
43
+ start: int
44
+ end: int
45
+
46
+ def to_dict(self) -> dict[str, Any]:
47
+ return asdict(self)
48
+
49
+
50
+ # --------------------------------------------------------------------------------------------
51
+ # validators (return True to keep the match)
52
+
53
+ _PLACEHOLDER_WORDS = ("your", "example", "placeholder", "xxxx", "changeme", "redacted",
54
+ "dummy", "<", ">", "${", "{{", "}}", "****", "....")
55
+ _PATHLIKE_PREFIXES = ("/", "~", "./", "../", "$", "%", "http://", "https://", "file://")
56
+ _DOTTED_IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+")
57
+
58
+
59
+ def _char_classes(s: str) -> int:
60
+ lo = up = dg = ot = False
61
+ for c in s:
62
+ if c.islower():
63
+ lo = True
64
+ elif c.isupper():
65
+ up = True
66
+ elif c.isdigit():
67
+ dg = True
68
+ else:
69
+ ot = True
70
+ return lo + up + dg + ot
71
+
72
+
73
+ def _plausible_secret_value(v: str) -> bool:
74
+ low = v.lower()
75
+ if low.startswith(_PATHLIKE_PREFIXES):
76
+ return False
77
+ if any(w in low for w in _PLACEHOLDER_WORDS):
78
+ return False
79
+ if len(set(v)) <= 2: # "********", "aaaaaaaa", "xxxxxxxx"
80
+ return False
81
+ if _DOTTED_IDENT.fullmatch(v): # os.environ, self.token, settings.SECRET
82
+ return False
83
+ if v.lower() in ("true", "false", "null", "none", "undefined"):
84
+ return False
85
+ return _char_classes(v) >= 2
86
+
87
+
88
+ def _luhn_ok(digits: str) -> bool:
89
+ total = 0
90
+ for i, ch in enumerate(reversed(digits)):
91
+ d = ord(ch) - 48
92
+ if i % 2 == 1:
93
+ d *= 2
94
+ if d > 9:
95
+ d -= 9
96
+ total += d
97
+ return total % 10 == 0
98
+
99
+
100
+ def _card_brand_ok(d: str) -> bool:
101
+ n = len(d)
102
+ if d[0] == "4":
103
+ return n in (13, 16, 19) # Visa
104
+ p2, p4 = int(d[:2]), int(d[:4])
105
+ if 51 <= p2 <= 55 or 2221 <= p4 <= 2720:
106
+ return n == 16 # Mastercard
107
+ if p2 in (34, 37):
108
+ return n == 15 # Amex
109
+ if d.startswith("6011") or p2 == 65 or 644 <= int(d[:3]) <= 649:
110
+ return 16 <= n <= 19 # Discover
111
+ if p2 in (36, 38, 39) or 300 <= int(d[:3]) <= 305:
112
+ return 14 <= n <= 19 # Diners
113
+ if p2 == 35:
114
+ return 16 <= n <= 19 # JCB
115
+ if d[:2] in ("62", "81"):
116
+ return 16 <= n <= 19 # UnionPay
117
+ return False
118
+
119
+
120
+ def _credit_card_ok(v: str) -> bool:
121
+ seps = {c for c in v if not c.isdigit()}
122
+ if len(seps) > 1:
123
+ return False
124
+ d = "".join(c for c in v if c.isdigit())
125
+ if not 13 <= len(d) <= 19 or len(set(d)) == 1:
126
+ return False
127
+ return _card_brand_ok(d) and _luhn_ok(d)
128
+
129
+
130
+ def _phone_ok(v: str) -> bool:
131
+ n = sum(c.isdigit() for c in v)
132
+ return 10 <= n <= 15
133
+
134
+
135
+ _FILE_EXTS = frozenset({"png", "jpg", "jpeg", "gif", "svg", "webp", "ico", "bmp", "js", "ts", "css",
136
+ "py", "json", "html", "md", "txt", "pdf", "zip", "gz", "tar", "map", "mjs"})
137
+
138
+
139
+ def _email_ok(v: str) -> bool:
140
+ return v.rsplit(".", 1)[-1].lower() not in _FILE_EXTS
141
+
142
+
143
+ # --------------------------------------------------------------------------------------------
144
+ # patterns
145
+
146
+ @dataclass(frozen=True)
147
+ class _Pattern:
148
+ kind: str
149
+ regex: re.Pattern[str]
150
+ group: int # capture group holding the secret (0 = whole match)
151
+ priority: int # lower = more specific; wins overlaps
152
+ literals: tuple[str, ...] = () # prefilter: at least one must occur (in text, or lowered text if lower_lits)
153
+ lower_lits: bool = False
154
+ validate: Callable[[str], bool] | None = None
155
+
156
+
157
+ _GENERIC_KW = (r"(?:password|passwd|passphrase|secret[_-]?key|secret|token|api[_-]?key|apikey|"
158
+ r"access[_-]?key|private[_-]?key|credentials?)")
159
+
160
+ _PATTERNS: tuple[_Pattern, ...] = (
161
+ _Pattern("private_key", re.compile(
162
+ r"-----BEGIN (?:[A-Z0-9]+ ){0,3}PRIVATE KEY(?: BLOCK)?-----"
163
+ r"(?:(?:[^-]|-(?!----)){0,20000}-----END (?:[A-Z0-9]+ ){0,3}PRIVATE KEY(?: BLOCK)?-----)?"),
164
+ 0, 0, ("PRIVATE KEY",)),
165
+ _Pattern("anthropic_key", re.compile(r"(?<![A-Za-z0-9_-])sk-ant-[A-Za-z0-9_-]{20,}"),
166
+ 0, 1, ("sk-ant-",)),
167
+ _Pattern("aws_access_key", re.compile(r"(?<![A-Za-z0-9])(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}(?![A-Za-z0-9])"),
168
+ 0, 1, ("AKIA", "ASIA", "ABIA", "ACCA")),
169
+ _Pattern("github_token", re.compile(
170
+ r"(?<![A-Za-z0-9_])(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{30,255})(?![A-Za-z0-9_])"),
171
+ 0, 1, ("ghp_", "gho_", "ghu_", "ghs_", "ghr_", "github_pat_")),
172
+ _Pattern("slack_token", re.compile(r"(?<![A-Za-z0-9_-])xox[baprs]-(?=[A-Za-z0-9-]*\d)[A-Za-z0-9-]{10,255}"),
173
+ 0, 1, ("xox",)),
174
+ _Pattern("stripe_key", re.compile(r"(?<![A-Za-z0-9_])(?:sk|rk)_live_[A-Za-z0-9]{16,255}"),
175
+ 0, 1, ("_live_",)),
176
+ _Pattern("google_api_key", re.compile(r"(?<![A-Za-z0-9_-])AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])"),
177
+ 0, 1, ("AIza",)),
178
+ _Pattern("jwt", re.compile(
179
+ r"(?<![A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}(?![A-Za-z0-9_-])"),
180
+ 0, 2, ("eyJ",)),
181
+ _Pattern("aws_secret_key", re.compile(
182
+ r"(?i)(?:aws[A-Za-z0-9_.-]{0,20}?secret|secret[_.-]?access[_.-]?key)[A-Za-z0-9_.-]{0,20}"
183
+ r"[\"']?\s*(?::=|=>|[:=])\s*[\"']?([A-Za-z0-9/+]{40})(?![A-Za-z0-9/+=])"),
184
+ 1, 2, ("secret",), True),
185
+ _Pattern("openai_key", re.compile(
186
+ r"(?<![A-Za-z0-9_-])sk-(?:(?:proj|svcacct|admin|None)-[A-Za-z0-9_-]{20,}"
187
+ r"|(?=[A-Za-z]*\d)(?=\d*[A-Za-z])[A-Za-z0-9]{32,})"),
188
+ 0, 3, ("sk-",)),
189
+ # password = "hunter2!!" / "api_key": "..." / token := '...'
190
+ _Pattern("generic_secret", re.compile(
191
+ r"(?i)(?<![A-Za-z0-9])" + _GENERIC_KW +
192
+ r"\\?[\"']?\s*(?::=|=>|==|[:=])\s*\\?([\"'`])([^\s\"'`\\]{8,256})\\?\1"),
193
+ 2, 5, ("pass", "secret", "token", "key", "credential"), True, _plausible_secret_value),
194
+ # .env style: DB_PASSWORD=s3cr3tP4ss
195
+ _Pattern("generic_secret", re.compile(
196
+ r"(?im)^[ \t]{0,16}(?:export[ \t]+)?[A-Za-z0-9_]{0,48}" + _GENERIC_KW +
197
+ r"[A-Za-z0-9_]{0,32}[ \t]{0,4}=[ \t]{0,4}([^\s\"'`#;,()\[\]{}]{8,256})[ \t]*$"),
198
+ 1, 5, ("pass", "secret", "token", "key", "credential"), True, _plausible_secret_value),
199
+ # Authorization: Bearer <token>
200
+ _Pattern("generic_secret", re.compile(r"(?i)(?<![A-Za-z0-9])bearer\s+([A-Za-z0-9._~+/-]{20,}=*)"),
201
+ 1, 5, ("bearer",), True, _plausible_secret_value),
202
+ # ---- PII ----
203
+ _Pattern("credit_card", re.compile(r"(?<![\d.-])\d(?:[ -]?\d){12,18}(?![\d-])"),
204
+ 0, 6, (), False, _credit_card_ok),
205
+ _Pattern("email", re.compile(
206
+ r"(?<![A-Za-z0-9._%+-])[A-Za-z0-9][A-Za-z0-9._%+-]{0,63}@"
207
+ r"(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,24}(?![A-Za-z0-9-])"),
208
+ 0, 7, ("@",), False, _email_ok),
209
+ _Pattern("phone", re.compile(
210
+ r"(?<![\w.+-])(?:\+?1[ .-]?)?(?:\(\d{3}\)[ ]?|\d{3}[ .-])\d{3}[ .-]\d{4}(?![\w-])"),
211
+ 0, 8, (), False, _phone_ok),
212
+ _Pattern("phone", re.compile(r"(?<![\w.+-])\+[1-9]\d{0,2}(?:[ .-]?\(?\d{1,4}\)?){2,5}(?![\w-])"),
213
+ 0, 8, ("+",), False, _phone_ok),
214
+ )
215
+
216
+ _DATA_URL = re.compile(r"data:[A-Za-z0-9.+/-]*(?:;[A-Za-z0-9=._-]+)*;base64,[A-Za-z0-9+/=]*")
217
+ _BASE64_BLOB = re.compile(r"[A-Za-z0-9+/=\r\n]+")
218
+ _BLOB_MIN = 1024
219
+
220
+
221
+ def _mask(kind: str, s: str) -> str:
222
+ """Masked preview: keep a short prefix and the last 4 chars."""
223
+ if kind == "private_key":
224
+ header = s.split("-----", 2)[1] if s.count("-----") >= 2 else "BEGIN PRIVATE KEY"
225
+ return f"-----{header}-----…"
226
+ n = len(s)
227
+ if n >= 24:
228
+ return f"{s[:6]}…{s[-4:]}"
229
+ if n >= 16:
230
+ return f"{s[:4]}…{s[-4:]}"
231
+ if n >= 12:
232
+ return f"{s[:2]}…{s[-4:]}"
233
+ if n >= 8:
234
+ return f"{s[:2]}…{s[-2:]}"
235
+ return "…"
236
+
237
+
238
+ def _is_base64_blob(text: str) -> bool:
239
+ return len(text) >= _BLOB_MIN and _BASE64_BLOB.fullmatch(text) is not None
240
+
241
+
242
+ def scan_text(text: str, pii: bool = False, path: str = "") -> list[Finding]:
243
+ """Find secrets (and PII if `pii`) in `text`. Overlaps resolve to the most specific kind."""
244
+ if not text or len(text) < 8 or _is_base64_blob(text):
245
+ return []
246
+ lowered: str | None = None
247
+ excluded: list[tuple[int, int]] = []
248
+ if ";base64," in text:
249
+ excluded = [(m.start(), m.end()) for m in _DATA_URL.finditer(text)]
250
+ if excluded and excluded[0] == (0, len(text)):
251
+ return []
252
+
253
+ cands: list[tuple[int, int, int, str]] = [] # (priority, start, end, kind)
254
+ for p in _PATTERNS:
255
+ if not pii and p.kind in PII_KINDS:
256
+ continue
257
+ if p.literals:
258
+ if p.lower_lits:
259
+ if lowered is None:
260
+ lowered = text.lower()
261
+ hay = lowered
262
+ else:
263
+ hay = text
264
+ if not any(lit in hay for lit in p.literals):
265
+ continue
266
+ for m in p.regex.finditer(text):
267
+ s, e = m.span(p.group)
268
+ if s < 0 or e <= s:
269
+ continue
270
+ if p.validate is not None and not p.validate(m.group(p.group)):
271
+ continue
272
+ cands.append((p.priority, s, e, p.kind))
273
+ if not cands:
274
+ return []
275
+
276
+ # Greedy selection: most specific kind first, then longest span; reject overlaps.
277
+ cands.sort(key=lambda c: (c[0], -(c[2] - c[1]), c[1]))
278
+ starts: list[int] = []
279
+ chosen: list[tuple[int, int, str]] = []
280
+ for ex_s, ex_e in excluded:
281
+ bisect.insort(starts, ex_s)
282
+ chosen.insert(bisect.bisect_left(starts, ex_s), (ex_s, ex_e, ""))
283
+ for _, s, e, kind in cands:
284
+ i = bisect.bisect_left(starts, s)
285
+ if i > 0 and chosen[i - 1][1] > s:
286
+ continue
287
+ if i < len(starts) and starts[i] < e:
288
+ continue
289
+ starts.insert(i, s)
290
+ chosen.insert(i, (s, e, kind))
291
+ return [Finding(kind, path, _mask(kind, text[s:e]), s, e) for s, e, kind in chosen if kind]
292
+
293
+
294
+ # --------------------------------------------------------------------------------------------
295
+ # object walking
296
+
297
+ def _child_path(path: str, key: Any) -> str:
298
+ if isinstance(key, int):
299
+ return f"{path}[{key}]"
300
+ return f"{path}.{key}" if path else str(key)
301
+
302
+
303
+ def _skip_key(d: dict[str, Any], key: str, parent_key: Any) -> bool:
304
+ """True for opaque binary payloads that must not be scanned (images, audio, signatures)."""
305
+ t = d.get("type")
306
+ if key == "data" and (t == "base64" or parent_key == "input_audio" or t == "redacted_thinking"):
307
+ return True
308
+ if key == "signature" and t in ("thinking", "redacted_thinking"):
309
+ return True
310
+ return False
311
+
312
+
313
+ def _walk(obj: Any, pii: bool, path: str, parent_key: Any, out: list[Finding],
314
+ redact: bool) -> Any:
315
+ if isinstance(obj, str):
316
+ found = scan_text(obj, pii, path)
317
+ if not found:
318
+ return obj
319
+ out.extend(found)
320
+ if not redact:
321
+ return obj
322
+ return _redact_text(obj, found)
323
+ if isinstance(obj, dict):
324
+ res: dict[Any, Any] = {}
325
+ for k, v in obj.items():
326
+ if isinstance(v, str) and _skip_key(obj, k, parent_key):
327
+ res[k] = v
328
+ else:
329
+ res[k] = _walk(v, pii, _child_path(path, k), k, out, redact)
330
+ return res if redact else obj
331
+ if isinstance(obj, (list, tuple)):
332
+ items = [_walk(v, pii, _child_path(path, i), parent_key, out, redact) for i, v in enumerate(obj)]
333
+ return (type(obj)(items) if isinstance(obj, tuple) else items) if redact else obj
334
+ return obj
335
+
336
+
337
+ def _redact_text(text: str, findings: list[Finding]) -> str:
338
+ parts: list[str] = []
339
+ pos = 0
340
+ for f in sorted(findings, key=lambda f: f.start):
341
+ parts.append(text[pos:f.start])
342
+ parts.append(f"[REDACTED:{f.kind}]")
343
+ pos = f.end
344
+ parts.append(text[pos:])
345
+ return "".join(parts)
346
+
347
+
348
+ def scan_obj(obj: Any, pii: bool = False) -> list[Finding]:
349
+ """Walk dicts/lists and scan every string value. Paths look like "messages[0].content"."""
350
+ out: list[Finding] = []
351
+ _walk(obj, pii, "", None, out, False)
352
+ return out
353
+
354
+
355
+ def redact_obj(obj: Any, pii: bool = False) -> tuple[Any, list[Finding]]:
356
+ """Return a NEW object with each match replaced by "[REDACTED:<kind>]", plus the findings."""
357
+ out: list[Finding] = []
358
+ new = _walk(obj, pii, "", None, out, True)
359
+ return new, out
360
+
361
+
362
+ def apply_guard(body: bytes, mode: str, pii: bool = False) -> tuple[bytes, list[Finding], bool]:
363
+ """Apply guard `mode` ("off" | "warn" | "redact" | "block") to a request body.
364
+
365
+ Returns (body_to_send, findings, blocked). Unknown modes behave like "warn".
366
+ """
367
+ if mode == "off" or not body:
368
+ return body, [], False
369
+ text = body.decode("utf-8", errors="surrogateescape")
370
+ obj: Any = None
371
+ is_json = False
372
+ try:
373
+ obj = json.loads(text)
374
+ is_json = True
375
+ except ValueError:
376
+ pass
377
+
378
+ if mode == "redact":
379
+ if is_json:
380
+ new, findings = redact_obj(obj, pii)
381
+ if not findings:
382
+ return body, [], False
383
+ return json.dumps(new, ensure_ascii=False).encode("utf-8", errors="surrogateescape"), findings, False
384
+ findings = scan_text(text, pii)
385
+ if not findings:
386
+ return body, [], False
387
+ return _redact_text(text, findings).encode("utf-8", errors="surrogateescape"), findings, False
388
+
389
+ findings = scan_obj(obj, pii) if is_json else scan_text(text, pii)
390
+ blocked = mode == "block" and bool(findings)
391
+ return body, findings, blocked