Skip to main content

Job File Specification

The following explains the Job file structure targeting: browser-based web applications and web APIs, both with and without authentication.

data​

A single resource object containing the following:

type​

The only valid value for this schema is Job.

attributes​

An attributes object containing the following:

version​

The schema version that the Job file must conform to.

sutAuthentication​

An object containing the following properties:

"sitesTreeSutAuthenticationPopulationStrategy": String,
"emissaryAuthenticationStrategy": String,
"route": String,
"usernameFieldLocater": String,
"passwordFieldLocater": String,
"submit": String,
"expectedPageSourceSuccess": String
  • sitesTreeSutAuthenticationPopulationStrategy - (Optional) (Mandatory for Browser App SUTs, meaningless for API SUTs) One of [ FormStandard | Link | NoAuthentication ]. The specific strategy used defines how the Emissary sites tree is populated for the SUT authentication URL. Only applicable for Job files that target Browser App SUTs. FormStandard and Link apply to authenticated SUTs, and NoAuthentication applies to non-authenticated SUTs. The only valid option for non-authenticated Browser App SUTs is NoAuthentication because there is no SUT authentication URL for non-authenticated Browser App SUTs
  • emissaryAuthenticationStrategy - (Optional, Default: NoAuthentication) One of [ FormStandard | ScriptLink | MaintainJwtJsonBasedBespokeCrApi | NoAuthentication ]. The specific strategy used defines how the Emissary should be authenticated to the SUT. FormStandard, ScriptLink applies to authenticated Browser App SUTs. MaintainJwtJsonBasedBespokeCrApi applies to authenticated APIs. NoAuthentication applies to non-authenticated Browser Apps and APIs. All of these strategy instances check to see if there are routes for a given Test Session, if there are they will each be added to the Emissary's scan Context. If there are no routes for a given Test Session the base URL (sutProtocol://sutHost:sutPort) will be added to the Emissary's scan Context with a .* following it so that everything under the base URL (sutProtocol://sutHost:sutPort) will be within the Emissary's scan Context. This allows the Build User to get either broad scans or narrowly focused scans. If you need a different behavior, discuss with us what you need
  • route - (Optional) (Mandatory for authenticated SUTs) A String specifying the route to authenticate to the SUT, conforming to the relevant regular expression in the Job schema
  • usernameFieldLocater - (Optional) (Mandatory for authenticated SUTs) A String that is used to find the element on the page (Browser App SUTs), or in an API request (API SUTs) to enter the username value to authenticate to the SUT. For Browser App SUTs, the String is used to search for the first occurrence of a DOM id, class name, or name that matches the given String. For APIs, the String is used as the parameter identifier. Must conform to the relevant regular expression in the Job schema
  • passwordFieldLocater - (Optional) Similar to usernameFieldLocater but for the password
  • submit - (Optional) Similar to usernameFieldLocater but to find the Browser App SUT page element to trigger authentication submission
  • expectedPageSourceSuccess - (Optional) (Mandatory for authenticated Browser App SUTs) A sub-string to expect as part of the response page to indicate that authentication has been successful. This is used by Selenium

sutHost​

A valid IP address or hostname (String) for the SUT you are targeting.

sutPort​

A valid port (Number) for the SUT you are targeting.

sutProtocol​

(Optional, Default: https) One of [ http | https ]. The only valid value for the TLS Tester is https.

browser​

(Optional) One of [ chrome | firefox (coming soon) ]. Only relevant for Job files that target Browser App SUTs. If not present the default will be chrome for Browser App SUTs.

forwardingProxy​

(Optional) Object containing the following properties:

"protocol": String,
"authorizationBase64": String,
"hostname": String,
"port": Number

  • protocol - (Optional, Default: http) The protocol of the explicit forwarding proxy you wish to pass through

  • authorizationBase64 - (Optional, Default: "" (an empty string)) The username:password base64 encoded, to authenticate to the explicit forwarding proxy you wish to pass through.
    For the string that you will need to base64 encode before adding as a string value to this property, the following examples are valid:

    • username or username: (if your forwarding proxy supports passwordless authentication)

    • username:password
      Where username can be made up of:

      • Lowercase alphabetical characters (a-z). In our testing, Squid didn't allow numbers, underscores, or capital letters in username
      • Hyphen (-)

      Where password can be made up of any keyboard character.

  • hostname - A valid IP address or hostname (String) for the explicit forwarding proxy you wish to pass through

  • port - (Optional, Default: 3128) The valid port (Number) for the explicit forwarding proxy you wish to pass through

loggedInIndicator​

(Optional) Sub-string to expect in a future response (from authenticated SUTs) indicating that the Emissary was successfully authenticated. See the Zaproxy documentation for additional details. Conflicts with loggedOutIndicator.

loggedOutIndicator​

(Optional) Sub-string to expect as part of a future response (from authenticated SUTs) indicating that the Emissary is not currently authenticated. See the Zaproxy documentation for additional details. Conflicts with loggedInIndicator.

relationships​

A relationships object containing a data (resource linkage) array of resource identifier objects. In the case of GuardRails, these refer to resource objects either [ tlsScanner | appScanner ].

data​

An array of resource identifier objects containing the following properties that identify the Test Session resource objects to be included in the Test Run:

{
  "type": ["tlsScanner"|"appScanner"],
  "id": String
}
  • type - One of [ tlsScanner | appScanner ]
  • id - The id of the type Test Session resource object being included

included​

An array of resource objects.

Such as Test Sessions (tlsScanner, appScanner) and route.

tlsScanner​

coming soon

The only valid number of tlsScanner resource objects is one.

type​

The only valid value is tlsScanner which defines the resource object.

id​

The only valid value is NA.

attributes​

An attributes object containing the following:

tlsScannerSeverity

(Optional) One of [ LOW | MEDIUM | HIGH | CRITICAL ].

If the TLS Tester finds a severity equal to or higher than the tlsScannerSeverity value, then it will be logged to reports: CSV and JSON only, as well as to the Graphical CLI bug counter. WARN is another level that translates to a client-side scanning error or problem. WARN and DEBUG records will always be seen in all reports if they occur.

INFO and OK records are only logged to CSV and JSON reports if the tlsScannerSeverity property doesn't exist. They are however logged to LOG and HTML reports regardless.

OK, INFO, WARN, and DEBUG records are not counted as defects.

All TLS Tester actions get logged to LOG and HTML reports, as well as to the CLI output. The CLI log for the TLS Tester is the same as the TLS Tester report but with some extra details about whether or not the Test Run was a pass or a fail. If it was a fail the CLI log for the TLS Tester will provide details about how many vulnerabilities exceeded the Build User defined alert threshold.

appScanner​

The only valid number of appScanner resource objects is from 1 to 12 inclusive if targeting a Browser App SUT, and 1 if targeting an API SUT.

type​

The only valid value is appScanner which defines the resource object.

id​

A String that conforms to the relevant regular expression in the Job schema.

attributes​

An attributes object containing the following:

sitesTreePopulationStrategy

(Optional, Default: WebDriverStandard) One of [ WebDriverStandard | ImportUrls | OpenApi | Soap | GraphQl ]. The specific strategy used defines how the Emissary sites tree is populated.

Use the WebDriverStandard strategy for a Job file that targets a Browser App SUT. Use one of [ ImportUrls | OpenApi | Soap | GraphQl ] depending on the API technology you are using in your SUT for a Job file that targets an API SUT.

spiderStrategy

(Optional, Default: Standard) One of [ Standard ]. The specific strategy used defines how the Emissary spider scans the SUT.

scannersStrategy

(Optional, Default: BrowserAppStandard) One of [ BrowserAppStandard | ApiStandard ]. The specific strategy used defines which Emissary scanners are activated and how they are configured.

Use the BrowserAppStandard strategy for a Job file that targets a Browser App SUT. Use the ApiStandard strategy for a Job file that targets an API SUT.

scanningStrategy

(Optional, Default: BrowserAppStandard) One of [ BrowserAppStandard | ApiStandard ]. The specific strategy used defines how the Emissary carries out its scanning.

Using the default strategy for a Job file that targets a Browser App SUT, both the Emissary's spider and the active scanner will scan all routes in a given Test Session if there are any. If there are none then the base URL (sutProtocol://sutHost:sutPort) will be scanned recursively. This allows the Build User to get either broad scans or narrowly focused scans. If you need a different behavior, discuss with us what you need.

For a Job file that targets an API SUT, you will need to use ApiStandard. Both the Emissary's spider and the active scanner will scan all routes specified in the API definition you provide unless specific routes are added to the excludedRoutes array.

postScanningStrategy

(Optional, Default: BrowserAppStandard) One of [ BrowserAppStandard | ApiStandard ]. The specific strategy used defines how the Emissary carries out its immediate post-scanning activities. BrowserAppStandard is only applicable for Job files that target Browser App SUTs. ApiStandard is only applicable to Job files that target APIs.

reportingStrategy

(Optional, Default: Standard) One of [ Standard ]. The specific strategy used here defines how the Emissary carries out its post-scanning reporting activities.

username

(Optional) (Mandatory for authenticated SUTs) A String used to authenticate to your SUT and/or for various other calls to the Emissary API. Must conform to the relevant regular expression in the Job schema.

passwordBase64

(Optional) base64 encoded String password used to authenticate to your SUT. Simply base64 encode the usual password that you would use to authenticate to your SUT.

note

For a Job file that targets an API SUT, specify one of the following [ openApi | soap | graphQl | importUrls ].

openApi

(Optional) Object containing one of [ importFileContentBase64 | importUrl ]. See openApi below for more details. Conflicts with soap, graphQl, and importUrls.

soap

(Optional) Object containing one of [ importFileContentBase64 | importUrl ]. See soap below for more details. Conflicts with openApi, graphQl, and importUrls.

graphQl

(Optional) Object containing one of [ importFileContentBase64 | importUrl ], as well as options to override the default behavior of the Emissary. See graphQl below for more details. Conflicts with openApi, soap, and importUrls.

importUrls

(Optional) Object containing one of [ importFileContentBase64 ]. See importUrls below for more details. Conflicts with openApi, soap, and graphQl.

aScannerAttackStrength

(Optional, Default: HIGH) One of [ LOW | MEDIUM | HIGH | INSANE ]. We usually recommend setting this to MEDIUM for API SUTs.

aScannerAlertThreshold

(Optional, Default: LOW) One of [ LOW | MEDIUM | HIGH ].

excludedRoutes

(Optional) Array of regular expression strings containing route sub-strings to be added to the Emissary's "Exclude from Context" list. These can be quite useful if you have decided to create an appScanner Test Session with no associated route resource objects which means the App Emissary will be scanning from sutProtocol://sutHost:sutPort recursively including all resources under it.

relationships​

(Optional) (Mandatory for Browser App SUTs, meaningless for API SUTs) A relationships object containing a data (resource linkage) array of resource identifier objects. In the case of GuardRails, these refer to route resource objects.

data

An array (can be empty) of resource identifier objects containing the following properties:

{
  "type": "route",  
  "id": String
}

route​

(Optional) (Mandatory for Browser App SUTs that have a resource linkage to it, meaningless for API SUTs) None to many route resource objects can be present.

type​

The only valid value is route which defines the resource object.

id​

A String that conforms to the relevant regular expression in the Job schema.

attributes​

An attributes object containing the following properties:

  "attackFields": [
    {"name": String, "value": [String|Boolean|Number], "visible": Boolean}
  ],
  "method": ["GET"|"PUT"|"POST"],
  "submit": String
  • attackFields - Are optional objects with fields: name, value, (Optional) visible. If visible is not defined, or set to false, the given field will not be attacked
  • method - One of [ GET | PUT | POST ]
  • submit - A String that is used to find the element on the page to submit. The String is used to search for the first occurrence of a DOM id, class name, or name that matches the given String

Sub Resources​

The best way to make sure that you're API spec is valid, is to import it into Zaproxy. Zap will then spider the SUT, if you see validation issues, you'll need to adjust your API spec. Once this is done, you can base64 encode it and add it to your Job file. Details below.

Base64 encoding API definition file contents.
On a Linux system you can encode a text file by following these directions:

  1. base64 --wrap=0 [plain-text-file.json > [encoded-file]
  2. If you would like to check the results:
    base64 --decode [encoded-file] > [decoded-plain-text-file]
  3. Diff your original [plain-text-file].json with the [decoded-plain-text-file]
  4. Add the contents of the [encoded-file] to the importFileContentBase64 value of your Job file:
    1. cat [encoded-file]
    2. Copy the printed text but not the % at the end
    3. Using VSCode (or your preferred text editor), paste the copied text into the property value of the Job file
    4. Check the Job file with VSCode or Vim

openApi​

An object containing the following properties:

"importFileContentBase64": String,
"importUrl": String
  • importFileContentBase64 - (Optional) The base64 encoded file contents of your API definition. Conflicts with importUrl
  • importUrl - (Optional) The URL to your API definition. Conflicts with importFileContentBase64

soap​

An object containing the following properties:

"importFileContentBase64": String,
"importUrl": String
  • importFileContentBase64 - (Optional) The base64 encoded file contents of your API definition. Conflicts with importUrl
  • importUrl - (Optional) The URL to your API definition. Conflicts with importFileContentBase64

graphQl​

An object containing the following properties:

"importFileContentBase64": String,
"importUrl": String
  • importFileContentBase64 - (Optional) The base64 encoded file contents of your API definition. Conflicts with importUrl
  • importUrl - (Optional) The URL to your API definition. Conflicts with importFileContentBase64
  • maxQueryDepth - (Optional, Default: 5) Specifies the maximum query generation depth
  • maxArgsDepth - (Optional, Default: 5) Specifies the maximum arguments generation depth
  • optionalArgsEnabled - (Optional, Default: true) Boolean that specifies whether or not Optional Arguments should be specified
  • argsType - (Optional, Default: BOTH) One of [ INLINE | VARIABLES | BOTH ]. Specifies how arguments are specified
  • querySplitType - (Optional, Default: LEAF) One of [ LEAF | ROOT_FIELD | OPERATION ]. Specifies the level for which a single query is generated
  • requestMethod - (Optional, Default: POST_JSON) One of [ POST_JSON | POST_GRAPHQL \ GET ]. Specifies the request method

importUrls​

An object containing the following properties:

"importFileContentBase64": String
  • importFileContentBase64 - The base64 encoded file contents of the URLs. The file contents before encoding must be plain text with one URL per line
Last updated on by Stefan Streichsbier