Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1e91f80

Browse files
blink-so[bot]ammario
blink-so[bot]
and
ammario
committed
Update branch with base main
Resolve README.md conflicts and retain Advanced Options heading; integrate r.requester_ip in JS API. Co-authored-by: ammario <[email protected]>
2 parents 031d8a7 + 08cc1ea commit 1e91f80

File tree

14 files changed

+880
-205
lines changed

14 files changed

+880
-205
lines changed

‎.github/workflows/tests.yml

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -32,14 +32,6 @@ jobs:
3232
- name: Install nextest
3333
run: cargo install cargo-nextest --locked
3434

35-
- name: Build httpjail binary
36-
run: |
37-
cargo build --bin httpjail --target-dir target
38-
export HTTPJAIL_BIN="$(pwd)/target/debug/httpjail"
39-
echo "Binary built at: ${HTTPJAIL_BIN}"
40-
ls -la "${HTTPJAIL_BIN}"
41-
echo "HTTPJAIL_BIN=${HTTPJAIL_BIN}" >> $GITHUB_ENV
42-
4335
- name: Run all tests
4436
run: cargo nextest run --profile ci
4537

@@ -94,15 +86,6 @@ jobs:
9486
sudo chown -R ci:ci target || true
9587
fi
9688
97-
- name: Build httpjail binary
98-
run: |
99-
source ~/.cargo/env
100-
cargo build --bin httpjail --target-dir target
101-
export HTTPJAIL_BIN="$(pwd)/target/debug/httpjail"
102-
echo "Binary built at: ${HTTPJAIL_BIN}"
103-
ls -la "${HTTPJAIL_BIN}"
104-
echo "HTTPJAIL_BIN=${HTTPJAIL_BIN}" >> $GITHUB_ENV
105-
10689
- name: Run all tests (non-root)
10790
run: |
10891
source ~/.cargo/env

‎CLAUDE.md

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,17 @@ protocol), we must establish a timeout for the operation.
1010

1111
Timeouts must not preclude long-running connections such as GRPC or WebSocket.
1212

13+
## Building
14+
15+
For faster builds during development and debugging, use the `fast` profile:
16+
17+
```bash
18+
cargo build --profile fast
19+
```
20+
21+
This profile inherits from release mode but uses lower optimization levels and disables LTO
22+
for significantly faster build times while still providing reasonable performance.
23+
1324
## Testing
1425

1526
When writing tests, prefer pure rust solutions over shell script wrappers.
@@ -18,6 +29,16 @@ When testing behavior outside of the strong jailing, use `--weak` for an environ
1829
invocation of the tool. `--weak` works by setting the `HTTP_PROXY` and `HTTPS_PROXY` environment
1930
variables to the proxy address.
2031

32+
### Integration Tests
33+
34+
The integration tests use the `HTTPJAIL_BIN` environment variable to determine which binary to test.
35+
Always set this to the most up-to-date binary before running tests:
36+
37+
```bash
38+
export HTTPJAIL_BIN=/path/to/httpjail
39+
cargo test --test linux_integration
40+
```
41+
2142
## Cargo Cache
2243

2344
Occasionally you will encounter permissions issues due to running the tests under sudo. In these cases,
@@ -60,12 +81,43 @@ In regular operation of the CLI-only jail (non-server mode), info and warn logs
6081

6182
The Linux CI tests run on a self-hosted runner (`ci-1`) in GCP. Only Coder employees can directly SSH into this instance for debugging.
6283

63-
To debug CI failures on Linux:
84+
The CI workspace is located at `/home/ci/actions-runner/_work/httpjail/httpjail`. **IMPORTANT: Never modify files in this directory directly as it will interfere with running CI jobs.**
85+
86+
### CI Helper Scripts
87+
6488
```bash
65-
gcloud --quiet compute ssh root@ci-1 --zone us-central1-f --project httpjail
89+
# SSH into CI-1 instance (interactive or with commands)
90+
./scripts/ci-ssh.sh # Interactive shell
91+
./scripts/ci-ssh.sh "ls /tmp/httpjail-*" # Run command
92+
93+
# SCP files to/from CI-1
94+
./scripts/ci-scp.sh src/ /tmp/httpjail-docker-run/ # Upload
95+
./scripts/ci-scp.sh root@ci-1:/path/to/file ./ # Download
6696
```
6797

