Document a self-contained URL allowlist webhook

[hexablob]

Description

Add a self-contained Python standard-library validating webhook that allows the fetch tool to request URLs on an exact hostname allowlist. Include local HTTPS setup with certificate verification, complete ToolHive configuration, allowed and denied CLI calls, and cleanup. Explain the policy's request-only scope and the separate controls needed for redirects, DNS changes, and returned content.

Correct the HMAC secret-reference field to match ToolHive's signing client and secret resolver.

This contribution was developed with AI assistance. The contributor is associated with IsMalicious; the guide contains no provider-specific integration, credentials, or service dependency.

Type of change

• Documentation update

Related issues/PRs

Closes #1192

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

Validation

• Nine Python standard-library tests pass, covering hostname matching, HTTP(S) schemes, credentials, ports, malformed envelopes, UID/version correlation, and scoped TLS trust.
• Real ToolHive CLI and remote proxy at 3ca3c8f71152ad6e109dbb881be13ceb17a2cf3c connect to the running HTTPS webhook and a synthetic local MCP server. Initialize and tool discovery work. The allowed URL executes exactly one tool call; an unlisted host and unknown tool return HTTP 403 without another backend tool call. Stopping the webhook prevents execution under failure_policy: fail.
• The local MCP server records calls without fetching URLs. This validates native proxy enforcement, not content retrieval or reputation accuracy. The attempt to launch the registry fetch image stopped at a GHCR denied response before startup; the public package and tag exist, but full container-fetch execution could not be verified in this environment.
• Touched MDX passes Prettier and ESLint. The production docs build passes under Node 24.19.0 and generates 331 documents. Its warning is on the unchanged enterprise API reference.
• Both contribution commits include the required DCO Signed-off-by trailer.

Reviewer checklist

Content

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

[vercel]

@hexablob is attempting to deploy a commit to the stacklok Team on Vercel.

A member of the Team first needs to authorize it.

[hexablob]

The current Vercel status is "Authorization required to deploy", and the fork workflow has no executed jobs yet. Could a team member authorize the preview and approve the pending workflow? Local validation is recorded in the PR body: the production docs build generated 331 documents, touched MDX passes Prettier/ESLint, and the native ToolHive middleware tests pass. The commit is signed and includes the required DCO trailer.

[danbarr]

Hi @hexablob, thanks for the contribution! A working webhook example would be a useful addition to this page, but we'd prefer to keep the core docs provider-neutral. Would you be open to reworking this into a self-contained example, such as a simple URL allowlist, with steps to try both an allowed and a denied request?

[hexablob]

@danbarr I have reworked the example into a self-contained Python standard-library URL allowlist. The guide now includes the service code, local HTTPS setup with scoped CA trust, complete ToolHive configuration, and commands for an allowed example.com request and a denied example.org request. It has no IsMalicious dependency or provider-specific configuration.

The running example passes nine Python protocol/policy/TLS tests. I also exercised the real ToolHive CLI and remote proxy against this HTTPS webhook and a local MCP stub: the allowed call reaches the backend once; the denied host and unknown tool return 403 without execution; stopping the webhook fails closed. Full container-fetch startup was blocked by a GHCR denied response, so that limitation is explicit in the PR's validation notes.

The HMAC field correction remains independent of the example. Certificate verification stays enabled, and the guide explains that redirects, DNS changes, and tool results need separate controls.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs-website	Ready	Preview	Oct 6, 2026 2:16pm UTC

[danbarr]

Thanks for reworking this! The self-contained example fits the page well and addresses the gap. One small compatibility fix: could you replace -noenc with -nodes in the certificate command? It works with Homebrew OpenSSL, but fails with macOS's built-in /usr/bin/openssl (LibreSSL). Otherwise, this looks good from an editorial perspective, pending CI.

[hexablob]

@danbarr Replaced -noenc with -nodes in the certificate command. The exact documented command succeeds with macOS /usr/bin/openssl (LibreSSL 3.3.6) and Homebrew OpenSSL 3.6.5; both certificates include the 127.0.0.1 SAN and load into the Python TLS server. I also reproduced the previous LibreSSL failure with -noenc.

Prettier, ESLint, and the production docs build pass under Node 24.21.0. The build generates 331 documents, with the same unrelated enterprise API-reference minifier warning. The follow-up commit retains the DCO sign-off.

The new commit is waiting for fork-workflow approval and Vercel deployment authorization again (On PR run); it has no executed CI jobs yet. Could a team member approve this run and authorize the preview?