Job File

You can think of the Job file as the executable specificatiion defining what you want PurpleTeam to test and in some cases how. The PurpleTeam CLI validates, filters and when necessary sanitises your Job file before sending to the back-end (specifically the orchestrator), where it is again passed through the same validation, filtering and sanitisation process. There is yet another schema for each Tester that validates, filters and sanitises the parts of the Job file that each specific Tester works with.

There are two Job file types (BrowserApp and Api) with accompanying schemas. The Job file type is specified within the top level data object:

{
  "data": {
    "type": ["BrowserApp"|"Api"],
    ...
  • type - One of [ BrowserApp | Api ]


As you work through creating your first Job file, remember to keep it as simple as possible to start with. Then build on it as you understand more.

  • Examples can be found at the CLI Github. Don’t be afraid to ask another community member on one or both of the PurpleTeam Slacks for examples
  • The Job file schemas conform to jsonapi
  • All properties are considered mandatory unless specified as optional
  • Bear in mind that there are optional properties that are required by certain strategies. If you are unsure check the strategy you intend on using as to whether or not it consumes the property in question. If you are still unsure ask on one of the PurpleTeam Slack channels
  • For properties marked as Optional that have a default value: If the Build User omits them, a validation message will be printed to the CUI (not in CLI logs) informing the Build User of which optional property values were added
  • The best way to test that your Job file is valid is by running the CLI’s testplan command as this command doesn’t start a Test Run and in-fact does very little, it will only return the Testers test plans if your Job file is valid. You can even run this command without the PurpleTeam back-end running, if you run the CLI’s testplan command and your Job file is valid, you will see a blank screen followed by a message telling you that the orchestrator is down, if your Job file is not yet valid, you will receive error messages informing you of which parts of your Job file are invalid.

Strategy Properties

There are a number of properties in the Job schema suffixed with Strategy. These values provide the Build User an opportunity to define the App Tester Emissary’s behaviour. The code for these strategies is located in the app-scanner repository. They are ordered in general sequence of execution as determined by the relevant (BrowserApp | Api) Cucumber step definitions. If you find you need something different, discus what you need with us and/or submit a Github Pull Request.

Regular Expressions

For Job file property values that allow regular expressions, if you have access to the App Tester Emissary (Zaproxy) running on your desktop as a GUI application you could use it’s regular expression tester to verify that your regular expressions will work as expected.

Last updated on Nov 27, 2021

Edit this page