# https://github.com/newrelic/csec-node-agent Project Manual

Generated at: 2026-06-17 19:06:26 UTC

## Table of Contents

- [page-1](#page-1)
- [page-2](#page-2)
- [page-3](#page-3)
- [` ... `](#page-4)

<a id='page-1'></a>

## page-1

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [third_party_manifest.json](https://github.com/newrelic/csec-node-agent/blob/main/third_party_manifest.json)
- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md)
- [lib/nr-security-agent/lib/core/sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/sec-agent-constants.js)
- [lib/nr-security-agent/lib/core/event.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js)
- [lib/nr-security-agent/lib/core/commonUtils.js](https://github.com/newrelic/csec-node-agent/lib/nr-security-agent/lib/core/commonUtils.js)
- [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js)
- [lib/instrumentation-security/hooks/http/nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js)
- [lib/instrumentation-security/hooks/fs/nr-fs.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/fs/nr-fs.js)

</details>

# page-1

## Overview

The `csec-node-agent` (also referred to as the New Relic Node Security Agent) is a New Relic–maintained companion module that augments the standard `newrelic` APM agent with Interactive Application Security Testing (IAST) and Runtime Application Self-Protection (RASP) capabilities for Node.js applications. The agent runs inside the host process, hooks sensitive Node.js APIs, and forwards detected events to a companion New Relic Security Engine service.

Its high-level goals, surfaced in the [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md), include: proxy-settings support, secure-cookie security event generation, scheduled IAST scans, server/application path detection, HTTP request truncation, and integration of the agent with the broader New Relic One security workflow. The current major release line is `v3.x`; the latest tagged release is `v3.0.4` (2026-05-14), which removes the `uuid` module dependency, updates the hapi instrumentation, and bumps dev dependencies such as `protobufjs` and `fast-xml-parser` (see [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md)).

The project is in preview and contributions are governed by the CSEC Agent Contributor License Agreement as described in [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md). All feedback is contributed under the Apache License 2.0.

## Repository Architecture

The codebase is split into two cooperating layers:

1. **The Security Agent core** under `lib/nr-security-agent/`, which owns process-level state, environment capture, application-UID generation, log-file rollover, and outbound transport to the Security Engine.
2. **The Instrumentation layer** under `lib/instrumentation-security/`, which monkey-patches Node.js core modules (e.g., `http`, `fs`) and popular framework modules, generates security events, and feeds them back to the agent core via the shared `nr-security-api` package.

```mermaid
flowchart LR
    A[Host Node.js Process] --> B[instrumentation-security<br/>hooks: http, fs, ...]
    B --> C[nr-security-agent<br/>core / event builders]
    C --> D[Security Engine<br/>prevent-web service]
    D --> E[New Relic Security UI]
    C --> F[Application UUID<br/>and metadata]
    F --> B
```

Key files backing this split:

- `lib/nr-security-agent/lib/core/sec-agent-constants.js` defines the central constant set, log messages, and module identifiers used throughout the agent. Strings such as `RASP`, `IAST`, `VULNERABLE`, MIME types, the `:IAST:` separator, and step markers (`[STEP-1]…[STEP-9]`) are all centralized here (see [sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/sec-agent-constants.js)).
- `lib/nr-security-agent/lib/core/commonUtils.js` provides helpers: a UUID generator (`getUUID`) that reuses `process.env.applicationUUID` when available, a kind/host identifier mapper (`getKindIdPair`) that distinguishes HOST, CONTAINER, ECS, and POD scopes, a worker-thread capability probe (`hasWorker`), and a feature-detection helper for function generators (`runtimeSupportsFunctionGenerators`) (see [commonUtils.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/commonUtils.js)).
- `lib/nr-security-agent/lib/core/event.js` enumerates the vulnerability catalog recognized by the agent (e.g., `SQLI`, `NOSQLI`, `RCE`, `RCI`, `SSRF`, `XXE`, `CRYPTO`, `HASH`, `WEAK_RANDOM`, `REFLECTED_XSS`, `UNVALIDATED_REDIRECT`) and the mapping between detected event categories and vulnerability identifiers (see [event.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js)).

## Instrumentation and Event Generation

The instrumentation layer is event-driven. Each hook wraps a target module function, captures arguments through the NR `shim`, associates the call with the in-flight HTTP request via the request manager, and emits a security event to the API surface exposed by `nr-security-agent`.

`lib/instrumentation-security/hooks/http/nr-http.js` is the largest and most central hook. It depends on the NR `shim`, `request-ip`, `unescape-js`, `content-type`, `sec-utils`, and the request manager. It inspects incoming request headers (including `NR-CSEC-TRACING-DATA`), classifies content types, and routes detected issues to `API.generateSecEvent` / `API.sendEvent`. The `self-test` flag lets the agent verify that the security pipeline is alive end-to-end (see [nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js)).

`lib/instrumentation-security/hooks/fs/nr-fs.js` instruments file-system calls. It maintains a list (`functionProbableToFI`) of file operations that may indicate file-integrity violations, dynamically extending it with `writeFileSync` on Node.js >19. The wrapper builds a security-metadata object via `securityMetaData.getSecurityMetadata`, generates a sec event for `copyFile`/`rename` and the main call, and forwards it through the same `API.sendEvent` pipeline (see [nr-fs.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/fs/nr-fs.js)).

The shared event vocabulary is defined in `lib/instrumentation-security/core/event-constants.js`. It exposes `EVENT_TYPE` (covering `SYSTEM_COMMAND`, `SYSTEM_EXIT`, `FILE_OPERATION`, `FILE_INTEGRITY`, `SQL_DB_COMMAND`, `NOSQL_DB_COMMAND`, `HTTP_REQUEST`, `CODE_INJECTION`, `XXE`, `HASH`, `RANDOM`, `UNVALIDATED_REDIRECT`, `REFLECTED_XSS`, `XPATH`, `LDAP`, `SECURE_COOKIE`, `TRUSTBOUNDARY`, `CRYPTO`) and a parallel `EVENT_CATEGORY` enumeration grouped by detection domain (MySQL, Postgres, Oracle, Mongo, MSSQL, SQLite, FILE, SYS, HTTP, etc.) (see [event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js)).

## Dependencies and Community-Reported Concerns

The agent pulls in a broad set of runtime and development dependencies captured in [third_party_manifest.json](https://github.com/newrelic/csec-node-agent/blob/main/third_party_manifest.json). Direct dependencies observed in the manifest include `content-type`, `fast-safe-stringify`, `find-package-json`, `hash.js`, `html-entities`, `https-proxy-agent`, `koa`, `mongodb`, `ws`, and `request`, alongside dev tools such as `sinon`, `@grpc/proto-loader`, `eslint-plugin-import`, and `eslint-plugin-jsdoc`.

The community has raised several CVE-related concerns about transitive dependencies:

- **#55** – `request-ip@^2.1.3` pulls in `is_js@^0.9.0`, which is affected by CVE-2020-26302.
- **#304** – `form-data` is reachable through `sync-request` and has its own advisory.
- **#282** – Release `2.3.0` was flagged for pulling in a `docker` dependency vulnerable to arbitrary code execution.

These issues have been partially addressed in subsequent releases; `v3.0.4` notably drops the `uuid` module and updates the hapi shim usage. Users evaluating the agent for compliance-sensitive environments should run a dependency audit and, where possible, pin or override vulnerable transitive packages.

## See Also

- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md) – full release history and known fixes.
- [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md) – CLA, code of conduct, and PR workflow.
- `lib/nr-security-agent/lib/core/sec-agent-constants.js` – central log messages, MIME types, and module identifiers.
- `lib/instrumentation-security/core/event-constants.js` – authoritative list of event types and categories.

---

<a id='page-2'></a>

## page-2

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [lib/nr-security-agent/lib/core/sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/sec-agent-constants.js)
- [lib/nr-security-agent/lib/core/event.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js)
- [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js)
- [lib/instrumentation-security/hooks/http/nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js)
- [lib/instrumentation-security/hooks/fs/nr-fs.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/fs/nr-fs.js)
- [lib/nr-security-agent/lib/core/commonUtils.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/commonUtils.js)
- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md)
- [third_party_manifest.json](https://github.com/newrelic/csec-node-agent/blob/main/third_party_manifest.json)

</details>

# page-2

## Security Event System Overview

The `csec-node-agent` is a New Relic security agent that performs both Interactive Application Security Testing (IAST) and Runtime Application Self-Protection (RASP) by instrumenting Node.js modules and emitting structured security events. The event system defines what kinds of activity the agent can observe, how activity is classified, and what downstream consumers (the New Relic backend, the local Security Agent process) do with that information.

Two parallel constant modules drive the system:

- [lib/nr-security-agent/lib/core/sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/sec-agent-constants.js) — exports string constants for routing, content types, separators (`CSEC_SEP: ':IAST:'`), and a `LOG_MESSAGES` block used to drive lifecycle log lines.
- [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js) — exports `EVENT_TYPE` and `EVENT_CATEGORY` objects used by every instrumentation hook to label what it observed.

Severity tags (`SEVERE`, `HIGH`, `CRITICAL`) and mode flags (`RASP`, `IAST`) live in `sec-agent-constants.js` and are referenced when an event is escalated into a vulnerability finding.

## Event Types and Categories

Every emitted event carries exactly one `EVENT_TYPE` (the action observed) and one `EVENT_CATEGORY` (the subsystem it belongs to). The classification maps in [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js) enumerate the supported actions, including `SQL_DB_COMMAND`, `NOSQL_DB_COMMAND`, `HTTP_REQUEST`, `CODE_INJECTION`, `XXE`, `HASH`, `RANDOM`, `UNVALIDATED_REDIRECT`, `REFLECTED_XSS`, `XPATH`, `LDAP`, `SECURE_COOKIE`, `TRUSTBOUNDARY`, and `CRYPTO`.

A companion map in [lib/nr-security-agent/lib/core/event.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js) (`VUNERABILITIES`, intentionally spelled that way in source) groups these into vulnerability identifiers: `SQLI`, `NOSQLI`, `RCE`, `RCI`, `FILE_ACCESS`, `WEAK_RANDOM`, `SSRF`, `RXSS`, `CRYPTO`, `HASH`, `XXE`, and `UNVALIDATED_REDIRECT`. The two layers exist because raw event types describe *what the application just did*, while vulnerability identifiers describe *what the rule engine decided about that action*.

The module’s general-purpose categories are summarized below.

| EVENT_TYPE | EVENT_CATEGORY examples | What is detected |
|---|---|---|
| `HTTP_REQUEST` | `HTTP` | Outbound HTTP — SSRF surface |
| `SQL_DB_COMMAND` / `NOSQL_DB_COMMAND` | `MYSQL`, `POSTGRES`, `MONGO`, … | SQLi / NoSQLi candidates |
| `SYSTEM_COMMAND` | `SYS` | Command / RCE injection |
| `FILE_OPERATION` / `FILE_INTEGRITY` | `FILE` | Path traversal & tamper detection |
| `HASH` / `RANDOM` | `HASH`, `WEAKRANDOM` | Weak crypto / PRNG use |
| `CODE_INJECTION` / `XXE` | `CODE_INJECTION`, `XXE` | Eval, XML external entities |
| `REFLECTED_XSS` / `UNVALIDATED_REDIRECT` | `REFLECTED_XSS`, `HTTP` | Output handling bugs |
| `SECURE_COOKIE` | `HTTP` | Missing Secure/HttpOnly/SameSite flags |

Source: [lib/instrumentation-security/core/event-constants.js:1-58](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js)

## Instrumentation Hooks and Event Generation

Instrumentation modules under `lib/instrumentation-security/hooks/` wrap target functions and, on each invocation, build a security metadata object that gets sent to the agent. The HTTP hook in [lib/instrumentation-security/hooks/http/nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js) is representative: it imports constants from `core/constants`, builds a metadata envelope using `securityMetaData.getSecurityMetaData(...)`, then calls `API.generateSecEvent(...)` and `API.sendEvent(...)`. The hook also reads a fuzz-request header (`NR_CSEC_FUZZ_REQUEST_ID`) so that only requests originated by the IAST fuzzer are escalated; production traffic is generally observed but not mutated.

The FS hook in [lib/instrumentation-security/hooks/fs/nr-fs.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/fs/nr-fs.js) follows the same pattern for `FILE_OPERATION` (category `FILE`). It iterates a `functionsProbableToFA` list, wraps each candidate (e.g. `readFile`, `writeFileSync` on Node ≥ 19), resolves the absolute path of `arguments[0]`, and emits `EVENT_TYPE.FILE_OPERATION` with category `FILE`. When the request carries a fuzz header, the hook additionally attaches a callback wrapper so the agent can correlate the file access with the response.

```js
// simplified from lib/instrumentation-security/hooks/fs/nr-fs.js
const secMetadata = securityMetaData.getSecurityMetaData(
  request, absoluteParameters, traceObject,
  secUtils.getExecutionId(),
  EVENT_TYPE.FILE_OPERATION, EVENT_CATEGORY.FILE
);
this.secEvent = API.generateSecEvent(secMetadata);
API.sendEvent(this.secEvent);
```

Source: [lib/instrumentation-security/hooks/fs/nr-fs.js:30-90](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/fs/nr-fs.js)

The two hooks share `secUtils`, `securityMetaData`, `requestManager`, and the `EVENT_TYPE`/`EVENT_CATEGORY` exports from [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js). This shared core means new vulnerability classes can be added by extending the constants module and adding a hook — without changing the agent transport.

## Lifecycle, Identifiers, and Shared Utilities

The agent attaches to every Node process by spawning a long-running companion through the `CSEC_GROUP_NAME` environment variable; if that variable is missing the static attachment fails and the message `AGENT_ATTACH_FAIL` is logged ([lib/nr-security-agent/lib/core/sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/lib/core/sec-agent-constants.js)). On success, the agent logs `AGENT_INIT_SUCCESSFUL_COMPLETE` and assigns an `applicationUUID` to the process.

The shared utilities module [lib/nr-security-agent/lib/core/commonUtils.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/commonUtils.js) supplies the supporting primitives every event path depends on:

- `getUUID()` — returns a process-stable UUID, reusing `process.env.applicationUUID` when present.
- `getKindIdPair(identifier, hostId)` — chooses a *kind/id* pair (`CONTAINER`, `ECS`, or `HOST`) so each event carries an identifier appropriate to the deployment topology.
- `hasWorker()` / `runtimeSupportsFunctionGenerators()` — capability probes used to skip instrumentation paths that the current Node runtime cannot support.

These identifiers propagate into every event so that the backend can correlate IAST findings with the host, container, or pod they came from.

```mermaid
flowchart LR
  App[Application code] --> Hook[Instrumentation hook<br/>http/fs/...]
  Hook --> Meta[securityMetaData.getSecurityMetaData]
  Meta --> Gen[API.generateSecEvent]
  Gen --> Send[API.sendEvent]
  Send --> Agent[NR security agent<br/>gRPC over :IAST:]
  Agent --> Backend[New Relic backend]
  Hook -.fuzz header.-> Cb[Callback hook]
```

## Operational Considerations

- **Dependency hygiene.** The community issues #55, #282, and #304 highlight that the agent itself has, in the past, pulled in vulnerable transitive dependencies (`request-ip` → `is_js`, `sync-request` → `form-data`, a `docker` helper). These affect the agent’s install footprint rather than the events it generates; the [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md) entries for v2.3.0+ show a sequence of dependency bumps addressing them.
- **Node version gating.** The FS hook conditionally adds `writeFileSync` to its instrumentation list when `semver.satisfies(process.version, '>19.0.0')`, showing how the event surface is gated by runtime version ([lib/instrumentation-security/hooks/fs/nr-fs.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/fs/nr-fs.js)).
- **Upgrade cadence.** Per the support statement in [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md), New Relic recommends regular upgrades; the latest tagged release at time of writing is v3.0.4 (2026-05-14), which removed the `uuid` runtime dependency in favor of the platform `crypto.randomUUID()` used by `commonUtils.getUUID`.
- **Contributing.** External changes are gated by the New Relic CLA as described in [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md); feedback is accepted under the Apache 2.0 license.

## See Also

- [lib/instrumentation-security/core/](https://github.com/newrelic/csec-node-agent/tree/main/lib/instrumentation-security/core) — shared metadata, request manager, and event-constants used by every hook.
- [lib/nr-security-agent/lib/core/](https://github.com/newrelic/csec-node-agent/tree/main/lib/nr-security-agent/lib/core) — agent constants, logger, health-check, and lifecycle log messages.
- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md) — version history, dependency bumps, and the support statement.
- [third_party_manifest.json](https://github.com/newrelic/csec-node-agent/blob/main/third_party_manifest.json) — license inventory for every shipped dependency.

---

<a id='page-3'></a>

## page-3

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js)
- [lib/nr-security-agent/lib/core/event.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js)
- [lib/nr-security-agent/lib/core/sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/sec-agent-constants.js)
- [lib/nr-security-agent/lib/core/commonUtils.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/commonUtils.js)
- [lib/instrumentation-security/hooks/http/nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js)
- [lib/nr-security-agent/lib/core/json-file-handler.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/json-file-handler.js)
- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md)
- [third_party_manifest.json](https://github.com/newrelic/csec-node-agent/blob/main/third_party_manifest.json)

</details>

# page-3

## Security Event Taxonomy and Detection Categories

### Purpose and Scope

The New Relic Security Agent for Node.js (csec-node-agent) classifies runtime observations through a fixed vocabulary of event types, event categories, and vulnerability identifiers. These constants are shared by the instrumentation layer (which instruments modules such as `http`, `fs`, `child_process`, and `mongodb`) and the core agent (which forwards events to the New Relic Security backend). Centralizing the taxonomy ensures that data emitted by hooks in [lib/instrumentation-security/hooks/http/nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js) can be aggregated, filtered, and correlated on the server without per-instrumentation translation. Source: [lib/instrumentation-security/core/event-constants.js:1-58]().

### Event Types and Event Categories

`EVENT_TYPE` describes **what operation was observed** (for example a SQL statement, a system command, or an HTTP request), while `EVENT_CATEGORY` groups observations by the **target subsystem** (MySQL, Postgres, Mongo, file system, HTTP, etc.). The full set of event types defined in the instrumentation layer includes `SYSTEM_COMMAND`, `SYSTEM_EXIT`, `FILE_OPERATION`, `FILE_INTEGRITY`, `SQL_DB_COMMAND`, `NOSQL_DB_COMMAND`, `HTTP_REQUEST`, `CODE_INJECTION`, `XXE`, `HASH`, `RANDOM`, `UNVALIDATED_REDIRECT`, `REFLECTED_XSS`, `XPATH`, `LDAP`, `SECURE_COOKIE`, `TRUSTBOUNDARY`, and `CRYPTO`. Source: [lib/instrumentation-security/core/event-constants.js:11-30]().

`EVENT_CATEGORY` mirrors this list with subsystem identifiers: `MYSQL`, `POSTGRES`, `ORACLE`, `MONGO`, `MSSQL`, `SQLITE`, `FILE`, `SYS`, `HTTP`, `CODE_INJECTION`, `XXE`, `CRYPTO`, `HASH`, `WEAKRANDOM`, `UNVALIDATED_REDIRECT`, `REFLECTED_XSS`, `XPATH`, `LDAP`, `SECURE_COOKIE`, `TRUSTBOUNDARY`, and `CIPHER`. The agent also exposes a `VUNERABILITIES` map (note the historical spelling) that assigns stable identifiers such as `SQLI`, `NOSQLI`, `RCE`, `RCI`, `SSRF`, `RXSS`, `SXSS`, `XXE`, `CRYPTO`, `HASH`, `FILE_ACCESS`, `XPATH`, `LDAP`, `WEAK_RANDOM`, and `UNVALIDATED_REDIRECT` to the corresponding event categories. Source: [lib/nr-security-agent/lib/core/event.js:1-58]().

### Detection Mapping

The agent maps application-layer attacks to their underlying event categories through a lookup table so that, for instance, a `sql_injection` finding is published as a `SQL_DB_COMMAND` event. The current mapping defined in the core utilities is:

| Application attack | Event category emitted |
| --- | --- |
| `sql_injection` | `SQL_DB_COMMAND` |
| `nosql_injection` | `NOSQL_DB_COMMAND` |
| `ldap_injection` | `LDAP` |
| `javascript_injection` | `JS_INJECTION` |
| `command_injection` | `SYSTEM_COMMAND` |
| `xpath_injection` | `XPATH` |
| `ssrf` | `HTTP_REQUEST` |
| `rxss` | `REFLECTED_XSS` |

Source: [lib/nr-security-agent/lib/core/commonUtils.js:1-30](). When an HTTP request hook fires, it reads the request body, parses `Content-Type` headers such as `application/json`, `application/xml`, `text/html`, `application/x-www-form-urlencoded`, and `multipart/form-data` (constants defined in the security agent core), and then routes the payload to the appropriate detector. Source: [lib/instrumentation-security/hooks/http/nr-http.js:1-40](), [lib/nr-security-agent/lib/core/sec-agent-constants.js:1-40]().

### Mermaid: Event Taxonomy Relationship

```mermaid
flowchart LR
    A[Instrumented Module<br/>http, fs, child_process, mongodb] --> B[EVENT_TYPE<br/>e.g. SQL_DB_COMMAND, FILE_OPERATION]
    B --> C[EVENT_CATEGORY<br/>e.g. MYSQL, FILE, HTTP]
    C --> D[VULNERABILITY<br/>e.g. SQLI, RCE, SSRF]
    D --> E[New Relic Security Backend]
    C -.lookup.-> F[Detection Mapping<br/>commonUtils.js]
    F --> D
```

### Supporting Utilities and Constants

The taxonomy is consumed by helper utilities in the agent core. `commonUtils.js` exposes `getUUID()` (reusing `process.env.applicationUUID` or a new `randomUUID()`), `getKindIdPair()` (which decides whether the running process should be reported as `CONTAINER`, `ECS`, or `HOST` based on the presence of container metadata), and `hasWorker()` / `runtimeSupportsFunctionGenerators()` (used to gate features that require worker threads or generator functions). Source: [lib/nr-security-agent/lib/core/commonUtils.js:1-80](). Configuration persistence is delegated to `JsonHandler`, a minimal wrapper around `fs.readFileSync` and `fs.writeFileSync` that loads and updates JSON files used to record application information between agent restarts. Source: [lib/nr-security-agent/lib/core/json-file-handler.js:1-60]().

### Community Context

Several of the dependencies that implement the event taxonomy — `request-ip`, `unescape-js`, `content-type`, `ws`, `is-invalid-path`, and `form-data` (transitively via `sync-request`) — have been the subject of open security advisories tracked in the project issue tracker. Reported CVEs include CVE-2020-26302 for an outdated `is_js` pulled in by `request-ip` (#55), a `form-data` advisory inherited through `sync-request` (#304), and a critically vulnerable `docker` dependency flagged after the 2.3.0 release (#282). The release notes for v3.0.4 (2026-05-14) document ongoing dependency hygiene, including the removal of the `uuid` module (#357) and updates to `protobufjs` and `fast-xml-parser`/`@aws-sdk/xml-builder`. Source: [CHANGELOG.md:1-40](), [third_party_manifest.json:1-40](), [CONTRIBUTING.md:1-20]().

## See Also

- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md) — version history and dependency changes
- [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md) — contribution and CLA process
- [package.json](https://github.com/newrelic/csec-node-agent/blob/main/package.json) — pinned dependency ranges referenced by community CVE reports

---

<a id='page-4'></a>

## ` ... `

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [third_party_manifest.json](https://github.com/newrelic/csec-node-agent/blob/main/third_party_manifest.json)
- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/newrelic/csec-node-agent/blob/main/CONTRIBUTING.md)
- [lib/nr-security-agent/lib/core/sec-agent-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/sec-agent-constants.js)
- [lib/nr-security-agent/lib/core/event.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js)
- [lib/nr-security-agent/lib/core/commonUtils.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/commonUtils.js)
- [lib/instrumentation-security/core/event-constants.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js)
- [lib/instrumentation-security/hooks/http/nr-http.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/http/nr-http.js)
- [lib/instrumentation-security/hooks/graphql/nr-graphql.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/graphql/nr-graphql.js)
- [lib/instrumentation-security/hooks/express/nr-express.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/express/nr-express.js)
- [lib/instrumentation-security/hooks/crypto/nr-crypto.js](https://github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/hooks/crypto/nr-crypto.js)

</details>

# Security Instrumentation Hooks and Event Detection System

The `csec-node-agent` is New Relic's Interactive Application Security Testing (IAST) and Runtime Application Self-Protection (RASP) module for Node.js, distributed as a companion to the `newrelic` APM agent. Its core job is to instrument popular framework methods, watch how request data flows into dangerous sinks, and emit categorized security events that the standalone Security Engine can analyze.

## Architecture Overview

The codebase is split into two cooperating layers. The `instrumentation-security/` folder holds the framework hooks that observe application behavior, while `nr-security-agent/` contains the long-lived agent that gathers environment data, manages identity, and ships events to the New Relic Security (Prevent) backend.

```mermaid
flowchart LR
  A[Application Code] --> B[Framework Hooks]
  B --> C{Event Constants}
  C --> D[Security Event]
  D --> E[Security Agent Core]
  E --> F[New Relic Security Engine]
  B -.uses.-> G[Common Utilities]
  E -.uses.-> G
```

The hooks module wraps framework methods using the New Relic shim API. For example, `lib/instrumentation-security/hooks/http/nr-http.js` imports `request-ip` to recover client IP, then routes intercepted arguments through `securityMetaData` to construct an event. Express's router is similarly wrapped: `lib/instrumentation-security/hooks/express/nr-express.js` calls `wrapExpress4` or `wrapExpress5` depending on the detected `express.Router` shape.

Source: [lib/instrumentation-security/hooks/http/nr-http.js:1-25]()
Source: [lib/instrumentation-security/hooks/express/nr-express.js:20-40]()

## Event Categories and Detection Types

The event system normalizes what the hooks observe into a closed enum so the Security Engine can reason about findings without parsing free-form strings.

| Layer | Module | Purpose |
|-------|--------|---------|
| Event constants | `lib/instrumentation-security/core/event-constants.js` | `EVENT_CATEGORY` and `EVENT_TYPE` enums including `SECURE_COOKIE`, `TRUSTBOUNDARY`, `CIPHER` added in later releases. |
| Vulnerability labels | `lib/nr-security-agent/lib/core/event.js` | Maps sink categories (e.g. `SQLI`, `NOSQLI`, `RCE`, `SSRF`, `XXE`, `RXSS`) to canonical identifiers. |
| Sink grouping | `lib/nr-security-agent/lib/core/commonUtils.js` | Aggregates event category names such as `sql_injection`, `nosql_injection`, `ldap_injection`, `xpath_injection`, and `ssrf`. |
| Protocol tagging | `lib/nr-security-agent/lib/core/sec-agent-constants.js` | Constants like `IAST`, `RASP`, `CSEC_SEP`, plus content-type tags (`APPLICATION_JSON`, `MULTIPART_FORM_DATA`, `TEXT_HTML`). |

Source: [lib/instrumentation-security/core/event-constants.js:1-30]()
Source: [lib/nr-security-agent/lib/core/event.js:1-35]()
Source: [lib/nr-security-agent/lib/core/commonUtils.js:1-40]()
Source: [lib/nr-security-agent/lib/core/sec-agent-constants.js:1-60]()

The constant `CSEC_SEP = ':IAST:'` is used as a delimiter to splice fuzz-request identifiers into headers, while `NR_CSEC_FUZZ_REQUEST_ID` (referenced in `nr-http.js`) lets the agent correlate a malicious probe with the generated event. The `EVENT_CATEGORY` enum and the `VUNERABILITIES` map in `event.js` together form the schema the Security Engine consumes.

## Hook Wiring and Execution Flow

Each framework hook follows the same pattern: import `requestManager` to recover the in-flight request, call `secUtils.getTraceObject` to build a stack trace, then push a `securityMetaData` record through `API.generateSecEvent` and `API.sendEvent`. In `lib/instrumentation-security/hooks/crypto/nr-crypto.js` the wrapper additionally checks whether the first stack frame is owned by the New Relic or Security Agent libraries, suppressing self-instrumentation noise:

```
if (secMetadata.traceObject.stacktrace[0].includes(NRLIB) ||
    secMetadata.traceObject.stacktrace[0].includes(SALIB)) {
    // do nothing
}
```

Source: [lib/instrumentation-security/hooks/crypto/nr-crypto.js:1-30]()

For GraphQL, `lib/instrumentation-security/hooks/graphql/nr-graphql.js` wraps `mod.execute` and uses the `x-apollo-operation-name` header plus the parsed query string to flag `*.query` as `GRAPHQL_QUERY` and `*.variables` as a fuzzable parameter. The same file shows that `shim.tracer.getTransaction()` is the preferred way to access the current request context.

The Express hook also installs two `response` patches — `download` and `sendFile` — unless `exclude_from_iast_scan.iast_detection_category.invalid_file_access` is set, giving operators a per-category kill switch. This is consistent with the v2.x series of bug-fix entries in `CHANGELOG.md` that mention default values for `scan_schedule`, `scan_controllers`, and `exclude_from_iast_scan`.

Source: [lib/instrumentation-security/hooks/graphql/nr-graphql.js:15-45]()
Source: [lib/instrumentation-security/hooks/express/nr-express.js:25-50]()
Source: [CHANGELOG.md:1-25]()

## Identity, Environment, and Common Utilities

The Security Agent must identify the process it is protecting before any event can be sent. `commonUtils.js` exposes `getUUID`, which reuses `process.env.applicationUUID` if set and otherwise mints a new one — this is how the agent survives `worker_threads` and child process forking without generating duplicate identities. `getKindIdPair` decides whether the running unit is a host, container, ECS task, or pod, which later drives the `HOST`/`CONTAINER`/`ECS` tagging seen in shipped events.

A runtime capability probe, `hasWorker`, gates worker-thread support, and `runtimeSupportsFunctionGenerators` confirms that the active Node.js version can evaluate generator functions. Together these let the agent degrade gracefully on legacy runtimes (the project dropped Node.js v16 in v2.0.0 per `CHANGELOG.md`).

Source: [lib/nr-security-agent/lib/core/commonUtils.js:1-80]()
Source: [CHANGELOG.md:10-30]()

## Dependency Posture and Community-Reported Vulnerabilities

Several open issues surface transitive dependencies as security risks in their own right, which is unusual for a security-focused agent:

- **#55** flags `request-ip@^2.1.3` (used inside `lib/instrumentation-security/hooks/http/nr-http.js`) because it pulls in `is_js@^0.9.0`, which is exposed to CVE-2020-26302.
- **#304** warns that `sync-request` brings in a vulnerable `form-data`.
- **#282** reports that a release pulled in a `docker` dependency with an arbitrary code execution advisory.

The v3.0.4 release notes address part of this concern by removing the `uuid` module entirely (#357) and bumping `protobufjs`, `fast-xml-parser`, and `@aws-sdk/xml-builder` to versions without known advisories. The `third_party_manifest.json` file is the authoritative inventory — it explicitly enumerates `request@2.88.2`, `ws@8.18.0`, `koa@3.1.2`, `mongodb@2.2.36` / `mongodb@3.7.4`, and a long list of `eslint-*` dev dependencies, each with license metadata. Operators auditing supply chain risk should cross-check this manifest against their SCA scanner baseline.

Source: [CHANGELOG.md:1-10]()
Source: [third_party_manifest.json:1-50]()

## Common Failure Modes

When wiring fails, the constants module records a clear `AGENT_ATTACH_FAIL` reason: "CSEC_GROUP_NAME Environment Not Present, Agent Attachment Failed". The agent also distinguishes between `AGENT_INIT_SUCCESSFUL` (static attachment) and the more verbose `AGENT_INIT_SUCCESSFUL_COMPLETE` emitted when protection is fully online. Operators who see no security events arriving should verify the `CSEC_GROUP_NAME` env var, the Security Agent status reported by `API.getSecAgent().status.getStatus() === 'active'`, and whether `exclude_from_iast_scan` is muting the categories in question.

Source: [lib/nr-security-agent/lib/core/sec-agent-constants.js:1-50]()

## See Also

- [New Relic Node.js Security Agent GitHub Repository](https://github.com/newrelic/csec-node-agent)
- [CHANGELOG.md](https://github.com/newrelic/csec-node-agent/blob/main/CHANGELOG.md)
- [Issue #55 — request-ip / is_js CVE](https://github.com/newrelic/csec-node-agent/issues/55)
- [Issue #282 — docker dependency advisory](https://github.com/newrelic/csec-node-agent/issues/282)
- [Issue #304 — form-data via sync-request](https://github.com/newrelic/csec-node-agent/issues/304)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: newrelic/csec-node-agent

Summary: Found 9 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

## 1. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/newrelic/csec-node-agent/issues/26

## 2. Identity risk - Identity risk requires verification

- Severity: medium
- Evidence strength: runtime_trace
- Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Repro command: `npm install @newrelic/security-agent@latest`
- Evidence: identity.distribution | https://www.npmjs.com/package/@newrelic/security-agent

## 3. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://www.npmjs.com/package/@newrelic/security-agent

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@newrelic/security-agent

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/@newrelic/security-agent

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://www.npmjs.com/package/@newrelic/security-agent

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/newrelic/csec-node-agent/issues/353

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@newrelic/security-agent

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@newrelic/security-agent

<!-- canonical_name: newrelic/csec-node-agent; human_manual_source: deepwiki_human_wiki -->