Doramagic Project Pack · Human Manual

csec-node-agent

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 Applic...

page-1

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 Applic...

Point 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).

Point 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).

Point 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, WEAKRANDOM, REFLECTEDXSS, UNVALIDATEDREDIRECT) 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)).

Point 55 – request-ip@^2.1.3 pulls in isjs@^0.9.0, which is affected by CVE-2020-26302.

Match this point to your task before installing or using the project.

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, 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).

The project is in preview and contributions are governed by the CSEC Agent Contributor License Agreement as described in 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.
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).
  • 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).
  • 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).

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).

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).

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).

Dependencies and Community-Reported Concerns

The agent pulls in a broad set of runtime and development dependencies captured in 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:

  • #55request-ip@^2.1.3 pulls in is_js@^0.9.0, which is affected by CVE-2020-26302.
  • #304form-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

Source: https://github.com/newrelic/csec-node-agent / Human Manual

page-2

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...

Point [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 (CSECSEP: ':IAST:'), and a LOGMESSAGES block used to drive lifecycle log lines.

Point [lib/instrumentation-security/core/event-constants.js](https

//github.com/newrelic/csec-node-agent/blob/main/lib/instrumentation-security/core/event-constants.js) — exports EVENTTYPE and EVENTCATEGORY objects used by every instrumentation hook to label what it observed.

Point getUUID() — returns a process-stable UUID, reusing process.env.applicationUUID when present.

Match this point to your task before installing or using the project.

Point getKindIdPair(identifier, hostId) — chooses a kind/id pair (CONTAINER, ECS, or HOST) so each event carries an identifier appropriate to the deployment topology.

Match this point to your task before installing or using the project.

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:

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 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 (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_TYPEEVENT_CATEGORY examplesWhat is detected
HTTP_REQUESTHTTPOutbound HTTP — SSRF surface
SQL_DB_COMMAND / NOSQL_DB_COMMANDMYSQL, POSTGRES, MONGO, …SQLi / NoSQLi candidates
SYSTEM_COMMANDSYSCommand / RCE injection
FILE_OPERATION / FILE_INTEGRITYFILEPath traversal & tamper detection
HASH / RANDOMHASH, WEAKRANDOMWeak crypto / PRNG use
CODE_INJECTION / XXECODE_INJECTION, XXEEval, XML external entities
REFLECTED_XSS / UNVALIDATED_REDIRECTREFLECTED_XSS, HTTPOutput handling bugs
SECURE_COOKIEHTTPMissing Secure/HttpOnly/SameSite flags

Source: lib/instrumentation-security/core/event-constants.js:1-58

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 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 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.

// 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

The two hooks share secUtils, securityMetaData, requestManager, and the EVENT_TYPE/EVENT_CATEGORY exports from 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). 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 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.

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-ipis_js, sync-requestform-data, a docker helper). These affect the agent’s install footprint rather than the events it generates; the 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).
  • Upgrade cadence. Per the support statement in 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; feedback is accepted under the Apache 2.0 license.

See Also

Source: https://github.com/newrelic/csec-node-agent / Human Manual

page-3

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...

Section Purpose and Scope

Continue reading this section for the full explanation and source context.

Section Event Types and Event Categories

Continue reading this section for the full explanation and source context.

Section Detection Mapping

Continue reading this section for the full explanation and source context.

Section Mermaid: Event Taxonomy Relationship

Continue reading this section for the full explanation and source context.

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 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 attackEvent category emitted
sql_injectionSQL_DB_COMMAND
nosql_injectionNOSQL_DB_COMMAND
ldap_injectionLDAP
javascript_injectionJS_INJECTION
command_injectionSYSTEM_COMMAND
xpath_injectionXPATH
ssrfHTTP_REQUEST
rxssREFLECTED_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

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

Source: https://github.com/newrelic/csec-node-agent / Human Manual

` ... `

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 newr...

Point 55 flags request-ip@^2.1.3 (used inside lib/instrumentation-security/hooks/http/nr-http.js) because it pulls in isjs@^0.9.0, which is exposed to CVE-2020-26302.

Match this point to your task before installing or using the project.

Point 304 warns that sync-request brings in a vulnerable form-data.

Match this point to your task before installing or using the project.

Point 282 reports that a release pulled in a docker dependency with an arbitrary code execution advisory.

Match this point to your task before installing or using the project.

Point [New Relic Node.js Security Agent GitHub Repository](https

//github.com/newrelic/csec-node-agent)

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.

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.

LayerModulePurpose
Event constantslib/instrumentation-security/core/event-constants.jsEVENT_CATEGORY and EVENT_TYPE enums including SECURE_COOKIE, TRUSTBOUNDARY, CIPHER added in later releases.
Vulnerability labelslib/nr-security-agent/lib/core/event.jsMaps sink categories (e.g. SQLI, NOSQLI, RCE, SSRF, XXE, RXSS) to canonical identifiers.
Sink groupinglib/nr-security-agent/lib/core/commonUtils.jsAggregates event category names such as sql_injection, nosql_injection, ldap_injection, xpath_injection, and ssrf.
Protocol tagginglib/nr-security-agent/lib/core/sec-agent-constants.jsConstants 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 [email protected], [email protected], [email protected], [email protected] / [email protected], 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

Source: https://github.com/newrelic/csec-node-agent / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

high Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Identity risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Capability evidence risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Maintenance risk requires verification

May increase setup, validation, or first-run risk for the user.

Doramagic Pitfall Log

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
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/newrelic/csec-node-agent/issues/26

2. Identity risk: Identity risk requires verification

  • Severity: medium
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: identity.distribution | https://www.npmjs.com/package/@newrelic/security-agent

3. Capability evidence risk: Capability evidence risk requires verification

  • Severity: medium
  • Finding: README/documentation is current enough for a first validation pass.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.assumptions | https://www.npmjs.com/package/@newrelic/security-agent

4. Maintenance risk: Maintenance risk requires verification

  • Severity: medium
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • 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
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • 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
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • 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
  • 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.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/newrelic/csec-node-agent/issues/353

8. Maintenance risk: Maintenance risk requires verification

  • Severity: low
  • Finding: issue_or_pr_quality=unknown。
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@newrelic/security-agent

9. Maintenance risk: Maintenance risk requires verification

  • Severity: low
  • Finding: release_recency=unknown。
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@newrelic/security-agent

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 12

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using csec-node-agent with real data or production workflows.

  • Dependency Vulnerability: uuid - github / github_issue
  • [[Repolinter] Open Source Policy Issues](https://github.com/newrelic/csec-node-agent/issues/26) - github / github_issue
  • v3.0.4 - github / github_release
  • v3.0.3 - github / github_release
  • v3.0.2 - github / github_release
  • v3.0.1 - github / github_release
  • v3.0.0 - github / github_release
  • v2.4.4 - github / github_release
  • v2.4.3 - github / github_release
  • v2.4.2 - github / github_release
  • v2.4.1 - github / github_release
  • v2.4.0 - github / github_release

Source: Project Pack community evidence and pitfall evidence