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...
IAST: separator, and step markers ([STEP-1]…[STEP-9]`) are all centralized here (see sec-agent-constants.js).
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).
//github.com/newrelic/csec-node-agent/blob/main/lib/nr-security-agent/lib/core/event.js)).
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:
- 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. - 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 sharednr-security-apipackage.
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 --> BKey files backing this split:
lib/nr-security-agent/lib/core/sec-agent-constants.jsdefines the central constant set, log messages, and module identifiers used throughout the agent. Strings such asRASP,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.jsprovides helpers: a UUID generator (getUUID) that reusesprocess.env.applicationUUIDwhen 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.jsenumerates 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:
- #55 –
request-ip@^2.1.3pulls inis_js@^0.9.0, which is affected by CVE-2020-26302. - #304 –
form-datais reachable throughsync-requestand has its own advisory. - #282 – Release
2.3.0was flagged for pulling in adockerdependency 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 – full release history and known fixes.
- 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.
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...
//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.
//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.
Match this point to your task before installing or using the project.
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:
- lib/nr-security-agent/lib/core/sec-agent-constants.js — exports string constants for routing, content types, separators (
CSEC_SEP: ':IAST:'), and aLOG_MESSAGESblock used to drive lifecycle log lines. - lib/instrumentation-security/core/event-constants.js — exports
EVENT_TYPEandEVENT_CATEGORYobjects 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 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_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
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, reusingprocess.env.applicationUUIDwhen present.getKindIdPair(identifier, hostId)— chooses a *kind/id* pair (CONTAINER,ECS, orHOST) 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-ip→is_js,sync-request→form-data, adockerhelper). 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
writeFileSyncto its instrumentation list whensemver.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
uuidruntime dependency in favor of the platformcrypto.randomUUID()used bycommonUtils.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
- lib/instrumentation-security/core/ — shared metadata, request manager, and event-constants used by every hook.
- lib/nr-security-agent/lib/core/ — agent constants, logger, health-check, and lifecycle log messages.
- CHANGELOG.md — version history, dependency bumps, and the support statement.
- third_party_manifest.json — license inventory for every shipped dependency.
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...
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
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 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
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 --> DSupporting 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 — version history and dependency changes
- CONTRIBUTING.md — contribution and CLA process
- package.json — pinned dependency ranges referenced by community CVE reports
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...
Match this point to your task before installing or using the project.
Match this point to your task before installing or using the project.
Match this point to your task before installing or using the project.
//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.-> GThe 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 insidelib/instrumentation-security/hooks/http/nr-http.js) because it pulls inis_js@^0.9.0, which is exposed to CVE-2020-26302. - #304 warns that
sync-requestbrings in a vulnerableform-data. - #282 reports that a release pulled in a
dockerdependency 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.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
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.
Count of project-level external discussion links exposed on this manual page.
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