Skip to content

Document SSL-bump feature for AWF firewall #14266

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Feb 7, 2026
Merged

Document SSL-bump feature for AWF firewall #14266

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
050a633
Initial plan
Copilot Feb 7, 2026
534cfd7
docs: Add SSL-bump feature documentation for AWF firewall
Copilot Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions docs/src/content/docs/reference/network.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,6 +261,61 @@ Available log levels:

The default log level is `info`, which provides a balance between visibility and log volume. Use `debug` for troubleshooting network access issues or `error` to minimize log output.

### SSL Bump for HTTPS Inspection

Enable SSL bump to allow the AWF firewall to inspect HTTPS traffic and filter by URL path patterns:

```yaml wrap
network:
firewall:
ssl-bump: true
allow-urls:
- "https://github.com/githubnext/*"
- "https://api.github.com/repos/*/issues"
allowed:
- defaults
Copy link

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first example enables ssl-bump with allow-urls, but the network.allowed list only contains defaults. In the compiler/engines AWF is still invoked with --allow-domains derived from network.allowed; allow-urls is additive and does not replace the domain allowlist. As written, this example would still block github.com/api.github.com unless those domains (or the github ecosystem) are included in network.allowed.

Suggestion: update this example to include the corresponding domains in network.allowed, or add an explicit note that allow-urls refines HTTPS access after the domain allowlist is satisfied.

Suggested change
- defaults
- defaults
- github.com
- api.github.com

Copilot uses AI. Check for mistakes.
```

The `ssl-bump` feature enables deep packet inspection of HTTPS traffic, allowing the firewall to filter based on URL paths instead of just domain names. When SSL bump is enabled, use `allow-urls` to specify HTTPS URL patterns that should be permitted through the firewall.

**Configuration Options:**

- `ssl-bump`: Boolean flag to enable SSL Bump for HTTPS content inspection (default: `false`)
- `allow-urls`: Array of HTTPS URL patterns to allow when SSL bump is enabled. Each pattern:
- Must use the `https://` scheme
- Supports wildcards (`*`) for flexible path matching
- Example patterns: `https://github.com/githubnext/*`, `https://api.github.com/repos/*/issues`

**Usage Example with Log Level:**

```yaml wrap
network:
firewall:
ssl-bump: true
allow-urls:
- "https://github.com/githubnext/*"
- "https://api.github.com/repos/*"
log-level: debug
allowed:
- defaults
- "github.com"
- "api.github.com"
```

> [!CAUTION]
> Security Considerations
> - SSL bump intercepts and decrypts HTTPS traffic for inspection, acting as a man-in-the-middle
> - Only enable SSL bump when URL-level filtering is necessary for your security requirements
> - Use `allow-urls` patterns carefully to avoid breaking legitimate HTTPS connections
> - This feature is specific to AWF (Agent Workflow Firewall) and does not apply to Sandbox Runtime (SRT) or other sandbox configurations
> - Requires AWF version 0.9.0 or later

> [!TIP]
> When to Use SSL Bump
> - You need to filter HTTPS traffic by specific URL paths, not just domain names
> - You want to allow access to specific API endpoints while blocking others on the same domain
> - You need fine-grained control over HTTPS resources accessed by the AI engine

See the [Sandbox Configuration](/gh-aw/reference/sandbox/) documentation for detailed AWF configuration options.

### Disabling the Firewall
Expand Down
Loading