Introduction

Welcome to the Caido documentation site! Here you will find a wealth of information on how to use Caido to perform web application security testing.

Explore our documentation to learn about the different features of Caido and how to install and configure it. We invite you to take a look around and discover all that Caido has to offer.

intercept_with_filter

FAQ

Is Caido free?

Yes, Caido is free to use. However, we also offer a pro tier which will include additional advanced features in the future. By purchasing the pro version, you will be supporting the development and maintenance of the tool.

Additionally, we offer an enterprise plan for organizations that need premium support and/or custom feature implementation.

You can check our website to stay informed about the new features that will be added in the future.

Is Caido open source?

Caido is not currently open source, but we have plans to offer an API for open source plugin development. We also employ standard open formats whenever possible.

On how many devices can I install Caido?

At this time, Caido can be installed on an unlimited number of devices. You are welcome to install Caido on as many devices as you like.

What data do you collect?

When you register for Caido, we collect your name and email address, as well as information about your user agent.

When you use Caido, we collect interaction data between your instances and our cloud services. This includes the IP address of the instance and API call actions/timestamps.

We do not collect any data stored on your instances nor interactions within the caido application.

Where can I ask for support and/or feature requests?

You can ask for support and submit feature requests through our public Discord or Github repository. Both are great places to share feedback and help improve Caido.

Installation

Caido is available as both a desktop application and a standalone command-line interface (CLI) binary, offering users the flexibility to choose the installation method that best suits their needs.

You can download the installer package from your dashboard or from the releases page of our Github repository. The available installer package can differ based on your operating system, make sure to download the package that is compatible with your system.

Installing Caido on Windows

Download the Caido installer package for Windows from the dashboard or Github repository.
Open the downloaded package and follow the prompts to install Caido on your system.
Once the installation is complete, you can launch Caido from the Start menu or by searching for it in the Windows search bar.

Installing Caido on Linux

Download the Caido installer package for Linux from the dashboard or Github repository.
Open a terminal and navigate to the directory where the downloaded package is located.
Use the command sudo dpkg -i <package-name> to install Caido.
Once the installation is complete, you can launch Caido by running the caido command in the terminal.

Installing Caido on MacOS

Download the Caido installer package for macOS from the dashboard or Github repository.
Open the downloaded package and follow the prompts to install Caido on your system.
Once the installation is complete, you can launch Caido from the Applications folder or by searching for it in Spotlight.

Running on a VPS

Caido is designed to be a flexible web application security testing tool, and one of its key features is the ability for users to host it anywhere, such as on a virtual private server (VPS).

By default, Caido listens on the IP address 127.0.0.1 and port 8080. This is the recommended configuration as there is currently no built-in access control on the proxy portion of Caido. Listening on 127.0.0.1 limits access to the local machine only.

Here are the steps to host Caido on a Linux-based VPS:

Once you have set up a VPS, you can install Caido on it by following the Linux installation guide found here.
To access Caido from another machine or another network, you will need to create an SSH tunnel from your local machine to your VPS. This can be done by running the following command on your local machine:
```
ssh -L <local port>:127.0.0.1:8080 <username>@<your vps IP address>
```
This will forward all traffic on port of your local machine to port 8080 of your VPS. For example, if you want to use port 1337 on your local machine, you can run the command:
```
ssh -L 1337:127.0.0.1:8080 <username>@<your vps IP address>
```
Once the tunnel is set up, you can access Caido by navigating to http://127.0.0.1:<local port> in your web browser.

In the example above, you would navigate to http://127.0.0.1:1337. You will also have to configure your browser to proxy requests to 127.0.0.1:1337.

Running in Docker

Building the image

We don't yet provide prebuilt Caido docker images, but you can easily build one yourself.

Here is a Dockerfile sample you can use:

## Base ##
FROM debian:bullseye-slim as base

RUN \
  apt-get update && \
  apt-get -y install ca-certificates && \
  apt-get clean

## Download ##
FROM base as download

RUN \
  apt-get -y install curl jq && \
  curl -s https://api.caido.io/releases/latest \
    | jq '.links[] | select(.display == "Linux") | .link' \
    | xargs curl -s --output caido.tar.gz && \
  tar -xf caido.tar.gz && \
  rm caido.tar.gz

## Runtime ##
FROM base

RUN groupadd -r caido && useradd --no-log-init -m -r -g caido caido

