blob: 9542fa641b19a2f2b380092412e33fa4d0be9ec7 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
# wg-wrap: Transparent Userspace VPN Wrapper
`wg-wrap` allows you to run specific Linux applications over a WireGuard VPN without requiring root privileges or affecting your entire system's network configuration.
## 🚀 Quick Start
### 1. Install
Build the binary using the provided Makefile:
```bash
make
```
### 2. Setup a Profile
Import your WireGuard `.conf` file as a profile:
```bash
./wg-wrap profile import ~/my-vpn.conf home-vpn
```
### 3. Run an Application
Run any command wrapped in the VPN using the `run` subcommand:
```bash
./wg-wrap run --profile home-vpn -- curl https://ifconfig.me
```
*Only the `curl` command is routed through the VPN; your browser, SSH sessions, and other apps remain on your local network.*
*Only the `curl` command is routed through the VPN; your browser, SSH sessions, and other apps remain on your local network.*
---
## 🛠️ Feature Overview
### Process-Level Isolation
Unlike standard VPNs, `wg-wrap` provides complete network isolation per process. This means:
- **No Route Pollution**: Your host routing table remains untouched.
- **Rootless Operation**: Works without `sudo` using unprivileged user namespaces.
- **VPN Concurrency**: Run multiple different VPN profiles at the same time in different terminals.
- **Zero-Leak DNS**: Each process gets its own isolated DNS resolver, preventing leaks to your ISP.
### Profile Management
Manage your VPN configurations easily from the CLI:
| Command | Description |
| :--- | :--- |
| `run [options] -- <cmd>` | Run a command in the wrapped environment. |
| `profile list` | List all available VPN profiles. |
| `profile import <path> [name]` | Import a `.conf` file as a new profile. |
| `profile configure <name>` | Edit a profile's configuration in your default editor. |
| `profile delete <name>` | Remove a profile. |
| `profile stop <name>` | Force-stop an active tunnel session. |
### Diagnostics
Check your environment and troubleshoot issues using these subcommands:
- `healthcheck`: Run a comprehensive diagnostic to ensure your system supports rootless namespaces.
- `show-config`: View resolved paths and current isolation status.
- `test-ns`: Verify that you are correctly isolated in a network namespace.
- `test-args`: (For developers) Verify 8-bit clean argument passing.
---
## 📖 Usage Examples
**Run Firefox on a specific VPN:**
```bash
./wg-wrap run --profile privacy-vpn -- firefox
```
**Run a series of tests against a private VPC:**
```bash
./wg-wrap run --profile dev-vpc -- pytest tests/integration
```
**Connect to a home server and a work server simultaneously:**
```bash
# Terminal 1
./wg-wrap run --profile home-vpn -- ssh home-nas
# Terminal 2
./wg-wrap run --profile work-vpn -- ssh work-server
```
---
## 🏗️ Development
### Building from Source
`wg-wrap` requires `gcc` and `go` (1.23+). It uses an embedded C launcher to handle the rootless namespace transition, so you must use the Makefile:
```bash
make
```
### Testing
- **Unit & Integration Tests**: `make test`
- **Security Fuzzing**: `make fuzz` (tests argument integrity through the bootstrap loop).
## License
This project is free and unencumbered software released into the public domain. See the [LICENSE](LICENSE) file for details.
|
