Network Permissions

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.

Note: Network permissions are currently supported by the Claude engine and the Copilot engine (when using the firewall feature).

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).

Tip

New to Network Configuration? See the Network Configuration Guide for practical examples, common patterns, and troubleshooting tips for package registries and CDNs.

Configuration

# Default: basic infrastructure only
engine:
  id: copilot
network: defaults

# Ecosystems + custom domains
network:
  allowed:
    - defaults              # Basic infrastructure
    - python               # Python/PyPI ecosystem
    - node                 # Node.js/NPM ecosystem
    - "api.example.com"    # Custom domain

# Custom domains with wildcard patterns
network:
  allowed:
    - "api.example.com"      # Exact domain (also matches subdomains)
    - "*.cdn.example.com"    # Wildcard: matches any subdomain of cdn.example.com

# Protocol-specific domain filtering (Copilot engine only)
network:
  allowed:
    - "https://secure.api.example.com"   # HTTPS-only access
    - "http://legacy.example.com"        # HTTP-only access
    - "example.org"                      # Both HTTP and HTTPS (default)

# No network access
network: {}

# Block specific domains
network:
  allowed:
    - defaults              # Basic infrastructure
    - python               # Python/PyPI ecosystem
  blocked:
    - "tracker.example.com" # Block specific tracking domain
    - "analytics.example.com" # Block analytics

# Block entire ecosystems
network:
  allowed:
    - defaults
    - github
    - node
  blocked:
    - python               # Block Python/PyPI even if in defaults

Blocking Domains

Use the blocked field to exclude specific domains or ecosystems from the allowed set. Blocked entries take precedence over allowed ones and include all subdomains, useful for privacy (block trackers), security (block known-bad domains), or compliance:

# Combine domain and ecosystem blocking
network:
  allowed:
    - defaults
    - github
    - node
  blocked:
    - python               # Block Python ecosystem
    - "cdn.example.com"    # Block specific CDN

Access Levels

Network permissions follow the principle of least privilege with four access levels:

1. Default Allow List (network: defaults): Basic infrastructure only
2. Selective Access (network: { allowed: [...] }): Only listed domains/ecosystems are accessible
3. No Access (network: {}): All network access denied
4. Automatic Subdomain Matching: Listed domains automatically match all subdomains (e.g., github.com allows api.github.com, raw.githubusercontent.com, etc.)
5. Wildcard Patterns: Use *.example.com to explicitly match any subdomain of example.com

Protocol-Specific Domain Filtering

Restrict domains to a specific protocol (HTTP or HTTPS only) for legacy systems, strict HTTPS enforcement, or gradual migration. Currently supported by the Copilot engine with AWF firewall enabled; domains without a protocol prefix allow both HTTP and HTTPS.

engine: copilot
network:
  allowed:
    - "https://secure.api.example.com"   # HTTPS-only access
    - "http://legacy.example.com"        # HTTP-only access
    - "example.org"                      # Both protocols (default)
    - "https://*.api.example.com"        # HTTPS wildcard

Compiled to AWF:

--allow-domains ...,example.org,http://legacy.example.com,https://secure.api.example.com,...

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.

Ecosystem Identifiers

Mix ecosystem identifiers with specific domains for fine-grained control:

Identifier	Includes
defaults	Basic infrastructure (certificates, JSON schema, Ubuntu, package mirrors)
github	GitHub domains
containers	Docker Hub, GitHub Container Registry, Quay
linux-distros	Debian, Alpine, and other Linux package repositories
dotnet, dart, go, haskell, java, node, perl, php, python, ruby, rust, swift	Language-specific package managers and registries
terraform	HashiCorp and Terraform domains
playwright	Playwright testing framework domains

Common identifiers: python (PyPI/pip), node (npm/yarn/pnpm), containers (Docker Hub/GHCR), go (proxy.golang.org). See the Network Configuration Guide for complete domain lists.

Strict Mode Validation

When strict mode is enabled (default), network configuration is validated to ensure security best practices. Strict mode recommends using ecosystem identifiers instead of individual domains for better maintainability.

Ecosystem Identifier Recommendation