COPY --from=download caido /usr/bin/caido

USER caido

EXPOSE 8080

ENTRYPOINT ["caido"]
CMD ["--listen", "0.0.0.0:8080"]

Create a Dockerfile file with the above contents.
Running docker build . -t caido:latest will create a docker image for Caido.

Running the image

Once you have built the image, you can run Caido with:

docker run --rm -p 7000:8080 caido:latest

This will start Caido on port 7000. You can then point your browser's proxy settings to 127.0.0.1:7000.

To use another port, replace 7000 in the command above with a different port.

Project persistence

By default, projects created in the docker container are not saved between docker run commands.

We recommend mounting a volume to keep your data on your file system and to avoid losing data between Caido updates.

This is done by appending the -v parameter to the docker run command using the format -v <HOST PATH>:/home/caido/.local/share/caido.

Note that the host path must be an absolute path.

Your running command should look like the following:

docker run --rm -p 7000:8080 \
  -v /home/my_user/my_data:/home/caido/.local/share/caido caido:latest

... where /home/my_user/my_data will be the folder containing Caido projects.

Default listening address/port

Caido, by default, listens on the IP address 127.0.0.1 and port 8080. This means that Caido will only be accessible from the same machine it is running on.

However, you can change the listening address and port to suit your needs. There are two ways to change the listening address, depending on whether you are using the CLI or the desktop application.

Please note that if you change the listening address to something other than 127.0.0.1, Caido will be accessible from any machine on the network, so it is important to consider the security implications of doing so.

CLI

When using the CLI, you can update the listening address by using the -l or --listen option followed by the desired address and port in the format ADDR:PORT. For example, to listen on all available network interfaces on port 8000, use the command:

caido -l 0.0.0.0:8000

Desktop App

When using the desktop app, you can change the listening address by using the connection manager. To do this, open the connection manager, and click on the "More options" icon on the right of the instance you want to edit.

connection_manager_instance_more_options

Click on "Edit", and update the listening IP and port to whatever you want.

connection_manager_instance_edit

Import the CA certificate in your browser

To use Caido to intercept (and tamper with) your https traffic, it is necessary to import and trust the CA certificate of Caido in your browser.

Log in to Caido

