Skip to content

Commit 26f1bbd

Browse files
6C656C656C656C65
committed
Transfer from GitHub wiki
1 parent 93beb93 commit 26f1bbd

23 files changed

Lines changed: 814 additions & 2 deletions

‎README.md‎

Lines changed: 69 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,69 @@
1-
# pyproxy-docs
2-
Pyproxy documentations
1+
<div align="center">
2+
<h1>pyproxy-docs</h1>
3+
</div>
4+
5+
This repository hosts the official documentation for **PyProxyTools**, a lightweight, fast, and customizable Python-based web proxy server. The documentation is built with MkDocs and published via GitHub Pages.
6+
7+
## 🚀 **Live Documentation**
8+
9+
The documentation is available here:
10+
11+
```
12+
https://pyproxytools.github.io/pyproxy-docs/
13+
```
14+
15+
## 📚 **About This Repository**
16+
17+
This repo contains:
18+
19+
* All Markdown source files for the documentation
20+
* The `mkdocs.yml` configuration file
21+
* A GitHub Actions workflow for automatic deployment
22+
23+
If you want to contribute or improve the docs for **PyProxyTools**, this is the place.
24+
25+
## 🛠️ **Local Setup**
26+
27+
### 1. Install dependencies
28+
29+
```bash
30+
pip install -r requirements.txt
31+
```
32+
33+
### 2. Run the documentation locally
34+
35+
```bash
36+
mkdocs serve
37+
```
38+
39+
The site will be available at:
40+
41+
```
42+
http://127.0.0.1:8000
43+
```
44+
45+
### 3. Build the static site
46+
47+
```bash
48+
mkdocs build
49+
```
50+
51+
This generates the final static HTML inside the `site/` directory.
52+
53+
## 🔄 **Deployment**
54+
55+
Deployment to GitHub Pages is automated using a GitHub Actions workflow.
56+
Every push to the branch "main" triggers a build and publishes updates to the live site.
57+
58+
No manual steps required once the workflow is set up.
59+
60+
## 🤝 **Contributing**
61+
62+
Contributions to improve or expand the documentation are welcome.
63+
Feel free to submit pull requests with corrections, new sections, or examples.
64+
65+
## 📄 **License**
66+
67+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
68+
69+
---

‎docs/assets/pyproxy.png‎

1.59 KB
Loading

‎docs/configuration/ca_certificates.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
This configuration is required to use SSL inspection. The proxy generates SSL certificates for intercepted HTTPS requests. These certificates will be presented to clients. The proxy will sign these certificates with a certificate authority. Therefore, it needs a CA (the key and the certificate).
2+
3+
The CA key and certificate should be placed in `./certs/ca/key.pem` and in `./certs/ca/cert.pem`.
4+
5+
## Generate a self-signed CA
6+
You can generate a self-signed CA with OpenSSL.
7+
```bash
8+
mkdir -p certs/ca/
9+
openssl req -x509 -newkey rsa:4096 -keyout certs/ca/key.pem -out certs/ca/cert.pem -days 365 -nodes
10+
```

