Sparrow Enterprise Runtime Agent

The runtime agent for instrumenting Node.js applications used in the following products in Sparrow Enterprise:

• TSO (Test Suite Optimization)
• RASP (Runtime Application Self Protection)
• DAST (Dynamic Application Software Testing) TrueScan

Installation

Install using the following command.

npm install sparrow-enterprise-runtime-agent

Quick Start

Command Line Interface (CLI)

The agent can be run with the target application without modifying the source code of the target application.

node --require sparrow-enterprise-runtime-agent {app.js} -conf {config.json}

app.js: Path to the entry point of the target application

config.json: Path to the agent configuration file

Embedded in Code

The agent can be loaded by inserting a single statement at the top of the entry point module of the target application.

require('sparrow-enterprise-runtime-agent');

require('target-module-a');
require('./target-module-b.js');
// ...

NOTE: In order to instrument the modules of the target application, the agent must be 'required' before them.

After inserting the require statement, the target application can be run by passing the configuration option like below.

node {app.js} -conf {config.json}

Configuration

The agent can be configured by setting the option values in config.json, which should be stored at the root directory of the target application.

The configuration is divided into five parts.

• Broker Server Interaction
  • sparrow.url: URL of the Broker Application
  • sparrow.opt.brokerTimeout: Timeout for Broker communication(ms), default: 3,000
  • sparrow.opt.detectionMaxCount: Maximum number of detections in one batch, default: 10,000
  • sparrow.opt.samplingPeriod: Period of detection sampling(ms), default: 100
  • sparrow.opt.heartbeatPeriod: Heartbeat period(ms), default: 5,000
• Backend Server Authentication
  • sparrow.username: Username of the Sparrow Enterprise user
  • sparrow.password: Password of the Sparrow Enterprise user
  • sparrow.projectKey: Key of the project that the agent should belong to
• Agent Information
  • sparrow.agent: Agent name
• Instrumentation
  • sparrow.opt.presets: Pre-defined lists of target signatures
    • Currently supports RASP_DEFAULTS
  • sparrow.opt.included: List of target signatures to be instrumented
  • sparrow.opt.excluded: List of target signatures not to be instrumented
• Logging
  • sparrow.opt.logPath: Path of the log file to be saved.
    • If this option is left blank, no log files will be saved.

Example:

{
  "sparrow.url": "192.168.100.98:10800",
  "sparrow.username": "jsmith",
  "sparrow.password": "password",
  "sparrow.projectKey": "test-project",
  "sparrow.agent": "jsmith-agent",
  "sparrow.opt.brokerTimeout": 3000,
  "sparrow.opt.detectionMaxCount": 10000,
  "sparrow.opt.samplingPeriod": 100,
  "sparrow.opt.heartbeatPeriod": 5000,
  "sparrow.opt.presets": ["RASP_DEFAULTS"],
  "sparrow.opt.included": ["express.lib.router.*"],
  "sparrow.opt.excluded": [],
  "sparrow.opt.logPath": "./log"
}

Supported Technologies

• Node.js version >= 12.22.12
• CommonJS module imports

Technology Stack

• Node.js
• gRPC
• Acorn