After starting Caido on your machine, navigate to localhost:8080 (or the port you've configured for Caido to listen to) and log in.

Get the Certificate

Open the "User Dropdown Menu" in the top right

user_dropdown

Navigate to "CA Certificate" or click here.

Download the Certificate and follow the instructions to import and trust it in your browser of choice.

download_cert

After you've successfully imported the certificate, you are good to go and can configure your browser to proxy it's traffic through Caido.

Overview

Our awesome community has put together many guides and videos 🎉

If you want your contributions to appear here, please follow the contribution guidelines!

Please note that these videos are not endorsed by Caido.

CryptoCat

Sean Wright

Tutorials

Our awesome community has put together many guides and videos 🎉

If you want your contributions to appear here, please follow the contribution guidelines!

Please note that these videos are not endorsed by Caido.

Password Attacks

Alex Kollar: https://www.youtube.com/watch?v=qPBK6sHjJt8

Command Injection

Alex Kollar: https://www.youtube.com/watch?v=d9EFV5zdkQY

Sitemap

The Sitemap feature allows you to visualize the structure of any website that is proxied through Caido.

It keeps track of domains, folders, and requests, as well as any variations in query parameters and post bodies. The Sitemap page provides a clear, hierarchical view of the website's structure, making it easy to identify and explore different parts of the site.

sitemap

Navigating the Sitemap

The Sitemap page displays a tree-like structure, with the root node representing the root domain of the website. Each branch of the tree represents a subdomain or subfolder, and the leaves of the tree represent individual requests. You can click on any node to expand or collapse it, revealing or hiding its child nodes.

Listing requests

You can also list all the requests that belong to a specific branch of the Sitemap tree by clicking on a tree node. The request table will be updated to display all the associated requests with details like the request method, path, status code and response length.

Intercept

The Intercept feature allows you to view requests and responses as they pass through the proxy. The Intercept page shows a table of all requests that have been proxied through Caido, along with details such as the request method, host, path, status code and length.

intercept

Filtering

The Intercept page provides several ways to filter and scope the requests displayed. These filters and scoping options can be useful to focus on specific requests or to exclude certain requests from the list.

You can filter requests by:

File Extension
Method
Port
Path
Status Code
...

intercept_with_filter_drawer

You can also scope the requests by host. See the Scope page for more details.

History

The History feature provides a comprehensive view of all the requests that have been generated by tools, such as the automate and replay features, in addition to requests that are proxied through Caido. The History page is similar to the Intercept page, with the same layout, filtering and scoping options.

history

Filtering

In addition to all the filter options available in Intercept, you can also filter by source tool (Replay, Intercept, Automate).

history_with_filter_drawer

Scope

The Scope feature allows you to filter requests throughout the app by creating presets of in-scope and out-of-scope hosts. Currently, scoping is only available for the history and intercept pages.

Creating a scope preset

The Scope feature is split into two panes, the left pane contains the list of scope presets, and the right pane contains the details for a scope preset. To create a new scope preset, follow these steps:

In the left pane, click on the "New Preset" button.
In the right pane, enter a name for the new preset in the "Preset Name" field.
Write the name of the host you want to add to the scope preset. You can use the wildcard characters '%' and '_' to create your presets.
Choose the type of the entry (in-scope or out-of-scope) and click "Add".
Click the "Save" button to create the preset.

scope_creation

Using scope presets

Once you have created a scope preset, you can apply it to the intercept and history pages by selecting it from the "Scope Preset" dropdown located in the top left corner of each page.

When you select a scope preset from the dropdown, the table in the page will be filtered based on the hosts defined in the selected scope preset.

selecting_scope

Forward

The Forward page allows you to control the flow of requests through the proxy by pausing and resuming forwarding. When forwarding is paused, requests that go through the proxy are temporarily stored in the Forward table, where you can review, edit, or drop them before forwarding them.

Pausing and Resuming Forwarding

To pause forwarding, toggle the "Forwarding" button on the top right of any page. This will prevent any new requests from being forwarded through the proxy and will queue them up in the Forward table.

For each request in the Forward table, you can then choose to edit its contents, as well as forward or drop it.

When you're done forwarding, toggle the "Queuing" button to resume forwarding. This will forward all the queued up requests in the Forward table.

forward

Replay

The Replay page allows you to edit and replay requests individually. This feature provides a flexible way to test your web applications by replaying requests with different parameters/headers.

You can create requests from scratch, or start from any existing request inside the application. Once a request is created, you can edit it and replay it as many times as needed.

replay

Replay Collections

Requests are organized into collections and sessions.

A session is a group of requests that are related to each other. Every time you edit and send a request, it is saved in the history of that replay session. This allows you to keep track of the changes you made to the request, and easily go back to previous versions.

Replay collections allow you to group sessions together. This allows you to keep your sessions organized and easily switch between them. You can group sessions however you want, for example, by project, by feature or by environment.

Automate (WIP)

Tamper

The Tamper feature allows you to define match and replace rules. These rules can be used to modify requests as they pass through the proxy.

Tamper 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 User-Agent rules, header rules, etc.

tamper

To create a tamper rule, click on the "More options" icon of the collection where you want to create the rule and select the option "Create rule."

When creating a new rule, you can update the following fields:

Name: A name for the rule.
Replace 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 term: The term to search for in the defined part of the request.
Replace term: The term to replace the search term with.

Testing your rule

When you're done updating your rule, you can use the right-side panes to test your rule against a mock request/response.

Click on the "Test" button and see if your rule works as intended.

Active rules

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 that pass through the proxy.

It's important to note that the order of the rules in the "Active rules" section determines the order in which they will be applied to the requests.

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.

Projects

The Projects page allows you to organize your work by creating different projects for different tasks or assessments. A project in Caido acts as a container for all the information related to a particular assessment, such as requests, filters, scope presets and tamper rules.

This allows you to easily switch between different assessments without losing track of the information you've collected and keep your work organized.

projects

Files

The Files page allows users to upload files to the Caido instance for future use in other features. This feature is particularly useful when you need to use the same file in different parts of the application.

Currently, files uploaded in this page are only available for use in the Automate page.

files

Layout Customization

Caido offers a high degree of customization, allowing users to rearrange and resize the different panes of the application to suit their needs.

To customize the layout of a page, simply click on the "Edit layout" button located on the top right corner of the page. Once the layout is in edit mode, you can move and resize the different panes according to your preferences.

layout_edit_mode

Convert

The Convert feature allows you to encode or decode text using a chain of encodings.

This feature consists of three main sections:

The encoder chain
The "Decoded" field where you can enter text.
The "Encoded" field where the final result of the encoding process is displayed.

convert

To use the Convert feature, you first need to define a chain of encodings. Once the chain is defined, you can enter text in the "Decoded" field. That text will be piped through the chain of encodings, with its output being displayed in the "Encoded" field.

Additionally, you can also pass data in the "Encoded" field and it will be piped through the chain in the opposite direction and update the "Decoded" section.

It's worth noting that this feature is one of our older features and we're planning on improving it during 2023, so its functionality may change in the future.

Files

Caido Storage Folder

All the data Caido creates is stored in a single folder. It can be moved to another computer, but you might encounter issues (we are working on project export/import).

OS	Location
Linux	`~/.local/share/caido`
MacOS	`~/Library/Application\ Support/io.caido.Caido/`
Windows	`%APPDATA%\caido\Caido\data`

Folder Structure

We do not recommend modifying the files directly as this might result in problems in the application and/or corruption of data. Proceed at your own risk.

Inside the storage folder you will see the following files:

config.db: Contains all the non-critical configurations of the instance. Also contains the cached data from the cloud for offline support.
secrets.db: Contains all the sensitive configurations. Currently, it is AES encrypted with a static secret, but we plan to support a user-specified password in the future.
projects.db: Contains the metadata of the projects and hosted files.

Each one of those files is a sqlite3 database in journal mode. We usually use pretty recent sqlite3 versions, but we do not make any guarantees on exactly which.

You can also see the following folders:

files: Those are the hosted files that you uploaded to your instance.
browsers: The binary of the browser used for rendering.
projects: The data for each project. Each sub-folder will be the UUID of the project (structure detailed below).

For each project, you will see the following:

database.caido: The majority of the data of the project is contained in that database.
database_raw.caido: Contains the raw data of the requests and responses, it is split for performance reasons.
exports: Folder containing the exported data

Each one of those files is a sqlite3 database in wal mode. Thus if you copy them, make sure to also copy the -wal files.

Authentication

The authentication in Caido is based on the OAuth 2.0 Authorization Framework. It replaces the need for licenses and will allow us to provide hosted and sharing services down the line. Each instance registers itself with our cloud API using the Dynamic Client Registration Protocol and obtains a client ID and secret. Upon the first login, the user will "claim" the client ID for its instance.

WARNING: Even if the API is authenticated, the actual proxy is currently not protected. That is why we strongly advise not to put your caido instances on the open internet.

Grants

We use a few OAuth2 grants depending on the API.

Client Credentials: We use this grant to get an access token that authenticates the instance itself with the cloud.
Device Authorization: We use this grant to get an access and refresh tokens that authenticate a user. This grant is nice because it doesn't require a redirect from the browser contrary to most other grants.
Refresh Token: We use this grant to refresh the access token of the user without having to ask the user to re-login. At this moment, we do not make any guarantees on the lifetime of the tokens.

authentication_user

Secrets storage

Client secret: Stored encrypted in the secrets.db database on the instance disk.
Instance access token: Stored encrypted in the secrets.db database on the instance disk.
User access & refresh tokens: Stored in the browser local storage of the user. Never stored on the instance, but can be present in memory.

Documentation

Our documentation is totally open source and is there to help the community. We are doing our best to improve it, but we would gladly welcome your contributions. Don't hesitate to join our Discord if you need help.

(Optional) Open an issue on the repository to let us know you are working on something
Fork the repository
Clone your fork: git clone https://github.com/[USERNAME]/documentation
Move into the directory: cd documentation
Create a new branch: git branch -b [BRANCH NAME]

You are now ready to edit files 🚀

Edits

Pages are primarely markdown files, but HTML can be used too
Always link pages in the SUMMARY.md file otherwise they won't show up
To render the website we suggest using: mdbook serve

Publish

Commit changes: git add . && git commit -m "[WHAT IS MY COMMIT ABOUT]"
Push changes to your fork: git push
Open a pull request on the Caido repository
A preview link will appear in a comment
Sign the CLA using the link that will also appear in a comment

We will then check your pull request, make changes if necessary and merge it. It will then appear on the official documentation 🎉

Caido Documentation