HTTP Client SSRF Mitigation with InetAddressFilter in Spring Boot

1. Introduction

It’s sometimes useful to limit the remote addresses that an HTTP client is permitted to call. It helps prevent applications from connecting to unintended destinations and provides an effective defense against Server-Side Request Forgery (SSRF) attacks. To limit the address that an HTTP client can call, we can use an InetAddressFilter. The filter determines which addresses are allowed for outgoing requests. In this tutorial, we’ll explore how to use the InetAddressFilter class in a Spring-based application.

2. Understanding SSRF in the Context of HTTP Clients

SSRF is a critical security vulnerability that allows an attacker to force a server to make requests to unintended locations. These requests may target internal systems, cloud metadata endpoints, or loopback addresses. To demonstrate how SSRF can occur in an HTTP client, let’s consider a simple endpoint that accepts a URL and uses RestClient to retrieve its contents:

@GetMapping("/fetch")
public String fetch(@RequestParam String url) {
    return restClient.get()
      .uri(url)
      .retrieve()
      .body(String.class);
}

The endpoint accepts a URL as a request parameter and forwards it to RestClient. The intention is to allow users to retrieve content from public URLs. For example, a legitimate request might look like:

curl --location http://127.0.0.1:8080/fetch?url=https://www.baeldung.com

However, an attacker could provide a URL that points to an internal resource instead:

curl --location http://127.0.0.1:8080/fetch?url=admin

Instead of contacting a public website, our server now makes requests to its own internal network. This can expose internal admin APIs, databases, Kubernetes services, etc. This class of vulnerability is known as SSRF. Historically, mitigating SSRF in Spring Boot applications required custom ClientHttpRequestInterceptor implementations or complex network-level firewalls. Spring Boot 4.1.0 introduces first-class support for SSRF mitigation via the InetAddressFilter interface.

3. Maven Dependency

Let’s start by importing the spring-boot-starter-restclient dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-restclient</artifactId>
    <version>4.1.1-SNAPSHOT</version>
</dependency>

4. Introducing InetAddressFilter

The InetAddressFilter interface is a functional interface. Unlike validating the hostname or URL, InetAddressFilter performs its checks after DNS resolution. Spring Boot provides several built-in filters for common scenarios, such as allowing only public addresses (InetAddressFilter.externalAddresses()) or blocking special-purpose network ranges (InetAddressFilter.internalAddresses()). We can combine these filters using logical operators:

InetAddressFilter.of("192.168.0.0/16")
  .andNot("192.168.1.100");

The API also supports and(), or(), and negate() for composing more complex rules:

InetAddressFilter.externalAddresses()
  .or(InetAddressFilter.of("10.20.0.0"));

This enables expressive allowlists and blocklists without custom networking code.

5. Applying the Filter Globally

The simplest and most common approach is to declare an InetAddressFilter bean. Spring Boot then automatically applies it to every auto-configured HTTP client builder (RestClient, WebClient, RestTemplate, etc.). Let’s configure the InetAddressFilter to allow connections only to external IP addresses:

@Configuration(proxyBeanMethods = false)
public class HttpClientSecurityConfig {

    @Bean
    public InetAddressFilter httpClientInetAddressFilter() {
        return InetAddressFilter.externalAddresses();
    }
}

With this single bean, any client created from the auto-configured builders will reject requests whose resolved address is not external. Now, we can create a RestClient without any additional security configuration:

@Bean
RestClient restClient(RestClient.Builder builder) {
    return builder.build();
}

Because the RestClient.Builder has already been customized by Spring Boot, the resulting RestClient automatically uses the configured InetAddressFilter. As a result, any request whose resolved destination is not an external address—for example, a loopback or private IP address—is rejected before a connection is established. This approach centralizes the application’s outbound network policy in a single place and ensures that all auto-configured HTTP clients consistently enforce the same SSRF protection.

6. Applying the Filter Per-Client

In some scenarios, applying a global InetAddressFilter may be too restrictive. For example, an application might communicate with both public APIs and specific internal services, each requiring different outbound access rules. In such cases, we can apply an InetAddressFilter to an individual HTTP client by configuring the underlying HttpClientSettings when creating the client. Let’s create a RestClient that only allows requests to external addresses:

@Bean
RestClient restClient(RestClient.Builder builder) {

    InetAddressFilter onlyExternalAddresses = InetAddressFilter.externalAddresses();
    HttpClientSettings settings = HttpClientSettings.defaults()
      .withInetAddressFilter(onlyExternalAddresses);
    ClientHttpRequestFactory requestFactory = ClientHttpRequestFactoryBuilder
      .jdk().build(settings);

    return builder
      .requestFactory(requestFactory)
      .build();
}

Here, the filter is attached only to this specific RestClient instance. Other HTTP clients in the application can use different security policies or remain unaffected. This approach is useful when different integrations have different network requirements. For example, a client used to call third-party APIs can be restricted to public addresses, while another client used for communication with trusted internal services can use a more specific allowlist. By configuring the filter at the client level, we can apply fine-grained outbound request controls without changing the behavior of the entire application.

7. Test

To verify that the configured InetAddressFilter is applied, we can write a unit test that uses the configured RestClient bean to access a loopback address. The application is configured with InetAddressFilter.externalAddresses(), which permits only publicly routable IP addresses. Since 127.0.0.1 is a loopback address, the request is rejected before an HTTP connection is established. Let’s create a test case:

@Test
void whenCallingLoopbackAddress_thenFilteredHostExceptionIsThrown() {

    assertThatThrownBy(() ->
        restClient.get()
          .uri("https://127.0.0.1:8080")
          .retrieve()
          .toBodilessEntity()
    ).isInstanceOf(FilteredHostException.class)
     .hasMessageContaining("127.0.0.1");
}

When the test executes, the RestClient resolves the destination host and passes the resulting InetAddress to the configured InetAddressFilter. Because the address does not satisfy the externalAddresses() policy, Spring Boot throws a FilteredHostException and aborts the request before opening a network connection.

8. Conclusion

In this tutorial, we explored how SSRF can affect applications that make outbound HTTP requests based on user-controlled input. We also looked at how Spring Boot 4.1 simplifies SSRF mitigation with InetAddressFilter. It allows applications to validate the resolved destination address before establishing an outbound connection. The feature integrates with Spring’s HTTP client infrastructure, including both blocking and reactive clients, and provides a flexible API for composing allowlists and blocklists. By applying InetAddressFilter, we can enforce outbound network access policies at the HTTP client level. This reduces the risk of unauthorized access to internal resources while keeping the application code clean and maintainable.

As always, the source code is available over on GitHub.