# How to Prevent SSRF Vulnerabilities in Agent-Native Using ssrfSafeFetch

> Prevent SSRF vulnerabilities in Agent-Native with ssrfSafeFetch. Learn how four validation layers secure server-side requests and protect your application.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-07-02

---

**TLDR:** Agent-Native's `ssrfSafeFetch` helper prevents Server-Side Request Forgery attacks by implementing four layers of validation—static URL parsing, DNS-aware runtime checks, connect-time IP filtering, and manual redirect inspection—before executing any server-side request.

Agent-Native safeguards every server-side request that receives a URL from users, agents, or external sources by routing it through the centralized `ssrfSafeFetch` utility. This helper, located in [`packages/core/src/extensions/url-safety.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/url-safety.ts), implements a defense-in-depth strategy against Server-Side Request Forgery (SSRF) that blocks both literal private network requests and sophisticated DNS rebinding attacks. By importing this single function from `@agent-native/core/extensions/url-safety`, developers ensure their agent actions inherit robust protection without implementing complex validation logic manually.

## Understanding the ssrfSafeFetch Security Layers

The `ssrfSafeFetch` function orchestrates multiple validation stages to eliminate SSRF attack vectors. According to the BuilderIO/agent-native source code, each layer addresses a specific vulnerability window in the request lifecycle.

### Static URL Validation with isBlockedExtensionUrl

Before any network activity occurs, `ssrfSafeFetch` invokes `isBlockedExtensionUrl` to parse and reject dangerous URLs based on their literal values. As implemented in lines 94-108 of [`packages/core/src/extensions/url-safety.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/url-safety.ts), this function blocks:

- Non-HTTP/HTTPS schemes (eliminating `file://`, `gopher://`, and other protocol handlers)
- Hostnames resolving to known private addresses (`localhost`, `::1`, `127.0.0.1`, etc.)
- Domains listed in `METADATA_HOSTS` (cloud metadata services)
- Hostnames ending with DNS-rebinding suffixes such as `.nip.io` or `.xip.io`

This static validation prevents obvious attacks where attackers supply literal internal IP addresses or known bypass domains.

### DNS-Aware Runtime Verification

To catch attacks where a public hostname resolves to a private IP after validation, `ssrfSafeFetch` employs `isBlockedExtensionUrlWithDns`. This function first runs the static check, then resolves the hostname using `node:dns/promises` as shown in lines 27-48 of [`packages/core/src/extensions/url-safety.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/url-safety.ts).

If any resolved IP address belongs to a private range (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, etc.), the request aborts immediately. This layer specifically targets DNS rebinding attacks where adversaries control DNS records that flip between public and private IPs.

### Connect-Time Protection with createSsrfSafeDispatcher

Even after DNS validation, a Time-of-Check to Time-of-Use (TOCTOU) window exists where the DNS record could change before the TCP connection establishes. To eliminate this race condition, Agent-Native uses `createSsrfSafeDispatcher` to build a custom Undici `Agent` that performs its own DNS lookup immediately before the TCP connection.

As implemented in lines 51-62 and the `lookup` callback in lines 89-108 of [`packages/core/src/extensions/url-safety.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/url-safety.ts), this dispatcher aborts the connection if the resolved IP is private. This connect-time verification ensures that even if the DNS record changes between the initial check and the actual socket connection, the request cannot reach internal networks.

### Manual Redirect Handling

Automatic redirects present another SSRF vector where a public URL redirects to a private internal address. The `ssrfSafeFetch` function disables automatic redirects by setting `redirect: "manual"` and caps the total number of hops using `maxRedirects` (defaulting to 3).