Strict mode allows but warns about individual ecosystem member domains (e.g., pypi.org, npmjs.org), recommending ecosystem identifiers (e.g., python, node) instead. This applies to all engines, including those with LLM gateway support.

# ! Allowed with warning in strict mode (all engines)
strict: true
network:
  allowed:
    - defaults
    - "pypi.org"        # Allowed but warns: recommend using 'python'
    - "npmjs.org"       # Allowed but warns: recommend using 'node'

# ✓ Recommended in strict mode (no warnings)
strict: true
network:
  allowed:
    - defaults
    - python           # Ecosystem identifier (recommended)
    - node             # Ecosystem identifier (recommended)

# ✓ Custom domains allowed in strict mode (no warnings)
strict: true
network:
  allowed:
    - defaults
    - python
    - "api.example.com"  # Custom domain (not part of known ecosystem)

Warning Messages

When strict mode encounters an individual ecosystem domain, it emits a warning suggesting the appropriate ecosystem identifier:

warning: strict mode: recommend using ecosystem identifiers instead of individual domain names for better maintainability: 'pypi.org' → 'python', 'npmjs.org' → 'node'

Implementation

Network permissions are enforced differently depending on the AI engine:

Copilot Engine

The Copilot engine supports network permissions through AWF (Agent Workflow Firewall). AWF is a network firewall wrapper sourced from github.com/github/gh-aw-firewall that wraps Copilot CLI execution and enforces domain-based access controls.

Enable network permissions in your workflow:

engine: copilot

network:
  firewall: true           # Enable AWF enforcement
  allowed:
    - defaults             # Basic infrastructure
    - python              # Python ecosystem
    - "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)
• Supports wildcard patterns (e.g., *.cdn.example.com matches img.cdn.example.com)
• Logs all network activity for audit purposes
• Blocks access to domains not explicitly allowed

Firewall Log Level

Control the verbosity of AWF firewall logs using the log-level field:

network:
  firewall:
    log-level: info      # Options: debug, info, warn, error
  allowed:
    - defaults
    - python

Available log levels: debug (verbose), info (default), warn, error.

SSL Bump for HTTPS Inspection

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

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

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:

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"

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 and does not apply to Sandbox Runtime (SRT); requires AWF version 0.9.0 or later

Use SSL bump when you need to allow specific API endpoints while blocking others on the same domain. See the Sandbox Configuration documentation for detailed AWF configuration options.

Disabling the Firewall

The firewall is always enabled via the default sandbox.agent: awf configuration:

engine: copilot
network:
  allowed:
    - defaults
    - python
    - "api.example.com"
# sandbox.agent defaults to 'awf' if not specified

When the firewall is disabled, network permissions still apply for content sanitization but the agent can make unrestricted network requests. Only disable during development or when AWF is incompatible with your workflow; keep it enabled in production.

Wildcard Domain Patterns

Use wildcard patterns (*.example.com) to match any subdomain of a domain. Wildcards provide explicit control when you need to allow a family of subdomains.

network:
  allowed:
    - defaults
    - "*.cdn.example.com"     # Matches img.cdn.example.com, static.cdn.example.com
    - "*.storage.example.com" # Matches files.storage.example.com

Wildcard matching behavior:

• *.example.com matches subdomain.example.com and deep.nested.example.com
• *.example.com also matches the base domain example.com
• Only a single wildcard at the start is allowed (e.g., *.*.example.com is invalid)
• The wildcard must be followed by a dot and domain (e.g., * alone is not allowed in strict mode)

Both example.com (simpler) and *.example.com (explicit about subdomain intent) match all subdomains.

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. For custom domains, both base domains (e.g., trusted.com) and wildcard patterns (e.g., *.trusted.com) work for subdomain matching.

Troubleshooting

If you encounter network access blocked 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.

Use gh aw logs --run-id <run-id> to view firewall activity and identify blocked domains. See the Network Configuration Guide for detailed troubleshooting steps and common solutions.

Related Documentation

• Network Configuration Guide - Practical examples and common patterns
• Frontmatter - Complete frontmatter configuration guide
• Tools - Tool-specific network access configuration
• Security Guide - Comprehensive security guidance