Automation Framework - Environment

This section of the YAML configuration file defines the applications which the rest of the jobs can act on.

The environment is covered in the video: ZAP Chat 08 Automation Framework Part 2 - Environment.

The Automation Framework supports all of the authentication mechanisms supported by ZAP.

Note When testing targets that operate on default ports (80 for http, 443 for https), the colon port portion of the URL should not be included. Including that portion (for example: http://example.com:80) may result in an inability to crawl or test the target. If a ‘default’ port is specified both browsers and ZAP treat it without the default port being included then it doesn’t match the expectation within the Context and there’s nothing to interact with as part of the Context.

env:                                   # The environment, mandatory
  contexts :                           # List of 1 or more contexts, mandatory
    - name: context 1                  # Name to be used to refer to this context in other jobs, mandatory
      urls:                            # A mandatory list of top level urls, everything under each url will be included
      includePaths:                    # An optional list of regexes to include
      excludePaths:                    # An optional list of regexes to exclude
      authentication:
        method:                        # String, one of 'manual', 'http', 'form', 'json' or 'script'
        parameters:                    # May include any required for scripts. All of the parameters support vars except for the port 
          hostname:                    # String, only for 'http' authentication
          port:                        # Int, only for 'http' authentication
          realm:                       # String, only for 'http' authentication
          loginPageUrl:                # String, the login page URL to read prior to making the request, only for 'form' or 'json' authentication
          loginRequestUrl:             # String, the login URL to request, only for 'form' or 'json' authentication
          loginRequestBody:            # String, the login request body - if not supplied a GET request will be used, only for 'form' or 'json' authentication
          script:                      # String, path to script, only for 'script' authentication
          scriptEngine:                # String, the name of the script engine to use, only for 'script' authentication
        verification:
          method:                      # String, one of 'response', 'request', 'both', 'poll'
          loggedInRegex:               # String, regex pattern for determining if logged in
          loggedOutRegex:              # String, regex pattern for determining if logged out
          pollFrequency:               # Int, the poll frequency, only for 'poll' verification
          pollUnits:                   # String, the poll units, one of 'requests', 'seconds', only for 'poll' verification
          pollUrl:                     # String, the URL to poll, only for 'poll' verification
          pollPostData:                # String, post dat to include in the poll, only for 'poll' verification
          pollAdditionalHeaders:       # List of additional headers for poll request, only for 'poll' verification
          - header:                    # The header name
            value:                     # The header value
      sessionManagement:
        method:                        # String, one of 'cookie', 'http', 'script'
        parameters:                    # List of 0 or more parameters - may include any required for scripts
          script:                      # String, path to script, only for 'script' session management
          scriptEngine:                # String, the name of the script engine to use, only for 'script' session management
      technology:
        exclude:                       # List of tech to exclude, as per https://www.zaproxy.org/techtags/ (just use last names)
        include:                       # List of tech to include, should only be used when targeting specific techs, the exclude takes precedence when configuring the context.
      structure:
        structuralParameters:          # List of names of structural parameters.
      users:                           # List of one or more users available to use for authentication
      - name:                          # String, the name to be used by the jobs
        credentials:                   # List of user credentials - may include any required for scripts
          username:                    # String, the username to use when authenticating, vars supported
          password:                    # String, the password to use when authenticating, vars supported
  vars:                                # List of 0 or more custom variables to be used throughout the config file
    myVarOne: CustomConfigVarOne       # Can be used as ${myVarOne} anywhere throughout the config
    myVarTwo: ${myVarOne}.VarTwo       # Can refer other vars    
  parameters:
    failOnError: true                  # If set exit on an error         
    failOnWarning: false               # If set exit on a warning
    continueOnFailure: false           # Continue running all jobs, even if one fails
    progressToStdout: true             # If set will write job progress to stdout
  proxy:                               # Optional upstream proxy settings
    hostname:                          # String, the proxy host
    port:                              # Int, the proxy port
    realm:                             # String, the proxy realm
    username:                          # String, the proxy username
    password:                          # String, the proxy password

Variables

Variables can be defined in the ‘vars’ section. They can be hardcoded, refer to other variables or refer to system environment variables in the same way as above, e.g. ‘${envvar}’. In case there are two variables with the same name, the value of the system variable would be preferred.

Format Changes

Originally the ’engine’ and ‘scriptEngine’ fields were directly under the ‘sessionManagement’ element - this is still supported when reading plans but they will now always be output under the ‘parameters’ element.

Originally the ‘username’ and ‘password’ fields were directly under the user element - this is still supported when reading plans but they will now always be output under the ‘credentials’ element.

When specifying technology the tech names are given on https://www.zaproxy.org/techtags/ - only specify the last name, e.g. “C”.