68-
The CI workspace is located at `/home/ci/actions-runner/_work/httpjail/httpjail`. Tests run as the `ci` user, not root. When building manually:
98+
### Manual Testing on CI
99+
69100
```bash
70-
su - ci -c 'cd /home/ci/actions-runner/_work/httpjail/httpjail && cargo test'
101+
# Set up a fresh workspace for your branch
102+
BRANCH_NAME="your-branch-name"
103+
gcloud --quiet compute ssh root@ci-1 --zone us-central1-f --project httpjail -- "
104+
rm -rf /tmp/httpjail-$BRANCH_NAME
105+
git clone https://github.com/coder/httpjail /tmp/httpjail-$BRANCH_NAME
106+
cd /tmp/httpjail-$BRANCH_NAME
107+
git checkout $BRANCH_NAME
108+
"
109+
110+
# Sync local changes to the test workspace
111+
gcloud compute scp --recurse src/ root@ci-1:/tmp/httpjail-$BRANCH_NAME/ --zone us-central1-f --project httpjail
112+
gcloud compute scp Cargo.toml root@ci-1:/tmp/httpjail-$BRANCH_NAME/ --zone us-central1-f --project httpjail
113+
114+
# Build and test in the isolated workspace (using shared cargo cache)
115+
gcloud --quiet compute ssh root@ci-1 --zone us-central1-f --project httpjail -- "
116+
cd /tmp/httpjail-$BRANCH_NAME
117+
export CARGO_HOME=/home/ci/.cargo
118+
/home/ci/.cargo/bin/cargo build --profile fast
119+
sudo ./target/fast/httpjail --help
120+
"
71121
```
122+
123+
This ensures you don't interfere with active CI jobs and provides a clean environment for testing.

‎Cargo.lock

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "httpjail"
3-
version = "0.1.5"
3+
version = "0.1.6"
44
edition = "2024"
55
license = "CC0-1.0"
66
description = "Monitor and restrict HTTP/HTTPS requests from processes"
@@ -52,3 +52,9 @@ tempfile = "3.8"
5252
assert_cmd = "2.0"
5353
predicates = "3.0"
5454
serial_test = "3.0"
55+
56+
[profile.fast]
57+
inherits = "release"
58+
opt-level = 1
59+
lto = false
60+
codegen-units = 16

‎README.md

Lines changed: 50 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,9 @@ httpjail --server --js "true"
5151
# Server defaults to ports 8080 (HTTP) and 8443 (HTTPS)
5252
# Configure your application:
5353
# HTTP_PROXY=http://localhost:8080 HTTPS_PROXY=http://localhost:8443
54+
55+
# Run Docker containers with network isolation (Linux only)
56+
httpjail --js "r.host === 'api.github.com'" --docker-run -- --rm alpine:latest wget -qO- https://api.github.com
5457
```
5558

5659
## Architecture Overview
@@ -123,39 +126,15 @@ httpjail creates an isolated network environment for the target process, interce
123126
- macOS 10.15+ (Catalina or later)
124127
- No special permissions required (runs in weak mode)
125128

126-
## Usage Examples
127-
128-
### Basic Usage
129-
130-
```bash
131-
# Simple allow/deny rules
132-
httpjail --js "r.host === 'api.github.com'" -- git pull
133-
134-
# Multiple allow patterns using regex
135-
httpjail \
136-
--js "/github\.com$/.test(r.host) || /githubusercontent\.com$/.test(r.host)" \
137-
-- npm install
138-
139-
# Deny telemetry while allowing everything else
140-
httpjail \
141-
--js "!/telemetry\.|analytics\.|sentry\./.test(r.host)" \
142-
-- ./application
143-
144-
# Method-specific rules
145-
httpjail \
146-
--js "(r.method === 'GET' && /api\..*\.com$/.test(r.host)) || (r.method === 'POST' && !/telemetry\./.test(r.host)) || r.method !== 'GET' && r.method !== 'POST'" \
147-
-- ./application
148-
```
149-
150-
### Configuration File
129+
## Configuration File
151130

152131
Create a `rules.js` file with your JavaScript evaluation logic:
153132

154133
```javascript
155134
// rules.js
156135
// Allow GitHub GET requests, block telemetry, allow everything else
157-
(r.method === 'GET' && /github\.com$/.test(r.host)) ||
158-
(!/telemetry/.test(r.host))
136+
(r.method === "GET" && /github\.com$/.test(r.host)) ||
137+
!/telemetry/.test(r.host);
159138
```
160139

161140
Use the config:
@@ -164,48 +143,7 @@ Use the config:
164143
httpjail --js-file rules.js -- ./my-application
165144
```
166145

