# Solpuga

> Solpuga is a cross-platform desktop HTTP/HTTPS debugging proxy for developers, QA, and security teams. Free during beta.

---

## Quick Start

Source: https://solpuga.pro/en/docs/quick-start

Solpuga is a desktop MITM proxy that captures, inspects, and modifies HTTP/HTTPS traffic on macOS, Windows, and Ubuntu.

## System Requirements

All platforms require a 64-bit operating system and network access for proxy traffic capture.

| Platform | Minimum Version | Notes |
|----------|----------------|-------|
| macOS    | 10.15 Catalina or later | Apple Silicon (ARM64) · Xcode Command Line Tools |
| Windows  | Windows 10 version 1803 or later | x64 · WebView2 runtime (included in Windows 11, auto-installed on Windows 10) · Microsoft Visual C++ Redistributable |
| Linux    | Ubuntu 22.04+ (AMD/ARM) | WebKitGTK 4.1 (libwebkit2gtk-4.1) · GTK 3 · OpenSSL · Privilege escalation via pkexec (Polkit), graphical sudo (zenity/kdialog/yad), or terminal sudo |

## First Launch

1. **Install the CA certificate** — SSL Certificate → Install certificate on this device. The wizard will guide you through the installation and ask for your system password. See [Certificate Installation](certificate) for details.

2. **Enable system proxy** — Click the play button in the control bar. Solpuga will configure your system proxy automatically.

3. **Browse** — Open any browser or app. HTTP and HTTPS traffic will appear in the flow list.

The default proxy port is **7070**. You can change it in [Settings](settings).

---

## Certificate Installation

Source: https://solpuga.pro/en/docs/certificate

Solpuga generates a unique CA certificate for every installation. This certificate is used to sign server certificates on the fly, allowing the proxy to intercept and decrypt HTTPS traffic.

## Desktop

Go to **SSL Certificate → Install certificate on this device**. A three-step wizard will walk you through:

1. **Introduction** — explains what will happen.
2. **Install** — click **Install Automatically**. Follow the system prompt.
3. **Verify** — confirms the certificate is trusted.

### Platform Details

**macOS** — A native security dialog appears (Touch ID or password). The certificate is added to your system keychain and marked as trusted for SSL.

### Manual Installation

If automatic installation fails, click **Install Manually** in the wizard. Download the certificate file and follow the on-screen instructions for your platform.

## Uninstalling the Certificate

Open **Settings** (Cmd+, / Ctrl+,) → **Proxy** section → click the trash icon next to the certificate info.

## Exporting the Certificate

Open **Settings** → **Proxy** section → click the download icon next to the certificate info. The certificate is exported in PEM format.

---

## Capture & Inspect Traffic

Source: https://solpuga.pro/en/docs/traffic

## Layout

The main window has three panes:

- **Traffic Panel** (left) — hosts organized by category.
- **Flow List** (center) — all captured HTTP requests.
- **Inspector** (right) — details of the selected request/response.

## Traffic Panel

Hosts are grouped into sections:

- **Pinned** — hosts you pinned via right-click menu.
- **Devices** — iOS Simulators, Android Emulators.
- **Apps** — detected applications.
- **Hosts** — all other hosts.

Click a host or section to filter the flow list.

## Flow List

Each row shows: **#**, **Method**, **Status**, **URL**, **Time**. The list is virtualized for performance — thousands of flows render smoothly.

### Filters

Click the filter bar above the flow list. Available filters:

| Filter | Options |
|--------|---------|
| **Method** | GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, etc. |
| **Scheme** | HTTP, HTTPS |
| **Status** | Success (2xx), Redirect (3xx), Client Error (4xx), Server Error (5xx), or a specific code |
| **Host** | Contains or exact match |
| **Path** | Contains or exact match |

Use **Quick search** to search across all fields at once. Click **Clear all** to reset filters.

### Context Menu

Right-click a flow to:

- **Pin Host** — add the host to the Pinned section in the traffic panel.
- **Map Local** — create a rewrite rule for this URL.
- **Bypass Host** — add the host to the bypass list (skip HTTPS interception).

## Inspector

Select a flow to open the inspector. Switch between **Request** and **Response** tabs.

### Tabs

**Request**: Headers, Body, Auth, Raw, Summary.
**Response**: Headers, Body, Raw, Summary.

### Body Viewers

The body tab auto-selects the appropriate viewer based on content type:

- **JSON** — syntax-highlighted, collapsible tree.
- **HTML** — rendered view.
- **Image** — preview with dimensions and file size.
- **Audio/Video** — inline media player.
- **Text** — plain text with syntax highlighting.
- **Binary** — hex preview.

For large bodies, a **Save to File** button appears instead.

### Export

From the inspector, you can copy headers, save the response body, or export the raw HTTP message.

## Rewrite Rules (Map Local)

Open via **Tools → Map Local** (Cmd+Shift+M / Ctrl+Shift+M).

Rules let you replace HTTP responses with custom content. Each rule has:

- **Name** — a label for the rule.
- **Domain pattern** — wildcard matching (e.g., `*.example.com`).
- **Search pattern** — regex to match the URL path (e.g., `api/v1/(.*)`).
- **Replacement** — capture group replacement (e.g., `api/v2/$1`).
- **Response** — custom status code, headers, and body (JSON, HTML, or plain text).
- **Enabled toggle** — turn rules on/off without deleting them.

Rules are stored in encrypted local storage.

---

## Mobile Devices

Source: https://solpuga.pro/en/docs/smartphones

