dd-native-appsec-js
Node.js bindings for libddwaf.
Supported platforms
This package supports the following platforms:
- Node.js version: 18 and higher
- Operating Systems:
- macOS 14.2.1 and higher (the minimum target of the bundled libddwaf)
- x64
- arm64
- Windows
- x86
- x64
- Linux
- x64 with glibc
- x64 with musl
- arm64
- macOS 14.2.1 and higher (the minimum target of the bundled libddwaf)
Therefore, unsupported platforms include:
- Linux x86
- arm32
- AIX
- PPC
Please feel free to contact support if you would like to request support for a new platform.
Migrating to native-appsec 12
This version bundles libddwaf 2.2.0 and changes the evaluation API.
context.run(data, timeout) now receives an address map directly. The previous
{ persistent, ephemeral } envelope is no longer supported. For scoped data,
create a subcontext with context.createSubcontext(), call its run(data, timeout)
method, and dispose it in finally. A subcontext inherits parent data and keeps
its own data and evaluation effects local. It can outlive the parent.
createContext() returns null when there is no active ruleset, including after
removing all configurations. A rejected same-path replacement can also remove
the previous configuration; callers must check diagnostics and configuration
paths when deciding whether to restore a fallback ruleset. Rejected map configurations
are fully removed from the builder, including their paths and any partially loaded
content. Top-level parsing failures are reported in diagnostics.error.
If a rebuild produces no handle, new contexts also return null; the binding
does not distinguish an empty ruleset from other build failures or retain a stale handle.
Durations are nanoseconds; timeout inputs are microseconds. Actions are a map keyed by action type.
Responsibilities
| native-appsec | dd-trace-js |
|---|---|
| Native handles, allocators, finalizers and safe marshalling | Request and operation lifetimes, including explicit disposal |
| Context and subcontext evaluation primitives | Persistent/scoped input routing, evaluation order and shared timeout budgets |
| Raw results, diagnostics and truncation measurements | Result aggregation, blocking, reporting and telemetry |
| Configuration binding and argument validation | Remote Config orchestration, fallback policy and known-address filtering |
The dd-trace-js dependency upgrade must ship with the companion API migration. Mixed persistent and scoped evaluations need explicit result aggregation and a shared time budget in the tracer. The native binding does not infer those policies.
Conversion and configuration limits
Evaluation data is limited to 4096 bytes per string, 256 entries per container, and 20 levels of nesting. String truncation preserves complete UTF-8 code points. Truncation metrics report original sizes. dd-trace-js owns exporting those measurements.
Configuration containers are not subject to the request size limit. libddwaf 2.1's large-container APIs support configuration arrays and maps beyond 65535 entries.
Obfuscator configuration is passed directly to libddwaf. The binding reports the builder result and diagnostics without additional regex validation.