Job File Structure

  • The following explains the Job file structure
  • Examples can be found at the CLI Github
  • The Job schema is where the validation of the Job file takes place
  • The Job file also conforms to jsonapi
  • All properties are considered mandatory unless specified as optional


data

A single resource object containing the following:

type

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

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:

{
  "route": String,
  "usernameFieldLocater": String,
  "passwordFieldLocater": String,
  "submit": String,
  "expectedPageSourceSuccess": String
}
  • route String specifying the route to authenticate to the SUT, conforming to the relevant regular expression in the Job schema
  • usernameFieldLocater String that is used to find the element on the page to enter the username value in order to authenticate to the SUT. The String is used to search for the first occurrence of a DOM id, class name, or name that matches the given String. Must conform to the relevant regular expression in the Job schema
  • passwordFieldLocater Similar to usernameFieldLocater but for the password
  • submit Similar to usernameFieldLocater but to find the page element to trigger submission
  • expectedPageSourceSuccess A sub String to expect as part of the response page to indicate that authentication has been successful. This is used by Selenium

sutIp

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

sutPort

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

sutProtocol

One of [ http | https ]. This property is optional, if not present the default will be https. The only valid value for the TSL Tester is https.

browser

One of [ chrome | firefox ]. This property is optional, if not present the default will be:

  • For client-side validation: What is specified in the CLI config file under sut.browser
  • For server-side validation: What is specified in the orchestrator config file under sut.browser

These config values are passed into the Job schema.

loggedInIndicator

Similar to expectedPageSourceSuccess, except that it is used by the App Emissary (Zaproxy).

relationships

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

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": [The id of a Test Session resource object to include in this Test Run]
}


included

An array of resource objects.

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

tlsScanner

The only valid number of tlsScanner resource objects is one.

This is handled in the orchestrator’s Tester models. A meaningful error will be generated and returned to the CLI if this number is not correct. Part of the orchestrator’s initialisation phase of each Tester is to validate that the number of their Test Session resource objects fits within the allowed range. If they don’t then none of the Testers will be started.

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

The tlsScannerSeverity property is optional. If it is present it’s value must be one of the following values (which can also be seen in the Job schema ane/or the config file for the TLS Tester):
[ 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 which 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 around how many vulnerabilities exceeded the Build User defined alert threshold.

alertThreshold

The alertThreshold property is optional. If it is present it’s value must be between 0 and 1000. This property is useful for expressing the number of defects you expect to be found, any defects over and above this number will fail the Test Run. If the alertThreshold exists in the Job file, it allows the Build User to ignore alerts for the sake of a Test Run passing.

appScanner

The only valid number of appScanner resource objects is from 1 to 12 inclusive.

This is handled in the orchestrator’s Tester models. A meaningful error will be generated and returned to the CLI if this number is not correct. Part of the orchestrator’s initialisation phase of each Tester is to validate that the number of their Test Session resource objects fits within the allowed range. If they don’t then none of the Testers will be started.

type

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

id

Any string that conforms to the relevant regular expression in the Job schema.

attributes

An attributes object containing the following:

username

The optional user name string used to authenticate to your SUT. Must conform to the relevant regular expression in the Job schema.

password

The optional password string used to authenticate to your SUT.

aScannerAttackStrength

The aScannerAttackStrength property is optional. If it is not present it defaults to HIGH. If it is present it’s value must be one of the following values (which can also be seen in the Job schema ane/or the config file for the App Tester):
[ LOW | MEDIUM | HIGH | INSANE ]

aScannerAlertThreshold

The aScannerAlertThreshold property is optional. If it is not present it defaults to LOW. If it is present it’s value must be one of the following values (which can also be seen in the Job schema ane/or the config file for the App Tester):
[ LOW | MEDIUM | HIGH ]

alertThreshold

The alertThreshold property is optional. If it is present it’s value must be between 0 and 1000. This property is useful for expressing the number of defects you expect to be found, any defects over and above this number will fail the Test Run. If the alertThreshold exists in the Job file, it allows the Build User to ignore alerts for the sake of a Test Run passing.

relationships

A relationships object containing a data (resource linkage) array of resource identifier objects. In the case of PurpleTeam, these refer to route resource objects.

data

An Array of resource identifier objects containing the following properties:

{
  "type": "route",  
  "id": [The id of a route resource object to include in this appScanner Test Session]
}

route

0 to many route resource objects can be present.

type

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

id

Any 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, "visible" [Boolean]}
  ],
  "method": ["GET"|"PUT"|"POST"],
  "submit": String
  • attackFields are optional objects with optional name, value and whether or not they are visible
  • method can be one of [ GET | PUT | POST ]
  • submit 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
Previous
Next