diff --git a/docs/src/content/docs/reference/network.md b/docs/src/content/docs/reference/network.md index 4cd647ed711..7bebecc211d 100644 --- a/docs/src/content/docs/reference/network.md +++ b/docs/src/content/docs/reference/network.md @@ -5,33 +5,24 @@ sidebar: order: 1300 --- -Control network access for AI engines using the top-level `network` field to specify which domains and services your agentic workflows can access during execution. +Control network access for AI engines using the top-level `network` field to specify which domains and services your agentic workflows can access during execution. Currently supported by the Claude engine and the Copilot engine (when using the [firewall feature](/gh-aw/reference/engines/#network-permissions)). -> **Note**: Network permissions are currently supported by the Claude engine and the Copilot engine (when using the [firewall feature](/gh-aw/reference/engines/#network-permissions)). - -If no `network:` permission is specified, it defaults to `network: defaults` which allows access to basic infrastructure domains (certificates, JSON schema, Ubuntu, common package mirrors, Microsoft sources). +Defaults to `network: defaults` (basic infrastructure: certificates, JSON schema, Ubuntu, package mirrors, Microsoft sources). ## Configuration ```yaml wrap -# Default: basic infrastructure only -engine: - id: copilot +# Default (basic infrastructure only) network: defaults -# Ecosystems + custom domains +# Ecosystems + custom domains (subdomains auto-included) network: allowed: - defaults # Basic infrastructure - python # Python/PyPI ecosystem - node # Node.js/NPM ecosystem - - "api.example.com" # Custom domain - -# Custom domains (automatically includes subdomains) -network: - allowed: - - "api.example.com" # Exact domain - - "trusted.com" # Includes all *.trusted.com subdomains + - "api.example.com" # Includes all subdomains + - "trusted.com" # Includes *.trusted.com # No network access network: {} @@ -39,32 +30,21 @@ network: {} ## Security Model -Network permissions follow the principle of least privilege with four access levels: +Network permissions follow least privilege with three access levels: 1. **Default Allow List** (`network: defaults`): Basic infrastructure only -2. **Selective Access** (`network: { allowed: [...] }`): Only listed domains/ecosystems are accessible +2. **Selective Access** (`network: { allowed: [...] }`): Only listed domains/ecosystems 3. **No Access** (`network: {}`): All network access denied -4. **Automatic Subdomain Matching**: AWF automatically matches all subdomains of allowed domains (e.g., `github.com` allows `api.github.com`, `raw.githubusercontent.com`, etc.) -:::note -AWF does not support wildcard syntax like `*.example.com`. Instead, listing a domain automatically includes all its subdomains. Use `example.com` to allow access to `example.com`, `api.example.com`, `sub.api.example.com`, etc. -::: +Domains automatically include all subdomains (e.g., `github.com` allows `api.github.com`, `raw.githubusercontent.com`). No wildcard syntax like `*.example.com` is supported. ## Content Sanitization -The `network:` configuration also controls which domains are allowed in sanitized content. URLs from domains not in the allowed list are replaced with `(redacted)` to prevent potential data exfiltration through untrusted links. - -:::tip -If you see `(redacted)` in workflow outputs, add the domain to your `network.allowed` list. This applies the same domain allowlist to both network egress (when firewall is enabled) and content sanitization. -::: - -GitHub domains (`github.com`, `githubusercontent.com`, etc.) are always allowed by default. +URLs from non-allowed domains are replaced with `(redacted)` in workflow outputs to prevent data exfiltration. If you see `(redacted)`, add the domain to your `network.allowed` list. GitHub domains are always allowed. ## Ecosystem Identifiers -Mix ecosystem identifiers with specific domains for fine-grained control: - | Identifier | Includes | |------------|----------| | `defaults` | Basic infrastructure (certificates, JSON schema, Ubuntu, package mirrors) | @@ -97,47 +77,26 @@ network: - "api.example.com" # Custom domain ``` -When enabled, AWF: -- Wraps the Copilot CLI execution command -- Enforces domain allowlisting using the `--allow-domains` flag -- Automatically includes all subdomains (e.g., `github.com` allows `api.github.com`) -- Logs all network activity for audit purposes -- Blocks access to domains not explicitly allowed - -:::caution -AWF does not support wildcard syntax. Do not use patterns like `*.example.com`. Instead, list the base domain (e.g., `example.com`) which automatically includes all subdomains. -::: +When enabled, AWF wraps Copilot CLI execution, enforces domain allowlisting, logs network activity, and blocks non-allowed domains. ### Firewall Log Level -Control the verbosity of AWF firewall logs using the `log-level` field: - ```yaml wrap network: firewall: - log-level: info # Options: debug, info, warn, error + log-level: info # debug | info (default) | warn | error allowed: - defaults - python ``` -Available log levels: -- `debug`: Detailed diagnostic information for troubleshooting -- `info`: General informational messages (default) -- `warn`: Warning messages for potential issues -- `error`: Error messages only - -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. +Use `debug` for troubleshooting, `error` to minimize output. See the [Copilot Engine - Network Permissions](/gh-aw/reference/engines/#network-permissions) documentation for detailed AWF configuration options. ### Disabling the Firewall -:::caution[Deprecated] -The `network.firewall` field is deprecated. Use `sandbox.agent: false` instead to disable the firewall for the agent. -::: - -To disable the firewall, use `sandbox.agent: false`: +Disable the firewall using `sandbox.agent: false`: ```yaml wrap engine: copilot @@ -145,37 +104,19 @@ network: allowed: - defaults - python - - "api.example.com" sandbox: agent: false ``` -**Legacy approach (deprecated):** - -```yaml wrap -strict: false -network: - allowed: - - defaults - - python - - "api.example.com" - firewall: false -``` - -When the firewall is disabled: -- Network permissions are still applied for content sanitization -- The agent can make network requests without firewall enforcement -- This is useful during development or when the firewall is incompatible with your workflow - -For production workflows, enabling the firewall is recommended for better network security. +When disabled, network permissions still apply for content sanitization but not for firewall enforcement. Recommended for production: enable the firewall. ## Best Practices -Follow the principle of least privilege by only allowing access to domains and ecosystems actually needed. Prefer ecosystem identifiers over listing individual domains. When adding custom domains, use the base domain (e.g., `trusted.com`) which automatically includes all subdomains—do not use wildcard syntax like `*.trusted.com`. +Follow least privilege: only allow needed domains/ecosystems. Prefer ecosystem identifiers over individual domains. ## Troubleshooting -If you encounter network access denied errors, verify that required domains or ecosystems are included in the `allowed` list. Start with `network: defaults` and add specific requirements incrementally. Network access violations are logged in workflow execution logs. +Network access denied errors: verify domains/ecosystems are in the `allowed` list. Start with `network: defaults` and add requirements incrementally. Check workflow logs for violations. ## Related Documentation