📣 ssrf-guard 3.1.0 released — LangChain4j module, GraalVM native-image hints, WebClient DNS-time guard / LangChain4j 모듈, GraalVM 네이티브 이미지 힌트, WebClient DNS-time 가드

[jlc488]

English · 한국어

TL;DR

• ssrf-guard 3.1.0 released — three big additions on top of the v3.0 multi-module layout:
  1. New ssrf-guard-langchain4j module — same LLM-agent SSRF defense as -springai, for the other major Java LLM framework.
  2. GraalVM native-image hints baked in — RuntimeHintsRegistrar registered on every Spring autoconfig, so Spring Boot 3 AOT builds Just Work.
  3. WebClient DNS-time guard — a SsrfGuardReactorAddressResolverGroup plugs into reactor-netty's DNS pipeline, blocking private IPs the moment the hostname resolves (not just at URL-parse time). Closes the late-binding-DNS rebinding window for WebClient.
• New ssrf-guard-langchain4j-demo in this repo joins the existing 5 ssrf-guard demos — 6 total.
• No breaking changes for existing consumers. Bump the version, you're done.

What's new in v3.1.0

ssrf-guard-langchain4j — LangChain4j tool URL validation

LangChain4j is the other major Java LLM framework (the one that's not Spring AI). It expresses tools via ToolExecutor rather than Spring AI's ToolCallback, but the SSRF surface is identical: the LLM emits a JSON arguments blob, the executor runs whatever URL is inside.

The new module wraps every ToolExecutor bean with SsrfGuardedToolExecutor. URL-shaped arguments in ToolExecutionRequest.arguments() are validated against your UrlPolicy before the underlying executor runs.

<dependency>
    <groupId>kr.devslab</groupId>
    <artifactId>ssrf-guard-langchain4j</artifactId>
    <version>3.1.0</version>
</dependency>

// Spring case — auto-wrap via BeanPostProcessor (no wiring code needed).
@Bean
public ToolExecutor fetchUrl() { return (req, mem) -> doFetch(req.arguments()); }

// Outside Spring — wrap by hand.
Map<ToolSpecification, ToolExecutor> safe =
    SsrfGuardedToolExecutors.wrap(Map.of(spec, raw), urlPolicy);

AiServices.builder(SupportAssistant.class)
    .chatModel(model)
    .tools(safe)
    .build();

Under the hood: extracted ssrf-guard-llm core

To avoid duplicating logic between -springai and -langchain4j, the JSON-tool-input validation moved into a new framework-agnostic module: ssrf-guard-llm. It exposes:

• ToolInputGuard interface — String checkOrFormatError(String input) — non-null return = JSON error to send back to the LLM.
• JsonToolInputGuard impl — walks the JSON tree, finds URL-shaped strings, validates each via UrlPolicy.

Both -springai and -langchain4j are now ~30-line adapters over -llm. If a third Java LLM framework appears, the work to support it is a few classes, not a rewrite.

GraalVM native-image hints

Every Spring autoconfig now ships a RuntimeHintsRegistrar wired through META-INF/spring/aot.factories. Reflection / proxy / resource hints for:

• UrlPolicy, HostPolicy, SsrfBlockPayload, BlockReason
• The new JsonToolInputGuard JSON-walking path
• The MicrometerSsrfGuardMetrics reflective bean registration

Spring Boot 3 AOT (./gradlew bootBuildImage / ./gradlew nativeCompile) now produces working native images without any extra reflect-config.json from consumers.

WebClient DNS-time guard

ssrf-guard-webclient previously checked URLs at the ExchangeFilterFunction layer (URL-parse time). v3.1 adds a SsrfGuardReactorAddressResolverGroup that plugs into reactor-netty's DNS resolution pipeline, so even if a hostname resolves to a private IP only at DNS-resolution time (DNS rebinding, late-binding A records), the request is rejected before the connection is opened.

The autoconfig wires the resolver group onto the WebClient automatically when reactor-netty is on the classpath. No consumer code changes.

SsrfBlockPayload record

The structured JSON error the wraps return to LLMs was previously a Map.of() build — fine for Jackson but invisible to GraalVM AOT. Now a proper Java record (SsrfBlockPayload), serialized via Jackson with explicit AOT hints. Same wire format, AOT-compatible.

New demo: ssrf-guard-langchain4j-demo

ssrf-guard-langchain4j-demo — sibling of the Spring AI demo, same SSRF story for LangChain4j users:

• Fake-LLM driver makes it runnable offline (no API key)
• Same 12-attack catalog at /agent/attacks
• Same JSON error contract on the block path

cd ssrf-guard-langchain4j-demo
./gradlew bootRun

# Legitimate prompt:
curl -X POST 'http://localhost:8080/agent/chat?message=Please%20fetch%20https://httpbin.org/get' | jq

# AWS-metadata attack:
curl -X POST 'http://localhost:8080/agent/chat?message=Please%20fetch%20http://169.254.169.254/...' | jq

Migration (v3.0.1 → v3.1.0)

<dependency>
    <groupId>kr.devslab</groupId>
    <artifactId>ssrf-guard</artifactId>
    <version>3.1.0</version>
</dependency>

That's it for consumers of the meta artifact. The -restclient, -resttemplate, -webclient, -feign, -springai, -jdkhttp, -okhttp, -httpclient5 modules all moved to 3.1.0 in lockstep — no API changes, no config changes, no source changes. The Spring AI wrap and Spring DI shape stayed identical even though the implementation moved under -llm.

If you're using GraalVM native-image: nothing extra to do — the hints register automatically.

Links

• Release notes: v3.1.0
• Maven Central: kr.devslab:ssrf-guard:3.1.0 · kr.devslab:ssrf-guard-langchain4j:3.1.0
• Documentation: https://ssrf-guard.devslab.kr/
• v3.0 announcement (for context on the multi-module split): Discussion #38
• Q&A on LLM-agent SSRF: Discussion #10

---

한국어

요약

• ssrf-guard 3.1.0 릴리즈 — v3.0의 멀티모듈 구조 위에 큰 추가 3가지:
  1. 신규 ssrf-guard-langchain4j 모듈 — -springai와 같은 LLM 에이전트 SSRF 방어를 또 다른 메이저 자바 LLM 프레임워크에 적용.
  2. GraalVM 네이티브 이미지 힌트 내장 — 모든 Spring 자동설정에 RuntimeHintsRegistrar 등록. Spring Boot 3 AOT 빌드가 그냥 동작.
  3. WebClient DNS-time 가드 — SsrfGuardReactorAddressResolverGroup이 reactor-netty의 DNS 해석 파이프라인에 hook해서 호스트네임이 사설 IP로 resolve되는 순간 차단 (URL parse 시점이 아니라). WebClient의 late-binding DNS rebinding 윈도우를 막음.
• 신규 ssrf-guard-langchain4j-demo를 이 repo에 추가 — 기존 5개 ssrf-guard 데모와 합쳐 총 6개.
• 기존 사용자에게 breaking change 없음. 버전만 올리면 끝.

v3.1.0 주요 변경

ssrf-guard-langchain4j — LangChain4j 툴 URL 검증

LangChain4j는 Spring AI가 아닌 또 다른 메이저 자바 LLM 프레임워크. 툴을 Spring AI의 ToolCallback이 아닌 ToolExecutor로 표현하지만, SSRF 표면은 동일 — LLM이 JSON arguments blob을 내놓고 executor가 그 안의 URL을 그대로 실행.

새 모듈은 모든 ToolExecutor 빈을 SsrfGuardedToolExecutor로 wrap. ToolExecutionRequest.arguments()의 URL 형식 인자를 UrlPolicy로 검증한 뒤에만 실제 executor가 동작.

<dependency>
    <groupId>kr.devslab</groupId>
    <artifactId>ssrf-guard-langchain4j</artifactId>
    <version>3.1.0</version>
</dependency>

// Spring 케이스 — BeanPostProcessor가 자동 wrap (wiring 코드 0줄).
@Bean
public ToolExecutor fetchUrl() { return (req, mem) -> doFetch(req.arguments()); }

// Spring 없이 — 직접 wrap.
Map<ToolSpecification, ToolExecutor> safe =
    SsrfGuardedToolExecutors.wrap(Map.of(spec, raw), urlPolicy);

AiServices.builder(SupportAssistant.class)
    .chatModel(model)
    .tools(safe)
    .build();

내부: ssrf-guard-llm 코어 모듈 추출

-springai와 -langchain4j 사이에서 로직 중복을 피하려고 JSON 툴 입력 검증을 새 프레임워크-무관 모듈 **ssrf-guard-llm**으로 추출. 노출 API:

• ToolInputGuard 인터페이스 — String checkOrFormatError(String input) — non-null 반환 = LLM에게 보낼 JSON 에러.
• JsonToolInputGuard 구현 — JSON 트리를 walk해서 URL 형식 문자열을 찾고, 각각을 UrlPolicy로 검증.

-springai와 -langchain4j는 이제 -llm 위의 ~30줄짜리 어댑터. 제3의 자바 LLM 프레임워크가 등장해도 새 모듈 추가는 클래스 몇 개로 끝 — 재작성이 아님.

GraalVM 네이티브 이미지 힌트

모든 Spring 자동설정이 META-INF/spring/aot.factories로 와이어된 RuntimeHintsRegistrar를 발행합니다. Reflection / proxy / resource 힌트:

• UrlPolicy, HostPolicy, SsrfBlockPayload, BlockReason
• 신규 JsonToolInputGuard의 JSON-walking 경로
• MicrometerSsrfGuardMetrics의 리플렉션 빈 등록

Spring Boot 3 AOT (./gradlew bootBuildImage / ./gradlew nativeCompile)가 사용자 측 reflect-config.json 추가 없이도 동작하는 네이티브 이미지를 생성.

WebClient DNS-time 가드

ssrf-guard-webclient는 v3.0까지 ExchangeFilterFunction 레이어 (URL parse 시점)에서만 URL을 검사했음. v3.1은 SsrfGuardReactorAddressResolverGroup을 reactor-netty의 DNS 해석 파이프라인에 plug — 호스트네임이 DNS 해석 시점에만 사설 IP로 resolve 되는 경우 (DNS rebinding, late-binding A 레코드) 연결을 열기 전에 거부.

자동설정이 classpath에 reactor-netty가 있으면 resolver group을 WebClient에 자동 와이어. 사용자 코드 변경 없음.

SsrfBlockPayload 레코드

wrap이 LLM에 돌려주는 구조화된 JSON 에러는 이전엔 Map.of() 빌드 — Jackson에는 괜찮지만 GraalVM AOT에는 invisible. 이제 정식 자바 record (SsrfBlockPayload), 명시적 AOT 힌트와 함께 Jackson 직렬화. wire format은 동일, AOT 호환.

새 데모: ssrf-guard-langchain4j-demo

ssrf-guard-langchain4j-demo — Spring AI 데모의 짝꿍, LangChain4j 사용자용으로 같은 SSRF 스토리:

• 가짜 LLM 드라이버 — 오프라인 실행 (API 키 불필요)
• 동일한 12개 공격 카탈로그를 /agent/attacks로
• 차단 경로의 JSON 에러 컨트랙트 동일

cd ssrf-guard-langchain4j-demo
./gradlew bootRun

# 정상 프롬프트:
curl -X POST 'http://localhost:8080/agent/chat?message=Please%20fetch%20https://httpbin.org/get' | jq

# AWS 메타데이터 공격:
curl -X POST 'http://localhost:8080/agent/chat?message=Please%20fetch%20http://169.254.169.254/...' | jq

마이그레이션 (v3.0.1 → v3.1.0)

<dependency>
    <groupId>kr.devslab</groupId>
    <artifactId>ssrf-guard</artifactId>
    <version>3.1.0</version>
</dependency>

메타 아티팩트 사용자는 이걸로 끝. -restclient, -resttemplate, -webclient, -feign, -springai, -jdkhttp, -okhttp, -httpclient5 모두 3.1.0으로 동시 진행 — API 변경 없음, 설정 변경 없음, 소스 변경 없음. Spring AI wrap과 Spring DI shape는 구현이 -llm 아래로 옮겨가도 동일.

GraalVM 네이티브 이미지 사용자: 추가 작업 없음 — 힌트가 자동 등록됨.

링크

• 릴리즈 노트: v3.1.0
• Maven Central: kr.devslab:ssrf-guard:3.1.0 · kr.devslab:ssrf-guard-langchain4j:3.1.0
• 문서: https://ssrf-guard.devslab.kr/ko/
• v3.0 출시 발표 (멀티모듈 분할 맥락): Discussion #38
• LLM 에이전트 SSRF Q&A: Discussion #10