Security Best Practices

The official guide opens by saying that it extends the Node.js threat model, which is the project’s definition of what counts as a vulnerability in Node.js itself. The idea is that Node.js treats some things as trusted: the code it is asked to run (your application and its dependencies), the file system the process can reach, and the inputs your own code hands to its APIs. A problem that needs one of those to be hostile is, by that definition, not a bug in Node.js core: it is your deployment’s problem. The practical consequence is the most important sentence on this page: the runtime will not save an application from a malicious dependency, a poisoned directory or unvalidated input, so those defences belong to you. The project’s own policy, including the threat model section, is in the SECURITY.md of the Node.js repository, listed in the references.

Two items in the official list are labelled as application-level threats even though the guide discusses them next to the others: malicious third-party modules and prototype pollution (and the same holds for the uncontrolled search path). The guide says in so many words that they are not vulnerabilities in Node.js core under the threat model, but that they are serious for the applications and libraries built on it. The rest of this page treats them that way: as things you defend against in your own code and pipeline.

Source: Node.js Learn: Security Best Practices

A denial of service (DoS) makes the application unavailable for the purpose it was built for. It does not need a malicious actor: a buggy client that retries in a tight loop has the same effect. The official guide draws a precise line. The Node.js HTTP server does not parse the request body and hands it to your handler, so a DoS that is triggered by the contents of a body (a pathological JSON document, a regular expression that backtracks) is the application’s responsibility. What the runtime does expect you to configure is everything about the timing and pattern of requests, because that is where an attack such as Slowloris lives: the client sends a request one fragment at a time, the server keeps resources reserved for every unfinished request, and enough of those exhaust the connection limit.

The guide gives three mitigations: put a reverse proxy in front of Node.js, configure the server timeouts, and limit open sockets (agent.maxSockets, agent.maxTotalSockets, agent.maxFreeSockets and server.maxRequestsPerSocket). It also warns about a smaller trap that is easy to miss: a server created without an 'error' listener on its sockets can crash the whole process on a bad request. The example sets the timeouts, answers malformed requests with a 400 through the 'clientError' event, and shows the equivalent listener for a raw node:net server.

Source: Node.js Learn: Security Best Practices, Denial of Service of HTTP server

The values above are illustrative. Choosing them, the size and connection limits, and the interaction with a reverse proxy are the subject of Server Timeouts, Limits & Hardening. The other DoS family, a handler that burns the CPU or blocks the loop for everyone, is in Don’t Block the Event Loop. A third family arrives with data you did not size: unbounded request bodies, unbounded uploads and decompression bombs (see Compression with zlib); always cap what you read.

This attack targets applications that run with the debugging inspector enabled (--inspect). Browsers allow any web page to send HTTP and WebSocket requests, and the same-origin policy normally stops a page from reading answers from a local address. DNS rebinding defeats that: the attacker controls both a website and the DNS server that resolves its name, so for a moment the name resolves to the victim’s local address and the browser believes the request is same-origin. If an inspector is listening on 127.0.0.1:9229, such a page can talk to it, and the inspector protocol can run arbitrary code in your process.

The mitigations in the guide are to keep the inspector out of production and to stop it from being started on demand by a signal. By default, a Node.js process that receives SIGUSR1 starts the inspector, so a signal is enough to open the door; the guide suggests attaching a process.on('SIGUSR1', …​) listener to prevent that, and the --disable-sigusr1 flag does the same without code (it was experimental when added, and is no longer experimental since v24.8.0 and v22.20.0). The CLI reference also warns that binding the inspector to a public address is insecure; the default is 127.0.0.1:9229, and --inspect=0 picks a random port.

The same trick works against any service that listens on localhost and trusts the network location of its caller: development servers, admin ports, sidecars. A general, application-level defence is to validate the Host header and refuse names you do not serve, so a rebinding page that arrives under the attacker’s host name gets a 421.

Source: Node.js Learn: Security Best Practices, DNS Rebinding

