Remote Images & SSRF Defense

Rules, size limits, allowed image formats, and multi-layered SSRF defense for logos and user avatars.

The Open Graph Image Generator allows embedding remote brand logos (logo) and author avatars (avatar) directly into generated social cards.

Because fetching arbitrary user-supplied URLs introduces security risks, all remote asset requests pass through a hardened, fail-closed security gateway with strict limits and comprehensive Server-Side Request Forgery (SSRF) defenses.

Remote Asset Constraints

All remote images must satisfy the following technical constraints:

ConstraintLimitViolation Error Code
ProtocolHTTPS only (https://...). Unencrypted HTTP is prohibited.remote_asset_blocked (422)
PortPort 443 (Standard HTTPS only). Non-standard ports are blocked.remote_asset_blocked (422)
Max File Size2,097,152 bytes (2 MB). Enforced via Content-Length and byte counting.remote_asset_failed (422)
Allowed Formatsimage/png, image/jpeg. (SVG, GIF, WebP are not supported).remote_asset_failed (422)
Max Dimensions4,096 × 4,096 pixels (max 16,777,216 total pixels).remote_asset_failed (422)
Fetch Timeout3,000 milliseconds (3 seconds).upstream_timeout (504)
Max Redirects3 hops maximum. Redirect targets are re-evaluated against SSRF rules.remote_asset_failed (422)

Server-Side Request Forgery (SSRF) Defense

To prevent malicious actors from using the generator as an internal port scanner or proxy to access private cloud infrastructure, the safe fetch pipeline executes multi-layered checks prior to initiating any socket connection:

  1. DNS Resolution & IP Validation: The host domain is resolved to its underlying IP addresses before connection. The IP is checked against comprehensive blacklists:
    • RFC 1918 Private Ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.
    • Loopback Addresses: 127.0.0.0/8, ::1.
    • Link-Local & Cloud Metadata: 169.254.0.0/16 (including AWS/GCP/Azure instance metadata at 169.254.169.254).
    • Carrier-Grade NAT & Shared: 100.64.0.0/10.
    • IPv6 Private & Link-Local: fc00::/7, fe80::/10.
    • Broadcast & Multicast: 224.0.0.0/4, 240.0.0.0/4, 255.255.255.255.
  2. DNS Rebinding Prevention: The socket connection is bound specifically to the validated IP address, preventing time-of-check to time-of-use (TOCTOU) DNS rebinding attacks.
  3. Redirect Evaluation: HTTP 301, 302, 307, and 308 redirects are never followed blindly. Each redirect URL is parsed, its hostname re-resolved, and its target IP independently re-validated.

If any check fails, the request immediately terminates with HTTP 422 remote_asset_blocked.

Best Practices for Logos and Avatars

  • Host on a CDN: Host logos on a reliable, public CDN (such as Cloudflare, AWS CloudFront, GitHub raw, or your production web domain).
  • Square Aspect Ratio: For author avatars (avatar), provide a square image (e.g. 256×256 or 512×512 px) for optimal circular clipping.
  • Transparent PNG for Logos: For company or project logos (logo), use a high-resolution transparent PNG with tight bounding boxes.
  • Cache Friendly: Remote assets are cached in memory during image rendering. Ensure your origin CDN serves standard Cache-Control headers.