What Does This Do

Implements the SCA Reachability subsystem for the Java APM agent. When DD_APPSEC_SCA_ENABLED=true, the agent detects at runtime which classes and methods from vulnerable library versions are actually loaded and invoked, and reports this via app-dependencies-loaded telemetry using the RFC stateful heartbeat model.

Build - Symbol database

• New Gradle task generateScaCvesJson in dd-java-agent/appsec/build.gradle downloads GHSA enrichments from the private sca-reachability-database and bundles sca_cves.json in the agent JAR. The committed copy is used in CI (no network access required at build time). Maintainers regenerate with ./gradlew generateScaCvesJson -PrefreshSca.
• GhsaEnrichmentParser (buildSrc Kotlin): converts the GHSA enrichment format to the internal format - one record per Maven artifact, class symbols in JVM internal format (slashes). Filters to JVM language and Maven ecosystem only.

Detection - ClassFileTransformer (two-phase design)

ScaReachabilityTransformer uses a two-phase approach to keep JAR I/O off the class-loading thread:

• First load (classBeingRedefined == null): transform() only enqueues a PendingClass(className, jarURL) record and returns null immediately. No I/O on the class-loading thread. Matches the pattern used by LocationsCollectingTransformer.
• Periodic processing (processPendingClassEvents()): runs on the telemetry heartbeat thread; drains the queue, resolves artifact versions from JAR pom.properties, evaluates version ranges, reports class-level hits, and schedules method-level retransformation.
• Retransform (classBeingRedefined != null): injects ASM bytecode callbacks at vulnerable method entry points. Tradeoff: method calls during the ~10s startup window before the first heartbeat are not captured; there is no behavioral difference for class-level symbols (the only active symbols today).

Additional transformer details:

• ScaReachabilitySystem: entry point called from Agent.java by reflection (same pattern as AppSecSystem).
• ScaReachabilityCallback (bootstrap): dedup + dispatch bridge between application classloader (injected bytecode) and agent classloader (handler). Must live in bootstrap to be visible from any classloader.
• Version resolution: JAR-local pom.properties first, then java.class.path scan as fallback for aggregator artifacts (e.g. Spring Boot starters). The java.class.path scan covers standard deployments (JARs passed via -cp) on both Java 8 and 9+. Known limitation: OSGi bundle JARs and Spring Boot fat JAR nested libraries loaded via LaunchedURLClassLoader are not listed in java.class.path, so version resolution for aggregator artifacts may fail in those environments (falls back to retrying on the next heartbeat). A URLClassLoader chain walk was not viable here because AgentThreadFactory sets the context classloader to null on all agent threads.
• VersionRangeParser: evaluates GHSA version range conditions (<, <=, >=, >, =, comma-separated AND).
• performPendingRetransforms(): uses contains()+removeAll() instead of remove() inside the getAllLoadedClasses() loop so that all classloader instances of the same class are retransformed (Spring Boot creates multiple LaunchedURLClassLoader instances).

Callsite detection

ScaReachabilitySystem.findCallsite() walks the thread stack to report the application frame that called the vulnerable method, not the vulnerable method itself:

• StackWalkerFactory.INSTANCE.walk() is used for lazy stack evaluation on JDK9+ (avoids materializing the full stack array). Agent frames are pre-filtered by the walker.
• ScaStackExclusionTrie (generated from sca_stack_exclusion.trie via tries.gradle) filters intermediate library frames so wrapper libraries are skipped and client code is reported.
• Overload findCallsite(String, StackTraceElement[]) for unit-testable stack simulation.

Telemetry - RFC stateful heartbeat

• ScaReachabilityDependencyRegistry (internal-api): stateful registry for CVE state per artifact@version. registerCve() creates an entry with reached:[]; recordHit() stores the first callsite via AtomicReference.compareAndSet (first-hit-wins).
• ScaReachabilityPeriodicAction (telemetry): on each heartbeat, drains both DependencyService (new JARs) and the registry (CVE state changes), merges into one entry per dependency. Replaces DependencyPeriodicAction when SCA is enabled to avoid duplicate app-dependencies-loaded entries.
• Dependency: new nullable reachabilityMetadata field; TelemetryRequestBody.writeDependency() writes the metadata array when present.

Benchmarks

The local benchmark/ folder has been removed from dd-trace-java (see #11502). The sca variant (-Ddd.appsec.enabled=true -Ddd.appsec.sca.enabled=true) was contributed to the new apm-sdks-benchmarks implementation by @sarahchen6 in DataDog/apm-sdks-benchmarks#161, based on the variant I added here originally.

Motivation

Implements APPSEC-62260 - SCA Reachability runtime detection per the RFC.

Additional Notes

• The generateScaCvesJson Gradle plugin and the committed sca_cves.json are a temporary solution. In a future iteration the SCA symbol database will be delivered at runtime via Remote Config, at which point this plugin and the committed JSON file will be removed.

• sca_cves.json is committed to the repo because sca-reachability-database is a private repo not accessible from CI without a token. Only the maintainer runs the refresh task.

• Method-level symbols in sca_cves.json (snakeyaml load/loadAll, xstream fromXML, etc.) are manually curated for testing. The database format does not yet define method-level entries; when it does, the Gradle task will be updated and the manual entries removed.

• AbstractStackWalker.isNotDatadogTraceStackElement visibility changed from package-private to public to allow callsite filtering from the appsec module.

• sca_stack_exclusion.trie is a curated copy of the IAST exclusion trie adapted for SCA callsite detection (testing framework entries removed). The trie cannot be reused directly from IAST without a circular dependency.

• Known limitation - aggregator artifacts in OSGi / Spring Boot fat JARs: version resolution for aggregator artifacts (e.g. spring-boot-starter-web) relies solely on java.class.path, which only covers JARs present on the standard classpath at JVM startup. OSGi bundle JARs and JARs nested inside a Spring Boot fat JAR (loaded by LaunchedURLClassLoader) are not listed there. In those environments, the version fallback for aggregator artifacts may return null and the CVE will be retried on the next heartbeat. Direct artifacts (those whose own JAR contains pom.properties) are unaffected.

• The ScaReachabilitySmokeTest extends AbstractAppSecServerSmokeTest and remains Groovy until that base class is migrated to Java.

Contributor Checklist

• Format the title according to the contribution guidelines
• Assign the type: and (comp: or inst:) labels in addition to any other useful labels
• Avoid using close, fix, or any linking keywords when referencing an issue
  Use solves instead, and assign the PR milestone to the issue
• Update the CODEOWNERS file on source file addition, migration, or deletion
• Update public documentation with any new configuration flags or behaviors

Jira ticket: APPSEC-62260

Note: Once your PR is ready to merge, add it to the merge queue by commenting /merge. /merge -c cancels the queue request. /merge -f --reason "reason" skips all merge queue checks; please use this judiciously, as some checks do not run at the PR-level. For more information, see this doc.