Skip to content

Commit b855b2a

Browse files
authored
fix: prevent SSRF via push notification URL validation (a2aproject#1096)
- Add PushNotificationUrlValidator with SSRF-safe default (scheme allowlist, private-network blocking incl. IPv4-mapped IPv6) - Disable HTTP redirect following on push notification POST requests - Add a2a.push-notifications.enabled config to gate push config storage Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent efb4e98 commit b855b2a

21 files changed

Lines changed: 871 additions & 44 deletions

File tree

‎compat-0.3/server-conversion/src/test/java/org/a2aproject/sdk/compat03/conversion/AbstractA2ARequestHandlerTest_v0_3.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
import org.a2aproject.sdk.server.tasks.InMemoryTaskStore;
3232
import org.a2aproject.sdk.server.tasks.PushNotificationConfigStore;
3333
import org.a2aproject.sdk.server.tasks.PushNotificationSender;
34+
import org.a2aproject.sdk.server.tasks.PushNotificationUrlValidator;
3435
import org.a2aproject.sdk.server.tasks.TaskStore;
3536
import org.a2aproject.sdk.spec.A2AError;
3637
import org.a2aproject.sdk.spec.StreamingEventKind;
@@ -129,7 +130,7 @@ public void cancel(RequestContext context, AgentEmitter agentEmitter) throws A2A
129130
// Create push notification components BEFORE MainEventBusProcessor
130131
httpClient = new TestHttpClient();
131132
PushNotificationConfigStore pushConfigStore = new InMemoryPushNotificationConfigStore();
132-
PushNotificationSender pushSender = new BasePushNotificationSender(pushConfigStore, httpClient);
133+
BasePushNotificationSender pushSender = new BasePushNotificationSender(pushConfigStore, httpClient, PushNotificationUrlValidator.ALLOW_ALL);
133134

134135
// Create MainEventBus and MainEventBusProcessor (production code path)
135136
mainEventBus = new MainEventBus();
@@ -144,6 +145,7 @@ public void cancel(RequestContext context, AgentEmitter agentEmitter) throws A2A
144145
.taskStore(taskStore)
145146
.queueManager(queueManager)
146147
.pushConfigStore(pushConfigStore)
148+
.pushNotificationsEnabled(true)
147149
.mainEventBusProcessor(mainEventBusProcessor)
148150
.executor(internalExecutor)
149151
.eventConsumerExecutor(internalExecutor)

‎compat-0.3/tck/src/main/resources/application.properties‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,11 @@ quarkus.log.console.level=INFO
2121

2222
# Authorization is not configured in this application
2323
a2a.authorization.required=false
24+
25+
# Push notifications enabled for TCK conformance testing
26+
a2a.push-notification.enabled=true
27+
# Push notification URL validation relaxed for CI/testing:
28+
# Allow http (TCK webhook runs plain HTTP on localhost)
29+
a2a.push-notification.url.allowed-schemes=https,http
30+
# Allow private/loopback targets (TCK runner listens on localhost)
31+
a2a.push-notification.url.allow-private-network-targets=true

‎docs/content/dev/configuration.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,34 @@ a2a.push-notification-config.max-per-task=100
8585

8686
Limits the number of distinct push notification configurations a single task may register. Each config consumes memory and can trigger an outbound HTTP request on every task event. Re-registering an existing config ID (updating it) does not count against the limit. Both `InMemoryPushNotificationConfigStore` and `JpaDatabasePushNotificationConfigStore` enforce this limit, throwing `InvalidParamsError` when exceeded.
8787

88+
### Push Notifications
89+
90+
```properties
91+
# Enable or disable push notification support (default: true)
92+
a2a.push-notification.enabled=true
93+
94+
# Allowed URL schemes for push notification targets, comma-separated (default: https)
95+
a2a.push-notification.url.allowed-schemes=https
96+
97+
# Allow push notification URLs targeting private/internal network addresses (default: false)
98+
a2a.push-notification.url.allow-private-network-targets=false
99+
100+
# TTL in seconds for DNS resolution caching during URL validation (default: 30, 0 to disable)
101+
a2a.push-notification.url.dns-cache-ttl-seconds=30
102+
```
103+
104+
**`a2a.push-notification.enabled`** controls whether the server accepts push notification configurations. When `false`, push notification configs embedded in `sendMessage` requests are silently ignored, and explicit `CreateTaskPushNotificationConfig` calls return `UnsupportedOperationError`.
105+
106+
**`a2a.push-notification.url.allowed-schemes`** restricts which URL schemes are accepted for push notification targets. Defaults to `https` only. To also allow plain HTTP (e.g. in development), set to `http,https`.
107+
108+
**`a2a.push-notification.url.allow-private-network-targets`** controls whether push notifications can target private/internal network addresses. The default (`false`) blocks loopback addresses, link-local (169.254.x.x), site-local (10.x, 172.16.x, 192.168.x), RFC 6598 shared space (100.64.0.0/10), IPv6 unique-local (fc00::/7), IPv4-mapped IPv6 variants, and multicast addresses. This prevents Server-Side Request Forgery (SSRF) attacks where a client registers a push notification URL pointing to internal infrastructure. Set to `true` **only** in trusted development environments.
109+
110+
**`a2a.push-notification.url.dns-cache-ttl-seconds`** controls how long (in seconds) resolved DNS results are cached during URL validation. Defaults to `30`. Caching avoids a blocking DNS lookup on every push notification delivery. Set to `0` to disable caching entirely (every validation triggers a fresh DNS resolution).
111+
112+
The `DefaultPushNotificationUrlValidator` enforces these policies. Custom implementations can be provided via CDI by implementing `PushNotificationUrlValidator`.
113+
114+
> **Known limitation — DNS rebinding:** hostname resolution happens at validation time, not at connection time. An attacker controlling a domain could register a URL that initially resolves to a public IP, then change the DNS record to an internal address before the next push event fires. The DNS cache reduces this window but does not eliminate it. Deployments with strict SSRF requirements should use network-level firewall rules to block outbound traffic to internal ranges.
115+
88116
### Tuning Guidelines
89117

90118
- **Streaming Performance**: The executor handles streaming subscriptions. Too few threads can cause timeouts under concurrent load.

‎extras/http-client-android/src/main/java/org/a2aproject/sdk/client/http/android/AndroidA2AHttpClient.java‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,16 +261,24 @@ public CompletableFuture<Void> getAsyncSSE(
261261
private static class AndroidPostBuilder extends AndroidBuilder<PostBuilder>
262262
implements PostBuilder {
263263
private String body = "";
264+
private boolean followRedirects = true;
264265

265266
@Override
266267
public PostBuilder body(String body) {
267268
this.body = body;
268269
return this;
269270
}
270271

272+
@Override
273+
public PostBuilder followRedirects(boolean follow) {
274+
this.followRedirects = follow;
275+
return self();
276+
}
277+
271278
@Override
272279
public A2AHttpResponse post() throws IOException {
273280
HttpURLConnection connection = createConnection("POST", false);
281+
connection.setInstanceFollowRedirects(followRedirects);
274282
connection.setDoOutput(true);
275283
try {
276284
try (OutputStream os = connection.getOutputStream()) {

‎extras/http-client-vertx/src/main/java/org/a2aproject/sdk/client/http/vertx/VertxA2AHttpClient.java‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -524,13 +524,20 @@ public CompletableFuture<Void> getAsyncSSE(
524524
private class VertxPostBuilder extends VertxBuilder<PostBuilder> implements A2AHttpClient.PostBuilder {
525525

526526
private String body = "";
527+
private boolean followRedirects = true;
527528

528529
@Override
529530
public PostBuilder body(String body) {
530531
this.body = body;
531532
return self();
532533
}
533534

535+
@Override
536+
public PostBuilder followRedirects(boolean follow) {
537+
this.followRedirects = follow;
538+
return self();
539+
}
540+
534541
/**
535542
* {@inheritDoc}
536543
*
@@ -546,7 +553,9 @@ public PostBuilder body(String body) {
546553
@Override
547554
public A2AHttpResponse post() throws IOException, InterruptedException {
548555
Buffer bodyBuffer = Buffer.buffer(body, StandardCharsets.UTF_8.name());
549-
return executeSyncRequest(webClient.postAbs(url), headers, bodyBuffer);
556+
HttpRequest<Buffer> request = webClient.postAbs(url);
557+
request.followRedirects(followRedirects);
558+
return executeSyncRequest(request, headers, bodyBuffer);
550559
}
551560

552561
@Override

‎extras/push-notification-config-store-database-jpa/src/test/java/org/a2aproject/sdk/extras/pushnotificationconfigstore/database/jpa/JpaPushNotificationConfigStoreTest.java‎

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import org.a2aproject.sdk.client.http.A2AHttpResponse;
2121
import org.a2aproject.sdk.server.tasks.BasePushNotificationSender;
2222
import org.a2aproject.sdk.server.tasks.PushNotificationConfigStore;
23+
import org.a2aproject.sdk.server.tasks.PushNotificationUrlValidator;
2324
import org.a2aproject.sdk.spec.ListTaskPushNotificationConfigsParams;
2425
import org.a2aproject.sdk.spec.ListTaskPushNotificationConfigsResult;
2526
import org.a2aproject.sdk.spec.Task;
@@ -54,7 +55,8 @@ public class JpaPushNotificationConfigStoreTest {
5455
@BeforeEach
5556
public void setUp() {
5657
MockitoAnnotations.openMocks(this);
57-
notificationSender = new BasePushNotificationSender(configStore, mockHttpClient);
58+
notificationSender = new BasePushNotificationSender(configStore, mockHttpClient,
59+
PushNotificationUrlValidator.ALLOW_ALL);
5860
}
5961

6062
@Test
@@ -233,6 +235,16 @@ public void testDeleteInfoWithNullConfigId() {
233235
assertTrue(configResult.configs().isEmpty(), "Should return empty list after deletion when using taskId as configId");
234236
}
235237

238+
private void setupBasicMockHttpResponse() throws Exception {
239+
when(mockHttpClient.createPost()).thenReturn(mockPostBuilder);
240+
when(mockPostBuilder.followRedirects(false)).thenReturn(mockPostBuilder);
241+
when(mockPostBuilder.url(any(String.class))).thenReturn(mockPostBuilder);
242+
when(mockPostBuilder.addHeader(any(String.class), any(String.class))).thenReturn(mockPostBuilder);
243+
when(mockPostBuilder.body(any(String.class))).thenReturn(mockPostBuilder);
244+
when(mockPostBuilder.post()).thenReturn(mockHttpResponse);
245+
when(mockHttpResponse.success()).thenReturn(true);
246+
}
247+
236248
@Test
237249
@Transactional
238250
public void testSendNotificationSuccess() throws Exception {
@@ -241,19 +253,14 @@ public void testSendNotificationSuccess() throws Exception {
241253
TaskPushNotificationConfig config = createSamplePushConfig("http://notify.me/here", "cfg1", null);
242254
configStore.setInfo(TaskPushNotificationConfig.builder(config).taskId(taskId).build());
243255

244-
// Mock successful HTTP response
245-
when(mockHttpClient.createPost()).thenReturn(mockPostBuilder);
246-
when(mockPostBuilder.url(any(String.class))).thenReturn(mockPostBuilder);
247-
when(mockPostBuilder.addHeader(CONTENT_TYPE, APPLICATION_JSON)).thenReturn(mockPostBuilder);
248-
when(mockPostBuilder.body(any(String.class))).thenReturn(mockPostBuilder);
249-
when(mockPostBuilder.post()).thenReturn(mockHttpResponse);
250-
when(mockHttpResponse.success()).thenReturn(true);
256+
setupBasicMockHttpResponse();
251257

252258
notificationSender.sendNotification(task, null);
253259

254260
// Verify HTTP client was called
255261
ArgumentCaptor<String> bodyCaptor = ArgumentCaptor.forClass(String.class);
256262
verify(mockHttpClient).createPost();
263+
verify(mockPostBuilder).followRedirects(false);
257264
verify(mockPostBuilder).url(config.url());
258265
verify(mockPostBuilder).addHeader(CONTENT_TYPE, APPLICATION_JSON);
259266
verify(mockPostBuilder).body(bodyCaptor.capture());
@@ -274,12 +281,7 @@ public void testSendNotificationWithToken() throws Exception {
274281
TaskPushNotificationConfig config = createSamplePushConfig("http://notify.me/here", "cfg1", "unique_token");
275282
configStore.setInfo(TaskPushNotificationConfig.builder(config).taskId(taskId).build());
276283

277-
// Mock successful HTTP response
278-
when(mockHttpClient.createPost()).thenReturn(mockPostBuilder);
279-
when(mockPostBuilder.url(any(String.class))).thenReturn(mockPostBuilder);
280-
when(mockPostBuilder.body(any(String.class))).thenReturn(mockPostBuilder);
281-
when(mockPostBuilder.post()).thenReturn(mockHttpResponse);
282-
when(mockHttpResponse.success()).thenReturn(true);
284+
setupBasicMockHttpResponse();
283285

284286
notificationSender.sendNotification(task, null);
285287

‎http-client/src/main/java/org/a2aproject/sdk/client/http/A2AHttpClient.java‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,27 @@ interface PostBuilder extends Builder<PostBuilder> {
154154
*/
155155
PostBuilder body(String body);
156156

157+
/**
158+
* Controls whether the HTTP client follows redirects for this request.
159+
* When set to {@code false}, redirect responses (3xx) are returned as-is
160+
* instead of being followed automatically.
161+
*
162+
* <p>Security-sensitive code (e.g. push notification delivery) should disable
163+
* redirects to prevent SSRF bypass via open redirectors.
164+
*
165+
* <p><strong>Note for implementors:</strong> The default implementation is a no-op
166+
* that silently ignores the {@code follow} argument. Third-party {@link A2AHttpClient}
167+
* implementations MUST override this method to honour the setting; otherwise
168+
* {@code followRedirects(false)} calls have no effect and redirects will still
169+
* be followed, bypassing SSRF protection.
170+
*
171+
* @param follow {@code true} to follow redirects (default), {@code false} to disable
172+
* @return this builder for chaining
173+
*/
174+
default PostBuilder followRedirects(boolean follow) {
175+
return this;
176+
}
177+
157178
/**
158179
* Executes a synchronous POST request.
159180
*

‎http-client/src/main/java/org/a2aproject/sdk/client/http/JdkA2AHttpClient.java‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@
5353
public class JdkA2AHttpClient implements A2AHttpClient {
5454

5555
private final HttpClient httpClient;
56+
private volatile @Nullable HttpClient noRedirectClient;
5657

5758
/**
5859
* Creates a new JDK-based HTTP client.
@@ -330,15 +331,39 @@ public A2AHttpResponse delete() throws IOException, InterruptedException {
330331

331332
}
332333

334+
private HttpClient getNoRedirectClient() {
335+
HttpClient local = noRedirectClient;
336+
if (local == null) {
337+
synchronized (this) {
338+
local = noRedirectClient;
339+
if (local == null) {
340+
local = HttpClient.newBuilder()
341+
.version(HttpClient.Version.HTTP_2)
342+
.followRedirects(HttpClient.Redirect.NEVER)
343+
.build();
344+
noRedirectClient = local;
345+
}
346+
}
347+
}
348+
return local;
349+
}
350+
333351
private class JdkPostBuilder extends JdkBuilder<PostBuilder> implements A2AHttpClient.PostBuilder {
334352
String body = "";
353+
boolean followRedirects = true;
335354

336355
@Override
337356
public PostBuilder body(String body) {
338357
this.body = body;
339358
return self();
340359
}
341360

361+
@Override
362+
public PostBuilder followRedirects(boolean follow) {
363+
this.followRedirects = follow;
364+
return self();
365+
}
366+
342367
private HttpRequest.Builder createRequestBuilder(boolean SSE) throws IOException {
343368
HttpRequest.Builder builder = super.createRequestBuilder()
344369
.POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8));
@@ -348,12 +373,16 @@ private HttpRequest.Builder createRequestBuilder(boolean SSE) throws IOException
348373
return builder;
349374
}
350375

376+
private HttpClient resolveClient() {
377+
return followRedirects ? httpClient : getNoRedirectClient();
378+
}
379+
351380
@Override
352381
public A2AHttpResponse post() throws IOException, InterruptedException {
353382
HttpRequest request = createRequestBuilder(false)
354383
.build();
355384
HttpResponse<String> response =
356-
httpClient.send(request, BodyHandlers.ofString(StandardCharsets.UTF_8));
385+
resolveClient().send(request, BodyHandlers.ofString(StandardCharsets.UTF_8));
357386

358387
if (response.statusCode() == HTTP_UNAUTHORIZED) {
359388
throw new IOException(A2AErrorMessages.AUTHENTICATION_FAILED,

‎http-client/src/test/java/org/a2aproject/sdk/client/http/JdkA2AHttpClientTest.java‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,52 @@ public void testConstructorRejectsNullHttpClient() {
9797
assertThrows(IllegalArgumentException.class, () -> new JdkA2AHttpClient(null), "foo");
9898
}
9999

100+
@Test
101+
public void testPostFollowRedirectsFalseDoesNotFollowRedirect() throws Exception {
102+
server = ClientAndServer.startClientAndServer(0);
103+
int port = server.getLocalPort();
104+
server.when(request().withMethod("POST").withPath("/redirect"))
105+
.respond(response()
106+
.withStatusCode(302)
107+
.withHeader("Location", "http://localhost:" + port + "/target"));
108+
server.when(request().withMethod("POST").withPath("/target"))
109+
.respond(response().withStatusCode(200).withBody("redirected"));
110+
111+
JdkA2AHttpClient client = new JdkA2AHttpClient();
112+
113+
A2AHttpResponse response = client.createPost()
114+
.url("http://localhost:" + port + "/redirect")
115+
.body("{}")
116+
.followRedirects(false)
117+
.post();
118+
119+
assertEquals(302, response.status(),
120+
"With followRedirects(false), the 302 should be returned as-is");
121+
}
122+
123+
@Test
124+
public void testPostDefaultFollowsRedirect() throws Exception {
125+
server = ClientAndServer.startClientAndServer(0);
126+
int port = server.getLocalPort();
127+
server.when(request().withMethod("POST").withPath("/redirect"))
128+
.respond(response()
129+
.withStatusCode(307)
130+
.withHeader("Location", "http://localhost:" + port + "/target"));
131+
server.when(request().withPath("/target"))
132+
.respond(response().withStatusCode(200).withBody("redirected"));
133+
134+
JdkA2AHttpClient client = new JdkA2AHttpClient();
135+
136+
A2AHttpResponse response = client.createPost()
137+
.url("http://localhost:" + port + "/redirect")
138+
.body("{}")
139+
.post();
140+
141+
assertEquals(200, response.status(),
142+
"By default, redirects should be followed");
143+
assertEquals("redirected", response.body());
144+
}
145+
100146
@Test
101147
public void testCancellationExceptionViaSubscriberOnErrorIsNotPropagated() throws Exception {
102148
AtomicReference<Throwable> capturedError = new AtomicReference<>();

‎itk/src/main/resources/application.properties‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,11 @@ quarkus.log.file.format=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n
99

1010
# Authorization is not configured in this application
1111
a2a.authorization.required=false
12+
13+
# Push notifications enabled for ITK interoperability testing
14+
a2a.push-notification.enabled=true
15+
# Push notification URL validation relaxed for CI/testing:
16+
# Allow http (ITK agents run plain HTTP on localhost)
17+
a2a.push-notification.url.allowed-schemes=https,http
18+
# Allow private/loopback targets (ITK agents listen on 127.0.0.1)
19+
a2a.push-notification.url.allow-private-network-targets=true

0 commit comments

Comments
 (0)