Setting up and Configuring the CxIAST Node.js Agent in the AUT Environmentoes

Pre-Requisites

Application servers running the CxIAST Node.js agent require the Node.js LTS as listed under Supported Environments for Applications Under Testing in the release notes for the IAST version in use.

Installation

In cases when the application under test runs via a process manager (e.g., forever), stop the application from the process manager. Otherwise, stop the application directly.

The Node.js agent can run on Windows or Linux depending on your installed application.

As of node.js v8.2.0, you can use npx to start the agent from the root directory of your app:

npx cxiast <MAIN_SCRIPT> [...args]

For older versions or when npx is unavailable, run the following command from the root directory of your application:

node node_modules/cxiast-nodejs-agent/iast.js <MAIN_SCRIPT> [...args]

You can also add an npm script to the application's package.json file:

"scan": "cxiast <MAIN_SCRIPT>"

Then run it as follows:

npm run scan [-- ...args]

Note

MAIN_SCRIPT is the entry point of the application. It is usually defined in the main property of the application's package.json file. You can also set the application's folder instead of the file (e.g., npx cxiast .).

We recommend creating a new branch dedicated for CxIAST scanning and make the following changes to the Dockerfile:

Usually there is a RUN command to install the application's dependencies (e.g., RUN npm install --production). After that command, add in a new line:
RUN npm install --save-dev <MANAGER_ORIGIN>/iast/nodejs
If you are using Docker Compose go to the next section, otherwise, modify the ENTRYPOINT or CMD command and replace the application execution command with npx cxiast <MAIN_SCRIPT> where MAIN_SCRIPT is either the application main script file or its folder.

Examples:

Replace CMD ["npm", "start"] with CMD ["npx", "cxiast", "."]
Replace CMD ["node", "server.js"] with CMD ["npx", "cxiast", "server.js"]

Perform the first step in the Dockerfile instructions above (i.e., adding the RUN command) so that the agent is deployed in the build step.

In the yml file command entry, locate the application execution command and replace it with npx cxiast <MAIN_SCRIPT> where MAIN_SCRIPT is either the application main script file or its folder.

Example: Original yml file

       services:
          web:
            build: .
            command: sh -c "node artifacts/db-reset.js && npm start"
            ports:
              - "4000:4000"
        
          mongo:
            image: mongo:latest
            user: mongodb
            expose:
              - 27017

Modify to

        services:
          web:
            build: .
            command: sh -c "node artifacts/db-reset.js && npx cxiast ."
            ports:
              - "4000:4000"
        
          mongo:
            image: mongo:latest
            user: mongodb
            expose:
              - 27017

Follow these instructions, if there is no Internet connection available on the host that runs the application or when using a private npm repository.

From a host with access to the public npm repository:

Download node.js agent from the UI.
Extract the tar file's content to any location.
Rename the package folder where you extracted the file to cxiast-nodejs-agent.
Open a terminal and change the directory to the cxiast-nodejs-agent folder and run the following command:

npm install --production

Copy the cxiast-nodejs-agent folder to a location on the target host.
Open a terminal and change the directory to the application's root folder.
Run the command:

npm install --save-dev <cxiast-nodejs-agent folder location>

Example:

From a host with access to the public npm repository, download the node.js agent as follows: wget <MANAGER_ORIGIN>/iast/nodejs. All of the agent files are now in /home/my_user/package
Run mv package cxiast-nodejs-agent.
Copy /home/ubuntu/cxiast-nodejs-agent in the source machine to /opt/cxiast-nodejs-agent in the target machine.
Open a terminal in the target machine and chzange the directory to /opt/your_app.
Run the command npm install --save-dev /opt/cxiast-nodejs-agent.

Note

CxIAST node.js agent uses a custom C++ add-on which runs as a compiled binary for the machine it runs on. Therefore, the machine where the agent is built and the one it is running on must have the same OS and node.js version for the agent to work properly.

We recommend using npm to deploy the agent by setting the CxIAST manager as the source. However, when the CxIAST manager is configured to run with a self-signed certificate, this might be an issue. By default, npm has a strict SSL policy and will fail.

To temporarily disable the strict ssl policy, run the following command:

npm config set strict-ssl false

Use any of the deployment methods described above and then run the command to set the policy back to strict:

npm config set strict-ssl true

If the npm policy cannot be changed, set the environment variable NODE_EXTRA_CA_CERTS to the location of the SSL certificate file in PEM format (available from node v7.3 and above).

Configuration

During installation, the agent creates a new directory named .cxiast-data under the application's folder.

The folder includes a file named cx-agent-config.json.

There you can override the agent's default configuration in json format.

