docs(appsec): add AppSec developer reference docs and module AGENTS.md files by jandro996 · Pull Request #11454 · DataDog/dd-trace-java

jandro996 · 2026-05-25T10:55:49Z

Summary

Adds docs/appsec/ with six reference documents: blocking patterns per framework, WAF API reference, IG event wiring checklist, multipart file content reading, RASP CSI pattern, and multipart framework invariants (Jersey/RESTEasy/Jetty/GlassFish)
Adds lean AGENTS.md files in netty-4.1, tomcat-appsec, akka-http, jetty-appsec, vertx-web, undertow, and the appsec module - each pointing to the extended docs
Updates top-level AGENTS.md with an AppSec entry in the index table

No functional code changes.

…d files Adds docs/appsec/ with six reference documents covering blocking patterns, WAF API, IG event wiring, file content reading, RASP CSI, and multipart framework invariants. Adds lean AGENTS.md files in netty-4.1, tomcat-appsec, akka-http, jetty-appsec, vertx-web, undertow, and the appsec module pointing to the extended docs.

dd-octo-sts · 2026-05-25T11:11:40Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Startup Time

Scenario	This PR	master	Change
insecure-bank / iast	13,956 ms	13,932 ms	+0.2%
insecure-bank / tracing	12,957 ms	13,015 ms	-0.4%
petclinic / appsec	16,564 ms	16,400 ms	+1.0%
petclinic / iast	16,435 ms	16,612 ms	-1.1%
petclinic / profiling	16,368 ms	16,448 ms	-0.5%
petclinic / tracing	15,796 ms	16,000 ms	-1.3%

Commit: 44bea27f · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

smola

A few comments. A lot of things here do need documentation but:

We should avoid large snippets of code copied to agent guidance. They'll go out of sync. Just use paths to the relevant files.
A lot of guidance very specific to a single instrumentation or class is better handled by comments in the relevant code, not as general guidance. When you're not working in that file, they are noise. And you risk missing the doc when you're actually working in the file.
Some things should be tests, not agent guidance.

smola · 2026-05-25T14:32:09Z

+
+## Adding a new WAF address: 4-file checklist
+
+Every new WAF address requires changes in exactly 4 files. Missing any one causes a silent no-op:


Missing any one causes a silent no-op -> Maybe we could add a test that checks all these 4 files are coherent in their registered addresses?

Then we wouldn't need to document it at all. If you miss them, you get a test error explaining the issue.

smola · 2026-05-25T14:33:26Z

+}
+```
+
+The ID must be unique and sequential. Check the last used ID before assigning.


Could we add a test for this instead?

smola · 2026-05-25T14:34:46Z

+### 1. `Events.java` — declare the event type
+
+```java
+static final int REQUEST_FILES_CONTENT_ID = 31;  // unique, increment from last used


This snippet will easily go out of date. I think agents will pick up the pattern just correctly if you say here that the event type must be declared in Events.java (maybe use full path).

smola · 2026-05-25T14:35:51Z

