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.

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.
What is the difference between Caido CLI and Caido Desktop
The Caido CLI is self-contained binary that launches the Caido proxy (also called instance). You can use it on remote servers or locally and access the instance using your browser. The Caido Desktop acts a connection manager to your instances and can also launch the Caido proxy in the background. It uses webviews to access the instance instead of the browser.
WARNING: At the moment, Caido Desktop is considered experimental and does not perform as well as the browser on Linux.
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 to127.0.0.1:1337
.
Running in Docker
Running the image
We offer images on Dockerhub that you can run directly on x86
:
docker run --rm -p 7000:8080 caido/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.
For M1 users, it is now possible to enable Rosetta in the Docker settings. You can then run images with
--platform linux/amd64
.
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.
Building the image
If you prefer to build the image 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"]
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.

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

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

Navigate to "CA Certificate" or click here.
Download the Certificate and follow the instructions to import and trust it in your browser of choice.
After you've successfully imported the certificate, you are good to go and can configure your browser to proxy it's traffic through Caido.
Data location
All the data Caido creates is stored in a single folder. Currently, it is not possible to create projects outside this folder. By default, this folder is in a standard location based on the OS.
OS | Location |
---|---|
Linux | ~/.local/share/caido |
MacOS | ~/Library/Application\ Support/io.caido.Caido/ |
Windows | %APPDATA%\caido\Caido\data |
You can however change the location of the whole folder if you need to!
WARNING: Make sure to copy your existing data to the new location before restarting your instance. Otherwise it will start fresh as if you were on a new device.
CLI
For the CLI, use the --data-path
option:
caido --data-path /some/data/path
Desktop
For the Desktop application, set the Data path
in the advanced options:

Reviews
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.
TheCyberMentor
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.
Hack The Box
- Intranet
Password Attacks
Command Injection
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.

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.
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 available for the Sitemap, Search and HTTP History 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.

Using scope presets
Once you have created a scope preset, you can apply it to the HTTP history and Search 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 on the page will be filtered based on the hosts defined in the selected scope preset.

Intercept
The Intercept 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 Intercept 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 Intercept table.

HTTP History
The HTTP History feature allows you to view requests and responses as they pass through the proxy. The HTTP History 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.

Filtering
The HTTP History 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
- ...

You can also scope the requests by host. See the Scope page for more details.
WS History
Streams
The WS History feature allows you to view data exchange between the client and the server passing through the proxy.
When an HTTP Connection is upgraded to Websocket, it will appear in the stream table.

Clicking on a stream will display the messages and their direction.

You can open each message to display the content.

Scopes
Scopes can be used to limit the domains displayed in the stream's table.
Match & Replace
The Match & Replace
feature allows you to define match & replace rules. These rules can be used to modify requests 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 User-Agent rules, header rules, etc.

To create a Match & Replace
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.
Make sure to save your rule, before you run the test!
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.
IMPORTANT
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.
Examples
Append a request header with a custom string
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. An example of this for Bugcrowd is to send the word bugcrowd
as your User-Agent header.
Strategy
Request header (Enable
Search as Regex
)
Search
^(User-Agent: .+)
Replace
$1 bugcrowd
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 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
The Automate page allows you to send requests in bulk. This feature provides a flexible way to bruteforce certain parameters of requests using wordlists.
You can create a session from scratch, or start from any existing request inside the application.

Payloads
To replace an element in your query, you first have to highlight it and click on Mark
. This will unlock the payload section on the right. Depending on the attack strategy and the number of markers, you will have one or more payloads to configure.
Strategies
We currently provide 4 attack strategies:
- Sequential: This will replace markers one at a time. If you have multiple markers, only one will be replaced for any given request.
- All: This will replace all the markers with the same value.
- Parallel: This will replace all the markers with different values from the different payloads. This requires payloads that each have the same number of elements.
- Matrix: This will replace all the markers with all the combinations of payloads. Payloads can have different number of elements, but beware that this can create a large number of requests.

Types
For each payload, you can choose a type
from the list:
- Hosted File: This allows you to select one of the files you had previously uploaded to the caido instance using the Files page.
- Simple List: This is for cases where you want to test a short list of elements.
- Null Payload: This is useful to generate requests without changing anything in it.

