Skip to content

Building AI agents, atomically

Validate result URL hosts and ports, wrap over-deep JSON, return body-or-reason from the request boundary, block non-loopback connects in tests

Juampi07d9f8cea3c5
diff --git a/atomic-forge/tools/firecrawl_search/README.md b/atomic-forge/tools/firecrawl_search/README.md
index 5edd2e0..c58eb9b 100644
--- a/atomic-forge/tools/firecrawl_search/README.md
+++ b/atomic-forge/tools/firecrawl_search/README.md
@@ -15,7 +15,7 @@ Searches the web or recent news through the [Firecrawl Search](https://www.firec
2. Or copy the `tool/` folder directly into your project.
## Configuration
-- `api_key` (`SecretStr`, a plain string is accepted): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty. It is only sent in the `Authorization` header and is redacted from raised errors and log messages.
+- `api_key` (`SecretStr`, a plain string is accepted): Firecrawl API key. Falls back to the `FIRECRAWL_API_KEY` environment variable when empty. It is only sent in the `Authorization` header. Raised errors, log messages and `failures` redact the configured key (when it is at least 8 characters) and anything in Firecrawl's `fc-` key format.
- `base_url` (str): API base URL (default `https://api.firecrawl.dev/v2`).
- `location` (str, optional): location to localise results, e.g. `Germany`.
- `time_range` (str, optional): `day`, `week`, `month`, or `year`. Only applies to web results.
@@ -31,8 +31,8 @@ Searches the web or recent news through the [Firecrawl Search](https://www.firec
- `include_content` (bool): also return each result page as Markdown (default `False`).
### Output Schema
-- `results`: a list of `FirecrawlSearchResultItem` items. Each has `query`, `title`, `url`, and optional `description` (a query-relevant excerpt or snippet), `position`, `published` (news), and `content` (Markdown, when `include_content` is set). Results without a well-formed http(s) URL (one with a host and no whitespace) are skipped, and badly typed optional fields are left empty.
-- `failures`: queries that failed while others returned results, each with `query` and `error` (the HTTP status and the API's error message). A key appearing in either is redacted. They are also logged as warnings.
+- `results`: a list of `FirecrawlSearchResultItem` items. Each has `query`, `title`, `url`, and optional `description` (a query-relevant excerpt or snippet), `position`, `published` (news), and `content` (Markdown, when `include_content` is set). Results without a well-formed http(s) URL (a real host, a valid port, no whitespace or control characters) are skipped, and badly typed optional fields are left empty.
+- `failures`: queries that failed while others returned results, each with `query` and `error` (the HTTP status and the API's error message). Keys are redacted from both as described for `api_key`. They are also logged as warnings.
## Usage
If no query returns results and at least one failed (for example a wrong API key, no credits, or a malformed response), `run` raises the first error instead of returning an empty list. Redirects are not followed; they are reported as errors.
diff --git a/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py
index 9b3098d..f92463b 100644
--- a/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py
+++ b/atomic-forge/tools/firecrawl_search/tests/test_firecrawl_search.py
@@ -6,7 +6,7 @@ import socket
import sys
import traceback
from contextlib import asynccontextmanager
-from typing import AsyncIterator, Awaitable, Callable, Dict, List, Sequence, Tuple, Union
+from typing import AsyncIterator, Awaitable, Callable, Dict, Iterator, List, Sequence, Tuple, TypedDict, Union
from unittest.mock import AsyncMock, patch
import pytest
@@ -28,6 +28,14 @@ from tool.firecrawl_search import ( # noqa: E402
Body = Dict[str, object]
Responder = Callable[[Body], Union[web.Response, Awaitable[web.Response]]]
+
+class Seen(TypedDict):
+ """One request as the fake server received it."""
+
+ headers: Dict[str, str]
+ body: Body
+
+
DUMMY_KEY = "fc-dummy0secret0key0123456789" # a configured key in a custom format
CANONICAL_KEY = "fc-0123456789abcdef0123456789abcdef" # a key in Firecrawl's own format
KEYS = (DUMMY_KEY, DUMMY_KEY.upper(), CANONICAL_KEY, CANONICAL_KEY.upper())
@@ -61,19 +69,28 @@ CONTENT_HIT = {
@pytest.fixture(autouse=True)
-def offline(monkeypatch):
- """Keep the suite offline: any attempt to resolve a host other than the local test server fails the test."""
+def offline(monkeypatch) -> Iterator[List[str]]:
+ """Keep the suite offline. Resolving a host other than loopback raises gaierror, and connecting to a
+ non-loopback address raises OSError; both are recorded, and the test fails unless it expected them."""
attempts: List[str] = []
real_getaddrinfo = socket.getaddrinfo
+ real_connect = socket.socket.connect
- def loopback_only(host, *args, **kwargs):
+ def resolve_loopback_only(host, *args, **kwargs):
if host not in LOOPBACK_HOSTS:
attempts.append(str(host))
raise socket.gaierror("network access is disabled in these tests")
return real_getaddrinfo(host, *args, **kwargs)
- monkeypatch.setattr(socket, "getaddrinfo", loopback_only)
- yield
+ def connect_loopback_only(sock, address):
+ if isinstance(address, tuple) and address[0] not in LOOPBACK_HOSTS:
+ attempts.append(str(address[0]))
+ raise OSError("network access is disabled in these tests")
+ return real_connect(sock, address)
+
+ monkeypatch.setattr(socket, "getaddrinfo", resolve_loopback_only)
+ monkeypatch.setattr(socket.socket, "connect", connect_loopback_only)
+ yield attempts
assert attempts == []
@@ -109,13 +126,13 @@ def respond_per_query(bad_query: str, bad: Responder, good: Responder) -> Respon
# Test harness #
################
@asynccontextmanager
-async def fake_firecrawl(respond: Responder) -> AsyncIterator[Tuple[str, List[Body]]]:
+async def fake_firecrawl(respond: Responder) -> AsyncIterator[Tuple[str, List[Seen]]]:
"""Serve POST /v2/search on a local aiohttp server; `respond(body)` builds each response."""
- seen: List[Body] = []
+ seen: List[Seen] = []
async def handler(request: web.Request) -> web.Response:
body = await request.json()
- seen.append({"headers": dict(request.headers), "body": body})
+ seen.append(Seen(headers=dict(request.headers), body=body))
response = respond(body)
return await response if asyncio.iscoroutine(response) else response
@@ -135,7 +152,7 @@ def http_tool(base_url: str, api_key: str = DUMMY_KEY, **config) -> FirecrawlSea
async def search(
respond: Responder, queries: Sequence[str] = ("q",), api_key: str = DUMMY_KEY, **params
-) -> Tuple[FirecrawlSearchToolOutputSchema, List[Body]]:
+) -> Tuple[FirecrawlSearchToolOutputSchema, List[Seen]]:
"""Run one search against a fake server and return (output, requests seen)."""
async with fake_firecrawl(respond) as (base_url, seen):
tool = http_tool(base_url, api_key)
@@ -229,6 +246,10 @@ def test_to_item_drops_badly_typed_fields(field, value, attribute, expected):
"https://example.com:8443/a?b=c#d",
"http://[::1]:8080/x",
"https://[email protected]/",
+ "http://192.0.2.1:8080/x",
+ "https://müller.de/straße",
+ "https://xn--mller-kva.de/",
+ "https://example.com/%C3%BC%20x.pdf",
],
)
def test_to_item_keeps_valid_http_urls(url):
@@ -259,6 +280,22 @@ def test_to_item_keeps_valid_http_urls(url):
{"url": "https://exa mple.com/a"},
{"url": "https://example.com/a\n"},
{"url": "https://example.com\t/a"},
+ {"url": "https://./"},
+ {"url": "https://-/"},
+ {"url": "https://%/"},
+ {"url": "https://_x.com/"},
+ {"url": "https://[:]/"},
+ {"url": "https://[zz]/"},
+ {"url": "https://a\x00b.com/"},
+ {"url": "https://example.com/a\x7f"},
+ {"url": "https://exa\u200bmple.com/"},
+ {"url": "https://example.com/\xa0"},
+ {"url": "https://example.com:abc/"},
+ {"url": "https://example.com:99999/"},
+ {"url": "https://example.com:65536/"},
+ {"url": "https://example.com:0/"},
+ {"url": "https://example.com:\u0664\u0664\u0663/"},
+ {"url": "https://a [email protected]/"},
],
)
def test_to_item_without_usable_url_is_none(hit):
@@ -412,6 +449,14 @@ async def test_non_json_bodies_raise_with_status(response, expected):
assert str(error) == f"Firecrawl search failed for 'q': {expected}"
+async def test_deeply_nested_json_is_a_wrapped_failure():
+ """JSON too deep for the parser must fail like any other bad body, not escape with the response in scope."""
+ error = await search_error(respond_raw(status=200, text="[" * 200_000, content_type="application/json"))
+ assert str(error) == "Firecrawl search failed for 'q': 200 response did not report success"
+ assert_no_key(error_surfaces(error))
+
+
@pytest.mark.asyncio
async def test_redirect_is_not_followed():
"""A redirect, even to another server, is reported as an error; the query is never re-sent elsewhere."""
@@ -511,6 +556,25 @@ async def test_invalid_base_url_is_wrapped_and_no_frame_holds_the_key(base_url,
assert_no_key(str(raised.value), repr(raised.value), *frame_locals(raised.value, is_outside_this_test_file))
+ "base_url, blocked_host",
+ [
+ ("http://exa\nmple.com/v2", "example.com"), # yarl drops the newline, so this resolves example.com
+ (f"http://{'a' * 70}.example.com/v2", f"{'a' * 70}.example.com"),
+ ],
+)
+async def test_unresolvable_base_url_is_wrapped(offline, base_url, blocked_host):
+ """A DNS failure is reported as a request failure; the offline guard answers the lookup, so nothing leaves."""
+ with pytest.raises(Exception) as raised:
+ await http_tool(base_url).run_async(FirecrawlSearchToolInputSchema(queries=["q"]))
+
+ assert str(raised.value).startswith("Firecrawl search failed for 'q': request failed: ClientConnectorDNSError ")
+ assert_no_key(str(raised.value), repr(raised.value), *frame_locals(raised.value, is_outside_this_test_file))
+ assert offline == [blocked_host]
+ offline.clear()
+
+
################
# Key handling #
################
diff --git a/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py
index 16bea80..32da97e 100644
--- a/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py
+++ b/atomic-forge/tools/firecrawl_search/tool/firecrawl_search.py
@@ -3,7 +3,8 @@ import logging
import os
import re
from concurrent.futures import ThreadPoolExecutor
-from typing import Dict, List, Literal, Optional, Tuple, Union, cast
+from typing import Dict, List, Literal, Optional, Tuple, Union
+from urllib.parse import urlsplit
import aiohttp
from pydantic import Field, SecretStr, field_validator
@@ -111,9 +112,10 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear
# when it is long enough that replacing it cannot mangle ordinary words.
KEY_PATTERN = re.compile(r"\bfc-[0-9a-f]{32}\b", re.IGNORECASE)
MIN_REDACTED_KEY_LENGTH = 8
- # A result is kept only when its whole URL is http(s) with a host and contains no whitespace.
+ # Shape of a usable result URL: http(s), optional userinfo, a host that starts with a letter or digit (or an
+ # IPv6 literal), an ASCII port, and no whitespace anywhere. urlsplit then validates the port range and IPv6.
RESULT_URL_PATTERN = re.compile(
- r"https?://(?:[^\s/?#@]*@)?(?:[^\s/?#@:\[\]]+|\[[0-9a-f:.]+\])(?::\d*)?(?:[/?#]\S*)?", re.IGNORECASE
+ r"https?://(?:[^\s/?#@]*@)?(?:[^\W_][^\s/?#@:\[\]]*|\[[0-9a-f:.]+\])(?::[0-9]*)?(?:[/?#]\S*)?", re.IGNORECASE
)
def __init__(self, config: FirecrawlSearchToolConfig = FirecrawlSearchToolConfig()):
@@ -130,20 +132,31 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear
"""Return the first non-empty string; result fields are provider data and may have any type."""
return next((value for value in values if isinstance(value, str) and value), None)
+ @classmethod
+ def _usable_url(cls, url: str) -> bool:
+ """True for a printable http(s) URL with a real host and an in-range, non-zero port."""
+ if not (url.isprintable() and cls.RESULT_URL_PATTERN.fullmatch(url)):
+ return False
+ try:
+ # urlsplit raises ValueError for an out-of-range port or an invalid IPv6 literal.
+ return urlsplit(url).port != 0
+ except ValueError:
+ return False
+
@classmethod
def _to_item(cls, hit: object, query: str, max_content_chars: Optional[int] = None) -> Optional[FirecrawlSearchResultItem]:
"""Normalise one result, or return None when it has no usable http(s) URL."""
fields: Dict[str, object] = hit if isinstance(hit, dict) else {}
url = str(fields.get("url"))
- if not cls.RESULT_URL_PATTERN.fullmatch(url):
+ if not cls._usable_url(url):
return None
content = cls._first_text(fields.get("markdown"))
return FirecrawlSearchResultItem(
query=query,
- title=cls._first_text(fields.get("title"), url),
+ title=cls._first_text(fields.get("title")) or url,
url=url,
description=cls._first_text(fields.get("description"), fields.get("snippet")),
- position=fields.get("position"),
+ position=FirecrawlSearchResultItem._positive_rank_or_none(fields.get("position")),
published=cls._first_text(fields.get("date")),
content=content[:max_content_chars] if content else None,
)
@@ -172,21 +185,22 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear
async def _read_json(resp: aiohttp.ClientResponse) -> object:
try:
return await resp.json(content_type=None)
- except ValueError:
+ except (ValueError, RecursionError):
+ # Invalid JSON, or JSON nested too deeply for the parser.
return None
- def _failure(self, status: int, reason: Optional[str], data: object) -> Optional[str]:
- """Return why a response is not a successful search (only a 200 whose body says success is true is),
- or None when it is. Provider text is redacted here, where it enters the tool."""
+ def _check_response(self, status: int, reason: Optional[str], data: object) -> Union[Dict[str, object], str]:
+ """Return the body of a successful search (a 200 whose body says success is true), or why the response
+ is not one. Provider text is redacted here, where it enters the tool."""
payload: Dict[str, object] = data if isinstance(data, dict) else {}
if status == 200 and payload.get("success") is True:
- return None
+ return payload
return self._redact(f"{status} {payload.get('error') or reason}")
async def _exchange(
self, session: aiohttp.ClientSession, query: str, params: FirecrawlSearchToolInputSchema
- ) -> Tuple[object, Optional[str]]:
- """Send one search request and return the parsed body plus why it failed (None on success).
+ ) -> Union[Dict[str, object], str]:
+ """Send one search request and return the body of a successful response, or why it failed.
Transport errors, timeouts and invalid URLs are turned into a failure reason here instead of propagating,
because aiohttp's own frames and errors hold the request headers, Authorization included."""
@@ -196,23 +210,21 @@ class FirecrawlSearchTool(BaseTool[FirecrawlSearchToolInputSchema, FirecrawlSear
) as resp:
payload = await self._read_json(resp)
reason = resp.reason if resp.status != 200 else "response did not report success"
- return payload, self._failure(resp.status, reason, payload)
+ return self._check_response(resp.status, reason, payload)
except (aiohttp.ClientError, asyncio.TimeoutError, ValueError) as error:
- return None, self._redact(f"request failed: {type(error).__name__} {str(error) or f'after {self.timeout:g}s'}")
+ return self._redact(f"request failed: {type(error).__name__} {str(error) or f'after {self.timeout:g}s'}")
async def _post(
self, session: aiohttp.ClientSession, query: str, params: FirecrawlSearchToolInputSchema
) -> Dict[str, object]:
"""Return the body of a successful search response, or raise.
- The raise happens in this frame, which holds neither the response nor an aiohttp error, and the body of a
- failed response is dropped first, so a traceback that captures locals cannot show a key echoed back."""
- payload, failure = await self._exchange(session, query, params)
- if failure:
- payload = None
- raise self._error(query, failure)
- # _failure only returns None for a dict body that reports success.
- return cast(Dict[str, object], payload)
+ The raise happens in this frame, which only ever holds the redacted failure reason: no response, no aiohttp
+ error and no failed body, so a traceback that captures locals cannot show a key echoed back."""
+ outcome = await self._exchange(session, query, params)
+ if isinstance(outcome, str):
+ raise self._error(query, outcome)
+ return outcome
@staticmethod
def _extract_hits(payload: Dict[str, object], search_type: str) -> Optional[List[object]]:
@@ -300,9 +312,9 @@ if __name__ == "__main__": # pragma: no cover
load_dotenv()
console = Console()
- tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key=os.getenv("FIRECRAWL_API_KEY", "")))
+ tool = FirecrawlSearchTool(config=FirecrawlSearchToolConfig(api_key=SecretStr(os.getenv("FIRECRAWL_API_KEY", ""))))
- examples = [
+ examples: List[Tuple[Literal["web", "news"], bool, str]] = [
("web", False, "atomic agents framework"),
("news", False, "AI agents"),
("web", True, "atomic agents framework"),