API Job File Structure

The following explains the Job file structure targeting web APIs.

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 Api.

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:

"emissaryAuthenticationStrategy": String,
"route": String

• emissaryAuthenticationStrategy - (Optional, Default: MaintainJwt) One of [ MaintainJwt ]. The specific strategy used defines how the Emissary should be authenticated to the SUT. The default strategy for the Api schema adds the base URL (sutIp) to the Emissary’s Context with an appended .* so that everything under the base URL (sutIp) of the API definition you provide will be within the Emissary scan Context. If you want less scanned you will need to break the API definition up into smaller definitions per Test Session. 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

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.

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: ImportUrls) One of [ ImportUrls | OpenApi | Soap | GraphQl ]. 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: ApiStandard) One of [ ApiStandard ]. The specific strategy used defines how the Emissary scanners are configured. The default strategy for the Api schema loads only a sub-set of the scanners used for web applications as there is no DOM. It also adds a couple of scripts.

scanningStrategy

(Optional, Default: ApiStandard) One of [ ApiStandard ]. The specific strategy used defines how the Emissary carries out it’s scanning. Using the default strategy for the Api schema both the Emissary’s spider and active scanner will scan the base URL (sutIp) recursively. If you want less scanned, you will need to break the API definition up into smaller definitions per Test Session. If you need a different behaviour discuss with us what you need

postScanningStrategy

(Optional, Default: ApiStandard) One of [ ApiStandard ]. 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.

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.

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 behaviour 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) The default is specified in the App Tester config file. One of [ LOW | MEDIUM | HIGH | INSANE ]. For APIs we usually recommend setting this to MEDIUM.

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.

serverScanner

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 ]

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

updateAlertsConfidence

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