Settings
The settings allow you to choose how the Automate session will run. This allows you to throttle the bruteforce to avoid limits and retry in case of error. We do not limit the number of workers, but we suggest to not put too high a number unless latency is an issue.

Assistant
PRO FEATURE
The Assistant helps you understand requests, explains elements like headers and suggests attack vectors. The AI assistant in Caido is taylored for security research. See our privacy policy for more info.
Make sure to anonymize sensitive information when you use this tool.
Data is sent to a third party (OpenAI) and can be stored for up to 30 days. See their privacy policy for more info.
What are models?
Large Language Models (LLM) like GPT-3.5 are created through deep learning techniques and have the capability to understand, generate and manipulate text in a wide range of natural language tasks.
However, there are certains limitations to LLMs such as hallucinations (LLMs generating info that is not accurate or even completely fabricated), lack of understanding and biases.
LLMs are not going to "hack for you" since they have no consciousness or intent. They generate responses based solely on patterns in the data and input they receive.
Credits system
To prevent abuse, we use a credit system. Each pro user gets 500 000 credits per month. Credit usage depends on the model used. We currently offer ChatGPT-3.5 Turbo, but we will add support for the other models eventually.
- 1 credit is equal to 1 token
- A token is roughly a word or ¾ of a word.
- If you send follow-up messages in the same session, the tokens of all previous messages count in your credit usage
- You can send a maximum of 4000 tokens in a single session
For more info on what tokens are, check the ChatGPT Tokenizer.
Explain requests
Prompt
Explain the operation being performed by the endpoint in this request:
===
<YOUR REQUEST HERE>
===
The Assistant can help you understand what a request is doing by explaining it in natural language.
Be careful if your payload is huge, it can cost a lot of credits.

You can access the Assistant feature easily by right-clicking on a request in HTTP History
or Search
.

Warning: the request is sent automatically along with any sensitive information contained in it
If you need to anonymize data, copy the prompt the Assistant
should use, paste it in a new attempt with your request and remove any sensitive information before submitting it.
Generate CSRF
Prompt
Generate a CSRF PoC in HTML for the following request:
===
<YOUR REQUEST HERE>
===
The Assistant page currently allows you to generate proof of concept CSRF. We are planning to add more attacks in the future.
You can generate CSRF payloads for a specified request with the right click menu, similar to the Explain
request.

Convert Workflows
NOTE: Convert workflows are part of our new workflow system, it is still a work-in-progress. This documentation might be outdated when you read it.
Convert workflows allow you to create arbitrary conversion pipelines using nodes
chained together.
When running a workflow, the input
is injected in the Convert Start
node and it will run until it reaches a Convert End
node.

Flow
When you add new nodes, you need to make sure you always create a valid path in between the start and the end nodes.
The execution will follow the nodes' Execution
property, usually named exec
.
Data mapping
Nodes can have multiple inputs and outputs. Caido will do its best to automatically map the data between the nodes, but it might not always be possible.
You can change the data mapping by clicking on the pen
icon on the line connecting two nodes.
Nodes
We currently only offer "official" nodes made by us, but we hope to allow the community to create custom nodes in the near future!
Regular
There are many "regular" nodes offered in Convert workflows, you can select them from the left panel.
They are grouped by tag
and can appear in multiple places.

They usually have some parameters that you can configure directly in the node. Those will affect how the node behaves.
Code
PRO FEATURE
Code nodes allow you to run custom scripts in your convert pipeline.
They have a minimal code editor that you can open when clicking on Edit Code
.
The code must export a function called run
that takes an input
and the sdk
as arguments and return either a String or an Array of numbers (representing the UTF-8 bytes).
By default, the input is an array of bytes.
export function run(input, sdk) {
let parsed = sdk.asString(input);
sdk.console.log(parsed);
return parsed;
}
The sdk
object provides some basic utilities, namely:
console
: This is similar to theconsole
provided in standard Javascript runtimes. Only thelog
method is available at the moment.asString
: This loosely converts an array of bytes into a String, invalid characters will be represented with the � character.
Please let us know which utilities you would like to see in the SDK!
Control flow
PRO FEATURE
Control flow nodes allow you to take various paths based on some conditions.
Right now we only offer an if/else
, but we will likely offer loops and other control flow nodes in the future.
The if/else
node is very similar to the code node, with the exception that it must return a boolean.