‎docs/configuration/command_argument.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
You can launch the proxy directly and configure it with the following arguments:
2+
3+
| Argument | Short | Description | Default Value | Slim version |
4+
|----------|-------|-------------|---------------|---------------|
5+
| `--version` | `-v` | Show version information | N/A | |
6+
| `--debug` | | Enable debug logging | `False` | |
7+
| `--host` | `-H` | IP address to listen on | `0.0.0.0` | |
8+
| `--port` | `-P` | Port to listen on | `8080` | |
9+
| `--config-file` | `-f` | Path to `config.ini` file | `./config.ini` | |
10+
| `--access-log` | | Path to the access log file | `logs/access.log` | |
11+
| `--block-log` | | Path to the block log file | `logs/block.log` | |
12+
| `--html-403` | | Path to the custom 403 Forbidden HTML page | `assets/403.html` | |
13+
| `--filter-mode` | | Disable URL and domain filtering | `False` | |
14+
| `--no-filter` | | Filter list mode (local or http) | `local` | |
15+
| `--blocked-sites` | | Path to the text file containing the list of sites to block | `config/blocked_sites.txt` | |
16+
| `--blocked-url` | | Path to the text file containing the list of URLs to block | `config/blocked_url.txt` | |
17+
| `--shortcuts` | | Path to the text file containing the list of shortcuts | `config/shortcuts.txt` | **not included** |
18+
| `--custom-header` | | Path to the json file containing the list of custom headers | `config/custom_header.json` | **not included** |
19+
| `--authorized-ips` | | Path to the txt file containing the list of authorized ips | `config/authorized_ips.txt` | |
20+
| `--no-logging-access` | | Disable access logging | `False` | |
21+
| `--no-logging-block` | | Disable block logging | `False` | |
22+
| `--ssl-inspect` | | Enable SSL inspection | `False` | |
23+
| `--inspect-ca-cert` | | Path to the CA certificate | `certs/ca/cert.pem` | |
24+
| `--inspect-ca-key` | | Path to the CA key | `certs/ca/key.pem` | |
25+
| `--inspect-certs-folder` | | Path to the generated certificates folder | `certs/` | |
26+
| `--cancel-inspect` | | Path to the text file containing the list of URLs without ssl inspection | `config/cancel_inspect.txt` | |
27+
| `--flask-port` | | Port to listen on for monitoring interface | `5000` | **not included** |
28+
| `--flask-pass` | | Default password to Flask interface | `password` | **not included** |
29+
| `--proxy-enable` | | Enable proxy after PyProxy | `False` | |
30+
| `--proxy-host` | | Proxy IP to use after PyProxy | `127.0.0.1` | |
31+
| `--proxy-port` | | Proxy Port to use after PyProxy | `8081` | |
32+
33+
## Example
34+
### With source
35+
Example of a launch with SSL inspection for HTTPS requests
36+
```bash
37+
python3 pyproxy.py --ssl-inspect
38+
```
39+
40+
!!! warning
41+
Please note: for SSL inspection, you must configure a certificate authority to generate SSL certificates.
42+
Here is the documentation on [SSL Inspection](../features/ssl_inspection.md)
43+
44+
### With Docker image
45+
Example of a launch with SSL inspection for HTTPS requests
46+
```bash
47+
docker run -d ghcr.io/6c656c65/pyproxy:latest --ssl-inspect
48+
```
49+
!!! warning
50+
Please note: for SSL inspection, you must configure a certificate authority to generate SSL certificates.
51+
Here is the documentation on [SSL Inspection](../features/ssl_inspection.md)
52+
53+
## With configuration file
54+
You can configure the proxy using a [From an .ini file](../configuration/from_ini_file.md) instead of arguments.

