Laravel Ssrf Guard Laravel Package

Getting Started

laravel-ssrf-guard defends outbound HTTP calls against Server-Side Request Forgery — the class of bug where an attacker tricks your server into fetching internal addresses (127.0.0.1, 169.254.169.254 for cloud metadata, 10.0.0.0/8, etc.).

1. composer require jeffersongoncalves/laravel-ssrf-guard
2. Publish the config (php artisan vendor:publish --tag=ssrf-guard-config) and skim config/ssrf-guard.php — this is where the blocklist/allowlist, allowed schemes, and redirect policy live.
3. Wrap your first untrusted fetch: validate the URL (rule / facade / macro depending on the surface) before passing it to Http::get() / GuzzleHttp\Client.

The first real-world use case is almost always "user supplies a URL, server fetches it" — webhook registration, image/avatar import from a URL, RSS feed ingestion, PDF/screenshot generation, or SSRF-prone "preview this link" features. Reach for this package the moment a URL comes from a request payload rather than from your own config.

Implementation Patterns

• FormRequest validation. Prefer the package's validation rule (or a custom rule built on the facade) so unsafe URLs fail at the request layer instead of deep in a controller. Fail fast, fail visibly.
• Facade guard before fetch. Even with validation, call the guard immediately before the actual HTTP call so a URL validated earlier can't be swapped or re-resolved (see DNS rebinding below).
• HTTP client macro / middleware. The most durable integration is a Http client-level hook so every outbound request goes through the guard, not just the ones where someone remembered to call it. If the package exposes this, wire it in a ServiceProvider::boot() behind a config flag.
• Route middleware for endpoints that exist only to proxy/fetch URLs — this keeps the guard out of controllers.
• Allowlist by host, block by IP range. Block private/reserved CIDRs by default; allow the known-good internal hosts explicitly (e.g. an internal microservice) rather than the other way around.
• Redirects. Laravel's Http client follows redirects by default. Ensure each hop is re-validated, or disable redirect-following and handle them yourself.
• Config-first. Keep the CIDR list, scheme allowlist, and DNS policy in ssrf-guard.php, not scattered across controllers.

Gotchas and Tips

• Validate the resolved IP, not the hostname string. evil.com can resolve to 127.0.0.1. Resolve first, check the IP, and ideally pin the connection to that IP.
• DNS rebinding. A host can resolve to a public IP at validation time and a private IP at fetch time. Resolve → check → pin, or re-check at request time.
• Redirect chains. A public URL can 302 to http://169.254.169.254/. Each hop must be checked.
• Alternate IP encodings. Decimal (2130706433), octal (0177.0.0.1), IPv6-mapped (::ffff:127.0.0.1), and DNS tricks can bypass naive string checks. Normalize before comparing.
• CIDR coverage. Don't forget 169.254.0.0/16 (link-local / cloud metadata), 0.0.0.0/8, 100.64.0.0/10 (CGNAT), fc00::/7, ::1, and the IPv4-mapped IPv6 range.
• Guzzle exceptions. The guard may throw a dedicated exception; catch it and translate to a 422 at the API boundary rather than letting a 500 leak internal detail.
• Test the bypasses, not just the happy path. Seed your test suite with http://127.0.0.1, http://[::1], http://localhost, metadata IPs, and a fake-DNS redirect.
• Release discipline. The v1.1.0 notes only link the compare view — diff v1.0.1...v1.1.0 and check the CHANGELOG before upgrading, particularly for changes to default CIDR coverage or redirect behavior, since silent loosening of those defaults is the security-relevant failure mode.

Caveat: the v1.1.0 release body is only a changelog link, so the exact API surface (facade name, rule class, macro name, config keys) should be confirmed against the package's README before copying any snippet.