WebArmor IAST Agent 🛡️

The official Interactive Application Security Testing (IAST) agent for WebArmor.

Unlike traditional Dynamic Application Security Testing (DAST) scanners that test your web application from the outside, the WebArmor IAST Agent installs directly inside your Node.js runtime. This allows it to completely bypass WAFs, CAPTCHAs, and complex login flows to monitor vulnerabilities in real-time as your application runs.

Capabilities

Currently, the WebArmor Agent detects the following in real-time:

• Leaked Stack Traces (Critical): Intercepts HTTP 500 errors and immediately alerts you if raw stack traces or internal file paths (like node_modules/...) are exposed to the user.
• Missing Security Headers (Low/Medium): Monitors outgoing HTML responses to ensure critical headers like Content-Security-Policy are present.

Installation

Install the package via npm:

npm install webarmor-agent

Usage

To use the agent, you must provide your Target ID. This is a unique identifier (e.g., "cb54251f-307d-44f7-9253-2a5641a11b02") that tells the agent which dashboard to send vulnerability reports to. You can copy the exact initialization snippet pre-filled with your Target ID from the WebArmor Dashboard under your specific Target's "Agent-Based Scanning" settings.

WebArmor currently supports the following Node.js environments:

• Express.js
• Fastify
• Koa.js
• Native Node.js HTTP Server

Choose the setup that matches your framework below and replace "YOUR_TARGET_ID_HERE" with your actual Target ID.

Express.js

Attach the agent as top-level middleware in your Express application:

const express = require('express');
const { webarmorExpress } = require('webarmor-agent');

const app = express();

// 1. Initialize the WebArmor Agent FIRST
// Replace with your actual Target ID from the WebArmor Dashboard
app.use(webarmorExpress("YOUR_TARGET_ID_HERE"));

app.get('/', (req, res) => res.send('Hello World!'));
app.listen(3000, () => console.log('Server is running on port 3000'));

Fastify

Register the agent as a plugin in your Fastify application:

const fastify = require('fastify')();
const { webarmorFastify } = require('webarmor-agent');

// Register the WebArmor Agent plugin FIRST
fastify.register(webarmorFastify("YOUR_TARGET_ID_HERE"));

fastify.get('/', (request, reply) => reply.send('Hello World!'));
fastify.listen({ port: 3000 }, () => console.log('Server is running on port 3000'));

Koa.js

Use the agent as the first middleware in your Koa application:

const Koa = require('koa');
const { webarmorKoa } = require('webarmor-agent');

const app = new Koa();

// Use the WebArmor Agent middleware FIRST
app.use(webarmorKoa("YOUR_TARGET_ID_HERE"));

app.use(ctx => {
  ctx.body = 'Hello World';
});

app.listen(3000, () => console.log('Server is running on port 3000'));

Native Node.js HTTP Server

Wrap your request handler with the agent:

const http = require('http');
const { webarmorNode } = require('webarmor-agent');

const agent = webarmorNode("YOUR_TARGET_ID_HERE");

const server = http.createServer((req, res) => {
  // Pass req and res through the agent FIRST
  agent(req, res, () => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello World!\n');
  });
});

server.listen(3000, () => console.log('Server is running on port 3000'));

How It Works

1. When your server starts, the agent sends a lightweight telemetry ping to the WebArmor Dashboard.
2. The agent acts as an invisible middleware layer that wraps the res.write and res.end streams.
3. As responses leave your server, the agent analyzes the HTTP status codes, headers, and payload body.
4. If a vulnerability is detected (such as a 500 error leaking a stack trace), it instantly fires a vulnerability alert to your WebArmor Dashboard securely over HTTPS.

Security & Performance

The WebArmor Agent is designed to be completely non-blocking and fail-safe. If the agent cannot reach the WebArmor backend, it fails silently in the background and will never crash your host application or impact your user's request latency.