📣 ssrf-guard 3.0.0 + 3.0.1 released — new modules, LLM agent SSRF defense, 5 new demos / 새 모듈, LLM 에이전트 SSRF 방어, 새 데모 5개

[jlc488]

English · 한국어

TL;DR

• ssrf-guard 3.0.0 released — split into 9 modules, added Spring AI tool URL validation for LLM agents, hardened the IP-bypass defenses, added Micrometer metrics.
• ssrf-guard 3.0.1 quick patch — ClassNotFoundException when consumers don't have micrometer-core on the classpath (the autoconfig referenced MeterRegistry by type instead of by class-presence). Fixed by gating the metrics bean with @ConditionalOnClass(MeterRegistry.class).
• Five new demos in this repo cover every shipped module.

v3.0.0 highlights

New modules (opt-in)

Module	Use case
ssrf-guard-core	Policy / NetUtil / Micrometer metrics interface — no Spring
ssrf-guard-httpclient5	Apache HttpClient 5 DnsResolver + RedirectStrategy (TOCTOU closure)
ssrf-guard-restclient	Spring 6.1+ RestClient autoconfig (the v2.0.0 surface, now its own module)
ssrf-guard-resttemplate	🆕 Spring RestTemplate autoconfig
ssrf-guard-webclient	🆕 Spring WebFlux WebClient ExchangeFilterFunction
ssrf-guard-feign	🆕 Spring Cloud OpenFeign RequestInterceptor
ssrf-guard-springai	🆕⭐ Spring AI ToolCallback URL validation — closes the LLM-agent SSRF surface
ssrf-guard-jdkhttp	🆕 java.net.http.HttpClient wrapper (no Spring)
ssrf-guard-okhttp	🆕 OkHttp Interceptor + Dns (no Spring)
ssrf-guard	Meta artifact — bundles -core + -httpclient5 + -restclient for v2.0.0 back-compat

Defense-in-depth hardening

• IP-literal host rejection — decimal (2130706433), hex (0x7f000001), octal-style (0177.0.0.1), partial (127.1), IPv6 ([::1]) — all rejected at the URL-time check.
• Userinfo rejection — https://user:pass@host/... blocked (known SSRF bypass + credential-leak risk).
• IPv4-mapped IPv6 + 6to4 unmapping — ::ffff:10.0.0.5 and 2002:0a00:: now correctly classified as private.

Observability

Auto-wired with Micrometer:

ssrf_guard_blocked_total{reason="blocked_private_ip", scheme="http"} 42
ssrf_guard_allowed_total{scheme="https"} 13042

v3.0.1 fix

If you bumped to 3.0.0 and got this:

java.lang.TypeNotPresentException: Type io.micrometer.core.instrument.MeterRegistry not present

That's the bug 3.0.1 fixes. The autoconfig declared ObjectProvider<MeterRegistry> as a method parameter — ObjectProvider handles missing beans gracefully but the JVM still resolves the parameter type at class-load time, so consumers without micrometer-core blew up.

Fix: moved the Micrometer-backed metrics bean into a static inner @Configuration class gated by @ConditionalOnClass(name = "io.micrometer.core.instrument.MeterRegistry") with a NoOp fallback. Drop in 3.0.1 — no consumer changes needed.

New demos

All in devslab-examples:

• ssrf-guard-demo — RestClient + RestTemplate + WebClient all wired through one UrlPolicy. 15-pattern attack matrix endpoint, Micrometer metrics.
• ssrf-guard-springai-demo — ⭐ LLM agent SSRF defense. Fake-LLM driver — runnable offline, no API key.
• ssrf-guard-feign-demo — Spring Cloud OpenFeign integration.
• ssrf-guard-jdkhttp-demo — java.net.http.HttpClient without Spring.
• ssrf-guard-okhttp-demo — OkHttp without Spring.

Every demo: clone, ./gradlew bootRun, curl. Smoke tests included.

Migration (v2.0.0 → v3.0.1)

Most consumers:

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

The meta artifact transitively pulls -core + -httpclient5 + -restclient — the entire v2.0.0 surface. Direct imports of kr.devslab.ssrfguard.security.* need updates per the v3.0.0 changelog.

SsrfGuardException extends SecurityException, so existing catch (SecurityException e) keeps working. Catch the new type to read e.reason() (a BlockReason enum).

Links

• Release notes: v3.0.0 · v3.0.1
• Maven Central: kr.devslab:ssrf-guard:3.0.1
• Documentation: https://ssrf-guard.devslab.kr/
• Q&A on LLM-agent SSRF: Discussion #10

---

한국어

요약

