Resources · 72

URL imports: prevent unauthorized server requests

Prevent SSRF in downloads, previews and connectors accessing user-supplied addresses.

· 8 min

Empty secure server and network corridor AI-generated editorial illustration

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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

SituationProtection decisionEvidence to retain
A connector uses only known servicesChoose 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 redirectDisable 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 addressesInspect 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 differentlyReject 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

  1. List permitted import destinations and networks.
  2. Test a loopback redirect in isolation.
  3. Keep the resolved destination and blocking evidence.

OWASP — Server Side Request Forgery Prevention

Reusable worksheet

Complete with your authorised observations. These fields are a working template, not observed results.

FieldInformation to record
FeatureURL input, component and legitimate destinations
PolicySchemes, hosts, ports, resolution and redirects
TestMock destination, expected and observed denial
AcceptanceAuthorized 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

MechanismPurposeCheck or limitation
Known destinationsRestrict to explicitly permitted servicesCheck resolution and redirects
Open external URLsSupport a broader featureRequires additional isolation and controls

Management indicators

IndicatorWhat it measuresFirst action
Documented outbound accessFeatures linked to policiesResolve connectors without owners
Verified denialsForbidden cases blocked before connectionFix 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.

Four controls, four pieces of evidence
Four controls, four pieces of evidence Four separate controls: contract and parser, resolution and connection, each redirect, and response limits. Passing the first does not validate the others. 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 A parseable URL is not network authorization.
  1. 1 · Contract and parser — Origin, port, path and credentials
  2. 2 · Resolution and connection — Validated address actually used
  3. 3 · Each redirect — New target, same destination policy
  4. 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 string
https://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 string
https://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 string
https://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 string
https://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 string
https://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 string
http://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 string
https://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 string
https://%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 string
https://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 string
https://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 string
https://[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

From the checked name to the actual destination
Fictional situationMissing evidence or changeExpected decision
N01 · Repeated lookupThe 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 responseLocation 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 proxyThe 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 fallbackA 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 responseThe 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

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.