Scripts overview

This document explains the similarities, differences, and use cases for pre-request scripts and authentication scripts to help you choose the right script type for your scanning needs.

Overview

Both script types serve different purposes within the Invicti Platform scanning workflow.

Pre-request scripts

Pre-request scripts allow you to manipulate HTTP requests before sending them to the target. They execute based on URL patterns and provide flexibility for targeted request modifications such as adding headers, modifying payloads, or computing signatures.

Key characteristics:

• Applied selectively based on URL patterns.
• Use global scriptArg context containing http and variables.
• Execute independently for each matching request.
• Best for URL-specific modifications and data transformations.

Authentication scripts

Authentication scripts are specialized pre-request scripts that manage login sessions and token-based authentication throughout the scan lifecycle. They provide centralized session management with three main entry points: acquiring sessions, authenticating requests, and determining when re-authentication is needed.

Key characteristics:

• Applied automatically to all in-session requests.
• Use specific interface functions with defined arguments.
• Execute atomically with request queuing during session acquisition.
• Best for centralized authentication and session management.

Similarities between scripts

• Deployment requirement: for on-demand deployment, the Support team must enable Pre-request scripts feature.
• Upload method: both are uploaded to the UI using the Pre-request script (.js) option.
• Code requirements: written in vanilla JS code with possible calls to engine API.
• External modules: possible calls to external vanilla JS modules via ax.loadModule when imported into the target.
• Response handling: only responses for HTTP jobs initiated within the scripts are accessible.
• Single script limitation: each target can only use one script file, either pre-request or authentication.

Differences between scripts

Feature	Pre-request scripts	Authentication scripts
Application	Applied based on the URL.	Applied automatically to all requests.
Script structure	Single execution context with URL and script type directives.	Three interface functions: acquireSession(), authenticateRequest(), isReAuthenticationRequired().
Arguments/scope	Use global scriptArg containing the http object and variables.	Use only the specific arguments provided in the interface functions.
Concurrency	Often run at the same time, causing multiple login attempts.	Designed to be atomic/blocking; requests wait for the finish.
Primary purpose	Modify specific requests based on URL patterns.	Manage authentication lifecycle and session state across all requests.

Use cases

The following sections describe typical scenarios where each script type is most effective.

Pre-request scripts use cases

• Targeted data injection: adding a specific timestamp or random ID only to certain POST requests.
• Variable pre-processing: reading a global environment variable and hashing it (for example, HMAC) before sending.
• URL-specific logic: changing a header or parameter based solely on which endpoint is being called.
• Environment setup: initializing one-off data that doesn't require complex session tracking.
• Request signing: adding signatures to specific API endpoints.

Authentication scripts use cases

• Automatic session recovery: detecting a 401 Unauthorized and logging back in without stopping the test.
• Centralized auth logic: handling the heavy lifting of a login handshake once so the rest of the project is just logged in.
• Token management: configure auth scripts to detect expired tokens and re-acquire them automatically, or set specific intervals to refresh tokens before they expire.
• Bearer token authentication: managing OAuth or API token-based authentication.
• JWT authentication: handling JSON Web Token acquisition and lifecycle.

Script structure comparison

The following examples illustrate the fundamental structural differences between the two script types.

Pre-request script structure

/// url: /target/path
/// script_type: prerequestscript

var job = scriptArg.http;
var request = job.request;
var variables = scriptArg.variables;

// Modify request based on URL pattern
request.setHeader("Custom-Header", "Value");

Authentication script structure

/// script_type: authscript

const AuthScriptSettings = {
    tokenLifetimeInMs: 60000,
    // Additional configuration
};

let tokenValue = "";

function acquireSession(session) {
    // Obtain new authentication token
    // Return true on success, false on failure
}

function authenticateRequest(http) {
    // Add authentication data to outgoing request
    // Return true on success, false on failure
}

function isReAuthenticationRequired(http) {
    // Check if token is still valid
    // Return true if re-authentication needed, false otherwise
}

Summary

• Both script types are written in vanilla JavaScript, uploaded using the same UI option, and can leverage external modules for enhanced capability.
• Use Pre-request scripts for URL-specific modifications and simple data transformations, such as injecting custom headers for particular request paths.
• Use Authentication scripts for centralized session management that monitors session health and prevents redundant authentication attempts.

---

Need help?

Invicti Support team is ready to provide you with technical help. Go to Help Center