+    new Address<>("server.request.body.files_content");
+```
+
+Also add it to the `fromString()` switch.


Can we add a test that verifies this is done correctly, instead of documenting it?

smola · 2026-05-25T14:37:07Z

+All handlers follow the same retry-on-expiry pattern:
+
+```java
+private Flow<Void> onRequestFilesContent(RequestContext ctx_, List<String> filesContent) {


Ideally we shouldn't have this big snippet in the docs. It'll get out of sync. I'm sure agents will pick up the pattern from the surrounding context.

smola · 2026-05-25T14:44:20Z

@@ -0,0 +1,168 @@
+# Multipart AppSec — Framework-Specific Patterns


All or most of this should be comments right in the instrumentation code or closer to the relevant code.

smola · 2026-05-25T14:46:38Z

+
+## Do not extract filenames callback dispatch into `UnmarshallerHelpers`
+
+Extracting the `requestFilesFilenames` callback dispatch into a shared helper method in


Which problems does it cause? Unless more detail is given, this risks becoming cargo cult and nobody remembers why we do it.

smola · 2026-05-25T14:47:20Z

+
+## Jetty 8.x: no `getSubmittedFileName()`, manual parsing required
+
+`Part.getSubmittedFileName()` (Servlet 3.1) is not available in Jetty 8.x (Servlet 3.0). Filenames


Better documneted in the code, not here.

smola · 2026-05-25T14:48:27Z

@@ -0,0 +1,286 @@
+# WAF API Reference — libddwaf-java
+
+Reference for the `libddwaf-java` binding used by the AppSec module. Based on libddwaf-java v1.30.0 / libddwaf v1.30.0.


Link github.com/datadog/libddwaf-java here. I'll help agents accessing its source code.

smola · 2026-05-25T14:49:16Z

+```
+
+**Values used in dd-trace-java** (see `AppSecSystem` / `WafInitialization`):
+- `maxDepth = 20`


Let's not copy values here, it'll go out of sync. Referencing the path to the relevant files is enough.

Remove Vert.x sections (pending #11268) and Jetty 8.x/9.4 sections (pending #10988) from docs and AGENTS.md files. Content will be added once the respective PRs are merged.

datadog-official · 2026-05-27T09:23:20Z

✨ Fix all issues with BitsAI

⚠️ Warnings

🚦 7 Pipeline jobs failed

DataDog/apm-reliability/dd-trace-java | spotless

🔧 Fix in code (Fix with Cursor).
Spotless check failed due to format violations in src/test/groovy/com/datadog/appsec/gateway/GatewayBridgeIGRegistrationSpecification.groovy.

DataDog/apm-reliability/dd-trace-java | test_base: [11, 4/4]

🔧 Fix in code (Fix with Cursor).
20 failed tests. Error: org.codehaus.groovy.runtime.typehandling.GroovyCastException at GatewayBridgeIGRegistrationSpecification.groovy:63

DataDog/apm-reliability/dd-trace-java | test_base: [21, 4/4]

🔧 Fix in code (Fix with Cursor).
20 failed tests due to GroovyCastException at GatewayBridgeIGRegistrationSpecification.groovy:63 while verifying event registrations.

View all 7 failed jobs.

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 44bea27 | Docs | Datadog PR Page | Give us feedback!}

- ig-events.md: replace large code snippets with file path references (Events.java, KnownAddresses.java, GatewayBridge handler pattern); remove instanceCount section (test is self-explanatory); remove @RequiresRequestContext code snippets, keep rule as prose; remove Undertow section (moved to code comment in instrumentation); remove Akka HTTP section (already in akka-http/AGENTS.md) - multipart-frameworks.md: remove framework-specific sections (Jersey dual-module note, RESTEasy case-insensitive lookup, Content-Disposition parser table, try-with-resources, GlassFish no-reflection) that belong as code comments next to the relevant code; keep cross-cutting patterns (reflection cache, per-part try/catch, three-callback ordering, Servlet tryBlock ordering) - waf-api.md: add link to libddwaf-java repo; replace hardcoded Limits values with references to WafInitialization.java / AppSecSystem.java - akka-http/AGENTS.md: add WHY to UnmarshallerHelpers rule (filenames callback silently skipped in Route 2 when body triggered blocking) - Undertow MultiPartUploadHandlerInstrumentation: add comment explaining why t == null guard must precede tryCommitBlockingResponse

…ecification For every entry in IGAppSecEventDependencies.DATA_DEPENDENCIES, verify that subscribing to that address causes all its associated events to be registered via registerCallback() in GatewayBridge.init(). This catches the common mistake of adding a DATA_DEPENDENCIES entry without the matching registerCallback() call inside an additionalIGEvents.contains() guard. The test error message names the missing event and the expected fix. Also update appsec/AGENTS.md to reference this test and KnownAddressesSpecificationForkedTest so the checklist explains what each test covers and what it does not.

jandro996 added type: documentation tag: no release notes Changes to exclude from release notes comp: asm waf Application Security Management (WAF) labels May 25, 2026

smola reviewed May 25, 2026

View reviewed changes

docs(appsec): remove content based on unmerged PRs

367690b

Remove Vert.x sections (pending #11268) and Jetty 8.x/9.4 sections (pending #10988) from docs and AGENTS.md files. Content will be added once the respective PRs are merged.

jandro996 added 2 commits May 27, 2026 12:24


		## Adding a new WAF address: 4-file checklist

		Every new WAF address requires changes in exactly 4 files. Missing any one causes a silent no-op:

		@@ -0,0 +1,168 @@
		# Multipart AppSec — Framework-Specific Patterns


		## Do not extract filenames callback dispatch into `UnmarshallerHelpers`

		Extracting the `requestFilesFilenames` callback dispatch into a shared helper method in


		## Jetty 8.x: no `getSubmittedFileName()`, manual parsing required

		`Part.getSubmittedFileName()` (Servlet 3.1) is not available in Jetty 8.x (Servlet 3.0). Filenames

		@@ -0,0 +1,286 @@
		# WAF API Reference — libddwaf-java

		Reference for the `libddwaf-java` binding used by the AppSec module. Based on libddwaf-java v1.30.0 / libddwaf v1.30.0.

Conversation

jandro996 commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

dd-octo-sts Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

smola left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

datadog-official Bot commented May 27, 2026 • edited by datadog-datadog-prod-us1 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jandro996 commented May 25, 2026 •

edited

Loading

dd-octo-sts Bot commented May 25, 2026 •

edited

Loading

datadog-official Bot commented May 27, 2026 •

edited by datadog-datadog-prod-us1 Bot

Loading