The second half of the defence is to make the signal harmless. The script below installs a SIGUSR1 listener and sends the signal to itself. I observed on all three lines that, without a listener (and without --disable-sigusr1), the same signal makes the process print "Debugger listening on ws://127.0.0.1:9229/…​"; with the listener, or with the flag, it does not.

Source: Node.js API: CLI, --disable-sigusr1

Debugging safely, including SSH tunnels instead of public bindings, is in Debugging.

The guide’s example of this CWE is a publishing accident: when you publish a package, everything in the current directory is pushed to the npm registry unless a mechanism excludes it. A .env file, a notes.txt, a private key or a local database ends up in a public tarball, and once somebody has downloaded it you cannot take it back. There are two mechanisms: a blocklist (the ignore files .npmignore and .gitignore) and an allowlist, the files field in package.json. The allowlist is the safer default because a new file is excluded until somebody opts it in. The guide’s checklist is to review what will be published with a dry run, maintain the ignore files, and unpublish in case of an exposure.

The check is one command, and it is worth running in CI: it prints exactly what would be in the tarball without publishing anything. The package here has a .env and a notes.txt next to dist/ and a files allowlist; only the allowlisted file (and package.json, which npm always includes) is listed.

Source: npm Docs: package.json, files

Source: Node.js Learn: Security Best Practices, Exposure of Sensitive Information, npm Docs: npm publish

The same principle applies to every channel a secret can leak through: keep secrets in the environment (loaded with --env-file, see CLI Options, Environment & Config File), keep the .env file out of version control and Docker build contexts, never put them in URLs (they end up in logs and proxies), and never log them. The CLI reference lists report options such as --report-exclude-env for diagnostic reports, and --no-extra-info-on-fatal-exception hides extra detail on fatal exceptions; the handling of secrets in code is the subject of Crypto, Passwords & Secrets.

Smuggling needs two HTTP servers, typically a proxy in front and Node.js behind it. If the front end and the back end read the same bytes as different requests (for example because a message carries both Content-Length and Transfer-Encoding), an attacker can hide a second request inside the first one: the proxy never sees it, the application does, and the proxy’s checks are bypassed. Whether a given case is a Node.js vulnerability depends on the specification: if Node.js interprets the message consistently with RFC 7230, then it is not considered a bug in Node.js, and the fix belongs in the front end (or in both).

The guide’s mitigations are: never enable insecureHTTPParser when creating an HTTP server, configure the front-end server to normalise ambiguous requests, monitor for new smuggling vulnerabilities in both Node.js and the front end, and use HTTP/2 end to end where possible (and disable HTTP downgrading). The leniency flag exists for interoperability with non-conformant clients; the CLI reference lists what it accepts, including a message that has both Transfer-Encoding and Content-Length. The experiment sends exactly that ambiguous message to a strict server (the default) and to one with the flag on.

Source: Node.js Learn: Security Best Practices, HTTP Request Smuggling, Node.js API: CLI, --insecure-http-parser

The second row is the point: the lenient parser accepted the ambiguous request, and a proxy that treats it differently is the opening smuggling needs. Run the strict parser, and see Server Timeouts, Limits & Hardening for the proxy side (keep-alive alignment and who the client is).

A timing attack learns a secret from how long the application takes to respond. It is not specific to Node.js; it is possible whenever a secret is used in a timing-sensitive operation. The guide’s example is a login: comparing the submitted password with the stored one using the built-in string comparison returns at the first differing character, so each additional correct prefix makes the response a little slower, and an attacker who can send many requests can recover the value.

