Overview
You can think of the Job file as the executable specification defining what you want GuardRails Runtime to test and in some cases how. GuardRails Runtime validates, filters, and when necessary sanitizes your Job file before sending it to the Runtime engines, where it is again passed through the same validation, filtering, and sanitization process.
Based on the Job file either generated or supplied explicitly by the Build User, Runtime works out what sort of SUT it is that you are targeting. There are currently four types of supported SUTs:
- Browser App non-authenticated (simple), no authentication is required to scan the SUT
- Browser App authenticated (advanced), authentication is required to scan the SUT
- API non-authenticated (simple), no authentication is required to scan the SUT
- API authenticated (advanced), authentication is required to scan the SUT
By default, the Job will target a Browser App SUT.
For the Job to be considered targeting an API it needs to have one resource object of type appScanner and one of the following attributes in that appScanner resource object: [ openApi | soap | graphQl | importUrls ].
For the Job to be considered an authenticated Job, it needs to have one of the following attributes in the data.attributes object [ loggedInIndicator | loggedOutIndicator ].
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 in the runtime-resources repository.
- The Job file schema conforms 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, ask us to check the strategy you intend on using as to whether or not it consumes the property in question
- For properties marked as Optional that have a default value: If the Build User omits them, a validation message will be printed to the UI informing the Build User of which optional property values were added
- The best way to test that your Job file is valid is by trying to upload it
Strategy Properties
There are several of properties in the Job schema suffixed with Strategy. These values provide the Build User an opportunity to define the Emissary's behavior.
They are ordered as per the scan steps sequence of execution, as determined by which type of SUT your Job file is targeting.
If you find you need something different, discuss what you need with us.
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 its regular expression tester to verify that your regular expressions will work as expected.