@contrast/agent 5.65.0 → 5.66.0

package/README.md

@@ -20,13 +20,12 @@ easiest and cheapest to remediate.
 
 - The agent no longer ships or operates with the `contrast-service` "sidecar" executables. This allows for a drastically smaller download size and simplified deployments.
 
-- Framework support includes `express`, `koa`, `fastify`, `hapi`, and `restify`.
 
 - The agent does not respond to any command-line configuration flags. Configuration options can be set using environment variables and/or `contrast_security.yaml` file. If you were previously using the agent's `-c` CLI option to set the location of your configuration file, you can use `CONTRAST_CONFIG_PATH` environment variable instead. See more about configuration [below](#configuration).
 
 - Structured logging.
 
-- Ablility to run Assess and Protect modes concurrently.
+- Ability to run Assess, Protect, Observability, and CVE Shield modes concurrently.
 
 - Full support for ESM modules
 
@@ -38,7 +37,7 @@ versioning (`major.minor.patch`).
 
 An API key or token, provided by Contrast Security, is required for the agent to function.
 
-Ensure you have installed the latest LTS (Long Term Support) version of [Node.js](http://nodejs.org/)
+Ensure you are running a supported LTS (Long Term Support) version of [Node.js](https://nodejs.org/). See [Usage](#usage) for the supported ranges.
 
 To install from npm using the command line (run from the app root directory):
 
@@ -51,8 +50,8 @@ $ npm install @contrast/agent
 ### With LTS (Long Term Support) Node.js Versions
 
 [Node.js policy](https://nodejs.org/en/about/previous-releases/) is that production applications
-should use only Active LTS or Maintenance LTS releases. All current LTS versions of Node.js support
-ECMAScript modules (ESM) and CommonJS modules (CJS) with the `--import` flag. To ensure that the
+should use only Active LTS or Maintenance LTS releases. On supported Node.js versions from 18.19.0, the
+agent instruments ECMAScript modules (ESM) and CommonJS modules (CJS) with the `--import` flag. To ensure that the
 agent can instrument your application, use:
 
 ```sh
@@ -60,19 +59,27 @@ node --import @contrast/agent app-main [app arguments]
 ```
 
 Notes:
-- `--import` should be used for Node.js LTS (Active and Maintenance) versions `>=18.19.0`
-- Node.js versions `>=20.0.0 <20.9.0` are not supported
 
-### With end-of-life Node.js Versions
+- Supported Node.js versions are `>=18.7.0 <19`, `>=20.9.0 <21`, `>=22.5.1 <23`, and `>=24.0.1 <25`. Other versions, including odd-numbered releases and the early releases of each LTS line, are not supported.
+- Use `--import` on supported versions `>=18.19.0`, and `--loader` on 18.7 to 18.18 (below).
 
-Use the `--loader` flag for Node.js versions `>=16.17.0 <18.19.0`.
+### With Node.js 18.7 to 18.18
+
+Use the `--loader` flag for Node.js versions `>=18.7.0 <18.19.0`.
 
 ```sh
 node --loader @contrast/agent app-main.mjs [app arguments]
 ```
 
-Note:
-- `--require` or `-r` will still work for Node.js versions that have no ESM modules or dependencies.
+### With applications that use no ES modules
+
+If neither your application nor any of its dependencies uses ES modules, you can also start the agent with `--require` (or `-r`):
+
+```sh
+node -r @contrast/agent app-main.js [app arguments]
+```
+
+ES modules loaded by an application started this way are not instrumented.
 
 ### Configuration
 
@@ -83,26 +90,23 @@ The agent will look for the `contrast_security.yaml` configuration file in the f
 1. Within the processes current working directory, that is `${process.cwd()}/contrast_security.yaml`.
 
 1. OS-specific configuration directories.
+   - Unix and MacOS systems:
+     - `/etc/contrast/node/contrast_security.yaml`, _then_
 
-    - Unix and MacOS systems:
+     - `/etc/contrast/contrast_security.yaml`
 
-      - `/etc/contrast/node/contrast_security.yaml`, _then_
+   - Win32 systems:
+     - `${process.env.ProgramData}\contrast\node\contrast_security.yaml`, _then_
 
-      - `/etc/contrast/contrast_security.yaml`
-
-    - Win32 systems:
-
-      - `${process.env.ProgramData}\contrast\node\contrast_security.yaml`, _then_
-
-      - `${process.env.ProgramData}\contrast\contrast_security.yaml`
+     - `${process.env.ProgramData}\contrast\contrast_security.yaml`
 
 1. Unix home directory.
+   - `~/.config/contrast/node/contrast_security.yaml`, _then_
 
-    - `~/.config/contrast/node/contrast_security.yaml`, _then_
-
-    - `~/.config/contrast/contrast_security.yaml`
+   - `~/.config/contrast/contrast_security.yaml`
 
 > Note: The optional `/node/` path segment is useful in cases where you want to organize configuration files by agent language:
+>
 > ```
 > /etc
 >   /contrast
@@ -111,16 +115,21 @@ The agent will look for the `contrast_security.yaml` configuration file in the f
 >     /python/contrast_security.yaml
 > ```
 
+The search stops at the first of these steps that finds a file. If a step finds both the `/node/` file and its parent's file, they are merged, and the `/node/` file's values win. A file that contains `root: true` is used on its own.
+
 You can also specify the location of the configuration file with the `CONTRAST_CONFIG_PATH` environment variable:
 
 ```sh
 CONTRAST_CONFIG_PATH=/path/to/config.yaml node --import @contrast/agent app-main
 ```
 
-> Note:  If `process.env.CONTRAST_CONFIG_PATH` set, the agent will look at that location _only_. If there is an issue reading the configuration file from this location the agent will not look in the standard locations described above, but instead do the following:
+> Note: If `process.env.CONTRAST_CONFIG_PATH` set, the agent will look at that location _only_. If there is an issue reading the configuration file from this location the agent will not look in the standard locations described above, but instead do the following:
+>
 > 1. Halt instrumentation
 > 2. Communicate an error
 > 3. Run the application as if without Contrast
+>
+> Set `CONTRAST_CONFIG_PATH` to the null device (`/dev/null`, or `\\.\nul` on Windows) to use no configuration file at all.
 
 #### Minimum Configuration Option Requirements
 
@@ -129,13 +138,13 @@ The agent requires a minimum set of configuration options be set. They are descr
 ```yaml
 api:
   # Organization's API key
-  api_key: dCBvm46uEJAUV2musNFb357SnvqYrlq1
+  api_key: <api_key>
   # Contrast user account service key
-  service_key: PZU499KK3YD4X2DT
+  service_key: <service_key>
   # Contrast user account ID (In most cases, this is your login ID)
-  user_name: agent_d228a527-130c-18cc-93b8-20096136ba0b@UserOrg
+  user_name: <user_name>
   # Address to the Contrast backend. This will vary.
-  url: https://app.contrastsecurity.com
+  url: https://app.contrastsecurity.com/Contrast
 ```
 
 OR
@@ -143,7 +152,7 @@ OR
 ```yaml
 api:
   # base64 encoded JSON object containing the url, api_key, service_key, and user_name
-  token: eyJ1cmwiOiJodHRwczovL2FwcC5jb250cmFzdHNlY3VyaXR5LmNvbSIsImFwaV9rZXkiOiJkQ0J2bTQ2dUVKQVVWMm11c05GYjM1N1NudnFZcmxxMSIsInNlcnZpY2Vfa2V5IjoiUFpVNDk5S0szWUQ0WDJEVCIsInVzZXJfbmFtZSI6ImFnZW50X2QyMjhhNTI3LTEzMGMtMThjYy05M2I4LTIwMDk2MTM2YmEwYkBVc2VyT3JnIn0=
+  token: <token>
 ```
 
 Visit https://agent.config.contrastsecurity.com/ to use our online tool for building your YAML file interactively.

package/lib/start-agent.js

@@ -66,6 +66,7 @@ function loadFeatures(core) {
   require('@contrast/library-analysis')(core);
   require('@contrast/route-coverage')(core);
   require('@contrast/assess')(core);
+  core.initComponentSync(require('@contrast/blocking'));
   core.initComponentSync(require('@contrast/cve-shield'));
   require('@contrast/protect')(core);
   require('@contrast/sec-obs')(core);
@@ -101,6 +102,7 @@ function startAgent({ type = 'cjs' } = {}) {
         'sources',
         'routeCoverage',
         'assess',
+        'blocking',
         'cveShield',
         'protect',
         'depHooks',

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@contrast/agent",
-  "version": "5.65.0",
-  "description": "Assess and Protect agents for Node.js",
+  "version": "5.66.0",
+  "description": "Contrast Security agent for Node.js",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
   "files": [
     "lib/",
-    "!*.test.*",
-    "!tsconfig.*",
-    "!*.map"
+    "!**/*.test.*",
+    "!**/tsconfig.*",
+    "!**/*.map"
   ],
   "exports": {
     ".": {
@@ -28,16 +28,17 @@
     "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/agentify": "1.73.0",
-    "@contrast/assess": "1.81.0",
-    "@contrast/cli": "1.69.0",
-    "@contrast/common": "1.42.0",
-    "@contrast/core": "1.68.0",
-    "@contrast/cve-shield": "1.4.0",
-    "@contrast/library-analysis": "1.58.0",
-    "@contrast/protect": "1.83.0",
-    "@contrast/route-coverage": "1.63.0",
-    "@contrast/sec-obs": "1.14.0",
-    "@contrast/telemetry": "1.43.0"
+    "@contrast/agentify": "1.74.0",
+    "@contrast/assess": "1.82.0",
+    "@contrast/blocking": "1.1.0",
+    "@contrast/cli": "1.70.0",
+    "@contrast/common": "1.43.0",
+    "@contrast/core": "1.69.0",
+    "@contrast/cve-shield": "1.5.0",
+    "@contrast/library-analysis": "1.59.0",
+    "@contrast/protect": "1.84.0",
+    "@contrast/route-coverage": "1.64.0",
+    "@contrast/sec-obs": "1.15.0",
+    "@contrast/telemetry": "1.44.0"
   }
 }