‎docs/configuration/env_var.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
You can configure the proxy using environment variables instead of command-line arguments. The environment variable names follow the pattern `PYPROXY_<CLI_ARGUMENT>`, where the argument is in uppercase and hyphens (`-`) are replaced by underscores (`_`).
2+
3+
Environment Variable | Description | Default Value | Slim version
4+
-- | -- | -- | --
5+
`PYPROXY_VERSION` | Show version information | `N/A` |  
6+
`PYPROXY_DEBUG` | Enable debug logging | `False` |  
7+
`PYPROXY_HOST` | IP address to listen on | `0.0.0.0` |  
8+
`PYPROXY_PORT` | Port to listen on | `8080` |  
9+
`PYPROXY_CONFIG_FILE` | Path to config.ini file | `./config.ini` |  
10+
`PYPROXY_ACCESS_LOG` | Path to the access log file | `logs/access.log` |  
11+
`PYPROXY_BLOCK_LOG` | Path to the block log file | `logs/block.log` |  
12+
`PYPROXY_HTML_403` | Path to the custom 403 Forbidden HTML page | `assets/403.html` |  
13+
`PYPROXY_FILTER_MODE` | Disable URL and domain filtering | `False` |  
14+
`PYPROXY_NO_FILTER` | Filter list mode (local or http) | `local` |  
15+
`PYPROXY_BLOCKED_SITES` | Path to the text file containing the list of sites to block | `config/blocked_sites.txt` |  
16+
`PYPROXY_BLOCKED_URL` | Path to the text file containing the list of URLs to block | `config/blocked_url.txt` |  
17+
`PYPROXY_SHORTCUTS` | Path to the text file containing the list of shortcuts | `config/shortcuts.txt` | **not included**
18+
`PYPROXY_CUSTOM_HEADER` | Path to the json file containing the list of custom headers | `config/custom_header.json` | **not included**
19+
`PYPROXY_AUTHORIZED_IPS` | Path to the txt file containing the list of authorized ips | `config/authorized_ips.txt` |
20+
`PYPROXY_NO_LOGGING_ACCESS` | Disable access logging | `False` |  
21+
`PYPROXY_NO_LOGGING_BLOCK` | Disable block logging | `False` |  
22+
`PYPROXY_SSL_INSPECT` | Enable SSL inspection | `False` |  
23+
`PYPROXY_INSPECT_CA_CERT` | Path to the CA certificate | `certs/ca/cert.pem` |  
24+
`PYPROXY_INSPECT_CA_KEY` | Path to the CA key | `certs/ca/key.pem` |  
25+
`PYPROXY_INSPECT_CERTS_FOLDER` | Path to the generated certificates folder | `certs/` |  
26+
`PYPROXY_CANCEL_INSPECT` | Path to the text file containing the list of URLs without SSL inspection | `config/cancel_inspect.txt` |  
27+
`PYPROXY_FLASK_PORT` | Port to listen on for the monitoring interface | `5000` | **not included**
28+
`PYPROXY_FLASK_PASS` | Default password to Flask interface | `password` | **not included**
29+
`PYPROXY_PROXY_ENABLE` | Enable proxy after PyProxy | `False` |
30+
`PYPROXY_PROXY_HOST` | Proxy IP to use after PyProxy | `127.0.0.1` |
31+
`PYPROXY_PROXY_PORT` | Proxy Port to use after PyProxy | `8081` |
32+
33+
## Example Usage with Docker Compose
34+
To configure `pyproxy` with Docker Compose and set environment variables, you can add the following to your `docker-compose.yml` file:
35+
36+
```yaml
37+
services:
38+
pyproxy:
39+
image: ghcr.io/6c656c65/pyproxy:latest
40+
environment:
41+
PYPROXY_HOST: 0.0.0.0
42+
PYPROXY_PORT: 8080
43+
PYPROXY_SSL_INSPECT: "True"
44+
PYPROXY_FLASK_PORT: 5000
45+
PYPROXY_DEBUG: "True"
46+
```

‎docs/configuration/from_ini_file.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
An example configuration file is provided `./config.ini.example`.
2+
You can copy it and call it `config.ini`. By default, the program will read the `config.ini` file located at the root of the project. The path can be changed with the `-f` argument.
3+
4+
!!! warning
5+
Please note: Command line configurations take precedence over the configuration
6+
7+
## Example of a configuration file
8+
9+
```ini
10+
[Server]
11+
host = 0.0.0.0
12+
port = 8080
13+
14+
[Logging]
15+
debug = false
16+
access_log = ./logs/access.log
17+
block_log = ./logs/block.log
18+
no_logging_access = false
19+
no_logging_block = false
20+
console_format = %(asctime)s - %(levelname)s - %(message)s
21+
datefmt = %d/%m/%Y %H:%M:%S
22+
23+
[Files]
24+
html_403 = assets/403.html
25+
26+
[Filtering]
27+
no_filter = false
28+
filter_mode = local
29+
blocked_sites = config/blocked_sites.txt
30+
blocked_url = config/blocked_url.txt
31+
32+
[Options]
33+
shortcuts = config/shortcuts.txt
34+
custom_header = config/custom_header.json
35+
authorized_ips = config/authorized_ips.txt
36+
37+
[Security]
38+
ssl_inspect = false
39+
inspect_ca_cert = certs/ca/cert.pem
40+
inspect_ca_key = certs/ca/key.pem
41+
inspect_certs_folder = certs/
42+
cancel_inspect = config/cancel_inspect.txt
43+
44+
[Monitoring]
45+
flask_port = 5000
46+
flask_pass = password
47+
48+
[Proxy]
49+
proxy_enable = false
50+
proxy_host = 127.0.0.1
51+
proxy_port = 8081
52+
```
53+
54+
!!! warning
55+
In the `slim` version, the `Monitoring`, `Custom header` and `Shortcuts` parts are not included
56+
57+
## With Docker image
58+
If you want to use the configuration file with the Docker image. You must put it in the container at the following path: `/app/config.ini` by default

