Security

Malicious URL Scanner

Web Application Firewall at the URL level, powered by the StruLink analysis engine. Scans all incoming requests to detect malicious patterns before they reach your controllers or routers.

What It Protects Against

Cross-Site Scripting (XSS) via the URL
Path Traversal (`../..`)
SQL and NoSQL injections in query parameters
Command Injections
Template Injections (SSTI)

Quick Setup

Enable the scanner with default settings (actively block malicious URLs):

typescript

import { createServer } from "xypriss";

const app = createServer({
    security: {
        maliciousUrlScanner: true,
    }
});

Disabling the Scanner

Not recommended in production, but possible for development or internal networks:

typescript

const app = createServer({
    security: {
        maliciousUrlScanner: false,
    }
});

Or explicitly via the configuration object:

typescript

const app = createServer({
    security: {
        maliciousUrlScanner: {
            enabled: false
        }
    }
});

Operating Modes

block (Default)

Immediately blocks the request if a malicious pattern is detected. Returns 403 Forbidden with internal error code EMALICIOUSURL.

log

Allows the request to pass but generates a security alert via the XyPriss logger (logger.warn). Ideal for an audit period to identify potential false positives before switching to blocking mode.

typescript

const app = createServer({
    security: {
        maliciousUrlScanner: {
            enabled: true,
            mode: "log", // observation mode
        }
    }
});

Advanced StruLink Configuration

Fine-tune the analysis behavior by passing options directly to the StruLink engine:

typescript

import { MaliciousPatternType } from "strulink";

const app = createServer({
    security: {
        maliciousUrlScanner: {
            enabled: true,
            mode: "block",
            options: {
                minScore: 40,
                sensitivity: 1.0,
                enabledPatternTypes: [
                    MaliciousPatternType.XSS,
                    MaliciousPatternType.PATH_TRAVERSAL,
                    MaliciousPatternType.COMMAND_INJECTION,
                    MaliciousPatternType.SQL_INJECTION
                ],
                advanced: {
                    maxEncodingLayers: 3,
                    entropyThreshold: 4.8
                }
            }
        }
    }
});

Engine Defaults

If no specific options are provided, the scanner applies the following strict settings:

minScore40

sensitivity1.0

advanced.maxEncodingLayers3

advanced.entropyThreshold4.8

Error Behavior (Fail-Open)

If the StruLink engine encounters an unexpected error while processing a URL, the scanner adopts a Fail-Open behavior. The error is logged (logger.error), but the request is allowed to continue. This prevents a parsing error from bringing down the entire application.

Production Recommendation

Keep mode: "block" in production. Use mode: "log" only during audit periods to tune minScore and sensitivity without disrupting traffic.

CORS Policy

Control cross-origin access with pattern matching, wildcard, and regex origin support.