@contrast/config

Discovers and resolves the Contrast Node.js agent's configuration from contrast_security.yaml, CONTRAST__* environment variables, and settings from the Contrast UI.

Usage

@contrast/agentify composes the config onto core as core.config.

// resolved values, as a nested object
if (core.config.protect.enable) { /* ... */ }

// a single option by its canonical name, and where its value came from
core.config.getEffectiveValue('assess.enable');
core.config.getEffectiveSource('assess.enable'); // e.g. 'ENVIRONMENT_VARIABLE'

// the effective options grouped by source, credentials redacted
core.config.getReport({ redact: true });

Every option, with its default and description, is defined in lib/options.js.

Precedence

For each option, an environment variable beats the YAML file, and the file beats the default. Settings from the Contrast UI only override options that are still at their default (or were already set by the UI), so a local value always wins.

Environment variable names are CONTRAST__ plus the option name in uppercase, with . replaced by __. For example, agent.node.app_root becomes CONTRAST__AGENT__NODE__APP_ROOT.

Configuration files

contrast_security.yaml is looked up in three tiers, stopping at the first tier that contains a file:

1. The current working directory
2. /etc/contrast/node/, then /etc/contrast/ (on Windows, %ProgramData%\contrast\node\, then %ProgramData%\contrast\)
3. ~/.config/contrast/node/, then ~/.config/contrast/

All files found in that tier are merged, and the node/ file wins where they overlap. A file containing root: true is used on its own and ends the search.

CONTRAST_CONFIG_PATH replaces the search with a single file. Setting it to the null device (/dev/null, or \\.\nul on Windows) skips file configuration entirely.

To see the effective configuration for an application, run npx -p @contrast/cli config-diagnostics <entrypoint> from its directory.