Skip to content

Commit 154997c

Browse files
en-milieen-milie
committed
chore: Update documentation with latest fuzzers and arguments
1 parent 6efb11b commit 154997c

28 files changed

+511
-22
lines changed

‎docs/advanced-topics/dynamic-values.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ This is `FunctionalFuzzer` file using the above dynamic value:
2828
```
2929
3030
You can check the responses using a similar syntax and also take into consideration the response.
31-
This will check if the `expiry` field returned within the json response, parsed as date, is after the current date ` T(java.time.LocalDate).now().isBefore(T(java.time.LocalDate).parse(expiry.toString()))`:
31+
This will check if the `expiry` field returned within the json response, parsed as date, is after the current date ` T(java.time.LocalDate).now().isBefore(T(java.time.LocalDate).parse(expiry))`:
3232

3333
```yaml
3434
/path:
@@ -45,14 +45,14 @@ This will check if the `expiry` field returned within the json response, parsed
4545
expectedResponseCode: HTTP_CODE
4646
httpMethod: HTTP_NETHOD
4747
verify:
48-
checkBoolean: T(java.time.LocalDate).now().isBefore(T(java.time.LocalDate).parse(expiry.toString()))
48+
checkBoolean: T(java.time.LocalDate).now().isBefore(T(java.time.LocalDate).parse(expiry))
4949
```
5050

5151
:::info
5252
Notice the keyword `checkBoolean` which will test if the expression is `true`. This is very useful when doing assertions on response data when running functional tests.
5353
:::
5454

55-
The syntax of dynamically setting dates is compliant with the [Spring Expression Language](https://docs.spring.io/spring-framework/docs/3.0.x/reference/expressions.html) specs.
55+
The syntax of dynamically setting dates is similar with [Spring Expression Language](https://docs.spring.io/spring-framework/docs/3.0.x/reference/expressions.html) specs. It's not a full implementation though, so it supports only basic operations.
5656

5757
Dynamic expressions can also refer variables or request/response fields internally. In the example above, `expiry` is a field returned in the response.
5858
If you want to refer a variable created in a previous test, let's call it `petName`, you can do so as: `T(org.apache.commons.lang3.StringUtils).substringAfterLast(${petName},'a')`.

‎docs/advanced-topics/fuzzers-config.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,22 @@ You can achieve this by providing a properties file using the `--fuzzersConfig`
1313
In this file, the keys correspond to the fuzzer names and configuration names, while the values represent the desired HTTP code to expect.
1414
At the moment, the only supported configuration is `expectedResponseCode`.
1515

16+
The format of the keys in the properties file is as follows:
17+
18+
```properties
19+
fuzzerName.[path].[method].expectedResponseCode=value
20+
```
21+
22+
where:
23+
- `fuzzerName` is the name of the fuzzer
24+
- `path` is the path of the endpoint exactly as it appears in the contract and it's optional
25+
- `method` is the HTTP method of the endpoint and it's optional
26+
- `value` is the expected HTTP response code
27+
28+
:::note
29+
The most specific value will be picked up first.
30+
:::
31+
1632
This is an example (file name `fuzzConfig.properties`):
1733

1834
```properties

‎docs/commands-and-arguments/arguments.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,17 @@ You can get the full list of arguments by running `cats -h`. Below is a short de
107107
- `--stopAfterTimeInSec=<stopAfterTimeInSec>` Amount of time in seconds for how long the continuous fuzzing will run before stopping. Only available in `cats random` sub-command.
108108
- `--pathsRunOrder=<pathsOrderFile>` A file with the order in which the paths will be executed. The paths are on each line. The order from file will drive the execution order
109109
- `--errorLeaksKeywords=<errorLeaksKeywords>` A properties file with error leaks keywords that will be used when processing responses to detect potential error leaks. If one of these keyword is found, the test case will be marked as error
110+
- `-P name=value` A list of `name=value` pairs that will be used to replace url params for all paths
111+
- `-H name=value` A list of `name=value` pairs that will be used to replace headers for all paths
112+
- `-Q name=value` A list of `name=value` pairs that will be used to replace query params for all paths
113+
- `-R name=value` A list of `name=value` pairs that will be used as reference data for all paths
114+
- `--operationIds=<operationIds>` A comma separated list of operationIds to include. If no operationId is supplied, all operationIds will be considered.
115+
- `--skipOperationIds=<skipOperationIds>` A comma separated list of operationIds to ignore. If no operationId is supplied, no operationId will be ignored.
116+
- `--skipFuzzersForExtension` Skip specific fuzzers for endpoints with certain OpenAPI extension values. Format: x-extension-name=value:Fuzzer1,Fuzzer2.
117+
- `--resolveXxxOfCombinationForResponses` Resolve anyOf/oneOf combinations for responses. Default: false
118+
- `--http2PriorKnowledge` If set to `true`, it will force a http2 connection, without fallback to HTTP 1.X
119+
- `--includeAllInjectionPayloads` Include all injection payloads for security fuzzers (SQL, XSS, Command, NoSQL injection). By default, only a curated top 10 payloads are used per injection type to reduce execution time.
120+
- `--seed=<value>` a seed used for deterministic generation of the random values
110121

