docs: add README.md

2026-05-13 12:20:54 -03:00
parent e58e4c3c01
commit 4730ddaf95
1 changed files with 130 additions and 0 deletions
@@ -0,0 +1,130 @@
+<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/)