Solpuga can intercept traffic from iOS and Android devices and emulators. Each has a dedicated setup wizard accessible from the **SSL Certificate** menu.

## iOS Simulator (macOS only)

**SSL Certificate → Install certificate on iOS Simulator**

The wizard has four steps:

1. **Install root CA** — installs the certificate into the macOS system keychain (if not already done).
2. **Push to simulator** — installs the certificate into each booted simulator's trust store via `xcrun simctl keychain`.
3. **Reboot** — reboots the simulator(s) to apply trust settings.
4. **Enable SSL trust** (optional) — if HTTPS traffic still isn't captured, manually enable trust in the simulator: Settings → General → About → Certificate Trust Settings.

A **Test Connection** button opens a test page in the simulator to verify interception.

**Requirements**: Xcode Command Line Tools.

## iOS Device (macOS only)

**SSL Certificate → Install certificate on iOS Device**

1. **Install root CA** — installs the certificate into the macOS system keychain.
2. **Deliver certificate** — transfer the profile to your device:
   - **QR / Browser** — scan the QR code with your device's camera (proxy must be running). The device downloads the profile from `http://solpuga.proxy/ssl`.
   - **AirDrop** — send the certificate file directly to the device.
3. **Install profile** — on the device, go to Settings → tap the "Profile Downloaded" banner → Install.
4. **Enable full trust** — Settings → General → About → Certificate Trust Settings → enable the Solpuga CA toggle.
5. **Configure Wi-Fi proxy** — on your device: Settings → Wi-Fi → tap (i) on your network → Configure Proxy → Manual. Enter the computer's IP and port **7070**.

> Disable VPN on both your Mac and iOS device before configuring the proxy.

### Removing the Profile

Settings → General → VPN & Device Management → Solpuga profile → Remove Profile.

## Android Emulator (all platforms)

**SSL Certificate → Install certificate on Android Emulator**

1. **Install root CA** — generates and stores the certificate.
2. **Push to emulator** — pushes the certificate to `/system/etc/security/cacerts/` via `adb push` (requires writable system partition).
3. **Configure proxy** — sets the Android global HTTP proxy to `10.0.2.2:7070` (the emulator-to-host gateway).
4. **Apply settings** — restart running apps.

A **Test Connection** button verifies interception. When done, use the **Revert Configuration** section to clear the proxy and remove the certificate.

**Requirements**: Android SDK, ADB.

> Google Play images are not supported (system partition is read-only). Certificate may reset on emulator reboot — re-run the installer.

## Android Device (all platforms)

**SSL Certificate → Install certificate on Android Device**

Two modes: **USB (ADB)** and **Wi-Fi (QR)**.

### USB Mode

1. **Install root CA** — generates and stores the certificate.
2. **Detect device** — connect via USB with USB Debugging enabled. Solpuga detects the device and checks root status.
3. **Configure proxy** — set the Wi-Fi proxy manually on the device: Settings → Network → tap your network → Modify → Advanced → Proxy → Manual. Enter the computer's IP and port **7070**. Alternatively, for USB, use ADB to set the global proxy.
4. **Install certificate**:
   - **Rooted device** — certificate is pushed directly to `/system/etc/security/cacerts/`. Trusted by all apps including those targeting API 24+. Device reboots.
   - **Non-rooted device** — certificate is pushed as a user certificate via `adb push` + install intent. Must be confirmed on the device. Note: Chrome ignores user CAs on Android 7+ — use Firefox, or root for system-level trust.
5. **Verify** — opens a test HTTPS page on the device to confirm interception.

### Wi-Fi Mode

No USB needed. Phone and computer must be on the same Wi-Fi network.

1. Set the Wi-Fi proxy manually on the phone (Settings → Wi-Fi → long-press network → Modify → Proxy → Manual, enter IP and port).
2. Scan the QR code to download and install the certificate.

### Platform Notes

- **Linux**: ADB may need udev rules for USB access.
- **Windows**: may require Google USB Driver.

### Removing Configuration

On the device: remove the proxy from Wi-Fi settings, then go to Settings → search "Trusted credentials" → remove the Solpuga CA from the User or System tab. Restart the device.

---

## Settings

Source: https://solpuga.pro/en/docs/settings

Open via menu **Settings**.

## Proxy

- **IP Address** — the address the proxy listens on. `0.0.0.0` = all interfaces (recommended), `127.0.0.1` = localhost only.
- **Port** — proxy port (1–65535). Default: **7070**. Ports below 1024 require elevated privileges.
- **Certificate** — shows the installed CA certificate name, issued/expires dates, and trust status. Buttons to **export** (PEM) or **uninstall** the certificate.

## Startup

- **Override system proxy at launch** — automatically configure the system proxy when the app starts.
- **Auto capture** — begin capturing traffic automatically on launch.

## Bypass List

Domains and IPs that skip HTTPS interception. Useful for certificate-pinned services.

Enter patterns in the input field and click **Add**. Supported formats:

- Hostnames: `example.com`
- Wildcards: `*.example.com`
- IP addresses: `192.168.1.1`
- CIDR ranges: `192.168.1.0/24`

Do not include `http://` or `https://`.

## Advanced

- **Strict TLS Validation** — when enabled, validates upstream server certificates against WebPKI roots. Disabled by default (the proxy accepts all upstream certificates). Requires proxy restart.

## Language

Switch between languages via **View → Language** in the menu bar.

## Theme

Switch between themes via **View → Theme** in the menu bar.