111122
:::tip
112123
When you want to skip fuzzing entirely for a specific JSON object or specific fields you must prefix the field name from the `--skipFields` argument with `!`.

‎docs/commands-and-arguments/sub-commands.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,10 @@ All available subcommands are listed below:
4141

4242
- `cats random` does continuous fuzzing based on mutators until a certain stop condition is hit
4343

44+
- `cats explain` will explain a given response code or reason message
45+
46+
- `cats generate` will generate a request based on a given OpenAPI contract
4447

4548
:::tip
46-
Each sub-command has its own help. You can run `cats sub-command -h` to check all available arguments: `cats fuzz -h`.
49+
Each sub-command has its own help. You can run `cats sub-command -h` to check all available arguments: `cats template -h`.
4750
:::

‎docs/fuzzers/field-fuzzers/additional-props-mass-assignment.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
hide_table_of_contents: true
3+
---
4+
5+
# Additional Properties Mass Assignment Fields Fuzzer
6+
7+
| Item | Description |
8+
|:--------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
9+
| **Full Fuzzer Name** | AdditionalPropertiesMassAssignmentFieldsFuzzer |
10+
| **Log Key** | **APMAF** |
11+
| **Description** | This fuzzer targets objects explicitly declared with `additionalProperties: false` and injects a large number of **unexpected extra properties** into them. The goal is to detect **Mass-Assignment / over-posting** vulnerabilities and schema enforcement gaps, where APIs accidentally accept or persist fields that are not part of the contract. |
12+
| **Enabled by default?** | Yes |
13+
| **Target field types** | OpenAPI type `object` with `additionalProperties: false` |
14+
| **Expected result when fuzzed field is required** | `4XX` |
15+
| **Expected result when fuzzed field is optional** | `4XX` |
16+
| **Expected result when fuzzed value is not matching field pattern** | `4XX` |
17+
| **Fuzzing logic** | Iteratively **replaces** each eligible object field with a mutated object that: <br/><br/> *1.* **Preserves existing properties** from the original payload (copies all keys and their values). <br/> *2.* Picks a **sample value** from one of the existing properties (any existing value); if none exists, uses `"catsFuzzyValue"`. <br/> *3.* Adds up to **100 extra properties** named `catsExtraProp0 ... catsExtraPropN`, each having the **same sample value**. <br/> *4.* The number of injected properties is capped by `min(100, processingArguments.getLargeStringsSize() / 4)` to avoid extreme payload sizes. <br/> *5.* The mutated object is serialized to JSON and used as the replacement value for the field. |
18+
| **Conditions when this fuzzer will be skipped** | When the field is **not an object** OR the schema does **not** declare `additionalProperties: false` OR the current payload value is **not a valid map/object** for the given field path. |
19+
| **HTTP methods that will be skipped** | `HEAD`, `GET`, `DELETE` |
20+
| **Reporting** | Reports `error` if: *1.* response code is `404`; *2.* response code is documented, but not expected; *3.* any unexpected exception. <br/><br/> Reports `warn` if: *1.* response code is expected and documented, but not matches response schema; *2.* response code is expected, but not documented; *3.* response code is `501`. <br/><br/> Reports `success` if: *1.* response code is expected, documented and matches response schema. |

0 commit comments

Comments
 (0)