The guide’s mitigations are crypto.timingSafeEqual(), which compares two values with a constant-time algorithm, and scrypt for passwords; more generally, avoid branching on secrets, and avoid using a secret as an index into memory when an attacker could share the machine. It adds that writing constant-time code in JavaScript is hard (partly because of the JIT), so use the built-in crypto APIs or WebAssembly rather than rolling your own. Three details trip people up. timingSafeEqual() throws ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH when the two inputs have different byte lengths, so hash both sides to a fixed size (or compare fixed-length digests) before comparing. The function does not turn a weak secret into a strong one. And a recently discovered case shows the lesson at the runtime level: the March 2026 security release fixed a non-constant-time comparison in the native HMAC verification code (CVE-2026-21713), which is a reminder to keep Node.js patched and to use the current APIs rather than hand-built ones.

Source: Node.js Learn: Security Best Practices, Information Exposure through Timing Attacks, Node.js API: crypto.timingSafeEqual(), Node.js API: crypto.scrypt() and OWASP Password Storage Cheat Sheet

Do not leave crypto.scrypt() at its defaults for passwords: the default cost N is 16384 (2¹⁴), eight times below the OWASP minimum of 2¹⁷. On Node.js 24.7 and later, crypto.argon2('argon2id', …​) is the first choice. The password parameters (cost, salt length, storing them next to the hash, Argon2id, PBKDF2 iteration counts) are covered in Crypto, Passwords & Secrets: password hashing, and authenticated encryption in the same page; session and token handling is in Authentication & Sessions.

Node.js treats the code it is asked to run, dependencies included, as trusted, so a malicious dependency is not a Node.js vulnerability. It is nevertheless, in the words of the guide, one of the most critical application-level risks. The reason is structural: any package in node_modules runs with the full privileges of your process. It can read the file system, open sockets, read process.env (where your database password lives), call eval(), and write files that will be loaded later. The guide gives two typical stories: a maintainer account of a popular logging library is compromised and a new minor version sends environment variables to a remote server when the logger initialises, and a typosquatted package with a name close to a well-known framework runs a postinstall script that uploads SSH keys.

A supply chain attack is the general form: one of your direct or transitive dependencies is compromised, and your application picks the bad version up because the specification was too lax (a range that admits new versions) or contained a typo. The guide lists the attack vectors: typosquatting, lockfile poisoning, compromised maintainers, malicious packages and dependency confusion. It also makes a point that is easy to miss: pinning a dependency to an exact version does not pin its transitive dependencies, so exact versions in package.json are not enough; only a lockfile pins the whole tree.

Source: Node.js Learn: Security Best Practices, Malicious Third-Party Modules, npm Docs: Threats and Mitigations

Memory-based attacks depend on a combination of memory-management errors and an exploitable allocator. Like every runtime, Node.js is exposed to them if the application shares a machine with code you do not control, and the guide offers two mitigations: do not run production applications on shared machines, and consider the secure heap. --secure-heap=n initialises an OpenSSL secure heap of n bytes, which OpenSSL uses for selected allocations during key generation and other operations, so that sensitive material is not exposed by pointer overruns and underruns. The heap is fixed in size and cannot be resized at run time, n must be a power of two (anything below 2 disables it), and --secure-heap-min=n sets the minimum allocation. It is disabled by default, and not available on Windows. Size it generously: when it is full, allocations fall back to ordinary memory.

crypto.secureHeapUsed() reports the state, so you can check that the flag took effect and watch utilisation.

Source: Node.js API: CLI, Node.js API: crypto.secureHeapUsed()

The used figure differs between lines (544 bytes on Node.js 26, 288 on 24 and 22), and with the heap disabled Node.js 22 reports utilization: 0 and min: 0 where 26 and 24 report NaN and 2; these are observed differences, not documented guarantees, so check total rather than parsing the rest. The secure heap does not protect the memory of the JavaScript heap itself: a secret held in a string is on the V8 heap and can end up in heap snapshots and core dumps (see Memory & Leaks), so keep secrets short-lived, and keep them out of diagnostic output.

