github.com/kubeshop/testkube@v1.17.23/docs/docs/test-types/executor-zap.md (about) 1 import Admonition from "@theme/Admonition"; 2 3 # OWASP Zed Attack Proxy Executor 4 5 Starting from version 1.12, Testkube has a dedicated executor for running ZAP tests. All you need to do is populate a file with the necessary parameters and create a Testkube test. 6 7 Default command for this executor is `<pythonScriptPath>`, which will be calculated based on the test type. 8 9 * "zap/baseline": "./zap-baseline.py" 10 * "zap/full": "./zap-full-scan.py" 11 * "zap/api": "./zap-api-scan.py" 12 13 Default arguments for this executor command: <fileArgs> 14 15 Parameters in <> are calculated at test execution: 16 17 * `<pythonScriptPath>` - calculated based on test type 18 * `<fileArgs>` - merged list of arguments from file input and `--args` input 19 20 [See more at "Redefining the Prebuilt Executor Command and Arguments" on the Creating Test page.](../articles/creating-tests.md#redefining-the-prebuilt-executor-command-and-arguments) 21 22 For more information on how the underlying Docker image behaves, please consult the documentation on the [official ZAP website](https://www.zaproxy.org/docs/docker/). 23 24 export const ExecutorInfo = () => { 25 return ( 26 <div> 27 <Admonition type="info" icon="🎓" title="What is ZAP?"> 28 <ul> 29 <li>OWASP Zed Attack Proxy (ZAP) is a security scanner used to scan web applications.</li> 30 <li>It is free and open-source, and also the most widely used web app scanner in the world. It provides a high range of options for security automation.</li> 31 </ul> 32 </Admonition> 33 </div> 34 ); 35 } 36 37 ## **Creating a ZAP Test** 38 39 The official ZAP Docker image, on which the executor was built, lets you run three types of tests: baseline, full and API scans. Depending on which of these functionalities you want to leverage, the test creation looks slightly different. Not only the type of the test (`--type`) needs to be specified differently, but the configuration file will also have some parameters that do not work with all types. 40 41 An example create test CLI command will look like: 42 43 ```bash 44 $ kubectl testkube create test --file contrib/executor/zap/examples/zap-tk-api.yaml --type "zap/api" --name zap-api-test --copy-files contrib/executor/zap/examples/zap-tk-api.conf:zap-tk-api.conf 45 Test created testkube / zap-api-test 🥇 46 ``` 47 48 ### **Input File** 49 50 Note that this command is using files available locally. The input file `--file contrib/executor/zap/examples/zap-tk-api.yaml`, will be the one defining the arguments the executable will run with. Possible values are: 51 52 | Variable name | ZAP parameter | Default value | Baseline | Full | API | 53 |---|---|---|---|---|---| 54 | target | -t | "" | ✓ | ✓ | ✓ | 55 | config | -u for http <br /> -z for api <br /> -c for others | "" | ✓ | ✓ | ✓ | 56 | debug | -d | false | ✓ | ✓ | ✓ | 57 | short | -s | false | ✓ | ✓ | ✓ | 58 | level | -l | "PASS" | ✓ | ✓ | ✓ | 59 | context | -n | "" | ✓ | ✓ | ✓ | 60 | user | -U | "" | ✓ | ✓ | ✓ | 61 | delay | -D | 0 | ✓ | ✓ | ✓ | 62 | time | -T | 0 | ✓ | ✓ | ✓ | 63 | zap_options | -z | "" | ✓ | ✓ | ✓ | 64 | fail_on_warn | -I | true | ✓ | ✓ | ✓ | 65 | ajax | -j | false | ✓ | ✓ | | 66 | minutes | -m | 1 | ✓ | ✓ | | 67 | format | -f | "" | | | ✓ | 68 | hostname | -O | "" | | | ✓ | 69 | safe | -S | false | | | ✓ | 70 71 An example file content would look like: 72 73 ```bash 74 api: 75 # -t the target API definition 76 target: https://www.example.com/openapi.json 77 # -f the API format, openapi, soap, or graphql 78 format: openapi 79 # -O the hostname to override in the (remote) OpenAPI spec 80 hostname: https://www.example.com 81 # -S safe mode this will skip the active scan and perform a baseline scan 82 safe: true 83 # -c config file 84 config: /data/uploads/zap-tk-api.conf 85 # -d show debug messages 86 debug: true 87 # -s short output 88 short: false 89 # -l minimum level to show: PASS, IGNORE, INFO, WARN or FAIL 90 level: INFO 91 # -n context file 92 # context: /data/uploads/context.conf 93 # username to use for authenticated scans 94 user: anonymous 95 # delay in seconds to wait for passive scanning 96 delay: 5 97 # max time in minutes to wait for ZAP to start and the passive scan to run 98 time: 60 99 # ZAP command line options 100 zap_options: -config aaa=bbb 101 # -I should ZAP fail on warnings 102 fail_on_warn: false 103 ``` 104 105 The first line always specifies the type of the test. It can be either `baseline`, `full` or `api`. 106 107 ### **Config File** 108 109 Another file that was passed in is `contrib/executor/zap/examples/zap-tk-api.conf`. This one is the rule configuration file. It should look something like: 110 111 ```bash 112 # zap-api-scan rule configuration file 113 # Change WARN to IGNORE to ignore rule or FAIL to fail if rule matches 114 # Active scan rules set to IGNORE will not be run which will speed up the scan 115 # Only the rule identifiers are used - the names are just for info 116 # You can add your own messages to each rule by appending them after a tab on each line. 117 0 WARN (Directory Browsing - Active/release) 118 10010 WARN (Cookie No HttpOnly Flag - Passive/release) 119 10011 WARN (Cookie Without Secure Flag - Passive/release) 120 10012 WARN (Password Autocomplete in Browser - Passive/release) 121 10015 WARN (Incomplete or No Cache-control and Pragma HTTP Header Set - Passive/release) 122 10016 WARN (Web Browser XSS Protection Not Enabled - Passive/release) 123 10017 WARN (Cross-Domain JavaScript Source File Inclusion - Passive/release) 124 10019 WARN (Content-Type Header Missing - Passive/release) 125 10020 WARN (X-Frame-Options Header Scanner - Passive/release) 126 10021 WARN (X-Content-Type-Options Header Missing - Passive/release) 127 . 128 . 129 . 130 ``` 131 132 For additional files that should be passed in as parameter to the executor, use the `--copy-files` feature when developing locally. These files will be uploaded to the path `/data/uploads` by default. 133 134 ## **Creating a Git-based ZAP Test** 135 136 For tests running on production, you should use a Git repository to keep track of the changes the test went through. When running these tests, Testkube will clone the repository every time. An example test creation command would look something like this: 137 138 ```sh 139 testkube create test --git-uri https://github.com/kubeshop/testkube.git --type "zap/api" --name git-zap-api-test --executor-args "zap-api.yaml" --git-branch main --git-path contrib/executor/zap/examples 140 ``` 141 142 ```sh title="Output:" 143 Test created testkube / git-zap-api-test 🥇 144 ``` 145 146 Please note that for using Git-based tests, the executor is expecting the test file as the last `--executor-args` argument. The path to the config file should be specified in this `yaml` file. 147 148 ## **Running a ZAP Test** 149 150 Running a ZAP test using the CLI is as easy as running any other kind of test in Testkube: 151 152 ```bash 153 $ kubectl testkube run test zap-api-test 154 Testkube will use the following file mappings: contrib/executor/zap/examples/zap-tk-api.conf:zap-tk-api.conf 155 Type: zap/api 156 Name: zap-api-test 157 Execution ID: 646f8d4bc5ba4e00f169aafe 158 Execution name: zap-api-test-1 159 Execution number: 1 160 Status: running 161 Start time: 2023-05-25 16:31:07.880658961 +0000 UTC 162 End time: 0001-01-01 00:00:00 +0000 UTC 163 Duration: 164 165 166 167 Test execution started 168 Watch test execution until complete: 169 $ kubectl testkube watch execution zap-api-test-1 170 171 172 Use following command to get test execution details: 173 $ kubectl testkube get execution zap-api-test-1 174 ``` 175 176 ## **Results** 177 178 When the test is finished running, it will have either `passed` or `failed` state. To check it, run: 179 180 ```bash 181 testkube get tests 182 ``` 183 184 To get a more detailed report, you can run: 185 186 ```bash 187 testkube get execution zap-api-test-1 188 ``` 189 190 Another indicator of how the tests completed are the report files created. These are uploaded as artifacts into the object storage used by Testkube, and can be retrieved using both the Testkube CLI and the Testkube UI. 191 192 ## **References** 193 194 * [ZAP Docker documentation](https://www.zaproxy.org/docs/docker) 195 * [ZAP - Baseline Scan documentation](https://www.zaproxy.org/docs/docker/baseline-scan/) 196 * [ZAP - Full Scan documentation](https://www.zaproxy.org/docs/docker/full-scan/) 197 * [ZAP - API Scan documentation](https://www.zaproxy.org/docs/docker/api-scan/)