Skip to content

Commit 43532ac

Browse files
CopilotCopilot
authored
Merge 594647b into 8b903e7 
2 parents 8b903e7 + 594647b commit 43532ac

2 files changed

Lines changed: 171 additions & 13 deletions

File tree

‎docs-site/src/content/docs/guides/domain-filtering.md‎

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -205,21 +205,40 @@ sudo awf \
205205
--prompt "Search for papers"
206206
```
207207

208+
## Protocol-specific filtering
209+
210+
Restrict domains to HTTP-only or HTTPS-only traffic by prefixing with the protocol:
211+
212+
```bash
213+
# HTTPS only - blocks HTTP traffic to this domain
214+
sudo awf --allow-domains 'https://secure.example.com' -- curl https://secure.example.com
215+
216+
# HTTP only - blocks HTTPS traffic to this domain
217+
sudo awf --allow-domains 'http://legacy-api.example.com' -- curl http://legacy-api.example.com
218+
219+
# Both protocols (default, no prefix)
220+
sudo awf --allow-domains 'example.com' -- curl https://example.com
221+
```
222+
223+
| Format | HTTP | HTTPS |
224+
|--------|------|-------|
225+
| `domain.com` | ✓ | ✓ |
226+
| `https://domain.com` | ✗ | ✓ |
227+
| `http://domain.com` | ✓ | ✗ |
228+
229+
Protocol prefixes work with wildcard patterns: `https://*.secure.example.com` matches only HTTPS traffic to any subdomain of `secure.example.com`.
230+
208231
## Normalization
209232

210233
Domains are normalized before matching:
211234

212235
- **Case-insensitive**: `GitHub.COM` = `github.com`
213-
- **Whitespace trimmed**: `" github.com "` = `github.com`
236+
- **Whitespace trimmed**: `" github.com "` = `github.com`
214237
- **Trailing dots removed**: `github.com.` = `github.com`
215-
- **Protocols stripped**: `https://github.com` = `github.com`
216238

