shipwright-kit 0.12.0__tar.gz → 0.12.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. {shipwright_kit-0.12.0/shipwright_kit.egg-info → shipwright_kit-0.12.1}/PKG-INFO +1 -1
  2. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/pyproject.toml +2 -1
  3. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/__init__.py +1 -1
  4. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/llm.py +10 -2
  5. shipwright_kit-0.12.1/shipwright_kit/security/injection.py +316 -0
  6. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/security/render.py +40 -10
  7. shipwright_kit-0.12.1/shipwright_kit/security/ssrf.py +169 -0
  8. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1/shipwright_kit.egg-info}/PKG-INFO +1 -1
  9. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_llm.py +26 -0
  10. shipwright_kit-0.12.0/shipwright_kit/security/injection.py +0 -206
  11. shipwright_kit-0.12.0/shipwright_kit/security/ssrf.py +0 -123
  12. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/LICENSE +0 -0
  13. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/README.md +0 -0
  14. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/setup.cfg +0 -0
  15. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/cli.py +0 -0
  16. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/config.py +0 -0
  17. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/__init__.py +0 -0
  18. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/banner.py +0 -0
  19. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/console.py +0 -0
  20. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/glyphs.py +0 -0
  21. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/output.py +0 -0
  22. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/palette.py +0 -0
  23. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/design/tiers.py +0 -0
  24. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/eval/__init__.py +0 -0
  25. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/eval/corpus.py +0 -0
  26. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/eval/harness.py +0 -0
  27. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/eval/metrics.py +0 -0
  28. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/py.typed +0 -0
  29. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/security/__init__.py +0 -0
  30. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/security/eval.py +0 -0
  31. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit/security/theme.py +0 -0
  32. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit.egg-info/SOURCES.txt +0 -0
  33. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit.egg-info/dependency_links.txt +0 -0
  34. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit.egg-info/entry_points.txt +0 -0
  35. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit.egg-info/requires.txt +0 -0
  36. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/shipwright_kit.egg-info/top_level.txt +0 -0
  37. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_cli.py +0 -0
  38. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_config.py +0 -0
  39. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_packaging.py +0 -0
  40. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_packs_entrypoint.py +0 -0
  41. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_release_config.py +0 -0
  42. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_template_wiring.py +0 -0
  43. {shipwright_kit-0.12.0 → shipwright_kit-0.12.1}/tests/test_tooling.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: shipwright-kit
3
- Version: 0.12.0
3
+ Version: 0.12.1
4
4
  Summary: Shipwright — AI-agent dev framework + import-light design/eval/security library
5
5
  Author: Christian Huhn
6
6
  License-Expression: MIT
@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
7
7
  # PyPI distribution name. The bare `shipwright` is taken on PyPI (unrelated 6si
8
8
  # tool), so the dist is `shipwright-kit`; the IMPORT name is `shipwright_kit`.
9
9
  name = "shipwright-kit"
10
- version = "0.12.0"
10
+ version = "0.12.1"
11
11
  description = "Shipwright — AI-agent dev framework + import-light design/eval/security library"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.11"
@@ -54,6 +54,7 @@ dev = [
54
54
  "copier>=9",
55
55
  "packaging",
56
56
  "typer>=0.9",
57
+ "urllib3>=2.8.0,<3",
57
58
  ]
58
59
 
59
60
  [tool.setuptools.packages.find]
@@ -1,3 +1,3 @@
1
1
  """Shipwright — design-token + tooling library."""
2
2
 
3
- __version__ = "0.12.0"
3
+ __version__ = "0.12.1"
@@ -26,7 +26,7 @@ caller unchanged so each tool can keep its own existing error handling
26
26
  (re-raise as ``RuntimeError``, swallow-and-fall-back-to-template, etc.) without
27
27
  this module making that policy choice for them. The only exception raised
28
28
  *by* this module itself is ``ValueError`` for an unrecognized ``extract``/
29
- ``system_mode`` literal — an input-validation guard, not error-swallowing.
29
+ ``system_mode`` literal or a non-http(s) Ollama ``base_url`` scheme — an input-validation guard, not error-swallowing.
30
30
 
31
31
  No ``max_tokens``/``temperature`` default is baked in here (the config.py
32
32
  lesson: no schema in the mechanism) — callers supply every value.
@@ -40,6 +40,7 @@ from __future__ import annotations
40
40
  import json
41
41
  import urllib.request
42
42
  from typing import Any
43
+ from urllib.parse import urlsplit
43
44
 
44
45
  __all__ = ["anthropic_complete", "ollama_generate", "openai_complete"]
45
46
 
@@ -189,7 +190,10 @@ def ollama_generate(
189
190
  tool's own call site is responsible for any such post-processing.
190
191
 
191
192
  Raises:
192
- ValueError: ``system_mode`` is not one of the two known modes.
193
+ ValueError: ``base_url`` has a scheme other than ``http``/``https``
194
+ (``file://``, ``ftp://`` etc. would be opened by ``urlopen``), or
195
+ ``system_mode`` is not one of the two known modes. Loopback and
196
+ private hosts stay allowed on purpose (local Ollama).
193
197
  urllib.error.URLError, OSError: network/HTTP failure — propagates
194
198
  unchanged, no try/except here.
195
199
  json.JSONDecodeError: the outer HTTP body is not valid JSON —
@@ -197,6 +201,10 @@ def ollama_generate(
197
201
  KeyError: the outer JSON envelope has no ``"response"`` key —
198
202
  propagates unchanged.
199
203
  """
204
+ scheme = urlsplit(base_url).scheme.lower()
205
+ if scheme not in {"http", "https"}:
206
+ raise ValueError(f"unsupported base_url scheme: {scheme or '(none)'!r}")
207
+
200
208
  generate_url = f"{base_url.rstrip('/')}/api/generate"
201
209
 
202
210
  if system_mode == "fold":
@@ -0,0 +1,316 @@
1
+ """Shared prompt-injection detector for attacker-influenced strings.
2
+
3
+ Single source of truth for the regex pattern set + detection engine used by
4
+ every consumer (vex, sift). A bypass fixed here propagates to all of them.
5
+
6
+ Import-light: stdlib only (no pydantic), so ``import
7
+ shipwright_kit.security.injection`` stays dependency-free. The finding type is a
8
+ frozen dataclass; consumers serialize via ``dataclasses.asdict`` at their JSON
9
+ boundary.
10
+
11
+ Operates on plain string values. Tool-specific I/O — vex's ``sanitize`` (str ->
12
+ marker) and sift's ``redact_alert`` (Alert -> Alert) — stays in each tool.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import re
18
+ import unicodedata
19
+ from dataclasses import dataclass
20
+ from enum import Enum
21
+
22
+ __all__ = [
23
+ "INJECTION_PATTERNS_VERSION",
24
+ "InjectionFinding",
25
+ "PromptInjectionDetector",
26
+ "SeverityLevel",
27
+ "scan",
28
+ ]
29
+
30
+ # Bump when the pattern SET changes (added/removed/retuned pattern). Lets
31
+ # consumers assert they are matching against a known engine version, mirroring
32
+ # the EVAL_SCHEMA_VERSION / OUTPUT_SCHEMA_VERSION contract discipline (G10).
33
+ INJECTION_PATTERNS_VERSION = 2
34
+
35
+ # Cyrillic/Greek look-alikes folded to Latin before matching (written as
36
+ # escapes — never paste the raw characters). The mapping targets only letters
37
+ # that are visually indistinguishable from a Latin letter. Best-effort, not
38
+ # complete: Unicode has more look-alikes than are listed here.
39
+ _CONFUSABLES = str.maketrans(
40
+ {
41
+ "\u0430": "a",
42
+ "\u0435": "e",
43
+ "\u0456": "i",
44
+ "\u043e": "o",
45
+ "\u0440": "p",
46
+ "\u0441": "c",
47
+ "\u0443": "y",
48
+ "\u0445": "x",
49
+ "\u0455": "s",
50
+ "\u0458": "j",
51
+ "\u0501": "d",
52
+ "\u04cf": "l",
53
+ "\u03bf": "o",
54
+ "\u03b1": "a",
55
+ "\u03b5": "e",
56
+ "\u03b9": "i",
57
+ "\u03bd": "v",
58
+ "\u03c4": "t",
59
+ "\u03ba": "k",
60
+ "\u03c1": "p",
61
+ "\u0410": "A",
62
+ "\u0415": "E",
63
+ "\u0406": "I",
64
+ "\u041e": "O",
65
+ "\u0420": "P",
66
+ "\u0421": "C",
67
+ "\u0425": "X",
68
+ "\u039f": "O",
69
+ "\u0391": "A",
70
+ "\u0395": "E",
71
+ "\u0399": "I",
72
+ "\u039a": "K",
73
+ "\u03a1": "P",
74
+ "\u03a4": "T",
75
+ "\u0578": "n",
76
+ "\u0585": "o",
77
+ "\u057d": "u",
78
+ "\u0261": "g",
79
+ "\u026a": "i",
80
+ "\u1d0f": "o",
81
+ "\u0475": "v",
82
+ "\u0433": "r",
83
+ "\u0442": "t",
84
+ "\ua4f2": "l",
85
+ }
86
+ )
87
+
88
+
89
+ # Categories dropped from the matching copy: combining/enclosing marks, format,
90
+ # surrogate, private-use and control characters (whitespace is mapped to a space first).
91
+ _DROP_CATEGORIES = frozenset({"Mn", "Me", "Cf", "Cs", "Co", "Cc"})
92
+ # Invisible "filler" characters that are not in a dropped category (U+1D159 is
93
+ # category So, so a category rule cannot catch it). NFKD (not NFKC) is used so a
94
+ # combining mark on a letter is separated and dropped; as a consequence an
95
+ # operator whitelist pattern containing accented letters no longer matches
96
+ # (fail-safe: more findings, never fewer).
97
+ _FILLERS = frozenset("\u115f\u1160\u3164\uffa0\u2800\u17b4\u17b5\ufffc\u0640\U0001d159")
98
+
99
+
100
+ def _fold(value: str, invisible_as: str = "") -> str:
101
+ """NFKD, normalize whitespace, neutralize invisibles, fold confusables.
102
+
103
+ Every ``isspace()`` character (any category, e.g. VT, FF, NEL, FS-US) becomes
104
+ a plain space so ``\\s`` patterns keep matching. Remaining invisible/combining/
105
+ control characters and fillers are replaced by ``invisible_as`` ("" drops
106
+ them, catching ``ig<X>nore``; " " separates, catching ``output<X>instead``).
107
+ """
108
+ text = unicodedata.normalize("NFKD", value)
109
+ out: list[str] = []
110
+ for c in text:
111
+ if c.isspace():
112
+ out.append(" ")
113
+ elif c in _FILLERS or unicodedata.category(c) in _DROP_CATEGORIES:
114
+ out.append(invisible_as)
115
+ else:
116
+ out.append(c)
117
+ return "".join(out).translate(_CONFUSABLES)
118
+
119
+
120
+ def _fold_variants(value: str) -> list[str]:
121
+ """The dropped variant, plus the spaced variant when it differs."""
122
+ dropped = _fold(value)
123
+ spaced = _fold(value, " ")
124
+ return [dropped] if spaced == dropped else [dropped, spaced]
125
+
126
+
127
+ class SeverityLevel(str, Enum):
128
+ """Severity of an injection finding."""
129
+
130
+ WARNING = "WARNING"
131
+ CRITICAL = "CRITICAL"
132
+
133
+
134
+ @dataclass(frozen=True)
135
+ class InjectionFinding:
136
+ """A detected injection pattern in a string value.
137
+
138
+ Attribute names match the prior pydantic models in vex/sift so consumer
139
+ call sites and ``.field`` / ``.pattern_type`` / ``.severity`` access are
140
+ unchanged.
141
+ """
142
+
143
+ field: str
144
+ pattern_type: str
145
+ severity: SeverityLevel
146
+ redaction: str
147
+ value_preview: str | None = None
148
+
149
+
150
+ class PromptInjectionDetector:
151
+ """Detects prompt-injection patterns in plain string values.
152
+
153
+ Args:
154
+ case_insensitive: case-insensitive matching when True (default).
155
+ whitelist_patterns: regex strings for operator-defined known-safe
156
+ text. A whitelist match exempts only the matched text; content
157
+ outside it is still scanned. Matching runs on the normalized,
158
+ confusable-folded string. Known limit: a whitelisted token placed
159
+ inside an attack word splits it once the span is removed, which
160
+ requires knowing the operator's whitelist. A broad slot such as
161
+ ``\\S+`` also exempts whatever token an attacker places in it;
162
+ the breadth of each pattern is the operator's choice.
163
+ """
164
+
165
+ def __init__(
166
+ self,
167
+ case_insensitive: bool = True,
168
+ whitelist_patterns: list[str] | None = None,
169
+ ) -> None:
170
+ self.case_insensitive = case_insensitive
171
+ flags = re.IGNORECASE if case_insensitive else 0
172
+ self._whitelist: list[re.Pattern[str]] = [re.compile(p, flags) for p in (whitelist_patterns or [])]
173
+ self._compile_patterns()
174
+
175
+ def _compile_patterns(self) -> None:
176
+ flags = re.IGNORECASE if self.case_insensitive else 0
177
+
178
+ # Pattern 1: "ignore previous instructions" variants.
179
+ self.pattern_ignore_instructions = re.compile(
180
+ r"(ignore|disregard|forget|dismiss|bypass|override)[\s\S]{0,40}?"
181
+ r"(previous|prior|earlier|above|preceding)[\s\S]{0,40}?"
182
+ r"(instruction|directive|prompt|command|context|system)",
183
+ flags | re.DOTALL,
184
+ )
185
+
186
+ # Pattern 2: LLM-redirection via "instead" / "rather than".
187
+ self.pattern_instead_output = re.compile(
188
+ r"(?:"
189
+ r"(output|respond|return|generate|create|print|write)\s*instead"
190
+ r"|instead[\s,;.]*(?:of\s*)?(output|respond|return|generate|create|print|write)"
191
+ r"|rather\s*than\s*(?:summariz|analyz|triag|the\s*above)"
192
+ r")",
193
+ flags,
194
+ )
195
+
196
+ # Pattern 3: JSON escape sequences.
197
+ self.pattern_json_escapes = re.compile(
198
+ r'\\(?:["\\/bfnrtu]|u[0-9a-fA-F]{4})',
199
+ flags,
200
+ )
201
+
202
+ # Pattern 4: Base64 / hex encoded payloads (thresholds tuned to exclude
203
+ # common security terms like "Exfiltration"/"Configuration").
204
+ self.pattern_base64_hex = re.compile(
205
+ r"(?:"
206
+ r"(?=[A-Za-z0-9+/]*[+/])[A-Za-z0-9+/]{12,}"
207
+ r"|[A-Za-z0-9+/]{4,}=="
208
+ r"|[A-Za-z0-9+/]{8,}="
209
+ r"|(?:[0-9a-fA-F]{2}){10,}"
210
+ r"|[A-Za-z0-9]{20,}"
211
+ r")",
212
+ flags,
213
+ )
214
+
215
+ # Pattern 5: Shell command injection.
216
+ self.pattern_shell_commands = re.compile(
217
+ r"(?:\$\([^)\n]{0,200}\)|`[^`\n]{0,200}`|\$\w+)",
218
+ flags,
219
+ )
220
+
221
+ # Pattern 6: Jailbreak / role override — role verb + (restriction
222
+ # adjective bound to an AI-context noun | known idiom). Bare markers are
223
+ # rejected to avoid FP on real SOC text.
224
+ self.pattern_jailbreak = re.compile(
225
+ r"(?:act as|you are now|pretend to be|roleplay as|behave as)[\s\S]{0,40}?"
226
+ r"(?:"
227
+ r"(?:unrestricted|unfiltered|jailbroken|uncensored|unaligned)\s*"
228
+ r"(?:assistant|ai|model|chatbot|llm|gpt|bot|agent|persona|mode|version)"
229
+ r"|jailbroken"
230
+ r"|dan\b"
231
+ r"|do\s*anything\s*now"
232
+ r")",
233
+ flags | re.DOTALL,
234
+ )
235
+
236
+ # Pattern 7: System-prompt exfiltration — exfil verb + high-signal prompt
237
+ # noun only (system prompt / your [system] prompt / system instructions).
238
+ self.pattern_prompt_exfil = re.compile(
239
+ r"(?:reveal|print|show|output|repeat|leak|disclose|dump|expose|contents?\s*of)"
240
+ r"[\s\S]{0,40}?"
241
+ r"(?:system\s*prompt|system\s*instructions?"
242
+ r"|your\s*(?:system\s*)?prompt|your\s*system\s*instructions?)",
243
+ flags | re.DOTALL,
244
+ )
245
+
246
+ def detect(
247
+ self,
248
+ value: str,
249
+ field_name: str = "",
250
+ *,
251
+ is_ioc_field: bool = False,
252
+ ) -> list[InjectionFinding]:
253
+ """Scan a single string value. Empty list means clean."""
254
+ if not isinstance(value, str):
255
+ return []
256
+
257
+ findings: list[InjectionFinding] = []
258
+ seen: set[str] = set()
259
+ preview = self._truncate(value)
260
+
261
+ # Two folded variants (invisibles dropped / replaced by a space); findings
262
+ # are unioned and deduplicated by pattern_type.
263
+ for variant in _fold_variants(value):
264
+ normalized = variant
265
+ if self._whitelist:
266
+ for p in self._whitelist:
267
+ normalized = p.sub(lambda m: " " if m.end() > m.start() else "", normalized)
268
+ if not normalized.strip():
269
+ continue
270
+ for pattern_type, severity, redaction in self._match(normalized, is_ioc_field):
271
+ if pattern_type in seen:
272
+ continue
273
+ seen.add(pattern_type)
274
+ findings.append(
275
+ InjectionFinding(
276
+ field=field_name,
277
+ pattern_type=pattern_type,
278
+ severity=severity,
279
+ redaction=redaction,
280
+ value_preview=preview,
281
+ )
282
+ )
283
+
284
+ return findings
285
+
286
+ def _match(self, normalized: str, is_ioc_field: bool) -> list[tuple[str, SeverityLevel, str]]:
287
+ """Run every pattern on one folded string (if, not elif: all are reported)."""
288
+ hits: list[tuple[str, SeverityLevel, str]] = []
289
+ if self.pattern_ignore_instructions.search(normalized):
290
+ hits.append(("instruction_override", SeverityLevel.CRITICAL, "[REDACTED: instruction override attempt]"))
291
+ if self.pattern_instead_output.search(normalized):
292
+ hits.append(("output_manipulation", SeverityLevel.CRITICAL, "[REDACTED: output manipulation attempt]"))
293
+ if self.pattern_json_escapes.search(normalized):
294
+ hits.append(("json_escape_sequence", SeverityLevel.WARNING, "[REDACTED: JSON escape sequences]"))
295
+ if not is_ioc_field and self.pattern_base64_hex.search(normalized):
296
+ hits.append(("encoded_payload", SeverityLevel.WARNING, "[REDACTED: encoded payload]"))
297
+ if self.pattern_shell_commands.search(normalized):
298
+ hits.append(("shell_injection", SeverityLevel.CRITICAL, "[REDACTED: shell command attempt]"))
299
+ if self.pattern_jailbreak.search(normalized):
300
+ hits.append(("jailbreak", SeverityLevel.CRITICAL, "[REDACTED: jailbreak / role-override attempt]"))
301
+ if self.pattern_prompt_exfil.search(normalized):
302
+ hits.append(
303
+ ("prompt_exfiltration", SeverityLevel.CRITICAL, "[REDACTED: system-prompt exfiltration attempt]")
304
+ )
305
+ return hits
306
+
307
+ @staticmethod
308
+ def _truncate(value: str, max_len: int = 80) -> str:
309
+ if len(value) <= max_len:
310
+ return value
311
+ return value[:max_len] + "..."
312
+
313
+
314
+ def scan(value: str) -> list[InjectionFinding]:
315
+ """Scan a single string value with a default detector."""
316
+ return PromptInjectionDetector().detect(value)
@@ -1,20 +1,28 @@
1
- """Terminal-safe rendering of untrusted (LLM-sourced) text.
1
+ """Terminal-safe rendering of untrusted (attacker-influenced) text.
2
2
 
3
- Neutralizes the two ways attacker-influenced text — chiefly an LLM summary or
4
- explanation a model can be steered to emit — manipulates a Rich-rendered
5
- terminal when a consumer (vex, sift, barb) prints it:
3
+ Neutralizes the ways attacker-influenced text — an LLM summary or explanation
4
+ a model can be steered to emit, a URL, an IOC value, an API-response field, an
5
+ alert title — manipulates a Rich-rendered terminal when a consumer (vex, sift,
6
+ barb) prints it:
6
7
 
7
8
  * Rich console markup (``[red]``, ``[link=...]``) — escaped so it renders as
8
9
  literal text, following Rich's own ``\\[`` escape convention.
9
10
  * ANSI / OSC escape sequences and other C0/C1 control characters — stripped, so
10
11
  a model cannot move the cursor, recolor, set the window title, or emit OSC-8
11
12
  hyperlinks. TAB (``\\t``) and newline (``\\n``) are preserved.
13
+ * Bidirectional-override/isolate and zero-width format characters (U+200B,
14
+ U+200E/F, U+202A-U+202E, U+2060-U+2069, U+061C, U+FEFF) — stripped, so text
15
+ cannot be visually reordered or hidden. ZWJ/ZWNJ (U+200D/U+200C) are kept
16
+ because legitimate Persian/Indic shaping and emoji sequences need them.
17
+ Every other format (Cf) character (tag characters, soft hyphen, U+206A-206F,
18
+ U+FFF9-FFFB, U+180E), U+2028/U+2029 and U+034F are stripped as well.
12
19
 
13
20
  Render-sink half of the fleet's LLM-output hardening (OWASP LLM05, Improper
14
21
  Output Handling); the prompt-input half lives in
15
- :mod:`shipwright_kit.security.injection`. Apply ``safe_render`` to the
16
- LLM-sourced field ONLY — trusted app-generated markup (e.g. a severity-color
17
- span) must never be routed through it.
22
+ :mod:`shipwright_kit.security.injection`. Apply ``safe_render`` to EVERY
23
+ attacker-influenced field that reaches a render sink (LLM output, URLs, IOC
24
+ values, API-response fields, alert titles, cluster labels); never route trusted
25
+ app-generated markup (e.g. a severity-color span) through it.
18
26
 
19
27
  Import-light: stdlib only (``re``), no Rich import — mirrors the import-light
20
28
  invariant of :mod:`shipwright_kit.security.injection`.
@@ -23,11 +31,12 @@ invariant of :mod:`shipwright_kit.security.injection`.
23
31
  from __future__ import annotations
24
32
 
25
33
  import re
34
+ import unicodedata
26
35
 
27
36
  __all__ = ["SAFE_RENDER_VERSION", "safe_render"]
28
37
 
29
38
  # Bump when the neutralization rule set changes (added/removed/retuned rule).
30
- SAFE_RENDER_VERSION = 1
39
+ SAFE_RENDER_VERSION = 2
31
40
 
32
41
  # CSI (ESC [ ... final byte), OSC (ESC ] ... BEL | ESC \), and other two-char
33
42
  # ESC sequences.
@@ -38,6 +47,24 @@ _ANSI_RE = re.compile(
38
47
  )
39
48
  # C0/C1 control chars except TAB (\x09) and LF (\x0a).
40
49
  _CTRL_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
50
+ # Bidi overrides/isolates and zero-width format chars (escapes, not raw chars).
51
+ # ZWJ (U+200D) and ZWNJ (U+200C) are deliberately NOT included.
52
+ _BIDI_CF_RE = re.compile("[\u200b\u200e\u200f\u202a-\u202e\u2060-\u2069\u061c\ufeff]")
53
+ # Every category-Cf character is stripped (tag characters U+E0000-E007F, soft
54
+ # hyphen, U+206A-206F, U+FFF9-FFFB, U+180E, ...) except ZWJ/ZWNJ; U+2028/2029
55
+ # (line/paragraph separators) and U+034F (combining grapheme joiner) too.
56
+ _KEEP_CF = frozenset("\u200c\u200d")
57
+ _EXTRA_STRIP = frozenset("\u2028\u2029\u034f")
58
+
59
+
60
+ def _is_stripped(c: str) -> bool:
61
+ if c in _EXTRA_STRIP:
62
+ return True
63
+ return c not in _KEEP_CF and unicodedata.category(c) == "Cf"
64
+
65
+
66
+ def _strip_format_chars(text: str) -> str:
67
+ return "".join(c for c in text if not _is_stripped(c))
41
68
 
42
69
 
43
70
  def safe_render(text: str, *, escape_markup: bool = True) -> str:
@@ -49,11 +76,14 @@ def safe_render(text: str, *, escape_markup: bool = True) -> str:
49
76
  Rich-markup-enabled sink (``console.print`` / ``Panel``). Set
50
77
  ``escape_markup=False`` for a plain builtin-``print`` sink, where there is no
51
78
  Rich to interpret markup and escaping ``[`` would only add spurious
52
- backslashes (the control/ANSI strip still applies). Use on LLM-sourced /
53
- attacker-influenceable text at the render site.
79
+ backslashes (the control/ANSI/bidi strip still applies). Use on every
80
+ attacker-influenceable field at the render site (LLM output, URLs, IOC
81
+ values, API-response fields, alert titles, cluster labels).
54
82
  """
55
83
  text = _ANSI_RE.sub("", text)
56
84
  text = _CTRL_RE.sub("", text)
85
+ text = _BIDI_CF_RE.sub("", text)
86
+ text = _strip_format_chars(text)
57
87
  if escape_markup:
58
88
  # Escape Rich markup. Double backslashes first so an attacker-supplied
59
89
  # backslash cannot combine with the one we insert (Rich collapses \\ ->
@@ -0,0 +1,169 @@
1
+ """SSRF host-allowlist guard for outbound HTTP requests.
2
+
3
+ A primitive that callers wire explicitly at their own outbound-request sites;
4
+ it is not applied automatically to any shipwright_kit transport (loopback and
5
+ private Ollama hosts are legitimate for ``shipwright_kit.llm``). Hostnames are
6
+ resolved by default (``resolve=True``) and every resolved address is checked.
7
+
8
+ Import-light: stdlib only (``ipaddress``, ``urllib.parse``, ``socket``) — no
9
+ third-party deps, no import-time side effects. Mirrors the import-light
10
+ invariant of ``shipwright_kit.security.injection``.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import ipaddress
16
+ import socket
17
+ from typing import Any
18
+ from urllib.parse import urlsplit
19
+
20
+ __all__ = [
21
+ "UnsafeURLError",
22
+ "assert_safe_url",
23
+ "is_safe_url",
24
+ ]
25
+
26
+ _ALLOWED_SCHEMES = {"http", "https"}
27
+
28
+ _IPAddress = ipaddress.IPv4Address | ipaddress.IPv6Address
29
+
30
+
31
+ class UnsafeURLError(ValueError):
32
+ """Raised by :func:`assert_safe_url` when a URL is unsafe to fetch."""
33
+
34
+
35
+ _EXTRA_BLOCKED_NETS = (
36
+ ipaddress.ip_network("192.0.0.0/24"), # IETF protocol assignments
37
+ ipaddress.ip_network("64:ff9b::/96"), # NAT64 (embeds an IPv4 address)
38
+ ipaddress.ip_network("fec0::/10"), # deprecated site-local
39
+ )
40
+
41
+
42
+ def _is_blocked_ip(ip: _IPAddress, *, allow_loopback: bool) -> bool:
43
+ """True if `ip` should be blocked as an SSRF target.
44
+
45
+ An IPv4-mapped IPv6 address (``::ffff:a.b.c.d``) is judged as its embedded
46
+ IPv4 address. Loopback (127.0.0.0/8, ::1) is carved out first so
47
+ ``allow_loopback`` can permit it; every other address that is not globally
48
+ routable stays blocked unconditionally: link-local (incl. the
49
+ 169.254.169.254 cloud-metadata address), private/unique-local, CGNAT
50
+ (100.64.0.0/10, incl. 100.100.100.200), multicast, reserved, unspecified,
51
+ 192.0.0.0/24 and the NAT64 prefix.
52
+ """
53
+ if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None:
54
+ ip = ip.ipv4_mapped
55
+ if ip.is_loopback:
56
+ return not allow_loopback
57
+ if ip.is_multicast or ip.is_unspecified or ip.is_reserved or ip.is_link_local or ip.is_private:
58
+ return True
59
+ if not ip.is_global:
60
+ return True
61
+ return any(ip.version == net.version and ip in net for net in _EXTRA_BLOCKED_NETS)
62
+
63
+
64
+ def _literal_ip(host: str) -> _IPAddress | None:
65
+ """Parse `host` as an IP literal, incl. legacy IPv4 forms (``127.1``, ``2130706433``, ``0x7f.0.0.1``)."""
66
+ try:
67
+ return ipaddress.ip_address(host)
68
+ except ValueError:
69
+ pass
70
+ try:
71
+ return ipaddress.IPv4Address(socket.inet_ntoa(socket.inet_aton(host)))
72
+ except (OSError, ValueError):
73
+ return None
74
+
75
+
76
+ def assert_safe_url(
77
+ url: str,
78
+ *,
79
+ allow_loopback: bool = False,
80
+ resolve: bool = True,
81
+ allow_hosts: frozenset[str] | None = None,
82
+ ) -> None:
83
+ """Raise :class:`UnsafeURLError` if `url` is unsafe to fetch outbound; else return None.
84
+
85
+ Blocks:
86
+ - non-http(s) schemes (``file://``, ``ftp://``, etc.) and malformed URLs.
87
+ - IP-literal hosts in RFC1918 private ranges (10/8, 172.16/12, 192.168/16),
88
+ link-local ranges including the 169.254.169.254 cloud-metadata address
89
+ (169.254.0.0/16), IPv6 unique-local (fc00::/7), IPv6 link-local
90
+ (fe80::/10), and loopback (127.0.0.0/8, ::1) — unless
91
+ ``allow_loopback=True``.
92
+
93
+ ``resolve=True`` (the default): a non-IP-literal hostname is resolved via
94
+ ``socket.getaddrinfo`` and rejected if ANY resolved address is blocked.
95
+ With ``resolve=False`` a hostname cannot be vetted, so it raises unless it
96
+ is in ``allow_hosts`` (a case-insensitive set of explicitly trusted
97
+ hostnames, checked before DNS; a listed host skips resolution). IP-literal
98
+ hosts, including legacy forms such as ``127.1`` or ``2130706433`` and a
99
+ trailing dot, are always range-checked.
100
+
101
+ URLs containing a backslash, a control character, a space or any non-ASCII
102
+ character are rejected outright (parser-differential guard); callers must
103
+ IDNA-encode internationalized hostnames to ASCII first.
104
+
105
+ Caveat: this is a best-effort, TOCTOU-prone check. DNS is not pinned —
106
+ the hostname can re-resolve to a different (unsafe) address between this
107
+ check and the actual outbound request (a classic DNS-rebinding SSRF
108
+ bypass). Callers with a hard safety requirement should connect to the
109
+ resolved IP directly (not re-resolve the hostname) or maintain an
110
+ explicit host allowlist; this function is a guardrail, not a substitute
111
+ for that.
112
+ """
113
+ # Parser differential (CWE-918/436): urlsplit treats a backslash as an
114
+ # ordinary character, while urllib3/requests treat it as a delimiter, so
115
+ # ``http://127.0.0.1\\@example.com/`` would be vetted as example.com yet
116
+ # fetched from loopback. Reject anything the two parsers could disagree on.
117
+ if any(c == "\\" or c <= " " or c == "\x7f" or ord(c) > 0x7F for c in url):
118
+ raise UnsafeURLError(f"URL contains a backslash, control, space or non-ASCII character: {url!r}")
119
+
120
+ try:
121
+ parsed = urlsplit(url)
122
+ except ValueError as exc:
123
+ raise UnsafeURLError(f"malformed URL: {url!r}") from exc
124
+
125
+ scheme = parsed.scheme.lower()
126
+ if scheme not in _ALLOWED_SCHEMES:
127
+ raise UnsafeURLError(f"unsupported scheme: {scheme or '(none)'!r}")
128
+
129
+ # Not wrapped in try/except: urlsplit() above already rejects malformed
130
+ # IPv6-bracket netlocs before .hostname would ever raise.
131
+ host = parsed.hostname
132
+ if not host:
133
+ raise UnsafeURLError(f"URL has no host: {url!r}")
134
+
135
+ if host.endswith("."):
136
+ host = host[:-1]
137
+ literal_ip = _literal_ip(host)
138
+
139
+ if literal_ip is not None:
140
+ if _is_blocked_ip(literal_ip, allow_loopback=allow_loopback):
141
+ raise UnsafeURLError(f"blocked address: {host}")
142
+ return None
143
+
144
+ if allow_hosts is not None and host.lower() in {h.lower() for h in allow_hosts}:
145
+ return None
146
+
147
+ if not resolve:
148
+ raise UnsafeURLError(f"host {host!r} is not an IP literal and is not in allow_hosts (resolve=False)")
149
+
150
+ try:
151
+ infos = socket.getaddrinfo(host, None)
152
+ except OSError as exc:
153
+ raise UnsafeURLError(f"could not resolve host: {host!r} ({exc})") from exc
154
+ for info in infos:
155
+ sockaddr = info[4]
156
+ resolved_ip = ipaddress.ip_address(sockaddr[0])
157
+ if _is_blocked_ip(resolved_ip, allow_loopback=allow_loopback):
158
+ raise UnsafeURLError(f"host {host!r} resolves to blocked address: {sockaddr[0]}")
159
+
160
+ return None
161
+
162
+
163
+ def is_safe_url(url: str, **kwargs: Any) -> bool:
164
+ """Convenience wrapper: True if `url` passes :func:`assert_safe_url`, else False."""
165
+ try:
166
+ assert_safe_url(url, **kwargs)
167
+ except UnsafeURLError:
168
+ return False
169
+ return True
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: shipwright-kit
3
- Version: 0.12.0
3
+ Version: 0.12.1
4
4
  Summary: Shipwright — AI-agent dev framework + import-light design/eval/security library
5
5
  Author: Christian Huhn
6
6
  License-Expression: MIT
@@ -471,6 +471,32 @@ class TestOllamaExceptionTransparency:
471
471
  )
472
472
 
473
473
 
474
+ class TestOllamaBaseUrlScheme:
475
+ """Audit F10: only http(s) base URLs may reach urlopen (file://, ftp:// would be read/fetched)."""
476
+
477
+ @pytest.mark.parametrize("base_url", ["file:///etc/hosts", "ftp://x", "FILE:///etc/hosts", "localhost:11434", ""])
478
+ def test_non_http_scheme_rejected_before_urlopen(self, monkeypatch, base_url):
479
+ def fail_urlopen(*args, **kwargs):
480
+ raise AssertionError("urlopen must not be called for an unsupported scheme")
481
+
482
+ monkeypatch.setattr("shipwright_kit.llm.urllib.request.urlopen", fail_urlopen)
483
+ with pytest.raises(ValueError, match="base_url scheme"):
484
+ ollama_generate(base_url=base_url, model="m", system="s", user="u", timeout=None, system_mode="fold")
485
+
486
+ def test_scheme_error_is_distinct_from_system_mode_error(self, monkeypatch):
487
+ monkeypatch.setattr("shipwright_kit.llm.urllib.request.urlopen", lambda *a, **k: None)
488
+ with pytest.raises(ValueError, match="base_url scheme"):
489
+ ollama_generate(base_url="ftp://x", model="m", system="s", user="u", timeout=None, system_mode="bogus")
490
+
491
+ @pytest.mark.parametrize(
492
+ "base_url", ["http://localhost:11434", "https://ollama.example.com", "HTTP://localhost:11434"]
493
+ )
494
+ def test_http_and_https_accepted(self, monkeypatch, base_url):
495
+ _install_fake_urlopen(monkeypatch, {"response": "ok"})
496
+ out = ollama_generate(base_url=base_url, model="m", system="s", user="u", timeout=None, system_mode="fold")
497
+ assert out == "ok"
498
+
499
+
474
500
  # ---------------------------------------------------------------------------
475
501
  # Dumb-transport contract: no redaction/scanning of system/user text.
476
502
  # ---------------------------------------------------------------------------
@@ -1,206 +0,0 @@
1
- """Shared prompt-injection detector for attacker-influenced strings.
2
-
3
- Single source of truth for the regex pattern set + detection engine used by
4
- every consumer (vex, sift). A bypass fixed here propagates to all of them.
5
-
6
- Import-light: stdlib only (no pydantic), so ``import
7
- shipwright_kit.security.injection`` stays dependency-free. The finding type is a
8
- frozen dataclass; consumers serialize via ``dataclasses.asdict`` at their JSON
9
- boundary.
10
-
11
- Operates on plain string values. Tool-specific I/O — vex's ``sanitize`` (str ->
12
- marker) and sift's ``redact_alert`` (Alert -> Alert) — stays in each tool.
13
- """
14
-
15
- from __future__ import annotations
16
-
17
- import re
18
- import unicodedata
19
- from dataclasses import dataclass
20
- from enum import Enum
21
-
22
- __all__ = [
23
- "INJECTION_PATTERNS_VERSION",
24
- "InjectionFinding",
25
- "PromptInjectionDetector",
26
- "SeverityLevel",
27
- "scan",
28
- ]
29
-
30
- # Bump when the pattern SET changes (added/removed/retuned pattern). Lets
31
- # consumers assert they are matching against a known engine version, mirroring
32
- # the EVAL_SCHEMA_VERSION / OUTPUT_SCHEMA_VERSION contract discipline (G10).
33
- INJECTION_PATTERNS_VERSION = 1
34
-
35
-
36
- class SeverityLevel(str, Enum):
37
- """Severity of an injection finding."""
38
-
39
- WARNING = "WARNING"
40
- CRITICAL = "CRITICAL"
41
-
42
-
43
- @dataclass(frozen=True)
44
- class InjectionFinding:
45
- """A detected injection pattern in a string value.
46
-
47
- Attribute names match the prior pydantic models in vex/sift so consumer
48
- call sites and ``.field`` / ``.pattern_type`` / ``.severity`` access are
49
- unchanged.
50
- """
51
-
52
- field: str
53
- pattern_type: str
54
- severity: SeverityLevel
55
- redaction: str
56
- value_preview: str | None = None
57
-
58
-
59
- class PromptInjectionDetector:
60
- """Detects prompt-injection patterns in plain string values.
61
-
62
- Args:
63
- case_insensitive: case-insensitive matching when True (default).
64
- whitelist_patterns: regex strings; a value matching any one is exempt
65
- from all checks (operator-defined known-safe templates).
66
- """
67
-
68
- def __init__(
69
- self,
70
- case_insensitive: bool = True,
71
- whitelist_patterns: list[str] | None = None,
72
- ) -> None:
73
- self.case_insensitive = case_insensitive
74
- flags = re.IGNORECASE if case_insensitive else 0
75
- self._whitelist: list[re.Pattern[str]] = [re.compile(p, flags) for p in (whitelist_patterns or [])]
76
- self._compile_patterns()
77
-
78
- def _compile_patterns(self) -> None:
79
- flags = re.IGNORECASE if self.case_insensitive else 0
80
-
81
- # Pattern 1: "ignore previous instructions" variants.
82
- self.pattern_ignore_instructions = re.compile(
83
- r"(ignore|disregard|forget|dismiss|bypass|override)[\s\S]{0,40}?"
84
- r"(previous|prior|earlier|above|preceding)[\s\S]{0,40}?"
85
- r"(instruction|directive|prompt|command|context|system)",
86
- flags | re.DOTALL,
87
- )
88
-
89
- # Pattern 2: LLM-redirection via "instead" / "rather than".
90
- self.pattern_instead_output = re.compile(
91
- r"(?:"
92
- r"(output|respond|return|generate|create|print|write)\s+instead"
93
- r"|instead[\s,;.]+(?:of\s+)?(output|respond|return|generate|create|print|write)"
94
- r"|rather\s+than\s+(?:summariz|analyz|triag|the\s+above)"
95
- r")",
96
- flags,
97
- )
98
-
99
- # Pattern 3: JSON escape sequences.
100
- self.pattern_json_escapes = re.compile(
101
- r'\\(?:["\\/bfnrtu]|u[0-9a-fA-F]{4})',
102
- flags,
103
- )
104
-
105
- # Pattern 4: Base64 / hex encoded payloads (thresholds tuned to exclude
106
- # common security terms like "Exfiltration"/"Configuration").
107
- self.pattern_base64_hex = re.compile(
108
- r"(?:"
109
- r"(?=[A-Za-z0-9+/]*[+/])[A-Za-z0-9+/]{12,}"
110
- r"|[A-Za-z0-9+/]{4,}=="
111
- r"|[A-Za-z0-9+/]{8,}="
112
- r"|(?:[0-9a-fA-F]{2}){10,}"
113
- r"|[A-Za-z0-9]{20,}"
114
- r")",
115
- flags,
116
- )
117
-
118
- # Pattern 5: Shell command injection.
119
- self.pattern_shell_commands = re.compile(
120
- r"(?:\$\([^)]*\)|`[^`]*`|\$\w+)",
121
- flags,
122
- )
123
-
124
- # Pattern 6: Jailbreak / role override — role verb + (restriction
125
- # adjective bound to an AI-context noun | known idiom). Bare markers are
126
- # rejected to avoid FP on real SOC text.
127
- self.pattern_jailbreak = re.compile(
128
- r"(?:act as|you are now|pretend to be|roleplay as|behave as)[\s\S]{0,40}?"
129
- r"(?:"
130
- r"(?:unrestricted|unfiltered|jailbroken|uncensored|unaligned)\s+"
131
- r"(?:assistant|ai|model|chatbot|llm|gpt|bot|agent|persona|mode|version)"
132
- r"|jailbroken"
133
- r"|dan\b"
134
- r"|do\s+anything\s+now"
135
- r")",
136
- flags | re.DOTALL,
137
- )
138
-
139
- # Pattern 7: System-prompt exfiltration — exfil verb + high-signal prompt
140
- # noun only (system prompt / your [system] prompt / system instructions).
141
- self.pattern_prompt_exfil = re.compile(
142
- r"(?:reveal|print|show|output|repeat|leak|disclose|dump|expose|contents?\s+of)"
143
- r"[\s\S]{0,40}?"
144
- r"(?:system\s*prompt|system\s+instructions?"
145
- r"|your\s+(?:system\s+)?prompt|your\s+system\s+instructions?)",
146
- flags | re.DOTALL,
147
- )
148
-
149
- def detect(
150
- self,
151
- value: str,
152
- field_name: str = "",
153
- *,
154
- is_ioc_field: bool = False,
155
- ) -> list[InjectionFinding]:
156
- """Scan a single string value. Empty list means clean."""
157
- if not isinstance(value, str):
158
- return []
159
-
160
- normalized = unicodedata.normalize("NFKC", value)
161
-
162
- if self._whitelist and any(p.search(normalized) for p in self._whitelist):
163
- return []
164
-
165
- findings: list[InjectionFinding] = []
166
- preview = self._truncate(value)
167
-
168
- def add(pattern_type: str, severity: SeverityLevel, redaction: str) -> None:
169
- findings.append(
170
- InjectionFinding(
171
- field=field_name,
172
- pattern_type=pattern_type,
173
- severity=severity,
174
- redaction=redaction,
175
- value_preview=preview,
176
- )
177
- )
178
-
179
- # if (not elif) so all patterns in a value are reported.
180
- if self.pattern_ignore_instructions.search(normalized):
181
- add("instruction_override", SeverityLevel.CRITICAL, "[REDACTED: instruction override attempt]")
182
- if self.pattern_instead_output.search(normalized):
183
- add("output_manipulation", SeverityLevel.CRITICAL, "[REDACTED: output manipulation attempt]")
184
- if self.pattern_json_escapes.search(normalized):
185
- add("json_escape_sequence", SeverityLevel.WARNING, "[REDACTED: JSON escape sequences]")
186
- if not is_ioc_field and self.pattern_base64_hex.search(normalized):
187
- add("encoded_payload", SeverityLevel.WARNING, "[REDACTED: encoded payload]")
188
- if self.pattern_shell_commands.search(normalized):
189
- add("shell_injection", SeverityLevel.CRITICAL, "[REDACTED: shell command attempt]")
190
- if self.pattern_jailbreak.search(normalized):
191
- add("jailbreak", SeverityLevel.CRITICAL, "[REDACTED: jailbreak / role-override attempt]")
192
- if self.pattern_prompt_exfil.search(normalized):
193
- add("prompt_exfiltration", SeverityLevel.CRITICAL, "[REDACTED: system-prompt exfiltration attempt]")
194
-
195
- return findings
196
-
197
- @staticmethod
198
- def _truncate(value: str, max_len: int = 80) -> str:
199
- if len(value) <= max_len:
200
- return value
201
- return value[:max_len] + "..."
202
-
203
-
204
- def scan(value: str) -> list[InjectionFinding]:
205
- """Scan a single string value with a default detector."""
206
- return PromptInjectionDetector().detect(value)
@@ -1,123 +0,0 @@
1
- """SSRF host-allowlist guard for outbound HTTP requests.
2
-
3
- Pre-committed guardrail for W3 (the LLM-provider layer making ollama's
4
- ``base_url`` configurable). This module is the primitive ONLY — it is not
5
- wired into any tool or into ``ollama.py`` yet (``base_url`` is hardcoded
6
- today, so wiring now would be dead code in the shipped path). W3 does the
7
- wiring.
8
-
9
- Import-light: stdlib only (``ipaddress``, ``urllib.parse``, ``socket``) — no
10
- third-party deps, no import-time side effects. Mirrors the import-light
11
- invariant of ``shipwright_kit.security.injection``.
12
- """
13
-
14
- from __future__ import annotations
15
-
16
- import ipaddress
17
- import socket
18
- from urllib.parse import urlsplit
19
-
20
- __all__ = [
21
- "UnsafeURLError",
22
- "assert_safe_url",
23
- "is_safe_url",
24
- ]
25
-
26
- _ALLOWED_SCHEMES = {"http", "https"}
27
-
28
- _IPAddress = ipaddress.IPv4Address | ipaddress.IPv6Address
29
-
30
-
31
- class UnsafeURLError(ValueError):
32
- """Raised by :func:`assert_safe_url` when a URL is unsafe to fetch."""
33
-
34
-
35
- def _is_blocked_ip(ip: _IPAddress, *, allow_loopback: bool) -> bool:
36
- """True if `ip` should be blocked as an SSRF target.
37
-
38
- Loopback (127.0.0.0/8, ::1) is carved out first so ``allow_loopback``
39
- can permit it — every other non-globally-routable range stays blocked
40
- unconditionally: link-local (169.254.0.0/16, incl. the 169.254.169.254
41
- cloud-metadata address, and IPv6 fe80::/10), RFC1918 private ranges and
42
- IPv6 unique-local (fc00::/7) via ``is_private``, plus multicast/
43
- reserved/unspecified as defense in depth.
44
- """
45
- if ip.is_loopback:
46
- return not allow_loopback
47
- if ip.is_link_local:
48
- return True
49
- if ip.is_multicast or ip.is_reserved or ip.is_unspecified:
50
- return True
51
- if ip.is_private:
52
- return True
53
- return False
54
-
55
-
56
- def assert_safe_url(url: str, *, allow_loopback: bool = False, resolve: bool = False) -> None:
57
- """Raise :class:`UnsafeURLError` if `url` is unsafe to fetch outbound; else return None.
58
-
59
- Blocks:
60
- - non-http(s) schemes (``file://``, ``ftp://``, etc.) and malformed URLs.
61
- - IP-literal hosts in RFC1918 private ranges (10/8, 172.16/12, 192.168/16),
62
- link-local ranges including the 169.254.169.254 cloud-metadata address
63
- (169.254.0.0/16), IPv6 unique-local (fc00::/7), IPv6 link-local
64
- (fe80::/10), and loopback (127.0.0.0/8, ::1) — unless
65
- ``allow_loopback=True``.
66
-
67
- When ``resolve=True``, a non-IP-literal hostname is resolved via
68
- ``socket.getaddrinfo`` and rejected if ANY resolved address is blocked.
69
-
70
- Caveat: this is a best-effort, TOCTOU-prone check. DNS is not pinned —
71
- the hostname can re-resolve to a different (unsafe) address between this
72
- check and the actual outbound request (a classic DNS-rebinding SSRF
73
- bypass). Callers with a hard safety requirement should connect to the
74
- resolved IP directly (not re-resolve the hostname) or maintain an
75
- explicit host allowlist; this function is a guardrail, not a substitute
76
- for that.
77
- """
78
- try:
79
- parsed = urlsplit(url)
80
- except ValueError as exc:
81
- raise UnsafeURLError(f"malformed URL: {url!r}") from exc
82
-
83
- scheme = parsed.scheme.lower()
84
- if scheme not in _ALLOWED_SCHEMES:
85
- raise UnsafeURLError(f"unsupported scheme: {scheme or '(none)'!r}")
86
-
87
- # Not wrapped in try/except: urlsplit() above already rejects malformed
88
- # IPv6-bracket netlocs before .hostname would ever raise.
89
- host = parsed.hostname
90
- if not host:
91
- raise UnsafeURLError(f"URL has no host: {url!r}")
92
-
93
- try:
94
- literal_ip: _IPAddress | None = ipaddress.ip_address(host)
95
- except ValueError:
96
- literal_ip = None
97
-
98
- if literal_ip is not None:
99
- if _is_blocked_ip(literal_ip, allow_loopback=allow_loopback):
100
- raise UnsafeURLError(f"blocked address: {host}")
101
- return None
102
-
103
- if resolve:
104
- try:
105
- infos = socket.getaddrinfo(host, None)
106
- except OSError as exc:
107
- raise UnsafeURLError(f"could not resolve host: {host!r} ({exc})") from exc
108
- for info in infos:
109
- sockaddr = info[4]
110
- resolved_ip = ipaddress.ip_address(sockaddr[0])
111
- if _is_blocked_ip(resolved_ip, allow_loopback=allow_loopback):
112
- raise UnsafeURLError(f"host {host!r} resolves to blocked address: {sockaddr[0]}")
113
-
114
- return None
115
-
116
-
117
- def is_safe_url(url: str, **kwargs: bool) -> bool:
118
- """Convenience wrapper: True if `url` passes :func:`assert_safe_url`, else False."""
119
- try:
120
- assert_safe_url(url, **kwargs)
121
- except UnsafeURLError:
122
- return False
123
- return True
File without changes