167-
### Script-Based Evaluation
168-
169-
Instead of writing JavaScript, you can use a custom script to evaluate each request. The script receives environment variables for each request and returns an exit code to allow (0) or block (non-zero) the request. Any output to stdout becomes additional context in the 403 response.
170-
171-
```bash
172-
# Simple script example
173-
#!/bin/bash
174-
if [ "$HTTPJAIL_HOST" = "github.com" ] && [ "$HTTPJAIL_METHOD" = "GET" ]; then
175-
exit 0 # Allow the request
176-
else
177-
exit 1 # Block the request
178-
fi
179-
180-
# Use the script
181-
httpjail --sh ./check_request.sh -- curl https://github.com
182-
183-
# Inline script (with spaces, executed via shell)
184-
httpjail --sh '[ "$HTTPJAIL_HOST" = "github.com" ] && exit 0 || exit 1' -- git pull
185-
```
186-
187-
If `--sh` has spaces, it's run through `sh`; otherwise it's executed directly.
188-
189-
**Environment variables provided to the script:**
190-
191-
- `HTTPJAIL_URL` - Full URL being requested
192-
- `HTTPJAIL_METHOD` - HTTP method (GET, POST, etc.)
193-
- `HTTPJAIL_HOST` - Hostname from the URL
194-
- `HTTPJAIL_SCHEME` - URL scheme (http or https)
195-
- `HTTPJAIL_PATH` - Path component of the URL
196-
- `HTTPJAIL_REQUESTER_IP` - IP address of the client making the request
197-
198-
**Script requirements:**
199-
200-
- Exit code 0 allows the request
201-
- Any non-zero exit code blocks the request
202-
- stdout is captured and included in 403 responses as additional context
203-
- stderr is logged for debugging but not sent to the client
204-
205-
> [!TIP]
206-
> Script-based evaluation can also be used for custom logging! Your script can log requests to a database, send metrics to a monitoring service, or implement complex audit trails before returning the allow/deny decision.
207-
208-
### JavaScript (V8) Evaluation
146+
## JavaScript (V8) Evaluation
209147

210148
httpjail includes first-class support for JavaScript-based request evaluation using Google's V8 engine. This provides flexible and powerful rule logic.
211149

@@ -232,6 +170,7 @@ httpjail --js "(r.block_message = 'Social media blocked', !r.host.includes('face
232170
**JavaScript API:**
233171

