Production-ready Rust library for HTTPS MITM proxy with enterprise-grade security
Derusted is a high-performance forward proxy library built in Rust for HTTPS traffic inspection via dynamic TLS certificate generation. Built for safety, security, and developer experience.
Version: 0.1.1 | Status: ✅ Production Ready
- ✅ Dynamic Certificate Generation - On-the-fly TLS certificates per domain
- ✅ CA Key Management - Secure integration with HashiCorp Vault, AWS KMS, or environment variables
- ✅ Certificate Caching - LRU + TTL cache (default 24-hour TTL, max 1000 certs)
- ✅ Thread-Safe Operations - Arc/Mutex for concurrent access
- ✅ Memory Protection - CA private key never logged, proper zeroing on drop
- ✅ Request Interception - Full HTTP/1.1 request inspection and modification
- ✅ Response Interception - Complete response capture with streaming support
- ✅ Method Support - GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
- ✅ Header Manipulation - Read, modify, add, remove headers
- ✅ Body Inspection - Access to request/response bodies
- ✅ SQLite Request Logging - Persistent storage of HTTP transactions
- ✅ PII Redaction - Automatic redaction of 6 sensitive data types:
- Email addresses →
[EMAIL REDACTED] - Credit cards →
[CC REDACTED] - Social Security Numbers →
[SSN REDACTED] - Phone numbers →
[PHONE REDACTED] - Bearer tokens →
[TOKEN REDACTED] - API keys →
[API_KEY REDACTED]
- Email addresses →
- ✅ Sensitive Header Redaction - Authorization, Cookie, Set-Cookie, X-API-Key, etc.
- ✅ 13 Unit Tests - Comprehensive PII redaction test coverage
- ✅ 60+ Static Bypass Rules - Pre-configured for certificate-pinned services
- ✅ Dynamic Pinning Detection - Automatic bypass after 3 failed TLS handshakes
- ✅ HSTS Support - Honors Strict-Transport-Security headers
- ✅ Localhost Bypass - Never MITM localhost/127.0.0.1
- ✅ Bypass Categories: Banking, payments, government, cloud providers, developer tools
- ✅ Full HTTP/2 Support - Stream multiplexing with flow control
- ✅ ALPN Negotiation - Automatic protocol selection
- ✅ Stream Management - Concurrent stream handling
- ✅ Chunked Transfer - Streaming response support
- ✅ Error Handling - Proper HTTP/2 error codes
- ✅ Connection Pooling - Reuses TLS connections (HTTP/1.1 + unknown protocols)
- Per-host pools with max 10 idle connections
- 90-second idle timeout, 10-minute max lifetime
- Background cleanup every 60 seconds
- ✅ Certificate Cache TTL - Bounded memory with dual eviction (LRU + TTL)
- ✅ Pool Statistics - Hits, misses, evictions tracking
- ✅ Comprehensive Security Audit - No blocking vulnerabilities for v0.1.0
- ✅ Threat Model - 6 major threats documented with mitigations
- ✅ CA Rotation Procedures - Both scheduled and emergency rotation playbooks
- ✅ Dependency Audit - 6 CVEs found, all assessed as non-blocking
- ✅ SSRF Protection - Blocks private IPs (RFC1918), localhost, cloud metadata endpoints
- ✅ Memory Safety - 100% safe Rust (no
unsafeblocks)
- ✅ Library-First Design - Clean API for integration
- ✅ 148 Passing Tests - Comprehensive test coverage (150 with
network-testsfeature) - ✅ Detailed Documentation - Security audit, threat model, guides
- ✅ MIT License - Maximum permissiveness for open source use
Add Derusted to your Cargo.toml:
[dependencies]
derusted = "0.1.0"Or use the latest from GitHub:
[dependencies]
derusted = { git = "https://github.com/your-org/derusted", tag = "v0.1.0" }# Generate CA private key (4096-bit RSA)
openssl genrsa -out ca-key.pem 4096
# Generate CA certificate (valid for 10 years)
openssl req -new -x509 -days 3650 \
-key ca-key.pem \
-out ca-cert.pem \
-subj "/C=US/ST=CA/L=SF/O=YourOrg/OU=IT/CN=YourOrg MITM CA"
# Set environment variables
export CA_CERT=$(cat ca-cert.pem)
export CA_KEY=$(cat ca-key.pem)use derusted::mitm::{CaKeyManager, CertificateAuthority, MitmInterceptor};
use std::sync::Arc;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Initialize CA from environment variables
let ca_manager = CaKeyManager::from_env("CA_CERT", "CA_KEY").await?;
// Create certificate authority with default config
let cert_authority = CertificateAuthority::new(ca_manager);
// Create MITM interceptor
let interceptor = Arc::new(MitmInterceptor::new(cert_authority));
// Use interceptor to handle TLS connections
// interceptor.intercept(client_stream, target_host, target_port).await?;
Ok(())
}use derusted::mitm::CaKeyManager;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Load CA from Vault
let ca_manager = CaKeyManager::from_vault(
"http://vault.example.com:8200",
"s.YourVaultToken",
"secret/data/mitm/ca"
).await?;
// Use ca_manager as before...
Ok(())
}use derusted::mitm::CaKeyManager;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Load CA from KMS
let ca_manager = CaKeyManager::from_kms(
"us-east-1",
"alias/mitm-ca-key",
"arn:aws:s3:::your-bucket/ca-cert.pem"
).await?;
Ok(())
}use derusted::mitm::MitmInterceptor;
use std::time::Duration;
// Enable automatic bypass for pinned domains
let interceptor = MitmInterceptor::with_pinning(
cert_authority,
3, // max failures before bypass
Duration::from_secs(300), // bypass duration: 5 minutes
);Built over 8 weeks with clear separation of concerns:
derusted/
├── src/
│ ├── lib.rs # Public API exports
│ ├── mitm/
│ │ ├── ca_key_manager.rs # CA key management (Week 1)
│ │ ├── certificate_authority.rs # Certificate generation + caching (Week 1)
│ │ ├── interceptor.rs # MITM decision engine (Week 2-3, 6)
│ │ ├── tls_config.rs # TLS configuration (Week 1)
│ │ ├── logging.rs # PII redaction (Week 4)
│ │ ├── log_storage.rs # SQLite storage (Week 4)
│ │ ├── bypass.rs # Smart bypass system (Week 5)
│ │ ├── pinning.rs # Pinning detection (Week 5)
│ │ ├── http_parser.rs # HTTP/1.1 parsing (Week 2-3)
│ │ ├── http2_mitm.rs # HTTP/2 MITM (Week 6)
│ │ └── error.rs # Error types
│ ├── connection_pool.rs # Connection pooling (Week 7)
│ ├── destination_filter.rs # SSRF protection
│ └── ...
│
├── docs/
│ ├── SECURITY_AUDIT.md # Complete security audit (Week 8)
│ ├── THREAT_MODEL.md # Threat analysis (Week 8)
│ ├── CA_ROTATION.md # Rotation procedures (Week 8)
│ └── CI_CD_NOTE.md # CI/CD decision (Week 8)
│
├── pdocs/ # Weekly development summaries
│ ├── WEEK1_FINAL_SUMMARY.md
│ ├── WEEK2_SUMMARY.md
│ ├── WEEK3_SUMMARY.md
│ ├── WEEK4_FINAL_SUMMARY.md
│ ├── WEEK5_SUMMARY.md
│ ├── WEEK6_SUMMARY.md
│ ├── WEEK7_SUMMARY.md
│ └── WEEK8_PLAN.md
│
└── tests/
└── (150 passing tests)
Run the full test suite:
# Default: 148/152 tests pass (DNS tests excluded)
cargo test --lib
# With network tests enabled: 150/152 tests pass (requires DNS)
cargo test --lib --features network-tests
# With output
cargo test --lib -- --nocapture
# Specific module
cargo test --lib mitm::logging::testsNote: By default, 148/152 tests pass. Two DNS-dependent tests (destination_filter::tests::test_allow_public_domain and test_dns_caching) are gated behind the network-tests feature flag to ensure compatibility with restricted/sandboxed environments. Enable them with --features network-tests to run all 150/152 tests (2 remain ignored).
Run security checks:
# Clippy lints
cargo clippy --all-targets -- -D warnings
# Security audit (requires cargo-audit)
cargo audit
# Format check
cargo fmt --all -- --checkTest Coverage: 150 tests covering:
- CA key management
- Certificate generation and caching
- HTTP/1.1 request/response interception
- HTTP/2 MITM
- PII redaction (13 dedicated tests)
- Bypass system
- Connection pooling
- SSRF protection
| Optimization | Expected Impact | Status |
|---|---|---|
| Connection Pooling | +20-30% throughput | ✅ Implemented |
| Certificate Cache TTL | Bounded memory <50MB | ✅ Implemented |
| TLS Handshake Savings | 150-300ms per pooled connection | ✅ Implemented |
| Latency (p99) | <500ms for cached connections | ✅ Target met |
use derusted::connection_pool::{ConnectionPool, PoolConfig};
let config = PoolConfig {
max_idle_per_host: 10, // Max idle connections per host
idle_timeout: Duration::from_secs(90), // 90-second idle timeout
max_lifetime: Duration::from_secs(600), // 10-minute max lifetime
connection_timeout: Duration::from_secs(30),
};
let pool = ConnectionPool::with_config(config);Overall Assessment: ✅ APPROVED FOR v0.1.0 RELEASE
| Category | Status | Details |
|---|---|---|
| CA Private Key | ✅ PASS | No logging, proper memory protection |
| PII Redaction | ✅ PASS | 6 patterns, 13 unit tests |
| Error Messages | ✅ PASS | No sensitive data exposure |
| Memory Safety | ✅ PASS | No unsafe blocks |
| Input Validation | ✅ PASS | SSRF protection, hostname validation |
| Dependencies | 6 CVEs, all non-blocking |
6 CVEs found, all assessed as non-blocking for v0.1.0:
- hpack v0.3.0 (CRITICAL): DoS via HTTP/2 headers - server recovers
- idna v0.4.0 (MEDIUM): Punycode validation - low risk for proxy
- protobuf v2.28.0 (HIGH): Recursion DoS - internal metrics only
- ring v0.16.20 (MEDIUM): AES panic - not default in release
- rsa v0.9.9 (MEDIUM): Timing attack - unused MySQL feature
- sqlx v0.7.4 (HIGH): Binary protocol - affects MySQL/PostgreSQL, not SQLite
Action Items for v0.2.0:
- Upgrade sqlx to 0.8.1+
- Upgrade rcgen to version using ring 0.17+
- Migrate trust-dns to hickory-dns
See docs/SECURITY_AUDIT.md for complete details.
Comprehensive documentation created during Week 8:
- SECURITY_AUDIT.md - Complete security code audit
- THREAT_MODEL.md - 6 major threats with mitigations
- CA_ROTATION.md - Scheduled and emergency rotation procedures
- CI_CD_NOTE.md - CI/CD decision and manual checks
Contributions are welcome! See CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and linters:
cargo test --all cargo clippy --all-targets -- -D warnings cargo fmt --all cargo audit - Commit your changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
See CHANGELOG.md for detailed version history.
Initial open source release after 8 weeks of development:
- Week 1: CA key management + certificate generation
- Week 2-3: HTTP/1.1 MITM (request + response interception)
- Week 4: Logging + PII redaction
- Week 5: Smart bypass system (60+ rules + dynamic pinning)
- Week 6: HTTP/2 MITM support
- Week 7: Performance optimization (connection pooling + caching)
- Week 8: Security hardening + documentation
Core Features:
- Dynamic certificate generation with Vault/KMS/env support
- HTTP/1.1 and HTTP/2 MITM capabilities
- Automatic PII redaction (6 patterns)
- Smart bypass for certificate-pinned domains
- Connection pooling for HTTP/1.1
- 150 passing tests
- Comprehensive security audit
Known Limitations:
- HTTP/2 connections cannot be pooled (handler takes ownership)
- 6 dependency CVEs (all non-blocking, tracked for v0.2.0)
- Certificate cache: 24-hour TTL, max 1000 certs
Licensed under the MIT License.
MIT License
Copyright (c) 2025 Kumar AS
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
See LICENSE for full details.
- Pinaka Edge V2 - Enterprise proxy management platform (proprietary)
- Uses Derusted as the core MITM proxy library
- Adds centralized policy management, smart categorization, and DLP
The following CVEs exist in indirect dependencies and are documented for transparency. None are blocking for v0.1.0 release:
| Dependency | Version | Advisory | Severity | Status | Notes |
|---|---|---|---|---|---|
| hpack | 0.3.0 | RUSTSEC-2024-0003 | CRITICAL | ❌ Unfixed | No patched version available. Tracked for v0.2.0 |
| h2 | 0.3.27 (indirect) | Unknown | Unknown | Newer h2 0.4.12 also in tree. Review needed | |
| protobuf | 2.28.0 | RUSTSEC-2021-0073 | HIGH | ❌ Unfixed | Via pprof (dev-dependency). Low risk |
| idna | 0.2.x | Multiple | MEDIUM | ❌ Unfixed | Indirect dependency |
| ring | Various | Various | MEDIUM | ❌ Unfixed | Indirect dependency |
| rsa | Various | Various | MEDIUM | ❌ Unfixed | Indirect dependency |
| trust-dns-resolver | Old | Deprecated | LOW | Should migrate to hickory-dns in v0.2.0 |
Fixed in v0.1.0:
- ✅ sqlx 0.7.4 → 0.8.6 (RUSTSEC-2024-0363, HIGH severity)
Impact Assessment: These CVEs are in HTTP/2 parsing, TLS, and DNS resolution libraries. The proxy operates in a trusted internal network environment where these risks are mitigated by network segmentation and access controls. Full remediation planned for v0.2.0.
Recommendations:
- Deploy behind firewall with restricted network access
- Monitor for updates to hpack, h2, and trust-dns-resolver
- Run
cargo auditregularly for new advisories
Two tests require network access and may fail in sandboxed CI environments:
destination_filter::tests::test_allow_public_domaindestination_filter::tests::test_dns_caching
These tests perform actual DNS resolution to example.com. In restricted environments without DNS access, they will fail with "Operation not permitted". This does not indicate a bug in the library.
Solutions:
- Run tests in Docker with network access:
docker-compose up - Use test feature flag (planned for v0.2.0)
- Accept 148/150 passing tests in sandboxed environments
For complete test results, see TEST_STATUS.md.
- Issues: https://github.com/your-org/derusted/issues
- Security: kumar.imlab@outlook.com
- Discussions: https://github.com/your-org/derusted/discussions
Built on the shoulders of giants:
- Tokio - Async runtime
- Hyper - HTTP implementation
- Rustls - TLS library
- rcgen - Certificate generation
- SQLx - SQLite integration
- h2 - HTTP/2 implementation
Special thanks to the Rust community.
Built with ❤️ in Rust
Developed by the Pinaka Engineering Team | 8-week development cycle | November 2025