Monkey patching modifies properties at run time to change existing behaviour. In an application it is a legitimate (if risky) technique; in a hostile dependency it is a way to change what Array.prototype.push, JSON.parse or a built-in module method does for the whole process, without touching your code. The guide’s mitigation is --frozen-intrinsics, which recursively freezes the built-in JavaScript objects and functions. The CLI reference marks it Stability 1 (Experimental): only the root context is supported, there is no guarantee that globalThis.Array is the default intrinsic, and code (including libraries) may break under it. To let polyfills work, --require and --import modules run before the intrinsics are frozen.

The guide points out the limit as well: freezing the intrinsics does not prevent defining new globals or replacing existing ones through globalThis; for that, freeze globalThis too with Object.freeze(globalThis). The experiment runs both: after --frozen-intrinsics, replacing Array.prototype.push throws a TypeError; without the flag the replacement succeeds. After Object.freeze(globalThis), replacing globalThis.Array throws as well.

Source: Node.js Learn: Security Best Practices, Monkey Patching, Node.js API: CLI, --frozen-intrinsics

Two honest caveats. The flag is experimental and may break libraries that patch built-ins on purpose (some polyfills, test frameworks and APM agents), so it needs a test run of your whole application; and a hostile dependency that already runs in your process can do far more than patch a prototype, so freezing is a tripwire, not a containment. The real fix for untrusted code is the controls in Malicious third-party modules and the supply chain (CWE-1357) and The Permission Model: a seat belt, not a sandbox.

Prototype pollution abuses __proto__, constructor, prototype and the other properties inherited from built-in prototypes to inject properties into every object of a type. The attacker needs a path where untrusted input is merged into an object: a deep merge, a "set by path" helper, or a configuration loader. The guide gives the canonical snippet (a JSON.parse result containing a __proto__ key, merged with Object.assign) and two effects: logic bugs, such as an isAdmin-style check that now passes for every object, and denial of service, such as hasOwnProperty stopping to exist after a null prototype is assigned. The guide notes that Node.js core does not count prototype pollution caused by attacker-controlled input as its own vulnerability, because the input comes from application code; it is a language characteristic that libraries and applications must defend against, as real examples show (CVE-2018-3721 in a popular utility library, CVE-2018-16487 for insecure recursive merges, CVE-2022-21824 in Node.js itself).

The mitigations in the guide are: avoid insecure recursive merges, validate untrusted input against a JSON schema, create dictionaries without a prototype (Object.create(null)), freeze prototypes (Object.freeze(MyObject.prototype)), run with --disable-proto, check own properties with Object.hasOwn(), and avoid methods inherited from Object.prototype. The experiment first shows the vulnerable merge, then a safer one that skips the dangerous keys and writes into prototype-less objects.

Source: Node.js Learn: Security Best Practices, Prototype Pollution Attacks

--disable-proto=mode removes the most common entry point at the process level: with delete the Object.prototype.__proto__ accessor is removed, with throw any access throws ERR_PROTO_ACCESS. The supported API, Object.getPrototypeOf(), keeps working, and JSON.parse() still creates __proto__ as an ordinary own property, which is why the flag complements, and does not replace, safe merging. It can break old libraries that read __proto__.

Source: Node.js API: CLI

The March 2026 security release fixed a related runtime case, a request with a header named __proto__ that made req.headersDistinct throw an uncatchable TypeError (CVE-2026-21710, in the release notes listed under Security releases and reporting), a reminder that dictionaries keyed by attacker-chosen names deserve Object.create(null) or a Map everywhere, including in the runtime.

Node.js resolves modules by the Module Resolution Algorithm and assumes that the directory in which a module is requested is trusted. The threat model considers the file system reachable by the process as trusted, so a problem that needs someone to plant a file in a directory the application resolves from is not a Node.js bug, but it is a real deployment risk, particularly together with a compromised dependency or a writable directory in a container. The guide’s example is a directory with server.js, auth.js and a second entry called auth (the experiment below uses a file), where require('./auth') is described as loading auth and not auth.js, because CommonJS tries the exact name first, then appends extensions, then looks for a directory. A file somebody drops next to your code silently wins.

