Skip to content

Commit 48a1eed

Browse files
timzaaktimzaak
committed
update readme
1 parent 71e2ff8 commit 48a1eed

File tree

2 files changed

+189
-98
lines changed

2 files changed

+189
-98
lines changed

‎README.md‎

Lines changed: 80 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,101 @@
1-
## https proxy
2-
It's mitm http/https proxy. It outputs the https request and response for test.
3-
4-
### Requires
5-
1. require JDK 19+
6-
2. https cert and private key
7-
3. https certificate.
8-
9-
If you want to install self-signed certificate, you could use [mkcert](https://github.com/FiloSottile/mkcert) to do this.
10-
more info can be found here [mkcert.md](mkcert.md)
11-
12-
### Usage
13-
If you want to get all requests and responses about `https://www.exmample.com (192.168.3.3)`
14-
1. change domain ip like:`127.0.0.1 www.example.com`
15-
2. run commands below:
16-
```shell
17-
# run with sbt
18-
sbt "runMain Main --dns=192.168.3.3:www.example.com --jks-path=jks.jks --jks-password=123456 --viewPort=9000"
19-
20-
21-
# run with docker
22-
# config file would be:
23-
24-
# jks {
25-
# path=/server/config/jks.jks
26-
# password=123456
27-
# }
28-
# resolver=[114.114.114.114]
29-
# viewerPort=9000
30-
# ##selfSignedCert = "" # if you use self signed cert.
1+
## HTTPS Proxy
2+
A MITM (Man-In-The-Middle) HTTP/HTTPS proxy that logs HTTPS requests and responses for debugging and testing purposes.
3+
### Features
4+
- Logs HTTPS request and response details.
5+
- View traffic through a browser UI.
6+
- Docker & CLI supported.
7+
- Supports custom DNS mappings and JKS SSL certificates.
8+
### Requirements
9+
1. JDK 19+
10+
2. HTTPS certificate and private key (in JKS format).
11+
3. If using self-signed certificates, consider using [mkcert](https://github.com/FiloSottile/mkcert).
12+
13+
> 📄 more info: [mkcert.md](mkcert.md)
14+
15+
### Quick Start
16+
Suppose you're intercepting traffic for https://www.example.com (IP: 192.168.3.3).
17+
#### Step 1: Local Host Mapping
18+
Edit your system's host file (e.g., `/etc/hosts` or `C:\Windows\System32\drivers\etc\hosts`):
3119

32-
docker run --rm -v ${pwd}/private.conf:/server/config/application.conf -v${pwd}/jks.jks:/server/config/jks.jks -p 443:443 -p 9000:9000 ghcr.io/timzaak/log-http-proxy:latest
20+
```
21+
127.0.0.1 www.example.com
22+
```
23+
#### Step 2: Run the Proxy
24+
##### Using SBT
25+
```bash
26+
sbt "runMain Main --dns=192.168.3.3:www.example.com --jks-path=jks.jks --jks-password=123456 --viewPort=9000"
27+
```
28+
##### Using Docker
29+
Create a `private.conf` file with the following content:
30+
```hocon
31+
jks {
32+
path = "/server/config/jks.jks"
33+
password = "123456"
34+
}
35+
resolver = [114.114.114.114]
36+
viewerPort = 9000
37+
# selfSignedCert = "" # Uncomment if using a self-signed cert
38+
```
39+
Then run:
40+
```bash
41+
docker run --rm \
42+
-v ${PWD}/private.conf:/server/config/application.conf \
43+
-v ${PWD}/jks.jks:/server/config/jks.jks \
44+
-p 443:443 -p 9000:9000 \
45+
ghcr.io/timzaak/log-http-proxy:latest
3346

47+
```
48+
> Open your browser and navigate to http://127.0.0.1:9000 to view traffic logs.
3449
35-
# open your browser to access http://127.0.0.1:9000
50+
<img src="/doc/usage.png" alt="Usage screenshot" width="500" />
3651

37-
```
38-
<img src="/doc/usage.png" alt="usage" width="500" />
52+
### Parameters
3953

40-
The params are:
54+
| Name | Description |
55+
|------------------| --------------------------------------------------------------- |
56+
| `--dns` | A list of `IP:domain` mappings to inject into the DNS resolver. |
57+
| `--jks-path` | Path to the JKS file containing the SSL certificate and key. |
58+
| `--jks-password` | Password for the JKS keystore. |
59+
| `--resolver` | (Optional) DNS resolver to use (e.g., `1.1.1.1`). |
60+
| `--viewPort` | (Optional) Port for the web UI or WebSocket logging. |
4161

42-
* dns: A list of domain-to-IP mappings in the format ip:domain. These mappings will be added to the DNS resolver.
43-
* jksPath: An optional path to a JKS file for SSL/TLS configuration.
44-
* jksPassword: An optional password for the JKS file specified by jksPath.
45-
* resolver: An optional custom DNS resolver address, e.g., 1.1.1.1, 8.8.8.8.
46-
* websocketPort: An optional port to start a WebSocket server for logging. If not provided, logs would output to the command line.
4762

48-
### Package as command-line tool
49-
```shell
50-
### you can package it with the following command:
63+
### Packaging as a CLI Tool
64+
```bash
65+
# Package with sbt
5166
sbt stage
52-
cd package
5367

68+
# Then package with jpackage
69+
cd package
5470
version="0.1.0"
55-
jpackage --name https-proxy --input ../target/universal/stage/lib --main-jar https-proxy.https-proxy-${version}.jar --main-class Main --type app-image --win-console
5671

72+
jpackage \
73+
--name https-proxy \
74+
--input ../target/universal/stage/lib \
75+
--main-jar https-proxy.https-proxy-${version}.jar \
76+
--main-class Main \
77+
--type app-image \
78+
--win-console
5779
```
5880

5981

6082
### Known Issue
61-
1. Request does not support brotli compression, would drop request header: Accept-Encoding.
62-
2. Request would drop header remote-address
83+
1. Brotli compression (Accept-Encoding: br) is not supported. This header will be stripped.
84+
2. remote-address headers are not retained.
6385

6486

65-
### Another way to log
87+
### Alternative Logging (Raw Packet Capture)
88+
#### On Linux Server
89+
> Note: Windows users may need to use `tshark` instead.
6690
67-
```shell
68-
### Linux Server
69-
#### Windows may need use tshark to replace it.
91+
```bash
7092
ssh user@remote 'tcpdump -i any -w - -U port <port>' | wireshark -k -i -
93+
```
7194

72-
73-
### K8S use debug to inject and run tcpdump, then k8s exec to get tcpdump output
74-
kubectl debug -it <pod-name> -n <namespace> --image=nicolaka/netshoot --target=<container-name>
75-
95+
#### On Kubernetes
96+
```bash
97+
kubectl debug -it <pod-name> -n <namespace> \
98+
--image=nicolaka/netshoot \
99+
--target=<container-name>
76100
```
101+
Use tcpdump inside the debug container to capture traffic.

‎mkcert.md‎

Lines changed: 109 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,125 @@
1-
## 📥 Install mkcert
2-
> Do NOT download the binary directly from the Releases page, especially on macOS, as it can lead to issues.
3-
> Instead, follow the installation steps provided in the official [README](https://github.com/FiloSottile/mkcert).
4-
5-
```shell
6-
# Install root CA in the system trust store (requires root privileges).
7-
# The root CA is valid for 10 years.
8-
# To undo this later, you can run: mkcert -uninstall
1+
# 📥 Installing and Using `mkcert` for Local HTTPS and Java Keystore
2+
3+
This guide walks you through the process of installing `mkcert`, generating local certificates, and importing them into a Java KeyStore (JKS) for use in HTTPS services.
4+
5+
---
6+
7+
## 🛠️ Prerequisites
8+
9+
- `mkcert` installed (see below)
10+
- `openssl` installed
11+
- JDK (includes `keytool`)
12+
- Environment variable `JAVA_HOME` properly configured (for Java truststore support)
13+
14+
---
15+
16+
## 📦 Install `mkcert`
17+
18+
> ⚠️ **Important:** Do **not** download the binary directly from the GitHub Releases page, especially on **macOS**.
19+
> Instead, follow the official instructions from the [`mkcert` README](https://github.com/FiloSottile/mkcert).
20+
21+
Once installed, set up the local root Certificate Authority (CA):
22+
23+
```bash
24+
# Install the root CA into the system trust store
925
mkcert -install
26+
```
1027

11-
# Get the directory where the root CA is stored:
28+
This will generate a root certificate valid for **10 years**, and install it into:
29+
30+
```bash
1231
cd "$(mkcert -CAROOT)"
32+
# You'll find:
33+
# - rootCA.pem (the root certificate)
34+
# - rootCA-key.pem (the private key)
35+
```
36+
37+
To uninstall the root CA later:
1338

14-
# In this directory, you'll find rootCA.pem and rootCA-key.pem
39+
```bash
40+
mkcert -uninstall
1541
```
16-
## 📄 Generate Certificates
17-
```shell
18-
# Generate certificate and private key for the domain example.com and its subdomains:
42+
43+
---
44+
45+
## 📄 Generate TLS Certificates
46+
47+
Generate a certificate and private key for your domain (e.g., `example.com` and its subdomains):
48+
49+
```bash
1950
mkcert example.com "*.example.com"
2051
```
21-
## 🔐 Create a Java KeyStore (JKS)
22-
```shell
23-
# Step 1: Convert to PKCS12 format (example.com.p12)
52+
53+
This will output two files:
54+
55+
- `example.com.pem` — the certificate
56+
- `example.com-key.pem` — the private key
57+
58+
---
59+
60+
## 🔐 Convert to Java KeyStore (JKS)
61+
62+
### Step 1: Convert to PKCS#12 (.p12)
63+
64+
```bash
2465
openssl pkcs12 -export \
25-
-in example.com.pem \
26-
-inkey example.com-key.pem \
27-
-out example.com.p12 \
28-
-name example.com \
29-
-CAfile rootCA.pem \
30-
-caname root
31-
32-
# Step 2: Import the PKCS12 file into a Java KeyStore (JKS)
66+
-in example.com.pem \
67+
-inkey example.com-key.pem \
68+
-out example.com.p12 \
69+
-name example.com \
70+
-CAfile rootCA.pem \
71+
-caname root
72+
```
73+
74+
> This creates `example.com.p12`, which bundles the certificate and private key.
75+
76+
### Step 2: Import `.p12` into JKS
77+
78+
```bash
3379
keytool -importkeystore \
34-
-srckeystore example.com.p12 \
35-
-srcstoretype PKCS12 \
36-
-destkeystore example.com.jks \
37-
-deststoretype JKS \
38-
-alias example.com
80+
-srckeystore example.com.p12 \
81+
-srcstoretype PKCS12 \
82+
-destkeystore example.com.jks \
83+
-deststoretype JKS \
84+
-alias example.com
85+
```
3986

40-
# 🔍 View the JKS Contents
87+
### 🔍 View the JKS Contents
88+
89+
```bash
4190
keytool -list -v -keystore example.com.jks -storepass changeit
4291
```
43-
> You can repeat the keytool -importkeystore step multiple times to import multiple .p12 files into the same JKS.
4492

45-
## 📦 Install the Root CA on Another Machine
46-
```shell
47-
# 1. Copy the rootCA.pem to the target machine.
48-
# 2. Set the CAROOT environment variable to the directory containing rootCA.pem
49-
export CAROOT=$(pwd)
93+
> 💡 You can repeat the `keytool -importkeystore` step to import additional `.p12` certificates into the same JKS file.
5094
51-
# 3. Verify the environment variable
52-
echo $CAROOT
95+
---
5396

54-
# 4. Install the root CA into the local trust store on the target machine
55-
mkcert -install
56-
```
57-
> ⚠️ Note: Ensure the JAVA_HOME environment variable is correctly set on the machine.
58-
If not, mkcert will not be able to inject the CA into the Java truststore.
97+
## 📤 Installing the Root CA on Another Machine
98+
99+
To use the generated certificates on another machine:
100+
101+
1. Copy the `rootCA.pem` file to the target machine.
102+
2. Set the `CAROOT` environment variable:
103+
104+
```bash
105+
export CAROOT=$(pwd) # Set to the directory containing rootCA.pem
106+
```
107+
108+
3. Confirm:
109+
110+
```bash
111+
echo $CAROOT
112+
```
113+
114+
4. Install the root CA:
115+
116+
```bash
117+
mkcert -install
118+
```
119+
120+
> ⚠️ Ensure that the `JAVA_HOME` environment variable is correctly set on the target machine.
121+
> If it's not, `mkcert` may fail to inject the CA into the Java truststore.
122+
123+
---
59124

125+
✅ Done! You now have local TLS certificates trusted by your OS and Java, ready for use in development or testing environments.

0 commit comments

Comments
 (0)