As shown in lines 60-78 of [`packages/core/src/extensions/url-safety.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/url-safety.ts), each redirect hop undergoes the same DNS-aware validation sequence before following the next URL. This prevents attackers from using 30x redirects to pivot from public endpoints into private infrastructure.

## Implementing ssrfSafeFetch in Server Actions

All server-side code that fetches external resources should import `ssrfSafeFetch` from `@agent-native/core/extensions/url-safety`. The helper abstracts the protection layers, presenting a standard `fetch`-like API.

### Basic Usage Pattern

```typescript
import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";

export async function fetchPublicJson(url: string) {
  // Automatically vets for private hosts and DNS rebinding
  const response = await ssrfSafeFetch(
    url,
    {
      headers: { "Accept": "application/json" },
      signal: AbortSignal.timeout(5000),
    },
    { maxRedirects: 2 }
  );

  if (!response.ok) {
    throw new Error(`Failed: ${response.status}`);
  }
  return response.json();
}

```

### Real-World Implementation Example

The [`analyze-brand-assets.ts`](https://github.com/BuilderIO/agent-native/blob/main/analyze-brand-assets.ts) template demonstrates production usage:

```typescript
const url = normalizeBrandWebsiteUrl(websiteUrl);
const response = await ssrfSafeFetch(
  url,
  {
    headers: {
      "User-Agent":
        "Mozilla/5.0 (compatible; AgentNative/1.0; +https://agent-native.com)",
    },
    signal: AbortSignal.timeout(10_000),
  },
  { maxRedirects: 3 },
);
const html = await response.text();

```

This pattern appears throughout the codebase, including in [`packages/core/src/file-upload/actions/upload-image.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/file-upload/actions/upload-image.ts) and [`packages/core/src/notifications/channels.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/notifications/channels.ts), ensuring consistent protection across image processing and notification delivery paths.

### Advanced: Custom Dispatcher Configuration

While rarely necessary, you can create a standalone SSRF-safe dispatcher for use with other fetch implementations:

```typescript
import { createSsrfSafeDispatcher } from "@agent-native/core/extensions/url-safety";

const dispatcher = await createSsrfSafeDispatcher();
if (dispatcher) {
  await fetch("https://example.com", { dispatcher });
}

```

## Validating SSRF Protections

The test suite in [`packages/core/src/extensions/ssrf-fetch.spec.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/ssrf-fetch.spec.ts) verifies protection against private hosts, DNS rebinding scenarios, and malicious redirect chains. When extending Agent-Native, reference these tests to ensure your implementations maintain the security guarantees of the core framework.

## Summary

- **Multi-layered validation**: `ssrfSafeFetch` combines static parsing, DNS resolution checks, and connect-time IP filtering to eliminate SSRF vectors.
- **DNS rebinding protection**: The helper validates IPs both before and during connection establishment, blocking attacks that switch DNS records between public and private addresses.
- **Redirect safety**: Manual redirect handling with re-validation prevents attackers from using intermediary public URLs to reach private networks.
- **Simple integration**: Import `ssrfSafeFetch` from `@agent-native/core/extensions/url-safety` to automatically apply protection to any server-side fetch operation.
- **Implementation location**: Core logic resides in [`packages/core/src/extensions/url-safety.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/extensions/url-safety.ts) with usage examples in [`templates/videos/actions/analyze-brand-assets.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/videos/actions/analyze-brand-assets.ts).

## Frequently Asked Questions

### How does Agent-Native prevent DNS rebinding attacks specifically?

Agent-Native prevents DNS rebinding through redundant IP validation at two distinct phases. First, `isBlockedExtensionUrlWithDns` resolves the hostname and checks for private ranges before initiating the request. Second, `createSsrfSafeDispatcher` performs a fresh DNS lookup immediately before the TCP connection via a custom Undici `lookup` callback. This dual verification ensures that even if an attacker changes the DNS record between validation and connection, the request aborts when the socket attempts to connect to a private IP.

### Can I increase the redirect limit for ssrfSafeFetch?

Yes, the third argument to `ssrfSafeFetch` accepts an options object where you can specify `maxRedirects`. While the default is 3 to prevent infinite loops and redirect chains, you can increase this value for legitimate use cases requiring multiple hops. Each redirect undergoes the same SSRF validation sequence regardless of the limit set.

### Does ssrfSafeFetch support protocols other than HTTP and HTTPS?

No, `ssrfSafeFetch` explicitly blocks non-HTTP/HTTPS schemes at the static validation layer via `isBlockedExtensionUrl`. This restriction prevents protocol-related attacks such as `file://` access to local filesystems or `gopher://` requests to internal services. The function is designed specifically for safe web resource fetching over standard HTTP protocols.

### When should I use createSsrfSafeDispatcher instead of ssrfSafeFetch?

You should use `createSsrfSafeDispatcher` only when integrating with libraries that require a custom Undici `Dispatcher` instance rather than a standard fetch call. The `ssrfSafeFetch` helper already handles dispatcher creation internally, so direct usage of `createSsrfSafeDispatcher` is rare and typically reserved for advanced scenarios where you need fine-grained control over the HTTP agent configuration while maintaining SSRF protections.