Skip to main content

Scripting

This page describes the general concepts and paradigms when adding scripts to the ZAP-Scan.

Warning

Script jobs are supported only on the DAST-CLI and are blocked for CheckmarxOne users for security reasons.

Scripts - Overview

The ZAP-Engine can execute external code (scripts) during the ZAP-scan.

This code interacts with ZAP internal objects and can be used to extract information not normally exported from the Engine or to influence the flow of the scan.

The ZAP-Engine comes with a series of built-in scripts that are ready to use. Also, there are community scripts that can be used as a base for custom scripts, tailor-made for specific sites: ZAP Community Scripts repo

Built-in scripts can be enabled or disabled, and custom scripts can be added or removed.

Supported languages:

Script-categories

Scripts are divided into categories:

  • Authentication - executed when the Engine detects it needs to authenticate before proceeding

  • Encode/Decode - help encode/decode payloads to be used by other scripts

  • HTTP Sender - executed on captured requests and/or responses

  • Proxy - change the behavior of ZAP’s internal proxy

  • Selenium - effective for jobs that utilize Selenium (Spider-Ajax for example);

    Can extract/modify data and/or DOM from within the browser

  • Session Management - executed after authentication (if applicable), used to reuse the session during the scan

  • Stand Alone - executed before or after a scan;

    Can be used for authentication in a demo, or to extract internal-engine-information

    (for example, extracting the list of attacked URLs).

Scripts structure

Many scripts contain:

  • Functions triggered by the ZAP-Engine’s objects. Those functions receive objects that expose the internal objects of ZAP to the script code, for example, request, response, session, and user credentials. Each script category uses a different set of methods, see https://github.com/zaproxy/community-scripts for detailed examples

  • A function that defines the required parameters for the script:

    getRequiredParamsNames() { return [“param1“, “param2”, …]; }

  • A function that defines the optional parameters for the script:

    getOptionalParamsNames() { return [“param1“, “param2”, …]; }

Automation

Warning

All script paths must be absolute paths due to a bug in the ZAP-Engine.

In order to use a script during the scan:

Each script job must contain the following parameters:

  • action - add/remove/enable/disable

  • type - the category

  • engine - the engine that will run the code

  • name - a label for the script

  • file - the location of the script;

    Alternatively - the content of the script can be in the inline parameter

Script Job Examples:

  • The script files are present at (or mounted into) /home/ubuntu

- parameters:
    action: "add"
    type: "authentication"
    engine: "ECMAScript : Graal.js"
    name: "ginandjuice"
    file: "/home/ubuntu/ginandjuice_auth.js"
    target: ""
    inline: ""
  name: "script"
  type: "script"
- parameters:
    action: "add"
    type: "session"
    engine: "ECMAScript : Graal.js"
    name: "ginandjuice_session"
    file: "/home/ubuntu/ginandjuice_session.js"
    target: "https://ginandjuice.shop"
    inline: ""
  name: "script"
  type: "script"

Notice

DAST-CLI supports Graal.js and Zest out of the box since these script engines are integrated into the ZAP package. CheckmarxOne users are blocked from using scripts for security reasons.

Other engines are required to add a plugin (which is not supported in the DAST-Workers).

Examples of engine names:

  • "ECMAScript : Graal.js"

  • "Zest : Mozilla Zest"

  • "ECMAScript : Oracle Nashorn"

  • "python : jython"

Referencing Scripts in the Configuration

Authentication and session management can directly reference scripts.

The scripts must be added in a script-job in order to be available

env:
  contexts:
    - name: "GinAndJuice"
      ...
      authentication:
        method: "script"
        parameters:
          script: "/home/ubuntu/ginandjuice_auth.js"
          scriptEngine: "ECMAScript : Graal.js"
          ...
      sessionManagement:
        method: "script"
        parameters:
          script: "/home/ubuntu/ginandjuice_session.js"
          scriptEngine: "ECMAScript : Graal.js"
      ...

DAST-CLI

In order for the ZAP-CLI (within the DAST-CLI container) to utilize the scripts, the script files must be mounted inside the container, just like the configuration file.

Except for mounting the script files, there are no other required modifications on the docker run command.

See Installing the DAST CLI in a Pipeline for more details on the docker run command.

GinAndJuice

  • These files are to be used as a reference to how scripts are built and how a configuration file can add and link scripts to the authorization process. They will require modifications in order to run as a demo.

  • Due to a bug in the Windows GUI for ZAP, when running a regular proxy scan, the authorization script must use hard-coded credentials.

    Running scans in automation (ZAP-CLI or GUI) works as expected.

ginandjuice_session.js

ginandjuice_yaml

ginandjuice_auth.js

In this section: