Httplug Ssrf Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require j0k3r/httplug-ssrf-plugin
   

   Add the plugin to your HTTPlug client stack:

   use Http\Client\Common\PluginClient;
   use Http\Client\Common\Plugin;
   use J0k3r\HttplugSsrfPlugin\SsrfPlugin;
   
   $client = new PluginClient($baseClient);
   $client->addPlugin(new SsrfPlugin());
   

2. First Use Case Configure allowed domains in config/ssrf.php (if using Laravel):

   'allowed_domains' => [
       'api.example.com',
       'internal.example.net',
   ],
   

   Then use the client as usual—invalid requests will throw J0k3r\HttplugSsrfPlugin\Exception\SsrfException.

Implementation Patterns

Workflow Integration

1. Centralized Client Setup Create a reusable client factory in Laravel’s AppServiceProvider:

   public function register()
   {
       $this->app->singleton('ssrfClient', function () {
           $client = new PluginClient(new \Http\Adapter\Guzzle7\Client());
           $client->addPlugin(new SsrfPlugin(config('ssrf.allowed_domains')));
           return $client;
       });
   }
   

2. Dynamic Domain Whitelisting Extend the plugin for runtime updates (e.g., via middleware):

   $plugin = new SsrfPlugin(['api.example.com']);
   $plugin->setAllowedDomains(['api.example.com', request('dynamic_domain')]);
   

3. Fallback for Untrusted Requests Use a secondary client for untrusted requests:

   if ($isTrusted) {
       return $ssrfClient->sendRequest($request);
   }
   return $fallbackClient->sendRequest($request);
   

Common Use Cases

• API Proxies: Validate external API calls in microservices.
• Scraping Tools: Block SSRF in web scrapers targeting internal services.
• Legacy Systems: Retrofit SSRF protection to existing HTTPlug-based integrations.

Gotchas and Tips

Pitfalls

1. False Positives

   • Issue: Blocking legitimate subdomains (e.g., *.example.com vs internal.example.com).
   • Fix: Use regex patterns or exact domain matching:

     $plugin = new SsrfPlugin(['#^api\..+\.example\.com$#']);
     

2. Case Sensitivity

   • Domains are case-insensitive by default, but some adapters (e.g., Guzzle) may normalize case. Explicitly lowercase domains in config:

     'allowed_domains' => array_map('strtolower', ['API.EXAMPLE.COM']),
     

3. IPv6 Addresses

   • The plugin may not handle ::1 or IPv6 literals by default. Extend the validator:

     $plugin->setIpValidator(function ($ip) {
         return filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6);
     });
     

Debugging

• Log Rejected Requests Override the exception handler to log blocked URIs:

  $plugin->setExceptionHandler(function ($request, $exception) {
      \Log::warning("SSRF blocked: {$request->getUri()}");
      throw $exception;
  });
  

• Test Edge Cases Verify with:

  $this->expectException(SsrfException::class);
  $client->sendRequest(new \Http\Message\Request('GET', 'http://169.254.169.254'));
  

Extension Points

1. Custom Validators Add logic for internal IPs or private ranges:

   $plugin->addValidator(function ($uri) {
       return str_starts_with($uri, 'http://10.');
   });
   

2. Performance Cache allowed domains if they rarely change:

   $plugin = new SsrfPlugin(cache()->remember('ssrf_allowed_domains', 3600, function () {
       return config('ssrf.allowed_domains');
   }));
   

3. Adapter-Specific Quirks

   • Guzzle: Disable allow_redirects if redirects bypass SSRF checks.
   • Symfony HTTP Client: Use withOptions(['max_redirects' => 0]) for stricter control.