234172
All request information is available via the `r` object:
173+
235174
- `r.url` - Full URL being requested (string)
236175
- `r.method` - HTTP method (GET, POST, etc.)
237176
- `r.host` - Hostname from the URL
@@ -258,8 +197,48 @@ All request information is available via the `r` object:
258197
> [!NOTE]
259198
> The `--js` flag conflicts with `--sh` and `--js-file`. Only one evaluation method can be used at a time.
260199
261-
### Advanced Options
200+
## Script-Based Evaluation
201+
202+
Instead of writing JavaScript, you can use a custom script to evaluate each request. The script receives environment variables for each request and returns an exit code to allow (0) or block (non-zero) the request. Any output to stdout becomes additional context in the 403 response.
203+
204+
```bash
205+
# Simple script example
206+
#!/bin/bash
207+
if [ "$HTTPJAIL_HOST" = "github.com" ] && [ "$HTTPJAIL_METHOD" = "GET" ]; then
208+
exit 0 # Allow the request
209+
else
210+
exit 1 # Block the request
211+
fi
212+
213+
# Use the script
214+
httpjail --sh ./check_request.sh -- curl https://github.com
215+
216+
# Inline script (with spaces, executed via shell)
217+
httpjail --sh '[ "$HTTPJAIL_HOST" = "github.com" ] && exit 0 || exit 1' -- git pull
218+
```
219+
220+
If `--sh` has spaces, it's run through `sh`; otherwise it's executed directly.
221+
222+
**Environment variables provided to the script:**
223+
224+
- `HTTPJAIL_URL` - Full URL being requested
225+
- `HTTPJAIL_METHOD` - HTTP method (GET, POST, etc.)
226+
- `HTTPJAIL_HOST` - Hostname from the URL
227+
- `HTTPJAIL_SCHEME` - URL scheme (http or https)
228+
- `HTTPJAIL_PATH` - Path component of the URL
229+
- `HTTPJAIL_REQUESTER_IP` - IP address of the client making the request
230+
231+
**Script requirements:**
232+
233+
- Exit code 0 allows the request
234+
- Any non-zero exit code blocks the request
235+
- stdout is captured and included in 403 responses as additional context
236+
- stderr is logged for debugging but not sent to the client
237+
238+
> [!TIP]
239+
> Script-based evaluation can also be used for custom logging! Your script can log requests to a database, send metrics to a monitoring service, or implement complex audit trails before returning the allow/deny decision.
262240
241+
## Advanced Options
263242
```bash
264243
# Verbose logging
265244
httpjail -vvv --js "true" -- curl https://example.com
@@ -276,7 +255,7 @@ HTTPJAIL_HTTP_BIND=3128 HTTPJAIL_HTTPS_BIND=3129 httpjail --server --js "true"
276255
HTTPJAIL_HTTP_BIND=192.168.1.100:8080 httpjail --server --js "true"
277256
```
278257

279-
### Server Mode
258+
## Server Mode
280259

281260
httpjail can run as a standalone proxy server without executing any commands. This is useful when you want to proxy multiple applications through the same httpjail instance. The server binds to localhost (127.0.0.1) only for security.
282261

‎scripts/ci-scp.sh

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
#!/bin/bash
2+
# SCP files to/from the CI-1 instance
3+
4+
set -e
5+
6+
BRANCH_NAME="${BRANCH_NAME:-$(git branch --show-current)}"
7+
8+
if [ $# -lt 1 ]; then
9+
echo "Usage: $0 <source> [destination]"
10+
echo " Copy files to CI-1: $0 src/ /tmp/httpjail-\$BRANCH_NAME/"
11+
echo " Copy from CI-1: $0 root@ci-1:/path/to/file local/"
12+
echo ""
13+
echo "Environment:"
14+
echo " BRANCH_NAME: Target branch directory (default: current git branch)"
15+
exit 1
16+
fi
17+
18+
SOURCE="$1"
19+
DEST="${2:-/tmp/httpjail-$BRANCH_NAME/}"
20+
21+
# Check if source is remote (contains ci-1:)
22+
if [[ "$SOURCE" == *"ci-1:"* ]]; then
23+
# Downloading from CI-1
24+
SOURCE_PATH="${SOURCE#*:}"
25+
gcloud compute scp --quiet --recurse \
26+
"root@ci-1:$SOURCE_PATH" \
27+
"$DEST" \
28+
--zone us-central1-f --project httpjail
29+
else
30+
# Uploading to CI-1
31+
# If destination doesn't start with root@ci-1:, prepend it
32+
if [[ "$DEST" != "root@ci-1:"* ]]; then
33+
DEST="root@ci-1:$DEST"
34+
fi
35+
36+
gcloud compute scp --quiet --recurse \
37+
"$SOURCE" \
38+
"$DEST" \
39+
--zone us-central1-f --project httpjail
40+
fi

‎scripts/ci-ssh.sh

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/bin/bash
2+
# SSH into the CI-1 instance for debugging
3+
4+
set -e
5+
6+
if [ $# -eq 0 ]; then
7+
echo "Connecting to CI-1 instance (interactive)..."
8+
gcloud --quiet compute ssh root@ci-1 --zone us-central1-f --project httpjail
9+
else
10+
# Execute command remotely
11+
gcloud --quiet compute ssh root@ci-1 --zone us-central1-f --project httpjail -- "$@"
12+
fi

0 commit comments

Comments
 (0)