export function run(input, sdk) {
return false;
}
Based on the result, the execution will take the True
or False
branch.
Make sure to connect both to the rest of the workflow!
Search
The Search 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 Search page is similar to the HTTP History page, with the same layout, filtering and scoping options.

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

Exports
The Exports feature allows you to export data from the HTTP History and Search pages and use data collected by Caido in other tools. This feature can also be used for archival purposes or audit purposes sometimes required by clients.
Exports types
The Exports feature generates two types of exports:
- All: exports all data of the specified tool.
- Current rows (Pro feature): exports only rows that match the filter and scope currently set.
Exports formats
Two export formats are available: JSON and CSV.
JSON
For the JSON format, data will be exported as an array of requests with their respective response nested. See the full JSON schema below.
SCHEMA
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "DataExport",
"type": "array",
"items": {
"$ref": "#/definitions/ExportRequest"
},
"definitions": {
"ExportRequest": {
"type": "object",
"required": [
"alteration",
"created_at",
"edited",
"host",
"id",
"is_tls",
"length",
"method",
"path",
"port",
"query",
"source"
],
"properties": {
"alteration": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64"
},
"edited": {
"type": "boolean"
},
"file_extension": {
"type": [
"string",
"null"
]
},
"host": {
"type": "string"
},
"id": {
"type": "integer",
"format": "int32"
},
"is_tls": {
"type": "boolean"
},
"length": {
"type": "integer",
"format": "int32"
},
"method": {
"type": "string"
},
"parent_id": {
"type": [
"integer",
"null"
],
"format": "int32"
},
"path": {
"type": "string"
},
"port": {
"type": "integer",
"format": "int32"
},
"query": {
"type": "string"
},
"raw": {
"type": [
"string",
"null"
]
},
"response": {
"anyOf": [
{
"$ref": "#/definitions/ExportResponse"
},
{
"type": "null"
}
]
},
"source": {
"type": "string"
}
}
},
"ExportResponse": {
"type": "object",
"required": [
"alteration",
"created_at",
"edited",
"id",
"length",
"status_code"
],
"properties": {
"alteration": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64"
},
"edited": {
"type": "boolean"
},
"id": {
"type": "integer",
"format": "int32"
},
"length": {
"type": "integer",
"format": "int32"
},
"parent_id": {
"type": [
"integer",
"null"
],
"format": "int32"
},
"raw": {
"type": [
"string",
"null"
]
},
"status_code": {
"type": "integer",
"format": "int32"
}
}
}
}
}
CSV
For the CSV format, each request/response pair will be exported on a row. Since CSV does not support nested columns, the response's columns have been renamed.
COLUMNS
id,host,method,path,length,port,raw,is_tls,query,file_extension,source,alteration,edited,parent_id,created_at,response_id,response_status_code,response_raw,response_length,response_alteration,response_edited,response_parent_id,response_created_at
Download
Once the export is completed, it will be available on the Exports page.
From there you can download it, rename it, or delete it.
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.

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.

Backups
You can create backups of you projects at anytime inside Caido.
They are self-contained files that can be easily shared with colleagues, partners, clients, etc.
Creating backups is a Pro
feature, but all plans can restore backups.
Create
PRO FEATURE
You create backups directly from the Projects
tab of your Workspace
in the 3-dots menu.
It is possible to backup any project including the currently selected one.

Once the backup is done, it will be available in the Backups
tab. If your instance is remote, you can Download
the backup to your local machine. Otherwise, you can click on the 3-dots menu to get the path on disk if you wish to copy it directly.

Restore
Restoring a backup is usually done via the Import
button in the Projects
tab.
You will need to upload a backup file to the instance to perform the restore.
Restoring always creates a new project, that is why you also need to enter a unique name.

Projects can also be restored from existing backups in the Backups
tab. It will also create a new project on restore.

Layout Customization
Caido offers a high degree of customization, allowing users to resize the different panes of the application to suit their needs.
To customize the layout of a page, simply drag the side of the panes to resize them according to your preferences.

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.

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.
Requirements
Steps
Prepare
- (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 🎉