Assetpicker Bundle Laravel Package

Getting Started

• This is a Symfony bundle, not a native Laravel package. To use it in a Laravel app you will either need a Symfony‑bundle bridge, or (more realistically) extract the proxy route/controller and adopt the secured HTTP client pattern.
• Install with Composer: composer require netresearch/assetpicker-bundle:^2.0.
• Start by reading the bundle’s README.md and its route definition (often config/routes.yaml or Resources/config/routing.xml). Look for the proxy route that accepts a to query parameter – that is the entry point an attacker exploited in 2.0.0 and earlier.
• The relevant service for security is assetpicker.proxy.http_client. In 2.0.1 this is a NoPrivateNetworkHttpClient wrapping your app’s http_client. In Laravel you will need to bind an equivalent client manually (see below).
• First use case: stand up the proxy route in a Laravel route file (or a dedicated controller) to fetch remote asset metadata from a single trusted storage (e.g. an S3 bucket or DAM). Verify that requests to 127.0.0.1, 169.254.169.254, and internal hostnames return 403 Forbidden before pointing the front‑end at it.

Implementation Patterns

• Importing the proxy route into Laravel: The bundle ships a route you can import. In Laravel, you can copy the route definition into routes/web.php and point it at a controller that replicates the bundle’s proxy logic using Laravel’s HTTP client. Ensure the controller uses a NoPrivateNetworkHttpClient‑equivalent wrapper. Do not forward arbitrary user‑supplied URLs without that wrapper.
• Secured proxy client binding: In a service provider, bind a singleton named assetpicker.proxy.http_client (or your own abstraction) that wraps Illuminate\Support\Facades\Http::buildClient() inside Symfony\Component\HttpClient\NoPrivateNetworkHttpClient. Requires symfony/http-client 8.1 or later for the allowList argument.
• Allowing internal storages: If your asset picker must reach an on‑prem DAM, private S3 endpoint, or internal DNS name, redefine the proxy client with an explicit allow list. For example (Symfony YAML style, translate to Laravel container binding):

  assetpicker.proxy.http_client:
      class: Symfony\Component\HttpClient\NoPrivateNetworkHttpClient
      arguments:
          - '@http_client'
          - { allowList: ['10.0.0.0/8', 'internal.example.com'] }
  

  In Laravel: $this->app->singleton('assetpicker.proxy.http_client', fn() => new NoPrivateNetworkHttpClient(Http::buildClient(), ['allowList' => [...]]));
• Caching and rate limiting: The proxy is likely used for every asset listing request. Cache remote metadata and apply throttle middleware to the proxy route to reduce abuse and load.
• Testing: Write feature tests that assert a request to the proxy with to=http://169.254.169.254/latest/meta-data/ returns 403. Also test a public URL returns the proxied content (mock the HTTP client).

Gotchas and Tips

• Breaking change: 2.0.1 refuses requests to internal hosts by default. If you previously used the proxy to reach an internal storage (including localhost or private IPs), your asset picker will now return 403 Forbidden. You must add an allow list as shown above.
• Symfony HttpClient version: The allowList option is only available in symfony/http-client 8.1+. Check composer show symfony/http-client. Laravel may lock an older version; upgrade if needed or keep the storages public.
• Laravel container differences: The bundle’s service definitions are not auto‑loaded in Laravel. You must explicitly bind the proxy client and any controllers. Do not assume the bundle’s YAML config will be read.
• Debugging 403s: The proxy now returns 403 for refused targets. Log the original to parameter and the resolved IP/host to distinguish an SSRF attempt from a legitimate private storage that needs allow‑listing. The application’s own http_client is unaffected – only the proxy client changed.
• Supply chain: 2.0.1 is the first release signed and attested by the release workflow. If your organisation requires verified builds, use the provided gh attestation verify command. This does not affect runtime, but it is a good reason to pin to 2.0.1 when possible.
• Default branch is now main – update any CI references or composer documentation links that pointed to master.
• Extension point: You can replace the proxy client entirely with your own implementation (e.g. adding custom logging, timeouts, or circuit breaking) as long as it preserves the NoPrivateNetworkHttpClient protection. The bundle exposes the service name assetpicker.proxy.http_client for this purpose.