130 lines
3.8 KiB
Markdown
130 lines
3.8 KiB
Markdown
<h1 align="center">
|
|
<b>TinyMITM</b>
|
|
</h1>
|
|
|
|
<p align="center">
|
|
A <b>tiny event-driven C++20</b> library for intercepting, debugging and modifying HTTP/HTTPS traffic.
|
|
</p>
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
* [Installation & Integration](#installation--integration)
|
|
* [Build Options](#build-options)
|
|
* [Usage](#usage)
|
|
* [Configuration](#configuration)
|
|
* [Running tests](#running-tests)
|
|
|
|
## Installation & Integration
|
|
|
|
### 1. Requirements
|
|
* **Compiler**: A C++20 compliant compiler.
|
|
* **Build System**: CMake 4.1.0 or higher.
|
|
|
|
### 2. Integration via CMake
|
|
#### Option A: Using FetchContent (Recommended)
|
|
You can pull the library directly into your project from the git repository. Add this to your CMakeLists.txt:
|
|
|
|
```cmake
|
|
include(FetchContent)
|
|
|
|
FetchContent_Declare(
|
|
tinymitm
|
|
GIT_REPOSITORY https://git.neru.rip/neru/tinymitm.git
|
|
GIT_TAG main # or a specific commit hash
|
|
)
|
|
|
|
FetchContent_MakeAvailable(tinymitm)
|
|
|
|
target_link_libraries(your_project PRIVATE tinymitm)
|
|
```
|
|
|
|
#### Option B: Local Path
|
|
If you have the library downloaded locally:
|
|
```cmake
|
|
add_subdirectory(path/to/tinymitm)
|
|
|
|
target_link_libraries(your_project PRIVATE tinymitm)
|
|
```
|
|
|
|
## Build Options
|
|
Toggle features by setting these variables to ``ON`` or ``OFF`` in your CMake configuration.
|
|
| Option | Description | Default |
|
|
| :--- | :--- | :--- |
|
|
| TINYMITM_LOGS | Adds log sink support (seallib) | OFF |
|
|
| TINYMITM_TEST | Adds test project | OFF |
|
|
|
|
---
|
|
|
|
|
|
## Usage
|
|
|
|
```cpp
|
|
#include <tinymitm/proxy.h>
|
|
|
|
int main() {
|
|
TinyMITMConfig config;
|
|
config.port = 44444;
|
|
config.threadCount = 10;
|
|
|
|
auto proxy = std::make_unique<TinyMITMProxy>(config);
|
|
|
|
// Intercept and modify outgoing requests
|
|
proxy->onClientRequest.add([](const std::string& url, std::string& body, std::string& headers, bool& block) {
|
|
if (url.find("example.com") != std::string::npos) {
|
|
printf("Intercepted request to example.com\\n");
|
|
// You can modify 'body' or 'headers' here, or just block the request altogether
|
|
}
|
|
});
|
|
|
|
// Intercept and modify incoming responses
|
|
proxy->onServerResponse.add([](const std::string& url, std::string& body, std::string& headers, bool blocked) {
|
|
if (!blocked) {
|
|
// Rewrite response content
|
|
size_t pos = body.find("Hello");
|
|
if (pos != std::string::npos) {
|
|
body.replace(pos, 5, "Goodbye");
|
|
}
|
|
}
|
|
});
|
|
|
|
proxy->init();
|
|
|
|
// Proxy is now running in the background...
|
|
while(true) std::this_thread::sleep_for(std::chrono::seconds(1));
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
The `TinyMITMConfig` struct allows you to customize the proxy's behavior:
|
|
|
|
| Field | Type | Default | Description |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `port` | `unsigned short` | `44444` | The port the proxy server listens on. |
|
|
| `threadCount` | `unsigned char` | `255` | Number of worker threads in the connection pool. |
|
|
| `caCertPath` | `std::string` | `"ca.pem"` | Path to the CA certificate used for signing. |
|
|
| `caKeyPath` | `std::string` | `"ca.key"` | Path to the CA private key. |
|
|
| `autoGenerateCA` | `bool` | `true` | Automatically create a new CA if files are missing. |
|
|
| `caName` | `std::string` | `"TinyMITM-CA"` | CN used when auto-generating a CA. |
|
|
| `caDays` | `int` | `365` | Validity period (in days) for auto-generated CA. |
|
|
| `installToSystemStore`| `bool` | `true` | (Windows only) Automatically install the CA to the user's Trusted Root store. |
|
|
|
|
## Running tests
|
|
|
|
### Windows (PowerShell + Visual Studio)
|
|
A script is provided to automate generation and open the solution in Visual Studio:
|
|
|
|
./create-test.ps1
|
|
|
|
### Cross-Platform (CLI)
|
|
To build and run manually from the terminal:
|
|
|
|
```bash
|
|
mkdir build && cd build
|
|
cmake .. -DTINYMITM_TEST=ON
|
|
cmake --build .
|
|
./tinymitm-test
|
|
```
|
|
|
|
### License
|
|
[MIT](https://choosealicense.com/licenses/mit/) |