The experiment recreates it with an extensionless file auth planted next to auth.js.

Source: Node.js Learn: Security Best Practices, Uncontrolled Search Path Element, Node.js API: Modules, CommonJS modules

The defences are boring and effective: write full file names with extensions in require() (ESM already requires them), make the application directory read-only at run time (container file systems and --allow-fs-write from the Permission Model both help), do not execute from directories that other users can write to (a temporary directory, an uploads directory), and do not rely on global lookup paths. The CLI flag --no-global-search-paths disables searching global paths such as $HOME/.node_modules and $NODE_PATH; I confirmed that a module only reachable through NODE_PATH loads normally, and fails with MODULE_NOT_FOUND with the flag. Module resolution itself is covered in CommonJS Modules and ECMAScript Modules, and --no-addons (see Hardening flags at a glance) prevents loading native addons altogether.

The official guide’s threat list does not have a section for injection, but it is the most common way real Node.js applications get compromised, and the guide’s own theme (untrusted input must not become code) applies. Three cases cover most of it, and each has one rule.

For commands, never build a shell string from input. child_process.execFile() and spawn() take an argument array, and with no shell involved there is nothing to interpret ;, $() or backticks. The trap is to add shell: true "to make it work": the arguments are then only concatenated, not escaped, which is why passing an args array together with the shell option is DEP0190 (documentation-only since v23.11.0 and v22.15.0, a runtime deprecation since v24.0.0). Pick the program from an allowlist, never from input.

For SQL, bind values with placeholders and never splice them into the statement; table and column names cannot be bound, so choose them from an allowlist too. The example uses the built-in node:sqlite (Stability 1.2, Release candidate; it still prints an ExperimentalWarning on Node.js 22.23.3), but every driver offers the same thing: ? or $1 placeholders.

For paths, resolve the input against a base directory and check that the result is still inside it before opening anything. A string startsWith() check on the unresolved input is not enough, and a bare rel.startsWith('..') rejects a legitimate file called ..notes, so the check below compares against the separator.

Source: Node.js API: child_process.execFile(), Node.js API: Deprecations, DEP0190, Node.js API: SQLite

Source: Node.js Learn: Security Best Practices, Node.js API: Path

A string check does not stop a symbolic link that points out of the base directory; resolve with fs.realpath() before the comparison when the directory can contain links, and prefer the Permission Model’s file-system allowlist as a second layer. Shell injection in depth, including the Windows .bat and .cmd case, is in Child Processes; database access with ORMs and drivers is in Databases from Node.js. Code built from strings is the fourth member of the family: --disallow-code-generation-from-strings makes eval and new Function throw an EvalError (the next section’s snippet shows it), and it does not affect node:vm.

node:vm lets you compile and run code in a separate V8 context with its own global object, and that sounds like isolation. The documentation is blunt: the module is not a security mechanism, and you must not use it to run untrusted code. The context object you pass in is made from the host realm, so any code inside can walk up its constructor chain to the host’s Function constructor and from there to process. The timeout option only limits how long synchronous code runs; it does not prevent anything else.

Source: Node.js API: VM

The practical rule: use node:vm for what it was built for (evaluating your own trusted code in a controlled global scope, for example a templating or REPL feature) and never as a boundary. If you must run untrusted code, give it a separate process (or container, or virtual machine) with no secrets, a read-only file system, no network and resource limits; a worker_threads worker is not a security boundary either, because it shares the process. The Permission Model can restrict what a whole process may do, and is covered next. --disallow-code-generation-from-strings is complementary and independent of vm:

Source: Node.js API: CLI, --disallow-code-generation-from-strings

