Skip to content

README.md

Latest commit

 

History

History
125 lines (89 loc) · 7.44 KB

README.md

File metadata and controls

125 lines (89 loc) · 7.44 KB
Raw

Titanium Web Proxy

A lightweight, asynchronous HTTP(S) proxy server for .NET.

Build NuGet NuGet downloads License

Code Quality

Quality Gate Coverage Lines of Code Bugs Vulnerabilities Code Smells Security Rating Reliability Rating Maintainability Rating Duplicated Lines Technical Debt

Features

  • Intercept, inspect, modify, redirect, or block HTTP and HTTPS traffic
  • Explicit, transparent, and SOCKS4/5 proxy endpoints
  • Request and response body streaming (see the protocol support matrix for the plain vs. TLS hook distinction)
  • HTTP/2 support, on by default, opt-out via ProxyServer.EnableHttp2 (see the protocol support matrix for exact coverage)
  • Upstream HTTP, HTTPS, and SOCKS proxies with automatic system proxy detection
  • Proxy authentication, mutual TLS, Kerberos, and NTLM support
  • Connection, certificate, and buffer pooling
  • Built-in, zero-overhead-when-disabled logging (every caught exception, optionally to console/file or your own ILoggerFactory) and opt-in structured request/connection timing — see Logging and diagnostics in the wiki

Installation

Install the stable package from NuGet:

dotnet add package Titanium.Web.Proxy

To use the latest prerelease:

dotnet add package Titanium.Web.Proxy --prerelease

Supported frameworks

  • .NET 10

Versions prior to 4.0 also supported .NET Framework 4.6.2 and .NET 8; starting with 4.0, the package targets .NET 10 only so the codebase can take full advantage of modern APIs.

Breaking change: ProxyServer.ExceptionFunc and SessionEventArgsBase.TimeLine were removed in favor of the unified ProxyServer.Logging/EnableRequestTimingCapture APIs described in Logging and diagnostics and Breaking changes: unified logging and timing.

Quick start

The following example starts an explicit HTTP(S) proxy on 127.0.0.1:8000 and logs each requested URL:

using System;
using System.Net;
using System.Threading.Tasks;
using Titanium.Web.Proxy;
using Titanium.Web.Proxy.EventArguments;
using Titanium.Web.Proxy.Models;

using var proxyServer = new ProxyServer();

proxyServer.BeforeRequest += OnRequest;

var endPoint = new ExplicitProxyEndPoint(IPAddress.Loopback, 8000, decryptSsl: true);
proxyServer.AddEndPoint(endPoint);

// Create and trust the root certificate used to decrypt HTTPS traffic.
proxyServer.CertificateManager.EnsureRootCertificate(
    userTrustRootCertificate: true,
    machineTrustRootCertificate: false);

proxyServer.Start();
Console.WriteLine("Proxy listening on 127.0.0.1:8000. Press Enter to stop.");
Console.ReadLine();
proxyServer.Stop();

static Task OnRequest(object sender, SessionEventArgs e)
{
    Console.WriteLine(e.HttpClient.Request.Url);
    return Task.CompletedTask;
}

Configure your client to use 127.0.0.1:8000 as its HTTP and HTTPS proxy. Trusting a generated root certificate changes the current user's certificate store; only do this on a machine you control.

Examples and documentation

Support and contributing

  • Report reproducible bugs and feature requests through GitHub Issues.
  • Ask programming questions on Stack Overflow using the titanium-web-proxy tag.
  • Pull requests are welcome. Please include tests for behavior changes when practical.

Maintainers

This project is actively maintained by:

Past contributors:

License

Titanium Web Proxy is available under the MIT License.