‎docs/features/api.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# API
2+
3+
The Monitoring API allows you to retrieve proxy server status, configuration, and manage filtering rules (blocked sites and URLs).
4+
5+
All routes are secured using HTTP Basic Authentication.
6+
7+
!!! note
8+
Here is a [python SDK](https://github.com/pyproxytools/pyproxy-sdk-py) to interact with the API.
9+
10+
---
11+
12+
## Endpoints
13+
14+
### `GET /`
15+
16+
Returns the main monitoring HTML dashboard.
17+
18+
---
19+
20+
### `GET /api/status`
21+
22+
Returns real-time monitoring information about the running proxy server.
23+
24+
**Response example:**
25+
```json
26+
{
27+
"pid": 12345,
28+
"threads": 10,
29+
"connections": 5,
30+
...
31+
}
32+
```
33+
34+
---
35+
36+
### `GET /api/settings`
37+
38+
Returns the current proxy server configuration.
39+
40+
**Response example:**
41+
42+
```json
43+
{
44+
"host": "127.0.0.1",
45+
"port": 8080,
46+
"debug": false,
47+
"html_403": true,
48+
"logger_config": { ... },
49+
"filter_config": { ... },
50+
"ssl_config": { ... },
51+
"flask_port": 5000
52+
}
53+
```
54+
55+
---
56+
57+
### `GET /api/filtering`
58+
59+
Returns current blocked domains and URLs.
60+
61+
**Response example:**
62+
63+
```json
64+
{
65+
"blocked_sites": ["example.com", "malware.com"],
66+
"blocked_url": ["http://badurl.com/path"]
67+
}
68+
```
69+
70+
---
71+
72+
### `POST /api/filtering`
73+
74+
Add a domain or URL to the block list.
75+
76+
**Request body:**
77+
78+
```json
79+
{
80+
"type": "domain" | "url",
81+
"value": "value_to_block"
82+
}
83+
```
84+
85+
**Responses:**
86+
87+
* `201`: Successfully added.
88+
* `400`: Invalid input.
89+
* `409`: Already blocked.
90+
91+
---
92+
93+
### `DELETE /api/filtering`
94+
95+
Remove a domain or URL from the block list.
96+
97+
**Request body:**
98+
99+
```json
100+
{
101+
"type": "domain" | "url",
102+
"value": "value_to_unblock"
103+
}
104+
```
105+
106+
**Responses:**
107+
108+
* `200`: Successfully removed.
109+
* `400`: Invalid input.
110+
* `404`: Value not found.
111+
* `500`: Server error.
112+
113+
---
114+
115+
## Authentication
116+
117+
All endpoints require HTTP Basic Authentication.
118+
119+
Provide your credentials in the `Authorization` header:
120+
121+
```http
122+
Authorization: Basic <base64(username:password)>
123+
```

‎docs/features/authorized_ips.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
You can define a list of subnets that are allowed to use the proxy
2+
3+
!!! warning
4+
Please note: To reload the list of allowed IP addresses, you must restart the proxy
5+
6+
By default, the list of authorized subnets is defined in the file `config/authorized_ips.txt`.
7+
8+
Here is an example of a `txt` file :
9+
```
10+
0.0.0.0/0
11+
127.0.0.1/8
12+
10.0.0.1/32
13+
```
14+
15+
## Change the file path
16+
You can change the path to the files containing authorized IP addresses. Here is the associated documentation, depending on your configuration.
17+
18+
* [From an .ini file](../configuration/from_ini_file.md)
19+
* [With command argument](../configuration/command_argument.md)
20+
* [Environment variables](../configuration/env_var.md)
21+
22+
## Disable IP address filtering
23+
The IP address filtering system is activated as soon as the file is present. Simply do not create the authorized IP file.

0 commit comments

Comments
 (0)