Configuration key	Supported values	Default value	Description
`protocol`	"http" / "https"	No default. Set according to IAST server configuration	IAST Manager connection protocol
`host`	string	"localhost"	IAST Manager connection host
`port`	unsigned int	8380	IAST Manager connection port
`logger.level`	"trace" / "info" / "warn" / "error"	"error"	Log level
`logger.format`	"text" / "json"	"text"	Log output format
`logger.transport`	"console" / "file"	"file"	Log output transport
`logger.logFolder`	string	"`<application folder>`/.cxiast_data/cxlogs"	Log files location
`logger.filename`	string	"nodejs-agent.log"	Filename will have a fix prefix of 'nodejs-agent--' and dynamic suffix: `<10 digits rand number><YYYY-MM-DD>`
`logger.maxLength`	unsigned int	0	Maximum length of a single log message
`logger.fileMaxSize`	unsigned int	10485760 (10 MB)	Maximum size (in Bytes) of a log file, default: 10
`logger.logCleanupIntervalDays`	int in [-1, 10]	10	Delete Agent log files older than X days, -1 will disable log retention. Note: value must be <= 10 days
`logger.compressFiles`	boolean	false	If true - will compress older files with .gz extension. Default: false
`logger.numOfLogsToExport`	unsigned int	2	Maximum number of log files that will be exported
`archiver.enabled`	boolean	true	If enabled, application source code and dependencies will be archived and uploaded to IAST manager to be viewed as result code snippets
`archiver.compressionLevel`	unsigned int	9	Compression level, the higher the level, the smaller the file and slower the compression
`archiver.compressionMethod`	"zip" / "tar"	"zip"	Compression method
`archiver.ignoreDependencies`	boolean	false	If enabled - dependencies code will be not included in the uploaded archive. Use when file gets too large or too much consumes is consumed
`checksum.extensionsFilter`	Array.<string>	[".js"]	Only files within the list will be archived and uploaded
`checksum.hashAlgorithm`	Any node.js hashing algorithm	"sha256"	Hash algorithm used to compare the local source code with the one from previous uploads
`agent.agentInitTimeout`	unsigned int	600000 (10 min)	How long the agent allows for compression and upload to complete (ms)
`agent.reportDelay`	unsigned int	2000 (s sec)	How long the agent waits after response is sent to client until it reports findings to Security Handler (ms)
`agent.reportThrottleWait`	unsigned int	50	Minimum report interval (ms)
`agent.maxStoredStringLength`	unsigned int	1000	Character limit for request / response body length in Security Handler payload
`agent.reportCoverageInterval`	null / unsigned int	null	Null - No reporting / Any number - Interval delay in ms
`agent.requestIDsRangeSize`	null / unsigned int	1000	For cluster mode, request ID allocation size
`agent.printSystemData`	boolean	true	Indicates whether or not the agent will print system data on startup
`agent.requestHashMaxResponseBodyLength`	null / unsigned int	null	Null - No limit, Any number - Number of characters limit
`agent.maxTaintedRangesPerSink`	unsigned int	50	Maximum number of tainted ranges per sink (the rest will be trimmed)
`agent.deepestTaintHistorySupport`	unsigned int	100	Set the deepest tracking flow which the system tracks.
`agent.maxSinksPerRequest`	unsigned int	200	Maximum number of sinks that will be sent in a single RequestData (the rest will be trimmed)
`agent.numOfDuplicatesInHistory`	null / int >= 2	5	Null - not removing duplicate entries at all, Number - number of duplicate entries not to remove (>=2)
`agent.recursionMaxDepth`	unsigned int	6	How deep objects are traversed recursively
`agent.allowSelfSignedCertificate`	boolean	true	If true - connection with IAST configured with a self signed SSL certificate will be accepted
`agent.requestsTimeout`	unsigned int	int / 4000 (4 sec)	How long to wait for manager response in ms, null for no timeout
`agent.autoUpdate`	boolean	true	If true - agent will be updated upon new version on next start
`agent.configOverrideFileName`	string	"`<application folder>`/.cxiast_data/cx-agent-config.json"	Override configuration file name
`agent.customizationsFileName`	string	"cx-agent-extensions.json"	Custom instrumentation file name
`agent.maxStringSizeCopyProperties`	unsigned int	1000	When copying a tainted string, properties will not be copied for strings larger than this number
`agent.metadataMandatory`	boolean	false	If true - the agent metadata CLI arguments are mandatory
`agent.maxTaintedStringSize`	unsigned int	10000	Strings larger than this value will not be tainted
`processCache.fsEnabled`	boolean	true	Disable the fs cache (development mode)
`processCache.excludeEnabled`	boolean	true	Disable the exclude (development mode)
`asyncHooks.logEnabled`	boolean	false	Log all the async operations details
`asyncHooks.logFile`	string	"`<application folder>`/.cxiast_data/async-operations.log"	File name for the async operations logs
`asyncHooks.addTrace`	boolean	true	Adds stack trace to the async operations logs
`stats.enabled`	boolean	false	If enabled - will generate aggregated overhead time per instrumentation
`stats.filename`	string	"cxstats"	Statistics file name
`stats.reportRate`	unsigned int	30000 (30 sec)	Statistics report rate

For example, your cx-agent-config.json file may look like

{ "protocol": "http", "host": "localhost", "port": 80, "logger": { "level": "error" }, "asyncHooks": { "logEnabled": true }, "agent": { "autoUpdate": false } }

In this section:

Setting up and Configuring the CxIAST Node.js Agent in the AUT Environmentoes

Pre-Requisites

Installation

Warning

Note

Note

Configuration

Search results