217-
```bash
218-
# These are all equivalent
219-
--allow-domains github.com
220-
--allow-domains " GitHub.COM. "
221-
--allow-domains "https://github.com"
222-
```
239+
:::note
240+
Protocol prefixes (`http://`, `https://`) are **not** stripped — they enable [protocol-specific filtering](#protocol-specific-filtering). A bare domain (no prefix) allows both HTTP and HTTPS.
241+
:::
223242

224243
## Debugging domain filtering
225244

@@ -259,5 +278,6 @@ awf logs --format json | jq 'select(.isAllowed == false)'
259278

260279
## See also
261280

262-
- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - Complete option documentation
281+
- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - Complete option documentation including implicit behaviors
282+
- [Playwright Testing](/gh-aw-firewall/guides/playwright-testing) - Using the `localhost` keyword for local development
263283
- [Security Architecture](/gh-aw-firewall/reference/security-architecture) - How filtering works

‎docs-site/src/content/docs/reference/cli-reference.md‎

Lines changed: 142 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ awf [options] -- <command>
6969

7070
### `--allow-domains <domains>`
7171

72-
Comma-separated list of allowed domains. Domains automatically match all subdomains. Supports wildcard patterns and protocol-specific filtering.
72+
Comma-separated list of allowed domains. Domains automatically match all subdomains. Supports wildcard patterns, protocol-specific filtering, and special keywords.
7373

7474
**If no domains are specified, all network access is blocked.** This is useful for running commands that should have no network access.
7575

@@ -82,7 +82,7 @@ Comma-separated list of allowed domains. Domains automatically match all subdoma
8282
awf -- echo "offline command"
8383
```
8484

85-
#### Protocol-Specific Filtering
85+
#### Protocol-specific filtering
8686

8787
Restrict domains to HTTP-only or HTTPS-only traffic by prefixing with the protocol:
8888

@@ -93,7 +93,7 @@ Restrict domains to HTTP-only or HTTPS-only traffic by prefixing with the protoc
9393
# HTTP only - blocks HTTPS traffic to this domain
9494
--allow-domains 'http://legacy-api.example.com'
9595

96-
# Both protocols (default behavior, backward compatible)
96+
# Both protocols (default behavior)
9797
--allow-domains 'example.com'
9898

9999
# Mixed configuration
@@ -103,6 +103,78 @@ Restrict domains to HTTP-only or HTTPS-only traffic by prefixing with the protoc
103103
--allow-domains 'https://*.secure.example.com'
104104
```
105105

106+
| Format | HTTP | HTTPS | Example |
107+
|--------|------|-------|---------|
108+
| `domain.com` | ✓ | ✓ | `--allow-domains example.com` |
109+
| `https://domain.com` | ✗ | ✓ | `--allow-domains 'https://api.example.com'` |
110+
| `http://domain.com` | ✓ | ✗ | `--allow-domains 'http://legacy.example.com'` |
111+
112+
:::tip
113+
Bare domains (without protocol prefix) allow both HTTP and HTTPS. Use protocol prefixes to restrict to a single protocol.
114+
:::
115+
116+
#### Wildcard patterns
117+
118+
Use `*` to match multiple domains:
119+
120+
```bash
121+
# Match any subdomain
122+
--allow-domains '*.github.com'
123+
124+
# Match prefix patterns within a subdomain label
125+
--allow-domains 'api-*.example.com'
126+
127+
# Combine plain domains and wildcards
128+
--allow-domains 'github.com,*.googleapis.com,api-*.example.com'
129+
```
130+
131+
:::caution
132+
Use quotes around patterns to prevent shell expansion of `*`.
133+
:::
134+
135+
| Pattern | Matches | Does Not Match |
136+
|---------|---------|----------------|
137+
| `*.github.com` | `api.github.com`, `raw.github.com` | `github.com` |
138+
| `api-*.example.com` | `api-v1.example.com`, `api-test.example.com` | `api.example.com` |
139+
| `github.com` | `github.com`, `api.github.com` | `notgithub.com` |
140+
141+
**Security restrictions:** Overly broad patterns like `*`, `*.*`, or `*.*.*` are rejected.
142+
143+
:::note
144+
Wildcard patterns and protocol prefixes can be combined: `https://*.secure.example.com` matches only HTTPS traffic to any subdomain of `secure.example.com`.
145+
:::
146+
147+
#### `localhost` keyword
148+
149+
Using `localhost` in `--allow-domains` triggers special behavior for local development:
150+
151+
```bash
152+
# Automatically configures everything for local testing
153+
sudo awf --allow-domains localhost -- npx playwright test
154+
```
155+
156+
When `localhost` is detected, awf automatically:
157+
158+
1. **Replaces `localhost` with `host.docker.internal`** — Maps to Docker's host gateway so containers can reach host services
159+
2. **Enables `--enable-host-access`** — Activates host network access (equivalent to passing `--enable-host-access`)
160+
3. **Allows common development ports** — Opens ports 3000, 3001, 4000, 4200, 5000, 5173, 8000, 8080, 8081, 8888, 9000, 9090
161+
162+
Protocol prefixes are preserved: `http://localhost` becomes `http://host.docker.internal` and `https://localhost` becomes `https://host.docker.internal`.
163+
164+
```bash
165+
# Override the default ports
166+
sudo awf --allow-domains localhost --allow-host-ports 3000,8080 -- npx playwright test
167+
168+
# Combine with other domains
169+
sudo awf --allow-domains localhost,github.com -- npx playwright test
170+
```
171+
172+
:::caution
173+
The `localhost` keyword enables access to services running on your host machine. Only use it for trusted workloads like local testing and development.
174+
:::
175+
176+
**See also:** [Playwright Testing with Localhost](/gh-aw-firewall/guides/playwright-testing) for detailed examples.
177+
106178
### `--allow-domains-file <path>`
107179

108180
Path to file with allowed domains. Supports comments (`#`) and one domain per line.
@@ -752,6 +824,71 @@ sudo -E awf --enable-api-proxy --no-rate-limit \
752824
When using a custom `--openai-api-target` or `--anthropic-api-target`, you must add the target domain to `--allow-domains` so the firewall permits outbound traffic. AWF emits a warning if a custom target is set but not in the allowlist.
753825
:::
754826

827+
## Implicit Behaviors
828+
829+
### Enterprise domain auto-detection
830+
831+
AWF automatically detects GitHub Enterprise environments and adds required domains to the allowlist. No manual configuration is needed — the domains are auto-added when the relevant environment variables are present.
832+
833+
#### GitHub Enterprise Cloud (GHEC)
834+
835+
When `GITHUB_SERVER_URL` points to a `*.ghe.com` tenant (set automatically by GitHub Agentic Workflows), AWF auto-adds:
836+
837+
| Auto-added Domain | Purpose |
838+
|-------------------|---------|
839+
| `<tenant>.ghe.com` | Enterprise tenant |
840+
| `api.<tenant>.ghe.com` | API access |
841+
| `copilot-api.<tenant>.ghe.com` | Copilot inference |
842+
| `copilot-telemetry-service.<tenant>.ghe.com` | Copilot telemetry |
843+
844+
Domains from `GITHUB_API_URL` are also detected — if `GITHUB_API_URL` points to a `*.ghe.com` hostname (e.g., `https://api.myorg.ghe.com`), that hostname is added to the allowlist as well. This ensures API access works even if only `GITHUB_API_URL` is set.
845+
846+
```bash
847+
# These environment variables are set automatically by GitHub Agentic Workflows
848+
# GITHUB_SERVER_URL=https://myorg.ghe.com
849+
# GITHUB_API_URL=https://api.myorg.ghe.com
850+
851+
# AWF auto-adds:
852+
# - myorg.ghe.com
853+
# - api.myorg.ghe.com
854+
# - copilot-api.myorg.ghe.com
855+
# - copilot-telemetry-service.myorg.ghe.com
856+
sudo awf --allow-domains github.com -- copilot-agent
857+
```
858+
859+
:::note
860+
Public `github.com` is not auto-added — it must be specified explicitly in `--allow-domains`.
861+
:::
862+
863+
#### GitHub Enterprise Server (GHES)
864+
865+
When `ENGINE_API_TARGET` is set (indicating a GHES environment), AWF auto-adds:
866+
867+
| Auto-added Domain | Purpose |
868+
|-------------------|---------|
869+
| `github.<company>.com` | GHES base domain (extracted from API URL) |
870+
| `api.github.<company>.com` | GHES API access |
871+
| `api.githubcopilot.com` | Copilot API (cloud-hosted) |
872+
| `api.enterprise.githubcopilot.com` | Enterprise Copilot API |
873+
| `telemetry.enterprise.githubcopilot.com` | Enterprise Copilot telemetry |
874+
875+
```bash
876+
# Set by GitHub Agentic Workflows on GHES
877+
# ENGINE_API_TARGET=https://api.github.mycompany.com
878+
879+
# AWF auto-adds:
880+
# - github.mycompany.com
881+
# - api.github.mycompany.com
882+
# - api.githubcopilot.com
883+
# - api.enterprise.githubcopilot.com
884+
# - telemetry.enterprise.githubcopilot.com
885+
sudo awf --allow-domains github.com -- copilot-agent
886+
```
887+
888+
:::tip
889+
Use `--log-level debug` to see which enterprise domains were auto-detected. Look for "Auto-added GHEC domains" or "Auto-added GHES domains" in the output.
890+
:::
891+
755892
## Exit Codes
756893

757894
| Code | Description |
@@ -1064,7 +1201,8 @@ Denied Requests (3):
10641201
## See Also
10651202

10661203
- [API Proxy Sidecar](/gh-aw-firewall/reference/api-proxy-sidecar) - Secure credential injection architecture and configuration
1067-
- [Domain Filtering Guide](/gh-aw-firewall/guides/domain-filtering) - Allowlists, blocklists, and wildcards
1204+
- [Domain Filtering Guide](/gh-aw-firewall/guides/domain-filtering) - Allowlists, blocklists, wildcards, and protocol-specific filtering
1205+
- [Playwright Testing](/gh-aw-firewall/guides/playwright-testing) - Using the `localhost` keyword for local development
10681206
- [SSL Bump Reference](/gh-aw-firewall/reference/ssl-bump/) - HTTPS content inspection and URL filtering
10691207
- [Quick Start Guide](/gh-aw-firewall/quickstart) - Getting started with examples
10701208
- [Usage Guide](/gh-aw-firewall/usage) - Detailed usage patterns and examples

0 commit comments

Comments
 (0)