…rting (#17092)

APPSEC-61908

## Summary
- Introduces `DependencyEntry` and `ReachabilityMetadata` dataclasses in `ddtrace/internal/telemetry/dependency.py` to replace the flat `dict[str, str]` used for `_imported_dependencies` in `TelemetryWriter`
- The new model supports optional reachability metadata on each dependency, with sent/unsent tracking and deduplication by CVE id
- Adds `attach_dependency_metadata()` method to `TelemetryWriter` for SCA to attach CVE metadata to already-reported dependencies, triggering re-reporting in the next `app-dependencies-loaded` telemetry cycle
- **No behavior change**: dependencies without metadata produce the exact same wire format as before
- **Reporting logic is identical to main**: `_report_dependencies` and `update_imported_dependencies` follow the same code path as main, the only difference is `DependencyEntry` as the internal storage type

This is the first PR in a series to implement [Runtime SCA Reachability](https://docs.google.com/document/d/1HbaI2rhOP7XtiFUUPVLivEz_BtXupu3laOs6mVgrtiA). The follow-up PR will wire the SCA detection hook to call `attach_dependency_metadata()` when `DD_APPSEC_SCA_ENABLED=true`.

## Performance benchmark

The overhead comes entirely from `DependencyEntry` dataclass construction instead of storing a plain version string. The reporting logic (`_report_dependencies`) is identical to main — no metadata scanning, no dirty-set tracking. That complexity will only be added in the future SCA PR, gated behind `DD_APPSEC_SCA_ENABLED`.

Benchmark script: https://gist.github.com/avara1986/eaa2389f4bf5ae18804772aaeb5e4f4a

### `update_imported_dependencies` (Python 3.12, 200 iterations)

| n_modules | main (median) | branch (median) | time overhead | mem overhead |
|-----------|--------------|-----------------|---------------|-------------|
| 50 | 46.5 us | 110.0 us | +137% | +47% |
| 200 | 134.1 us | 350.1 us | +161% | +46% |
| 500 | 336.6 us | 899.3 us | +167% | +48% |
| 1000 | 671.2 us | 1,738.5 us | +159% | +48% |

### `_report_dependencies` (Python 3.12, 200 iterations)

| n_modules | main (median) | branch (median) | time overhead | mem overhead |
|-----------|--------------|-----------------|---------------|-------------|
| 50 | 21.4 us | 51.1 us | +139% | +30% |
| 200 | 74.5 us | 186.3 us | +150% | +31% |
| 500 | 180.8 us | 461.2 us | +155% | +30% |
| 1000 | 378.1 us | 915.5 us | +142% | +34% |

### Per-entry memory footprint

| Type | B/entry (n=1000) |
|------|-----------------|
| `str` value (main) | 121.9 B |
| `DependencyEntry` (branch) | 274.1 B |

> **Note**: The overhead is constant per-dependency (~150 extra bytes, ~2.5x time) and comes entirely from constructing the `DependencyEntry` dataclass instead of storing a plain string. The reporting logic is identical to main. A typical application imports 50-200 dependencies, so the absolute cost is ~50-350 us per periodic tick — well within acceptable limits for a background telemetry task that runs every 10 seconds.


Co-authored-by: christophe.papazian <[email protected]>

## Description

Implements **Runtime SCA Reachability** — the tracer reports which vulnerable symbols (functions/methods in third-party libraries with known CVEs) have actually been invoked at runtime, reducing false positives from static SCA analysis.

**RFC**: https://docs.google.com/document/d/1xDw9iG6h41VCEgJGTqoJdruRaNS4pYgNifO6nhiizWA/edit?tab=t.a9gurws0d8ua

### How it works

When `DD_APPSEC_SCA_ENABLED=true`:

1. **CVE data loading** — At tracer startup, reads `_cve_data.json` containing vulnerability targets (symbol + CVE + version constraint). Filters against installed packages.
2. **Runtime instrumentation** — For each applicable CVE target, applies bytecode injection (`inject_hook`) to the vulnerable function. Supports both eager (already-imported modules) and lazy (via `ModuleWatchdog` for deferred imports).
3. **CVE registration** — Immediately registers all applicable CVEs on their dependencies with `reached: []` in the telemetry `app-dependencies-loaded` payload. The backend knows which CVEs apply before any symbol is hit.
4. **Reachability detection** — When an instrumented function executes, the hook captures the caller's file path, method name, and line number, then attaches it to the CVE's `reached` array. Only the first occurrence is reported per CVE (RFC: "reporting a single occurrence is sufficient").
5. **Telemetry reporting** — On each heartbeat (default 60s), dependencies with new reachability data are re-reported with all their metadata via `app-dependencies-loaded`.

### Telemetry payload (RFC v3)

```json
{
  "request_type": "app-dependencies-loaded",
  "payload": {
    "dependencies": [
      {
        "name": "requests",
        "version": "2.31.0",
        "metadata": [
          {
            "type": "reachability",
            "value": "{\"id\":\"CVE-2024-35195\",\"reached\":[{\"path\":\"myapp/views.py\",\"method\":\"handle_request\",\"line\":42}]}"
          }
        ]
      }
    ]
  }
}
```

Before any symbol is hit, CVEs are reported with `"reached":[]`. When a symbol executes, the first caller info is added to the `reached` array.

## Performance

Benchmark: `scripts/perf_bench_heartbeat_cycles.py`

Measures `collect_report()` execution time per heartbeat cycle under different scenarios. The overhead is paid only in the background telemetry thread (every 60s), never in user request paths.

- **SCA OFF (main)**: baseline on `main` branch — old `update_imported_dependencies()` path, no `DependencyTracker`, no re-report scan
- **SCA OFF**: this branch with `DD_APPSEC_SCA_ENABLED=false` — new `DependencyTracker` with `metadata=None`, re-report scan skipped
- **SCA ON**: this branch with `DD_APPSEC_SCA_ENABLED=true` — new `DependencyTracker` with `metadata=[]`
- **Overhead**: `(SCA ON − SCA OFF) / SCA OFF`

### 1,000 dependencies (typical large application)

| Heartbeat Cycle | SCA OFF (main) | SCA OFF | SCA ON | Overhead |
|---|---|---|---|---|
| First heartbeat (all new) | 4.56ms | 4.63ms | 5.10ms | **+10.1%** |
| Idle (nothing to report) | 0.2us | 72.2us | 239.6us | **+231.8%** |
| CVE registration (100 CVEs, reached=[]) | 0.3us | 73.5us | 1.20ms | **+1527.5%** |
| SCA hits (100 hits on 50 deps) | 0.3us | 73.7us | 1.44ms | **+1857.1%** |

### 10,000 dependencies (extreme scale)

| Heartbeat Cycle | SCA OFF (main) | SCA OFF | SCA ON | Overhead |
|---|---|---|---|---|
| First heartbeat (all new) | 53.15ms | 57.18ms | 62.12ms | **+8.6%** |
| Idle (nothing to report) | 0.3us | 742.6us | 2.20ms | **+195.7%** |
| CVE registration (1,000 CVEs, reached=[]) | 0.3us | 720.7us | 13.51ms | **+1774.4%** |
| SCA hits (1,000 hits on 500 deps) | 0.3us | 718.9us | 15.56ms | **+2064.2%** |

### Payload size

| Scenario (1,000 deps) | Entries | Size |
|---|---|---|
| First heartbeat SCA OFF | 1,000 | 62 KB |
| First heartbeat SCA ON | 1,000 | 62 KB |
| CVE registration (100 CVEs) | 50 | 10 KB |
| SCA hits (100 hits) | 50 | 16 KB |

### Memory overhead

| Scenario (1,000 deps) | SCA OFF | SCA ON | Delta |
|---|---|---|---|
| Idle heartbeat | 155.3 KB | 192.5 KB | +37.2 KB |
| CVE registration (100 CVEs) | 136.4 KB | 205.8 KB | +69.4 KB |
| SCA hits (100 hits) | 136.2 KB | 208.5 KB | +72.3 KB |

> **Note on overhead**: The percentage overhead for idle, CVE registration, and SCA hits appears very high because the SCA OFF baseline includes mock/benchmark harness overhead (~72us at 1K deps) that dominates the measurement. In absolute terms:
>
> - **First heartbeat**: nearly identical across all three columns (4.56ms → 4.63ms → 5.10ms at 1K deps), confirming the `DependencyTracker` refactor adds **minimal overhead** to initial dependency discovery.
> - **Idle heartbeat with SCA OFF**: ~72us includes benchmark mock overhead; measured independently at ~8us (lock acquisition + `get_newly_imported_modules()` + lazy config check). The re-report scan is **completely skipped** when SCA is disabled.
> - **SCA ON worst case** at 1,000 dependencies: **1.44ms per 60s heartbeat** — 0.002% of the cycle.
> - **SCA ON worst case** at 10,000 dependencies with 1,000 CVEs: **16ms** — 0.027% of the heartbeat interval.
>
> All overhead runs entirely in the background telemetry thread and does not affect user request latency.

### SLO benchmark

A CI-integrated benchmark suite is available at `benchmarks/telemetry_dependencies/` with 8 scenarios covering first/idle/cve/hits phases at 100 and 1,000 dependencies. It is triggered automatically when `ddtrace/internal/telemetry/dependency*.py` or `ddtrace/appsec/sca/*` files change and compares performance between the base branch and this PR.

## Risks

- **Bytecode injection**: Uses the existing `inject_hook` infrastructure from dd-trace-py. The hook is exception-safe (wrapped in try/except) and never raises in user code.
- **Memory**: `DependencyEntry` objects add ~150 bytes per dependency vs plain strings. At 1,000 deps this is ~150KB total — negligible.
- **Lock contention**: The `DependencyTracker._lock` is held briefly during `attach_metadata` calls from the SCA hook. After the first hit per CVE (max reached=1), subsequent hook invocations short-circuit before any lock acquisition.

## Additional Notes

- Merge this PR first: DataDog/datadog-lambda-python#761
- Previous model PR benchmarks: #17092
- The static CVE JSON (`_cve_data.json`) will be replaced by Remote Config in the long-term solution

Co-authored-by: alberto.vara <[email protected]>

## Description

Implements **Runtime SCA Reachability** — the tracer reports which vulnerable symbols (functions/methods in third-party libraries with known CVEs) have actually been invoked at runtime, reducing false positives from static SCA analysis.

**RFC**: https://docs.google.com/document/d/1xDw9iG6h41VCEgJGTqoJdruRaNS4pYgNifO6nhiizWA/edit?tab=t.a9gurws0d8ua

### How it works

When `DD_APPSEC_SCA_ENABLED=true`:

1. **CVE data loading** — At tracer startup, reads `_cve_data.json` containing vulnerability targets (symbol + CVE + version constraint). Filters against installed packages.
2. **Runtime instrumentation** — For each applicable CVE target, applies bytecode injection (`inject_hook`) to the vulnerable function. Supports both eager (already-imported modules) and lazy (via `ModuleWatchdog` for deferred imports).
3. **CVE registration** — Immediately registers all applicable CVEs on their dependencies with `reached: []` in the telemetry `app-dependencies-loaded` payload. The backend knows which CVEs apply before any symbol is hit.
4. **Reachability detection** — When an instrumented function executes, the hook captures the caller's file path, method name, and line number, then attaches it to the CVE's `reached` array. Only the first occurrence is reported per CVE (RFC: "reporting a single occurrence is sufficient").
5. **Telemetry reporting** — On each heartbeat (default 60s), dependencies with new reachability data are re-reported with all their metadata via `app-dependencies-loaded`.

### Telemetry payload (RFC v3)

```json
{
  "request_type": "app-dependencies-loaded",
  "payload": {
    "dependencies": [
      {
        "name": "requests",
        "version": "2.31.0",
        "metadata": [
          {
            "type": "reachability",
            "value": "{\"id\":\"CVE-2024-35195\",\"reached\":[{\"path\":\"myapp/views.py\",\"method\":\"handle_request\",\"line\":42}]}"
          }
        ]
      }
    ]
  }
}
```

Before any symbol is hit, CVEs are reported with `"reached":[]`. When a symbol executes, the first caller info is added to the `reached` array.

## Performance

Benchmark: `scripts/perf_bench_heartbeat_cycles.py`

Measures `collect_report()` execution time per heartbeat cycle under different scenarios. The overhead is paid only in the background telemetry thread (every 60s), never in user request paths.

- **SCA OFF (main)**: baseline on `main` branch — old `update_imported_dependencies()` path, no `DependencyTracker`, no re-report scan
- **SCA OFF**: this branch with `DD_APPSEC_SCA_ENABLED=false` — new `DependencyTracker` with `metadata=None`, re-report scan skipped
- **SCA ON**: this branch with `DD_APPSEC_SCA_ENABLED=true` — new `DependencyTracker` with `metadata=[]`
- **Overhead**: `(SCA ON − SCA OFF) / SCA OFF`

### 1,000 dependencies (typical large application)

| Heartbeat Cycle | SCA OFF (main) | SCA OFF | SCA ON | Overhead |
|---|---|---|---|---|
| First heartbeat (all new) | 4.56ms | 4.63ms | 5.10ms | **+10.1%** |
| Idle (nothing to report) | 0.2us | 72.2us | 239.6us | **+231.8%** |
| CVE registration (100 CVEs, reached=[]) | 0.3us | 73.5us | 1.20ms | **+1527.5%** |
| SCA hits (100 hits on 50 deps) | 0.3us | 73.7us | 1.44ms | **+1857.1%** |

### 10,000 dependencies (extreme scale)

| Heartbeat Cycle | SCA OFF (main) | SCA OFF | SCA ON | Overhead |
|---|---|---|---|---|
| First heartbeat (all new) | 53.15ms | 57.18ms | 62.12ms | **+8.6%** |
| Idle (nothing to report) | 0.3us | 742.6us | 2.20ms | **+195.7%** |
| CVE registration (1,000 CVEs, reached=[]) | 0.3us | 720.7us | 13.51ms | **+1774.4%** |
| SCA hits (1,000 hits on 500 deps) | 0.3us | 718.9us | 15.56ms | **+2064.2%** |

### Payload size

| Scenario (1,000 deps) | Entries | Size |
|---|---|---|
| First heartbeat SCA OFF | 1,000 | 62 KB |
| First heartbeat SCA ON | 1,000 | 62 KB |
| CVE registration (100 CVEs) | 50 | 10 KB |
| SCA hits (100 hits) | 50 | 16 KB |

### Memory overhead

| Scenario (1,000 deps) | SCA OFF | SCA ON | Delta |
|---|---|---|---|
| Idle heartbeat | 155.3 KB | 192.5 KB | +37.2 KB |
| CVE registration (100 CVEs) | 136.4 KB | 205.8 KB | +69.4 KB |
| SCA hits (100 hits) | 136.2 KB | 208.5 KB | +72.3 KB |

> **Note on overhead**: The percentage overhead for idle, CVE registration, and SCA hits appears very high because the SCA OFF baseline includes mock/benchmark harness overhead (~72us at 1K deps) that dominates the measurement. In absolute terms:
>
> - **First heartbeat**: nearly identical across all three columns (4.56ms → 4.63ms → 5.10ms at 1K deps), confirming the `DependencyTracker` refactor adds **minimal overhead** to initial dependency discovery.
> - **Idle heartbeat with SCA OFF**: ~72us includes benchmark mock overhead; measured independently at ~8us (lock acquisition + `get_newly_imported_modules()` + lazy config check). The re-report scan is **completely skipped** when SCA is disabled.
> - **SCA ON worst case** at 1,000 dependencies: **1.44ms per 60s heartbeat** — 0.002% of the cycle.
> - **SCA ON worst case** at 10,000 dependencies with 1,000 CVEs: **16ms** — 0.027% of the heartbeat interval.
>
> All overhead runs entirely in the background telemetry thread and does not affect user request latency.

### SLO benchmark

A CI-integrated benchmark suite is available at `benchmarks/telemetry_dependencies/` with 8 scenarios covering first/idle/cve/hits phases at 100 and 1,000 dependencies. It is triggered automatically when `ddtrace/internal/telemetry/dependency*.py` or `ddtrace/appsec/sca/*` files change and compares performance between the base branch and this PR.

## Risks

- **Bytecode injection**: Uses the existing `inject_hook` infrastructure from dd-trace-py. The hook is exception-safe (wrapped in try/except) and never raises in user code.
- **Memory**: `DependencyEntry` objects add ~150 bytes per dependency vs plain strings. At 1,000 deps this is ~150KB total — negligible.
- **Lock contention**: The `DependencyTracker._lock` is held briefly during `attach_metadata` calls from the SCA hook. After the first hit per CVE (max reached=1), subsequent hook invocations short-circuit before any lock acquisition.

## Additional Notes

- Merge this PR first: DataDog/datadog-lambda-python#761
- Previous model PR benchmarks: #17092
- The static CVE JSON (`_cve_data.json`) will be replaced by Remote Config in the long-term solution

Co-authored-by: alberto.vara <[email protected]>

## Description

Implements **Runtime SCA Reachability** — the tracer reports which vulnerable symbols (functions/methods in third-party libraries with known CVEs) have actually been invoked at runtime, reducing false positives from static SCA analysis.

**RFC**: https://docs.google.com/document/d/1xDw9iG6h41VCEgJGTqoJdruRaNS4pYgNifO6nhiizWA/edit?tab=t.a9gurws0d8ua

### How it works

When `DD_APPSEC_SCA_ENABLED=true`:

1. **CVE data loading** — At tracer startup, reads `_cve_data.json` containing vulnerability targets (symbol + CVE + version constraint). Filters against installed packages.
2. **Runtime instrumentation** — For each applicable CVE target, applies bytecode injection (`inject_hook`) to the vulnerable function. Supports both eager (already-imported modules) and lazy (via `ModuleWatchdog` for deferred imports).
3. **CVE registration** — Immediately registers all applicable CVEs on their dependencies with `reached: []` in the telemetry `app-dependencies-loaded` payload. The backend knows which CVEs apply before any symbol is hit.
4. **Reachability detection** — When an instrumented function executes, the hook captures the caller's file path, method name, and line number, then attaches it to the CVE's `reached` array. Only the first occurrence is reported per CVE (RFC: "reporting a single occurrence is sufficient").
5. **Telemetry reporting** — On each heartbeat (default 60s), dependencies with new reachability data are re-reported with all their metadata via `app-dependencies-loaded`.

### Telemetry payload (RFC v3)

```json
{
  "request_type": "app-dependencies-loaded",
  "payload": {
    "dependencies": [
      {
        "name": "requests",
        "version": "2.31.0",
        "metadata": [
          {
            "type": "reachability",
            "value": "{\"id\":\"CVE-2024-35195\",\"reached\":[{\"path\":\"myapp/views.py\",\"method\":\"handle_request\",\"line\":42}]}"
          }
        ]
      }
    ]
  }
}
```

Before any symbol is hit, CVEs are reported with `"reached":[]`. When a symbol executes, the first caller info is added to the `reached` array.

## Performance

Benchmark: `scripts/perf_bench_heartbeat_cycles.py`

Measures `collect_report()` execution time per heartbeat cycle under different scenarios. The overhead is paid only in the background telemetry thread (every 60s), never in user request paths.

- **SCA OFF (main)**: baseline on `main` branch — old `update_imported_dependencies()` path, no `DependencyTracker`, no re-report scan
- **SCA OFF**: this branch with `DD_APPSEC_SCA_ENABLED=false` — new `DependencyTracker` with `metadata=None`, re-report scan skipped
- **SCA ON**: this branch with `DD_APPSEC_SCA_ENABLED=true` — new `DependencyTracker` with `metadata=[]`
- **Overhead**: `(SCA ON − SCA OFF) / SCA OFF`

### 1,000 dependencies (typical large application)

| Heartbeat Cycle | SCA OFF (main) | SCA OFF | SCA ON | Overhead |
|---|---|---|---|---|
| First heartbeat (all new) | 4.56ms | 4.63ms | 5.10ms | **+10.1%** |
| Idle (nothing to report) | 0.2us | 72.2us | 239.6us | **+231.8%** |
| CVE registration (100 CVEs, reached=[]) | 0.3us | 73.5us | 1.20ms | **+1527.5%** |
| SCA hits (100 hits on 50 deps) | 0.3us | 73.7us | 1.44ms | **+1857.1%** |

### 10,000 dependencies (extreme scale)

| Heartbeat Cycle | SCA OFF (main) | SCA OFF | SCA ON | Overhead |
|---|---|---|---|---|
| First heartbeat (all new) | 53.15ms | 57.18ms | 62.12ms | **+8.6%** |
| Idle (nothing to report) | 0.3us | 742.6us | 2.20ms | **+195.7%** |
| CVE registration (1,000 CVEs, reached=[]) | 0.3us | 720.7us | 13.51ms | **+1774.4%** |
| SCA hits (1,000 hits on 500 deps) | 0.3us | 718.9us | 15.56ms | **+2064.2%** |

### Payload size

| Scenario (1,000 deps) | Entries | Size |
|---|---|---|
| First heartbeat SCA OFF | 1,000 | 62 KB |
| First heartbeat SCA ON | 1,000 | 62 KB |
| CVE registration (100 CVEs) | 50 | 10 KB |
| SCA hits (100 hits) | 50 | 16 KB |

### Memory overhead

| Scenario (1,000 deps) | SCA OFF | SCA ON | Delta |
|---|---|---|---|
| Idle heartbeat | 155.3 KB | 192.5 KB | +37.2 KB |
| CVE registration (100 CVEs) | 136.4 KB | 205.8 KB | +69.4 KB |
| SCA hits (100 hits) | 136.2 KB | 208.5 KB | +72.3 KB |

> **Note on overhead**: The percentage overhead for idle, CVE registration, and SCA hits appears very high because the SCA OFF baseline includes mock/benchmark harness overhead (~72us at 1K deps) that dominates the measurement. In absolute terms:
>
> - **First heartbeat**: nearly identical across all three columns (4.56ms → 4.63ms → 5.10ms at 1K deps), confirming the `DependencyTracker` refactor adds **minimal overhead** to initial dependency discovery.
> - **Idle heartbeat with SCA OFF**: ~72us includes benchmark mock overhead; measured independently at ~8us (lock acquisition + `get_newly_imported_modules()` + lazy config check). The re-report scan is **completely skipped** when SCA is disabled.
> - **SCA ON worst case** at 1,000 dependencies: **1.44ms per 60s heartbeat** — 0.002% of the cycle.
> - **SCA ON worst case** at 10,000 dependencies with 1,000 CVEs: **16ms** — 0.027% of the heartbeat interval.
>
> All overhead runs entirely in the background telemetry thread and does not affect user request latency.

### SLO benchmark

A CI-integrated benchmark suite is available at `benchmarks/telemetry_dependencies/` with 8 scenarios covering first/idle/cve/hits phases at 100 and 1,000 dependencies. It is triggered automatically when `ddtrace/internal/telemetry/dependency*.py` or `ddtrace/appsec/sca/*` files change and compares performance between the base branch and this PR.

## Risks

- **Bytecode injection**: Uses the existing `inject_hook` infrastructure from dd-trace-py. The hook is exception-safe (wrapped in try/except) and never raises in user code.
- **Memory**: `DependencyEntry` objects add ~150 bytes per dependency vs plain strings. At 1,000 deps this is ~150KB total — negligible.
- **Lock contention**: The `DependencyTracker._lock` is held briefly during `attach_metadata` calls from the SCA hook. After the first hit per CVE (max reached=1), subsequent hook invocations short-circuit before any lock acquisition.

## Additional Notes

- Merge this PR first: DataDog/datadog-lambda-python#761
- Previous model PR benchmarks: #17092
- The static CVE JSON (`_cve_data.json`) will be replaced by Remote Config in the long-term solution

Co-authored-by: alberto.vara <[email protected]>