diff --git a/.vitepress/sidebars/reference.ts b/.vitepress/sidebars/reference.ts index 8a22df88..c7ae1da6 100644 --- a/.vitepress/sidebars/reference.ts +++ b/.vitepress/sidebars/reference.ts @@ -12,6 +12,10 @@ export const referenceSidebar: DefaultTheme.SidebarItem[] = [ text: "HTTPQL", link: "/reference/httpql", }, + { + text: "Match & Replace", + link: "/reference/match_replace", + }, ], }, { diff --git a/src/_images/base64_request_body.png b/src/_images/base64_request_body.png new file mode 100644 index 00000000..95b7e944 Binary files /dev/null and b/src/_images/base64_request_body.png differ diff --git a/src/_images/create_match_replace_rule.png b/src/_images/create_match_replace_rule.png new file mode 100644 index 00000000..e056f374 Binary files /dev/null and b/src/_images/create_match_replace_rule.png differ diff --git a/src/_images/custom_bounty_header.png b/src/_images/custom_bounty_header.png new file mode 100644 index 00000000..7e35b1df Binary files /dev/null and b/src/_images/custom_bounty_header.png differ diff --git a/src/_images/match_and_replace.png b/src/_images/match_and_replace.png new file mode 100644 index 00000000..b5849fb1 Binary files /dev/null and b/src/_images/match_and_replace.png differ diff --git a/src/_images/match_replace_active_rules.png b/src/_images/match_replace_active_rules.png new file mode 100644 index 00000000..9a6a9b31 Binary files /dev/null and b/src/_images/match_replace_active_rules.png differ diff --git a/src/_images/match_replace_collection_list_rules.png b/src/_images/match_replace_collection_list_rules.png new file mode 100644 index 00000000..9fea3699 Binary files /dev/null and b/src/_images/match_replace_collection_list_rules.png differ diff --git a/src/_images/match_replace_collection_options.png b/src/_images/match_replace_collection_options.png new file mode 100644 index 00000000..42f9475e Binary files /dev/null and b/src/_images/match_replace_collection_options.png differ diff --git a/src/_images/match_replace_condition.png b/src/_images/match_replace_condition.png new file mode 100644 index 00000000..5b6e597e Binary files /dev/null and b/src/_images/match_replace_condition.png differ diff --git a/src/_images/match_replace_create_collection.png b/src/_images/match_replace_create_collection.png new file mode 100644 index 00000000..0cdb8998 Binary files /dev/null and b/src/_images/match_replace_create_collection.png differ diff --git a/src/_images/match_replace_rule_options.png b/src/_images/match_replace_rule_options.png new file mode 100644 index 00000000..981852b0 Binary files /dev/null and b/src/_images/match_replace_rule_options.png differ diff --git a/src/_images/match_replace_rule_test.png b/src/_images/match_replace_rule_test.png new file mode 100644 index 00000000..f62281fc Binary files /dev/null and b/src/_images/match_replace_rule_test.png differ diff --git a/src/_images/matcher.png b/src/_images/matcher.png new file mode 100644 index 00000000..d6bca489 Binary files /dev/null and b/src/_images/matcher.png differ diff --git a/src/_images/matchreplace_marked_layout.png b/src/_images/matchreplace_marked_layout.png deleted file mode 100644 index d9117508..00000000 Binary files a/src/_images/matchreplace_marked_layout.png and /dev/null differ diff --git a/src/_images/regex_request_body.png b/src/_images/regex_request_body.png new file mode 100644 index 00000000..c02afda0 Binary files /dev/null and b/src/_images/regex_request_body.png differ diff --git a/src/_images/replacer.png b/src/_images/replacer.png new file mode 100644 index 00000000..abb21394 Binary files /dev/null and b/src/_images/replacer.png differ diff --git a/src/_images/replacer_workflow.png b/src/_images/replacer_workflow.png new file mode 100644 index 00000000..bdfa132f Binary files /dev/null and b/src/_images/replacer_workflow.png differ diff --git a/src/_images/request_header_actions.png b/src/_images/request_header_actions.png new file mode 100644 index 00000000..abba75b1 Binary files /dev/null and b/src/_images/request_header_actions.png differ diff --git a/src/_images/request_query_actions.png b/src/_images/request_query_actions.png new file mode 100644 index 00000000..94e2f08b Binary files /dev/null and b/src/_images/request_query_actions.png differ diff --git a/src/_images/request_sections.png b/src/_images/request_sections.png new file mode 100644 index 00000000..3414ad08 Binary files /dev/null and b/src/_images/request_sections.png differ diff --git a/src/_images/response_header_actions.png b/src/_images/response_header_actions.png new file mode 100644 index 00000000..77647cd7 Binary files /dev/null and b/src/_images/response_header_actions.png differ diff --git a/src/_images/response_sections.png b/src/_images/response_sections.png new file mode 100644 index 00000000..2c055ab5 Binary files /dev/null and b/src/_images/response_sections.png differ diff --git a/src/guides/match_replace.md b/src/guides/match_replace.md index 1afab009..08f02964 100644 --- a/src/guides/match_replace.md +++ b/src/guides/match_replace.md @@ -1,56 +1,53 @@ -# Match & Replace +# Creating Match & Replace Rules -The `Match & Replace` tab allows you to define match and replace rules using HTTPQL and regex syntax. These rules can be used to automate the modification of requests and responses as they pass through the proxy. - -Match & Replace rules can be organized into `Collections`, which allows you to group rules however you see fit. For example, you can create a Collection to group header rules, user authorization rules, etc. - making testing against certain elements a seamless process. - -## Creating a New Match & Replace Rule - -Match & Replace. +In this guide, we'll cover how to create match and replace rules for three different use cases. ::: info -In this example - the Match & Replace rule created will change the value of the **isAdmin** response parameter from **false** to **true**. +For additional documentation on Caido's Match & Replace feature - click [here](/reference/match_replace.md). ::: -1. Select the `Match & Replace` tab from the left-hand menu within the Caido window. -2. Click `New Rule`. The drop down arrow attached to this button allows you to switch between `New Rule` and `New Collection`. -3. When creating a new rule, you can update the following fields: +## Creating a New Rule -- `Name`: A name for the rule. -- `Strategy`: Defines what part of the request to perform the match/replace on, such as request header, response header, request body, request first line, etc. -- `Search as regex`: If the `Search term` is a regex or a simple string match. -- `Search term`: The term to search for in the defined part of the request or response. -- `Replace term`: The term to replace the search term with. -- `Condition`: An [HTTPQL](/reference/httpql.md) query that defines which requests/responses this rule applies to. +There are numerous ways to create a new rule in the Match & Replace interface: -4. When you're done updating your rule, you can use the bottom panes to test your rule against a mock request/response. Click on the `Test` button and see if your rule works as intended. -5. You can enable or disable individual rules by clicking on the checkbox next to each rule in the tree view. Enabled rules will be shown in the `Active rules` section of the page. This section displays the list of the rules that are currently active and will be applied to the requests/responses that pass through the proxy. -6. These are your rule Collections. To move rules between collections - **click, hold and drag** a rule into the Collection folder you wish to include the rule in. +Creating a new match and replace rule. ::: tip TIPS -- If you're having an issue with your Match & Replace rule not taking affect, and you've already double checked your `Strategy`, -make sure you're looking at the un-prettified version of the request/response body by pressing the `{} Prettify` button within any request/response pane to ensure your spacing is correct. -- The order of the rules in the "Active rules" section determines the order in which they will be applied to the requests and responses. You can change the order of the rules by dragging and dropping. This allows you to adjust the order to suit your needs and can be useful when working with multiple rules that may have conflicting or overlapping conditions. +- If you're having an issue with your Match & Replace rule not taking affect make sure you're looking at the un-prettified version of the request/response body by pressing the `{} Prettify` button within any request/response pane to ensure your spacing is correct. +- The order of the rules in the Active Rules section determines the order in which they will be applied to the requests and responses. You can change the order of the rules by dragging and dropping. This allows you to adjust the order to suit your needs and can be useful when working with multiple rules that may have conflicting or overlapping conditions. ::: -## Append a Request Header with a Custom String Example +## Adding a Custom Request Header -Many popular bug bounty programs require a custom header to be sent with your requests. You can do this in Caido using the `Match and Replace` feature. +To add an additional header to a request, select the `Request Header` option from the `Section` dropdown menu. Then select the `Add` action. Provide the key name of the header and a string value. -::: info -In this example - the Match & Replace rule created will change the value of the **User-Agent** header to **bughunter**. +Creating a new match and replace rule. + +## Base64 Encode Request Body Data + +To Base64 encode the body data of a request, select the `Request Body` option from the `Section` dropdown menu. Next, set the `Matcher` to `Full` and the `Replacer` to `Workflow`. Then select the `Base64 Encode` Workflow. + +::: tip +Using [HTTPQL](/reference/httpql.html) statements, a `Condition` can be defined in order to target specific requests or responses. ::: -### Strategy +Creating a new match and replace rule. + +## Using Capture Groups + +Caido Match & Replace rules also support regex capture groups (_expressions enclosed in parenthesis that can be referenced using `$` followed by the group integer_). -- Request Header (_enable_ `Search as regex`) +::: warning NOTE +Caido does not currently support look-around and backreference regular expressions. +::: -### Search +::: tip TIPS -- ^(User-Agent: .+) +- To test your regular expressions, visit [regex101.com](https://regex101.com/). +- Refer to the [Rust regex documentation](https://docs.rs/regex/latest/regex/). -### Replace +::: -- $1 bughunter +Creating a new match and replace rule. diff --git a/src/reference/match_replace.md b/src/reference/match_replace.md new file mode 100644 index 00000000..7d048d2f --- /dev/null +++ b/src/reference/match_replace.md @@ -0,0 +1,138 @@ +# Match & Replace + +The `Match & Replace` interface allows you to define rules to automate the modification of requests and responses as they pass through the proxy. + +Match and replace interface + +## Section + +The `Section` refers to the portion of the request or response that the rule will apply to. To target a Section, expand the dropdown menu and select one of the available options. + +### Request Sections + +- `Request Path`: The path of a request. +- `Request Method`: The HTTP method of a request. +- `Request Query`: The query of a request. +- `Request First Line`: The first line of a request. +- `Request Header`: The header or headers of a request. +- `Request Body`: The body data of a request. + +Match and replace request sections. + +### Response Sections + +- `Response First Line`: The first line of a response. +- `Response Status Code`: The HTTP status code of a response. +- `Response Header`: The header or headers of a response. +- `Response Body`: The body data of a response. + +Match and replace response sections. + +## Section Actions + +Certain Sections will include additional modification options that will be located to the right of the Section dropdown menu. + +When targeting the `Request Query` section: + +- `Update Raw`: Makes modifications to the query as a whole. +- `Update Param`: Matches a query parameter key name and modifies its value. +- `Add Param`: Appends an additional query parameter. +- `Remove Param`: Removes a query parameter by key name. + +Request query actions. + +When targeting either the `Request Header` or `Response Header` sections: + +- `Update Raw`: Makes modifications to the headers as a whole. +- `Update Value`: Matches a header's key name and modifies its value. +- `Add`: Inserts a new header key-value pair. +- `Remove`: Removes a header by key name. + +Request header actions. + +--- + +Response header actions. + +## Matcher + +The `Matcher` specifies which search term will be matched for replacement. To specify a Matcher, expand the dropdown menu and select one of the available options: + +- `Full`: The entire Section will be replaced. If there are multiple Section parameters, such as when dealing with headers, all instances will be replaced. +- `Regex`: Matches to Rust flavor regular expressions will be replaced. + +::: warning NOTE +Caido does not currently support look-around and backreference regular expressions. +::: + +- `String`: Matches to string values will be replaced. + +::: tip +To test your regular expressions, visit [regex101.com](https://regex101.com/). +::: + +Matcher options. + +## Replacer + +The `Replacer` specifies the modification that will replace Matcher. To specify a Replacer, expand the dropdown menu and select one of the available options: + +- `Term`: Replace the Matcher with a string value. +- `Workflow`: Apply a [Convert Workflow](/concepts/workflows_intro.html#convert-workflows) to the Matcher. + +Replacer options. + +--- + +Replacer Workflow options. + +::: tip +If you're having an issue with your Match & Replace rule not taking affect, +make sure you're looking at the un-prettified version of the request/response body by pressing the `{} Prettify` button within any request/response pane to ensure your spacing is correct. +::: + +## Conditions + +Using [HTTPQL](/reference/httpql.html) statements, a `Condition` can be defined in order to target specific requests or responses. + +Replacer Workflow options. + +## Testing + +Once a rule has been defined, you can test its efficacy by supplying a mock request or response in the `Before` pane, clicking the `Test` button, and viewing the results in the `After` pane. + +Match and replace rule testing. + +## Collections + +Collections allow you to help you stay organized during testing by grouping rules together. By default, once a rule is saved by clicking the `+ Add` button, it will be added to the `Default Collection`. + +To create a new Collection, select the down carat button attatched to the `+ New Rule` button in the upper-left corner of the interface and select `New Collection`. + +New match and replace Collection. + +To move rules between collections - **click, hold and drag** a rule into the Collection folder you wish to include the rule in. + +To list all the rules of a certain Collection, expand its contents by clicking on the leading carat button of the Collection entry. Clicking the carat button again will collapse the list. + +Match and replace Collection rules list. + +By clicking on the `...` button of a Collection, you can add a rule, rename the Collection, and delete the Collection. + +Match and replace Collection rules list. + +Similarly, by clicking on the `...` button of a rule in a Collection, you can enable/disable, rename, and delete it. You can also enable/disable a rule by clicking on the checkbox of the associated rule. + +Match and replace Collection rules list. + +All enabled rules will appear in the `Active Rules` pane. + +Match and replace Collection rules list. + +::: tip +The order of the rules in the Active Rules section determines the order in which they will be applied to the requests and responses. You can change the order of the rules by dragging and dropping. This allows you to adjust the order to suit your needs and can be useful when working with multiple rules that may have conflicting or overlapping conditions. +::: + +## What's next? + +[Learn how to create match and replace rules for three different use cases here.](/guides/match_replace.md)