Client Side Integration - Automation Framework Support

This add-on supports the Automation Framework.

Job: spiderClient

The spiderClient job allows you to run the Client Spider, which is designed to explore modern web apps more effectively.

This job supports monitor tests.

  - type: spiderClient                 # The client spider - a spider which explores modern web apps more effectively
    parameters:
      context:                         # String: Name of the context to spider, default: first context
      user:                            # String: An optional user to use for authentication, must be defined in the env
      url:                             # String: URL to start spidering from, default: first context URL
      maxDuration:                     # Int: The max time in minutes the spider will be allowed to run for, default: 0 unlimited
      maxCrawlDepth:                   # Int: The maximum tree depth to explore, default 5
      maxChildren:                     # Int: The maximum number of children to add to each node in the tree
      numberOfBrowsers:                # Int: The number of browsers the spider will use, more will be faster but will use up more memory, default: number of cores/2 max 8
      browserId:                       # String: Browser ID to use, default: firefox-headless
      initialLoadTime:                 # Int: The time in seconds to wait after the initial URL is loaded, default: 0
      pageLoadTime:                    # Int: The time in seconds to wait after a new URL is loaded, default: 0
      actionWaitTime:                  # Int: The time in seconds to wait after performing an action (e.g. clicking a button), default: 0
      shutdownTime:                    # Int: The time in seconds to wait after no activity before shutting down, default: 5
      scopeCheck:                      # String: The scope check, either Flexible or Strict, default: Flexible
      logoutAvoidance:                 # Bool: When enabled, the spider will avoid clicking common logout elements, default: true
      runOnlyIfModern:                 # Boolean: If true then the spider will only run if a "modern app" alert is raised, default: false

If ‘runOnlyIfModern’ is set to ‘True’ then the passiveScan-wait job MUST be run before this one and the Modern Web Application rule installed and enabled. If either of those things are not done then the Client Spider will always run and a warning output. If they are both done and no “Modern Web Application” alert is raised then the assumption is made that this is a traditional app and therefore the Client Spider is not needed.

Job: spiderAjax (AJAX Spider add-on not installed)

If the AJAX Spider add-on is not installed then this add-on also registers a spiderAjax job, which runs the Client Spider in its place, so that existing plans which use the AJAX Spider keep working. Only the parameters also supported by the spiderClient job (above) are applied; any AJAX Spider only parameters (for example clickDefaultElems or randomInputs) are ignored, and a warning is raised to say that the Client Spider is being used instead.

If the AJAX Spider add-on is installed while ZAP is running then this add-on hands control of the spiderAjax job type back to it (and takes it back if the AJAX Spider add-on is later uninstalled). However, a plan that is already open in the Automation Framework tab at the time will keep using the Client Spider for any spiderAjax job it contains - close and reopen the plan (or reload the plan file) to pick up the AJAX Spider add-on’s own job.

Job: export (Client Map)

When the Import/Export add-on is installed, the Client Map can be exported via the standard export job using source: clientmap and type: yaml. The YAML produced by this job differs from the manual Client Map export, for example it includes url fields and omits components.

  - type: export            # Exports the Client Map
    parameters:
      context:            # String: Name of the context from which to export. Default: first context
      type: yaml            # YAML is the only supported format for the Client Map
      source: clientmap     # Export the Client Map
      fileName:             # String: Name/path of the output file

An example of the YAML produced:

- node: "ClientMap"
  children:
  - node: "http://localhost:3000"
    url: "http://localhost:3000/"
    children:
    - node: "/"
      url: "http://localhost:3000/"
      visited: false
    - node: "/#"
      url: "http://localhost:3000/#"
      visited: false
      children:
      - node: "/"
        url: "http://localhost:3000/#/"
      - node: "/about"
        url: "http://localhost:3000/#/about"
      - node: "/contact"
        url: "http://localhost:3000/#/contact"
      - node: "/forgot-password"
        url: "http://localhost:3000/#/forgot-password"
      - node: "/login"
        url: "http://localhost:3000/#/login"
      - node: "/photo-wall"
        url: "http://localhost:3000/#/photo-wall"
      - node: "/register"
        url: "http://localhost:3000/#/register"

Passive Scan Rules

The Client Passive Scan Rules can be set via the standard passiveScan-config job.