Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(security): cap fetched page bodies, contain screenshot paths, time out the schema hook

Agrici Daniel1644ffec7cb9
diff --git a/hooks/hooks.json b/hooks/hooks.json
index 51d70f7..dd4b9cc 100644
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -11,7 +11,8 @@
"${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js",
"${CLAUDE_PLUGIN_ROOT}/hooks/validate-schema.py",
"${tool_input.file_path}"
- ]
+ ],
+ "timeout": 30
}
]
}
diff --git a/scripts/capture_screenshot.py b/scripts/capture_screenshot.py
index 0df2b3a..6f94db8 100755
--- a/scripts/capture_screenshot.py
+++ b/scripts/capture_screenshot.py
@@ -158,6 +158,27 @@ def capture_screenshot(
return result
+def _within(path: str, root: str) -> bool:
+ """True when ``path`` is ``root`` or inside it (both already resolved)."""
+ try:
+ return os.path.commonpath([path, root]) == root
+ except ValueError: # different drives on Windows
+ return False
+
+
+def safe_output_dir(path: str) -> str | None:
+ """Resolve ``path`` and return it when it lies within the current
+ directory or the home directory, else None.
+
+ Both roots are resolved too: a plain string prefix check let
+ ``/home/user2`` pass for ``/home/user``, and a symlinked home (for
+ example ``/home`` -> ``/var/home``) never matched a resolved path.
+ """
+ resolved = os.path.realpath(path)
+ roots = (os.path.realpath(os.getcwd()), os.path.realpath(os.path.expanduser("~")))
+ return resolved if any(_within(resolved, root) for root in roots) else None
+
+
def main():
parser = argparse.ArgumentParser(description="Capture web page screenshots")
parser.add_argument("url", help="URL to capture")
@@ -170,15 +191,13 @@ def main():
args = parser.parse_args()
# Sanitize output path - prevent directory traversal
- output_dir = os.path.realpath(args.output)
- cwd = os.getcwd()
- home = os.path.expanduser("~")
- if not (output_dir.startswith(cwd) or output_dir.startswith(home)):
+ output_dir = safe_output_dir(args.output)
+ if output_dir is None:
print("Error: Output path must be within current directory or home directory", file=sys.stderr)
sys.exit(1)
# Create output directory
- os.makedirs(args.output, exist_ok=True)
+ os.makedirs(output_dir, exist_ok=True)
try:
normalized_url, parsed_url = normalize_url(args.url)
@@ -193,7 +212,7 @@ def main():
for viewport in viewports:
filename = f"{base_name}_{viewport}.png"
- output_path = os.path.join(args.output, filename)
+ output_path = os.path.join(output_dir, filename)
print(f"Capturing {viewport} screenshot...")
result = capture_screenshot(
diff --git a/scripts/fetch_page.py b/scripts/fetch_page.py
index c9c7274..e4780ff 100755
--- a/scripts/fetch_page.py
+++ b/scripts/fetch_page.py
@@ -34,7 +34,9 @@ if _SCRIPTS_DIR not in sys.path:
from url_safety import ( # noqa: E402
DEFAULT_REQUEST_HEADERS,
URLSafetyError,
+ decode_body,
decode_response_text,
+ read_bounded,
safe_requests_session,
validate_url_strict,
)
@@ -63,6 +65,10 @@ DEFAULT_HEADERS = dict(DEFAULT_REQUEST_HEADERS)
# that fetches through the safe helpers decodes the same way (issue #314).
_decode_response_content = decode_response_text
+# Largest body read, counted after decompression. Real HTML pages are far
+# smaller; the cap stops a decompression bomb or an endless stream.
+MAX_PAGE_BYTES = 10 * 1024 * 1024
+
def fetch_page(
url: str,
@@ -70,6 +76,7 @@ def fetch_page(
follow_redirects: bool = True,
max_redirects: int = 5,
user_agent: Optional[str] = None,
+ max_bytes: int = MAX_PAGE_BYTES,
) -> dict:
"""
Fetch a web page and return response details.
@@ -85,10 +92,13 @@ def fetch_page(
follow_redirects: Whether to follow redirects
max_redirects: Maximum number of redirects to follow
user_agent: Override the default User-Agent
+ max_bytes: Stop reading the body past this many bytes (after
+ decompression); ``too_large`` is then True and ``content`` holds
+ the part read.
Returns:
Dictionary with url, status_code, content, headers, redirect_chain,
- redirect_details, and error.
+ redirect_details, too_large, and error.
"""
result: dict = {
"url": url,
@@ -97,6 +107,7 @@ def fetch_page(
"headers": {},
"redirect_chain": [],
"redirect_details": [],
+ "too_large": False,
"error": None,
}
@@ -124,11 +135,18 @@ def fetch_page(
headers=headers,
timeout=timeout,
allow_redirects=follow_redirects,
+ stream=True,
)
+ # Streamed so the body is read under the cap, inside the pinned
+ # session; .content must not be read after this.
+ try:
+ raw, result["too_large"] = read_bounded(response, max_bytes)
+ finally:
+ response.close()
result["url"] = response.url
result["status_code"] = response.status_code
- result["content"] = _decode_response_content(response)
+ result["content"] = decode_body(raw, response.headers.get("Content-Type", ""))
result["headers"] = dict(response.headers)
if response.history:
@@ -191,7 +209,11 @@ def _as_render_result(result: dict, *, mode_used: str) -> dict:
"headers": result.get("headers", {}),
"redirect_chain": redirect_chain,
"console_errors": [],
- "render_diagnostics": [],
+ "render_diagnostics": (
+ ["body exceeded the size cap; content holds the part read before it"]
+ if result.get("too_large")
+ else []
+ ),
"render_engine": None,
"render_ms": None,
"mode_used": mode_used,
diff --git a/scripts/sitemap_discovery.py b/scripts/sitemap_discovery.py
index 47b237b..9ee766c 100644
--- a/scripts/sitemap_discovery.py
+++ b/scripts/sitemap_discovery.py
@@ -22,7 +22,7 @@ _SCRIPTS = os.path.dirname(os.path.abspath(__file__))
if _SCRIPTS not in sys.path:
sys.path.insert(0, _SCRIPTS)
-from url_safety import URLSafetyError, safe_requests_session, validate_url # noqa: E402
+from url_safety import URLSafetyError, read_bounded, safe_requests_session, validate_url # noqa: E402
COMMON_PATHS = (
"/sitemap.xml",
@@ -93,17 +93,7 @@ def _bounded_fetch(url: str, max_bytes: int) -> dict:
result["status_code"] = response.status_code
result["content_type"] = response.headers.get("Content-Type", "")
result["final_url"] = response.url
- chunks = []
- size = 0
- for chunk in response.iter_content(chunk_size=65536):
- if not chunk:
- continue
- size += len(chunk)
- if size > max_bytes:
- result["too_large"] = True
- break
- chunks.append(chunk)
- result["content"] = b"".join(chunks)
+ result["content"], result["too_large"] = read_bounded(response, max_bytes)
response.close()
except URLSafetyError:
result["error"] = "URL safety validation failed"
diff --git a/scripts/url_safety.py b/scripts/url_safety.py
index b4dd25e..6df77cd 100644
--- a/scripts/url_safety.py
+++ b/scripts/url_safety.py
@@ -845,6 +845,28 @@ def decode_body(raw: bytes, content_type: str = "") -> str:
return raw.decode("utf-8", errors="replace")
+def read_bounded(response, max_bytes: int) -> tuple[bytes, bool]:
+ """Read a ``stream=True`` response body, stopping past ``max_bytes``.
+
+ Counts bytes after decompression, so a small gzip body that inflates
+ without bound (a decompression bomb) is cut off. Returns the bytes read
+ before the chunk that crossed the cap, and whether the cap was hit.
+ Decode the result with :func:`decode_body`, not ``response.content``.
+ """
+ chunks = []
+ size = 0
+ too_large = False
+ for chunk in response.iter_content(chunk_size=65536):
+ if not chunk:
+ continue
+ size += len(chunk)
+ if size > max_bytes:
+ too_large = True
+ break
+ chunks.append(chunk)
+ return b"".join(chunks), too_large
+
+
def _with_default_headers(kwargs: dict) -> dict:
"""Fill in DEFAULT_REQUEST_HEADERS for header keys the caller did not set."""
headers = dict(DEFAULT_REQUEST_HEADERS)
diff --git a/tests/test_capture_screenshot_paths.py b/tests/test_capture_screenshot_paths.py
new file mode 100644
index 0000000..b7d4d15
--- /dev/null
+++ b/tests/test_capture_screenshot_paths.py
@@ -0,0 +1,68 @@
+"""capture_screenshot.py only writes inside the current or home directory.
+
+The old check compared string prefixes, so a sibling such as /home/user2
+passed for /home/user, and a symlinked home never matched a resolved path.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("playwright")
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+import capture_screenshot # noqa: E402
+
+
+def roots(tmp_path, monkeypatch):
+ home = tmp_path / "home" / "user"
+ work = home / "project"
+ work.mkdir(parents=True)
+ monkeypatch.setenv("HOME", str(home))
+ monkeypatch.setenv("USERPROFILE", str(home))
+ monkeypatch.chdir(work)
+ return tmp_path, home, work
+
+
+def test_paths_inside_cwd_or_home_are_allowed(roots):
+ _tmp, home, work = roots
+ assert capture_screenshot.safe_output_dir("screenshots") == os.path.realpath(work / "screenshots")
+ assert capture_screenshot.safe_output_dir(str(home / "shots")) == os.path.realpath(home / "shots")
+ assert capture_screenshot.safe_output_dir(str(home)) == os.path.realpath(home)
+
+
+def test_sibling_with_a_shared_prefix_is_refused(roots):
+ tmp, _home, _work = roots
+ assert capture_screenshot.safe_output_dir(str(tmp / "home" / "user2" / "shots")) is None
+ assert capture_screenshot.safe_output_dir(str(tmp / "home" / "user-evil")) is None
+
+
+def test_traversal_out_of_the_roots_is_refused(roots):
+ assert capture_screenshot.safe_output_dir("../../../outside") is None
+
+
[email protected](os.name != "posix", reason="symlinks need POSIX here")
+def test_symlinked_home_still_matches(tmp_path, monkeypatch):
+ real = tmp_path / "var" / "home" / "user"
+ real.mkdir(parents=True)
+ (tmp_path / "home").symlink_to(tmp_path / "var" / "home")
+ monkeypatch.setenv("HOME", str(tmp_path / "home" / "user"))
+ monkeypatch.chdir(tmp_path)
+ assert capture_screenshot.safe_output_dir(str(tmp_path / "home" / "user" / "shots")) == str(real / "shots")
+
+
+def test_main_writes_into_the_resolved_directory(roots, monkeypatch):
+ _tmp, _home, work = roots
+ calls = []
+ monkeypatch.setattr(
+ capture_screenshot, "capture_screenshot",
+ lambda url, path, **kw: calls.append(path) or {"success": True, "error": None},
+ )
+ monkeypatch.setattr(sys, "argv", ["capture_screenshot.py", "https://example.com", "-o", "shots"])
+ capture_screenshot.main()
+ assert calls == [os.path.join(os.path.realpath(work / "shots"), "example_com_desktop.png")]
+ assert (work / "shots").is_dir()
diff --git a/tests/test_cross_platform_hooks.py b/tests/test_cross_platform_hooks.py
index 8ae7e00..51ba968 100644
--- a/tests/test_cross_platform_hooks.py
+++ b/tests/test_cross_platform_hooks.py
@@ -32,6 +32,9 @@ def test_schema_hook_uses_exec_form_args_and_tool_input_placeholder() -> None:
assert handler["args"][0] == "${CLAUDE_PLUGIN_ROOT}/hooks/run-python-hook.js"
assert handler["args"][1] == "${CLAUDE_PLUGIN_ROOT}/hooks/validate-schema.py"
assert handler["args"][2] == "${tool_input.file_path}"
+ # Seconds. The hook runs one local Python validator; a hung interpreter
+ # probe must not stall every Edit or Write for the default 10 minutes.
+ assert handler["timeout"] == 30
assert "$FILE_PATH" not in serialized
assert "$" not in handler["command"]
assert handler["command"] != "sh"
diff --git a/tests/test_fetch_page_size_cap.py b/tests/test_fetch_page_size_cap.py
new file mode 100644
index 0000000..5b600db
--- /dev/null
+++ b/tests/test_fetch_page_size_cap.py
@@ -0,0 +1,87 @@
+"""fetch_page.py stops reading a body past its size cap (after decompression).
+
+A tiny gzip body can inflate without bound; the cap counts decompressed
+bytes, so it holds. The server is a local stub reached through a fake
+session, so no network is used.
+"""
+
+from __future__ import annotations
+
+import gzip
+import io
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+
+import requests
+from urllib3.response import HTTPResponse
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+import fetch_page # noqa: E402
+import url_safety # noqa: E402
+
+
+def _streamed_response(body: bytes, *, gzipped: bool = False) -> requests.Response:
+ """A streamed requests.Response built the way the HTTP adapter builds one."""
+ headers = {"Content-Type": "text/html; charset=utf-8"}
+ payload = body
+ if gzipped:
+ payload = gzip.compress(body)
+ headers["Content-Encoding"] = "gzip"
+ raw = HTTPResponse(body=io.BytesIO(payload), headers=headers, status=200, preload_content=False)
+ resp = requests.Response()
+ resp.status_code = 200
+ resp.headers.update(headers)
+ resp.raw = raw
+ resp.url = "https://example.com/"
+ return resp
+
+
+def _patched_fetch(monkeypatch, response: requests.Response, **kwargs) -> dict:
+ seen = {}
+
+ class _Session:
+ max_redirects = 5
+
+ def get(self, url, **kw):
+ seen.update(kw)
+ return response
+
+ @contextmanager
+ def fake_session(_url):
+ yield _Session()
+
+ monkeypatch.setattr(fetch_page, "validate_url_strict", lambda url: (url, "93.184.216.34"))
+ monkeypatch.setattr(fetch_page, "safe_requests_session", fake_session)
+ result = fetch_page.fetch_page("https://example.com/", **kwargs)
+ result["_stream"] = seen.get("stream")
+ return result
+
+
+def test_gzip_bomb_is_cut_at_the_cap(monkeypatch):
+ bomb = _streamed_response(b"A" * (8 * 1024 * 1024), gzipped=True) # ~8 KB on the wire
+ result = _patched_fetch(monkeypatch, bomb, max_bytes=1024 * 1024)
+ assert result["_stream"] is True
+ assert result["error"] is None
+ assert result["too_large"] is True
+ assert 0 < len(result["content"]) <= 1024 * 1024
+
+
+def test_normal_page_is_read_whole_and_decoded(monkeypatch):
+ page = _streamed_response("<html><title>Café</title></html>".encode())
+ result = _patched_fetch(monkeypatch, page)
+ assert result["too_large"] is False
+ assert result["content"] == "<html><title>Café</title></html>"
+
+
+def test_cap_is_reported_in_the_json_contract():
+ rendered = fetch_page._as_render_result({"too_large": True, "content": "x"}, mode_used="raw")
+ assert rendered["render_diagnostics"] and "size cap" in rendered["render_diagnostics"][0]
+ assert fetch_page._as_render_result({"content": "x"}, mode_used="raw")["render_diagnostics"] == []
+
+
+def test_read_bounded_counts_decompressed_bytes():
+ raw, too_large = url_safety.read_bounded(_streamed_response(b"B" * 300_000, gzipped=True), 100_000)
+ assert too_large is True and len(raw) <= 100_000
+ raw, too_large = url_safety.read_bounded(_streamed_response(b"B" * 50_000), 100_000)
+ assert too_large is False and raw == b"B" * 50_000