Browser App Job File Structure

The following explains the Job file structure targeting browser based web applications.


Table of Contents

data

A single resource object containing the following:

type

The type defines the resource and which schema that will be used. The only valid value for this schema is BrowserApp.

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) One of [ FormStandard | Link ]. If not present the default will be FormStandard. The specific strategy used here defines how the Emissary sites tree is populated for the SUT authentication URL. Only used for the BrowserApp Job schema
  • emissaryAuthenticationStrategy - (Optional, Default: FormStandard) One of [ FormStandard | ScriptLink ]. The specific strategy used defines how the Emissary should be authenticated to the SUT. The default strategy for the BrowserApp schema checks 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 (sutIp) will be added to the Emissary’s scan Context with a .* following it so that everything under the base URL (sutIp) will be within the Emissary’s scan Context. This allows the Build User to get either broad scans or narrow focussed scans. If you need a different behaviour discuss with us what you need.
  • route - A String specifying the route to authenticate to the SUT, conforming to the relevant regular expression in the Job schema
  • usernameFieldLocater - (Optional) A 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 - (Optional) Similar to usernameFieldLocater but for the password
  • submit - (Optional) 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

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

browser

(Optional) One of [ chrome | firefox ]. 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

The browser config values are passed into the BrowserApp Job schema. Only used for the BrowserApp Job schema.

loggedInIndicator

(Optional) Sub-string to expect in a future response 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 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 PurpleTeam, these refer to one of [ tlsScanner | appScanner | serverScanner (coming soon)] 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": String
}
  • type - One of [ tlsScanner | appScanner | serverScanner (coming soon)]
  • id - The id of the type Test Session resource object being included

included

An array of resource objects.

Such as Test Sessions (tlsScanner, appScanner, serverScanner (coming soon)) 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

(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 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

(Optional) If present it’s value must be between 0 and 9999. 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

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 ]. The specific strategy used defines how the Emissary sites tree is populated

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 ]. The specific strategy used defines how the Emissary scanners are configured

scanningStrategy

(Optional, Default: BrowserAppStandard) One of [ BrowserAppStandard ]. The specific strategy used defines how the Emissary carries out it’s scanning. Using the default strategy for the BrowserApp schema both the Emissary’s spider and active scanner will scan all routes in a given Test Session if there are any. If there are non then the base URL (sutIp) will be scanned recursively. This allows the Build User to get either broad scans or narrow focussed scans. If you need a different behaviour discuss with us what you need

postScanningStrategy

(Optional, Default: BrowserAppStandard) One of [ BrowserAppStandard ]. The specific strategy used defines how the Emissary carries out it’s immediate post scanning activities

reportingStrategy

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

reports

(Optional) object containing the single property templateThemes array. If not present all report types will be generated. See templateThemes below for more details.

Just be aware that the AWS API Gateway only allows responses of 10MB maximum, if the outcomes archive is larger than that, then you will receive a generic error: Error occurred while downloading the outcomes file, error was: purpleteam Cloud API responded with "orchestrator is down" due to a 500 error from API Gateway. If this happens, reduce the set of reports you specify.

username

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.

password

(Optional) String used to authenticate to your SUT.

aScannerAttackStrength

(Optional, Default: HIGH) The default is specified in the App Tester config file. One of [ LOW | MEDIUM | HIGH | INSANE ].

aScannerAlertThreshold

(Optional, Default: LOW) The default is specified in the App Tester config file. One of [ LOW | MEDIUM | HIGH ]

alertThreshold

(Optional, Default: 0) If present it’s value must be between 0 and 9999. 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.

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 sutIp recursively including all resources under it.

updateAlertsConfidence coming soon

(Optional) Array containing objects of [ confidenceId & filter ] properties. See updateAlertsConfidence below for more details.

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": String
}

route

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
  • 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

serverScanner

comming soon

Sub Resources

The following resources are referenced from the above Job schema.

templateThemes

An array containing one or more of the following report meta data objects you expect to be generated by the Emissary. This allows the Build User to specify which report types they desire:

{
  "name": String
}
  • name - One of [ traditionalHtml | traditionalHtmlPlusLight | traditionalHtmlPlusDark | traditionalJson | traditionalMd | traditionalXml | riskConfidenceHtmlDark | modernMarketing | highLevelReport ]

updateAlertsConfidence

coming soon

An array containing none to many objects with the following properties. This allows the Build User to define none to many sets of a filter to apply a confidence level to. A given alert raised by the Emissary must have all of the properties matching a given filter in order for the specified confidence to be applied:

"confidenceId": integer,
"filter": {
  "name": String,
  "cweid": String, 
  "wascid": String,
  "confidence": String,
  "risk": String,
  "description": String,
  "url": String
}
  • confidenceId - One of [ 0 | 1 | 2 | 3 | 4 ]. 0: False Positive, 1: Low, 2: Medium, 3: High, 4: Build User Confirmed
  • filter - An object containing none to all of the following properties. None means there is no filter so act on all alerts:
    • name - (Optional) The name of the alert to filter on
    • cweid - (Optional) The cweid of the alert to filter on
    • wascid - (Optional) The wascid of the alert to filter on
    • confidence - (Optional) The existing confidence of the alert to filter on
    • risk - (Optional) The current risk of the alert to filter on
    • description - (Optional) The description of the alert to filter on
    • url - (Optional) The url of the alert to filter on
Next

Last updated on Nov 27, 2021

Edit this page