The official guide ends the threat list by pointing at the Permission Model, which limits what a given process may do at run time: file-system reads and writes, child processes, worker threads, native addons, WASI, and (since Node.js 25, as an Active-development feature) network access. Its value for this page is containment: even trusted code is stopped from doing things you did not grant, so a compromised dependency that tries to read ~/.ssh or spawn a shell fails with ERR_ACCESS_DENIED instead of succeeding. It is a seat belt for mistakes and for supply-chain surprises, and not a sandbox for hostile code: the project’s own security releases in 2026 fixed several bypasses (see Security releases and reporting), and the guide’s threat model still treats the process as a trust boundary you must otherwise defend.

Source: Node.js API: Permissions, Node.js API: CLI, --permission

Every flag, the audit mode, the config-file block and the limits are in The Permission Model. Two operational points belong here: grant the narrowest paths that work (a directory per concern, not *), and combine it with the other layers on this page rather than relying on it alone.

The flags below are the ones the official guide and the CLI reference present as security controls. Each is a start-up option; put them in the service’s unit file, container command or the Node.js config file rather than in application code, so they are visible to whoever reviews the deployment. Always test them: several (especially --frozen-intrinsics) can break libraries.

Source: Node.js API: Command-line API, Node.js Learn: Security Best Practices

Experimental features deserve a sentence of their own, because the guide gives it one: do not use them in production. They can change in incompatible ways, and their behaviour is not guaranteed to be securely stable. Check the Stability index of every API you rely on; this page and the rest of the section label it each time. For the full list of options and NODE_OPTIONS, see CLI Options, Environment & Config File.

The guide ends with the OpenJS Foundation’s Open Source Security Foundation (OpenSSF) tools that matter if you publish packages: the OpenSSF Scorecard, which scores a repository with automated security checks, and the OpenSSF Best Practices Badge, with which a project self-certifies. Both are useful to look at when choosing dependencies as well as for your own.

Everything above reduces the risk, but the runtime itself has vulnerabilities, and the control that matters most is applying fixes. The Node.js project publishes security releases through a documented process, and the release lines you can run are listed in Release Lines & LTS. Only the Current, Active LTS and Maintenance lines receive them: on the dates checked for this page that was Node.js 26, 24 and 22. Anything older (Node.js 20 reached end of life on 2026-04-30, Node.js 25 on 2026-06-01) gets no fixes, whatever your application does.

Source: Node.js: Security Reporting

To receive announcements, subscribe through the channels the policy lists (the Node.js security mailing list, a Google Group, and the Node.js blog’s Vulnerabilities category), and make "update Node.js" a routine job: run the latest patch of your line, rebuild container images when a security release appears, and pin the runtime version in CI and Docker so the update is deliberate (see Installing Node.js and Docker & Containers). process.version and process.release.lts tell a running process what it is. Download Node.js only from nodejs.org (or your OS vendor, or a version manager that verifies checksums), and verify the checksum file when you script downloads; the nodejs.org download page links the instructions for verifying signed SHASUMS files.

Source: Node.js Blog: Vulnerabilities, March 2026 Security Releases, June 2026 Security Releases, July 2026 Security Releases, January 2026 DoS mitigation post

The table lists a selection of the announced items with their announced severities, copied from the blog, not a complete list; read the posts for the affected versions of each. Three patterns recur: the HTTP and HTTP/2 stacks (denial of service, smuggling), TLS hostname handling, and the Permission Model’s boundary checks. None of this is a reason to avoid Node.js; it is the evidence for treating patching as part of the application.

If you find a vulnerability, report it as the policy says (HackerOne for Node.js itself, the maintainers for a third-party module). If you find a malicious package on npm, the npm documentation has a page on reporting malware.

Source: npm Docs: Reporting malware in an npm package

A realistic baseline for the Bookshelf service, combining the controls above, looks like this. None of it is exotic; the discipline is applying all of it.

Two books were consulted for this section: Efficient Node.js by Samer Buna (O’Reilly, 2025) and Node.js Projects by Jonathan Wexler (O’Reilly, 2025). Neither covers the application security landscape described here, and the points below should be checked against the official documentation instead of the books.