• ssrf-guard 3.0.0 릴리즈 — 9개 모듈로 분할, LLM 에이전트용 Spring AI 툴 URL 검증 추가, IP 우회 방어 강화, Micrometer 메트릭 추가.
• ssrf-guard 3.0.1 빠른 패치 — 소비자가 micrometer-core를 클래스패스에 안 가지면 발생하던 ClassNotFoundException. 자동설정이 MeterRegistry를 타입으로 직접 노출시켜서 발생. @ConditionalOnClass(MeterRegistry.class) 게이트로 격리해서 수정.
• 새 데모 5개가 이 repo에 출시된 모든 모듈을 커버.

v3.0.0 주요 변경

새 모듈 (opt-in)

모듈	용도
ssrf-guard-core	정책 / NetUtil / Micrometer 메트릭 인터페이스 — Spring 없음
ssrf-guard-httpclient5	Apache HttpClient 5 DnsResolver + RedirectStrategy (TOCTOU 차단)
ssrf-guard-restclient	Spring 6.1+ RestClient 자동설정 (v2.0.0의 surface가 별도 모듈로)
ssrf-guard-resttemplate	🆕 Spring RestTemplate 자동설정
ssrf-guard-webclient	🆕 Spring WebFlux WebClient ExchangeFilterFunction
ssrf-guard-feign	🆕 Spring Cloud OpenFeign RequestInterceptor
ssrf-guard-springai	🆕⭐ Spring AI ToolCallback URL 검증 — LLM 에이전트 SSRF 차단
ssrf-guard-jdkhttp	🆕 java.net.http.HttpClient 래퍼 (Spring 없음)
ssrf-guard-okhttp	🆕 OkHttp Interceptor + Dns (Spring 없음)
ssrf-guard	메타 아티팩트 — -core + -httpclient5 + -restclient 묶음으로 v2.0.0 호환

방어 강화

• IP 리터럴 호스트 거부 — 십진수 (2130706433), 16진수 (0x7f000001), 8진수 스타일 (0177.0.0.1), 부분 (127.1), IPv6 ([::1]) — URL 단계에서 모두 거부.
• Userinfo 거부 — https://user:pass@host/... 차단 (알려진 SSRF 우회 + 자격증명 누출 리스크).
• IPv4-mapped IPv6 + 6to4 unmapping — ::ffff:10.0.0.5와 2002:0a00::이 사설로 정확히 분류.

관찰성

Micrometer로 자동 와이어:

ssrf_guard_blocked_total{reason="blocked_private_ip", scheme="http"} 42
ssrf_guard_allowed_total{scheme="https"} 13042

v3.0.1 fix

3.0.0으로 올린 후 이 에러를 봤다면:

java.lang.TypeNotPresentException: Type io.micrometer.core.instrument.MeterRegistry not present

3.0.1이 그 버그를 고쳤습니다. 자동설정이 ObjectProvider<MeterRegistry>를 메서드 파라미터로 선언했었음 — ObjectProvider는 없는 빈을 우아하게 처리하지만 JVM은 클래스 로드 시점에 파라미터 타입을 그래도 resolve합니다. 그래서 micrometer-core 없는 소비자가 부팅 시 폭발.

수정: Micrometer 기반 메트릭 빈을 @ConditionalOnClass(name = "io.micrometer.core.instrument.MeterRegistry")로 게이트된 static inner @Configuration 클래스로 격리하고 NoOp fallback 등록. 3.0.1로 바로 올리면 됨 — 소비자 코드 변경 불필요.

새 데모

모두 devslab-examples에:

• ssrf-guard-demo — RestClient + RestTemplate + WebClient가 모두 하나의 UrlPolicy로 wiring. 15가지 공격 매트릭스 엔드포인트, Micrometer 메트릭.
• ssrf-guard-springai-demo — ⭐ LLM 에이전트 SSRF 방어. 가짜 LLM 드라이버 — 오프라인 실행, API 키 불필요.
• ssrf-guard-feign-demo — Spring Cloud OpenFeign 통합.
• ssrf-guard-jdkhttp-demo — Spring 없이 java.net.http.HttpClient.
• ssrf-guard-okhttp-demo — Spring 없이 OkHttp.

데모마다: clone, ./gradlew bootRun, curl. 스모크 테스트 포함.

마이그레이션 (v2.0.0 → v3.0.1)

대부분의 사용자:

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

메타 아티팩트가 -core + -httpclient5 + -restclient를 transitive로 끌어옴 — v2.0.0 전체 surface 그대로. kr.devslab.ssrfguard.security.* 직접 import한 코드는 v3.0.0 changelog의 매핑 참고.

SsrfGuardException extends SecurityException — 기존 catch (SecurityException e) 코드는 그대로 동작. 새 타입으로 catch하면 e.reason() (BlockReason enum) 접근 가능.

링크

• 릴리즈 노트: v3.0.0 · v3.0.1
• Maven Central: kr.devslab:ssrf-guard:3.0.1
• 문서: https://ssrf-guard.devslab.kr/ko/
• LLM 에이전트 SSRF Q&A: Discussion #10