Resources · 72
URL imports: prevent unauthorized server requests
Prevent SSRF in downloads, previews and connectors accessing user-supplied addresses.
· 8 min
What this guide helps achieve
- Inventory outbound access
- Restrict destinations
- Limit network access
- Test denials
- Prefer a reconstructed destination
Quick check
- Which destinations can the component reach?
- Is each redirect checked before connection?
- Are denials tested with mock targets?
Step-by-step method
- 01
Inventory outbound access
List image imports, document retrieval, link previews and connectors. Record protocols, libraries, legitimate destinations and networks reachable from each component. The public interface does not describe server access.
Deliverable: outbound-access map.
- 02
Restrict destinations
For known services, use a strict allowlist. Validate schemes, names, ports and resolved addresses with suitable tools. Check each redirect or disable redirects. A regular expression on URL text is insufficient.
Deliverable: destination policy.
- 03
Limit network access
Add egress restrictions and isolation for the retrieval component. Limit time, size and redirects. Check internal and metadata-service protections without placing secrets in tests.
Deliverable: outbound rules and limits.
- 04
Test denials
In an authorized lab, use mock destinations representing private networks, loopback, redirects and changed resolution. Check rejection before connection and ensure errors disclose no sensitive information. Retain results when connectors change.
Deliverable: negative tests and denial evidence.
- 05
Prefer a reconstructed destination
For a connector with known destinations, accept a service identifier or permitted host and construct the request with application-fixed scheme, port and path. Do not freely carry over other components of a user URL. Reject disagreement between the validating component and the component that performs the request.
Deliverable: input contract and destination-construction rule.
Inspect the effective destination, beyond the displayed link
Fictional defensive cases for a controlled test environment only. No access to third-party services or real metadata endpoints is required.
| Situation | Protection decision | Evidence to retain |
|---|---|---|
| A connector uses only known services | Choose an application-defined destination instead of accepting an arbitrary URL. | Input contract, permitted hosts and a request rebuilt with controlled parameters. |
| A permitted test target returns a redirect | Disable automatic following; if redirects are required, apply policy before each new connection. | Initial destination log and denial of a non-permitted mock target. |
| A test name has multiple addresses | Inspect IPv4 and IPv6 responses under the policy and address resolution changes. | Observed resolutions and a decision tied to the destination actually used. |
| The validator and HTTP client interpret an input differently | Reject the input and review the component contract; do not validate with a regex then pass on an ambiguous URL. | Regression case without sensitive payloads and agreement between components. |
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"initial_host": "public.example",
"redirect_host": "internal.example",
"resolved_ip": "127.0.0.1",
"network": "isolated-test"
}Expected decision
The redirect resolves to loopback. Block this route in the isolated test environment. Checking the initial hostname does not cover the redirected destination. In the isolated environment, keep automatic following disabled and verify that no connection reaches loopback. Expect a traceable rejection, without retrieving internal content to prove the block.
Verification procedure
- List permitted import destinations and networks.
- Test a loopback redirect in isolation.
- Keep the resolved destination and blocking evidence.
Reusable worksheet
Complete with your authorised observations. These fields are a working template, not observed results.
| Field | Information to record |
|---|---|
| Feature | URL input, component and legitimate destinations |
| Policy | Schemes, hosts, ports, resolution and redirects |
| Test | Mock destination, expected and observed denial |
| Acceptance | Authorized effective destination, denial before access and no returned internal data |
Worked example
Illustrative situation
Fictional example: a preview tool accepts a public test URL redirecting to a mock private service.
Decision and expected evidence
Policy rejects the new destination. The team checks the denial log, transfer limits and absence of returned private content.
Distinguish the mechanisms
| Mechanism | Purpose | Check or limitation |
|---|---|---|
| Known destinations | Restrict to explicitly permitted services | Check resolution and redirects |
| Open external URLs | Support a broader feature | Requires additional isolation and controls |
Management indicators
| Indicator | What it measures | First action |
|---|---|---|
| Documented outbound access | Features linked to policies | Resolve connectors without owners |
| Verified denials | Forbidden cases blocked before connection | Fix uncontrolled paths |
Common pitfalls
- Validate only the name displayed in the URL
- Allow the component to reach all internal networks
Frequently asked questions
Is HTTPS enough?
No. The protocol does not establish authorization or a stable destination after resolution or redirection.
Can validation exist only in the browser?
No. The requesting service must enforce its policy, complemented by network controls.
Can tests target third-party systems?
Use controlled environments and explicit authorization. The method requires no intrusive third-party testing.
Does a host allowlist replace network controls?
No. It narrows application scope but must connect to resolution, the request client and component egress rules. Also document time, volume and logging; no single layer covers every path.
SSRF: URLs and connections
SSRF: read the URL, then control the connection
Server-Side Request Forgery (SSRF) occurs when an application is induced to send a server request to a destination it should not reach. A report importer, link preview or AI agent tool may have network access unavailable to its user. The control must cover the destination actually reached, beyond the displayed string.
Fictional offline exercise: the 12 strings below are processed only by the maintenance Node runtime’s WHATWG URL parser. No DNS lookup or connection is performed. The .example domains are teaching fixtures; 2001:db8::10 belongs to RFC 3849’s IPv6 documentation prefix. These results are not a production SSRF validator.
The exercise’s local contract
The fictional connector accepts only an absolute HTTPS URL, without credentials, with hostname exactly reports.partner.example, effective port 443 and a normalized path starting with /reports/. Comparison uses parsed fields. This contract rejects a trailing dot and assumes no DNS equivalence. It does not cover query parameters, their interpretation by the remote service or business authorization.
For a known service, prefer a report identifier and reconstruct the URL on the server from a controlled origin and path. This exercise explains user-supplied URL pitfalls; it does not recommend exposing arbitrary URLs. Access to the whole Web needs a separate egress architecture and cannot be secured by copying this small allowlist.
- 1 · Contract and parser — Origin, port, path and credentials
- 2 · Resolution and connection — Validated address actually used
- 3 · Each redirect — New target, same destination policy
- 4 · Response and resources — Timeouts, size and expected type
12 fictional URLs: observed result and limits
Each disclosure shows the original string, computed fields and the decision of the local contract alone. “Continue to resolution” means network checks remain outstanding. A hostname matching the contract is neither resolved nor declared safe.
U01 · Expected name, unknown network
Original stringhttps://reports.partner.example/reports/daily.json
- Serialized URL
https://reports.partner.example/reports/daily.json- Scheme
https:- Hostname
reports.partner.example- Effective port
443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Continue to resolution — network unchecked
The string meets the contract, but no address is known. DNS validation, enforcement of the validated address at connection time and a network policy remain necessary.
U02 · Uppercase host and explicit HTTPS port
Original stringhttps://REPORTS.PARTNER.EXAMPLE:443/reports/daily.json
- Serialized URL
https://reports.partner.example/reports/daily.json- Scheme
https:- Hostname
reports.partner.example- Effective port
443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Continue to resolution — network unchecked
The parser lowercases the hostname and removes the default HTTPS port from serialization. The effective port remains 443; comparing parsed fields separates presentation from destination.
U03 · The reassuring name is before @
Original stringhttps://reports.partner.example@untrusted.example/reports/daily.json
- Serialized URL
https://reports.partner.example@untrusted.example/reports/daily.json- Scheme
https:- Hostname
untrusted.example- Effective port
443- Username
reports.partner.example- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Hostname differs from the exact allowlist
- Embedded credentials are forbidden
The parser places reports.partner.example in username. The actual hostname is untrusted.example: finding an allowed substring in the whole URL does not control its destination.
U04 · An added suffix changes the host
Original stringhttps://reports.partner.example.untrusted.example/reports/daily.json
- Serialized URL
https://reports.partner.example.untrusted.example/reports/daily.json- Scheme
https:- Hostname
reports.partner.example.untrusted.example- Effective port
443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Hostname differs from the exact allowlist
This hostname ends in untrusted.example. Exact comparison fails even though the expected name appears at the beginning. The contract uses neither substring matching nor a permissive expression.
U05 · Same host, different port
Original stringhttps://reports.partner.example:8443/reports/daily.json
- Serialized URL
https://reports.partner.example:8443/reports/daily.json- Scheme
https:- Hostname
reports.partner.example- Effective port
8443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Effective port is not 443
The effective port is 8443. Allowing a hostname must not open every service available on its other ports.
U06 · HTTP does not meet HTTPS
Original stringhttp://reports.partner.example/reports/daily.json
- Serialized URL
http://reports.partner.example/reports/daily.json- Scheme
http:- Hostname
reports.partner.example- Effective port
80- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Scheme is not HTTPS
- Effective port is not 443
The HTTP scheme and default port 80 differ from the HTTPS/443 contract. Silently rewriting the string would hide the original request; keep the decision explicit.
U07 · The .. segment changes the path
Original stringhttps://reports.partner.example/reports/../admin/status
- Serialized URL
https://reports.partner.example/admin/status- Scheme
https:- Hostname
reports.partner.example- Effective port
443- Username
Absent- Password present
No- Normalized path
/admin/status
Reject under the local contract
Contract reasons:
- Path is outside the /reports/ prefix
The parser resolves /reports/../admin/status to /admin/status. A prefix test on the raw string would decide differently. Even after normalization, the service’s path interpretation must remain controlled.
U08 · An encoded host character is normalized
Original stringhttps://%72eports.partner.example/reports/daily.json
- Serialized URL
https://reports.partner.example/reports/daily.json- Scheme
https:- Hostname
reports.partner.example- Effective port
443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Continue to resolution — network unchecked
The initial %72 becomes r in the computed hostname for this special HTTPS URL. The result matches U01; this provides no evidence about DNS, TLS or business authorization.
U09 · Trailing dot: an exact contract
Original stringhttps://reports.partner.example./reports/daily.json
- Serialized URL
https://reports.partner.example./reports/daily.json- Scheme
https:- Hostname
reports.partner.example.- Effective port
443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Hostname differs from the exact allowlist
The hostname retains its final dot in this WHATWG result. The teaching profile requires exact equality and rejects it. A production policy must document its normalization and apply it consistently.
U10 · Relative reference without a base URL
Original string//reports.partner.example/reports/daily.json
Cannot parse an absolute URL without a base
Reject: parser failure
Without a base, new URL rejects this reference beginning with //. Adding a base elsewhere could change the result: the validator and client must use the same parsing model.
U11 · Expected host with embedded username
Original stringhttps://training@reports.partner.example/reports/daily.json
- Serialized URL
https://training@reports.partner.example/reports/daily.json- Scheme
https:- Hostname
reports.partner.example- Effective port
443- Username
training- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Embedded credentials are forbidden
The expected hostname is insufficient: username contains training. The profile forbids all embedded credentials. This fictional value is neither an account nor a secret.
U12 · Documentation IPv6 address
Original stringhttps://[2001:db8::10]/reports/daily.json
- Serialized URL
https://[2001:db8::10]/reports/daily.json- Scheme
https:- Hostname
[2001:db8::10]- Effective port
443- Username
Absent- Password present
No- Normalized path
/reports/daily.json
Reject under the local contract
Contract reasons:
- Hostname differs from the exact allowlist
The parser accepts bracketed IPv6 syntax, but the contract allows no IP literal. This prefix is reserved for documentation and must not be described as an operational Internet destination.
From the checked name to the actual destination
| Fictional situation | Missing evidence or change | Expected decision |
|---|---|---|
| N01 · Repeated lookup | The application validates one answer; the client resolves again and receives an internal address. | Block the unchecked second lookup. Connect only to an address validated against the destination policy. |
| N02 · 302 response | Location names a different host, port or path. | Disable automatic redirect following. If controlled redirects are a product requirement, parse and validate every new target before connecting. |
| N03 · Egress proxy | The proxy resolves the name and chooses the destination; its rules are unknown to the application. | Do not claim a verified destination. Document enforcement and evidence at the component that actually establishes the connection. |
| N04 · Failure fallback | A new A/AAAA address, retry or fallback is attempted. | Apply the same policy to every address and attempt; no fallback path may bypass enforcement. |
| N05 · Excessive response | The allowed destination returns a large stream or unexpected content. | Enforce client timeouts and size limits, check the expected type and handle content separately. No universal threshold is invented here. |
Binding a connection to the validated address does not mean disabling TLS: preserve the original hostname for HTTP Host, SNI and certificate verification. The component opening the connection must enforce the binding; an earlier DNS observation does not prove it. Network rules complement application checks, including local, private, loopback and link-local destinations in both IPv4 and IPv6.
Cloud metadata: a separate control
In EC2, “token required” enforces IMDSv2; “token optional” permits IMDSv1 or IMDSv2. Enabling the IPv6 endpoint is an explicit option. Check these settings on the relevant instances: merely naming IMDSv2 in documentation does not prove their configuration. Protecting metadata replaces neither egress isolation nor controls on other internal services.
Six records for an SSRF acceptance review
- The business need and the services, ports and operations actually required.
- Parser and HTTP client versions, with expected negative-case results.
- The IPv4/IPv6 address policy and where it is enforced before connection.
- Evidence linking the validated destination to the connection, including proxies, retries and fallback.
- The redirect decision and response bounds, tested in an authorized environment.
- Minimized logs: decision, necessary target information and correlation, without copying passwords, tokens or sensitive parameters.
The 12 cases, four controls and six records are a local editorial method, not OWASP certification. The parser supplies fields; the sources describe risks and controls. “Reject” and “continue” labels do not predict the behavior of your HTTP stack.
Primary sources and scope
- OWASP · SSRF Prevention Cheat Sheet · Living documentation · checked 2026-10-22
Case 1: application/network layers · DNS rebinding · validated connection · retries/fallbacks · redirects - WHATWG · URL Living Standard · Updated 2026-10-19 · checked 2026-10-22
§2 Security considerations · §3 Hosts · §4 URLs · basic URL parser - AWS EC2 · Instance metadata options · Living documentation · checked 2026-10-22
Metadata access · IPv6 endpoint · IMDSv2 token requirements - IETF · RFC 3849 · Informational · July 2004
§2 Documentation IPv6 address prefix: 2001:DB8::/32
Sources reviewed on
Files: quarantine and withdrawal
Retrieved content still needs checks before release
Uploading a document or fetching it by URL does not decide its availability. Originals and derivatives need to retain version, checks and access state through every read.
- Isolate received files before processing and release.
- Reject results targeting an older content version or control decision.
- Check permissions and withdrawal for previews and originals alike.
View the three journeys and late task results →
Sources reviewed on · OWASP · File Upload Cheat Sheet · OWASP · Authorization Cheat Sheet · WHATWG · HTML input accept · PostgreSQL 18 · Transaction isolation
Official references
References consulted: . The method and worksheet propose checks to adapt to your context; they do not constitute certification.
