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. Supported by all four engines (Copilot, Claude, Codex, Gemini) via the AWF firewall.

If no network: permission is specified, it defaults to network: defaults, which allows basic infrastructure domains (certificates, JSON schema, Ubuntu, common package mirrors, Microsoft sources).

Configuration

Network permissions follow the principle of least privilege:

Default (network: defaults) allows basic infrastructure only.
Selective (network: { allowed: [...] }) allows only the listed domains or ecosystems.
No access (network: {}) blocks all network access.

Listed domains automatically match all subdomains; wildcard patterns (*.example.com) are also supported — see Wildcard Domain Patterns.

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

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:

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

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 and Claude engines 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

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.

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 (`github.com`, `docs.github.com`, `github.blog`, `*.githubusercontent.com`, and related)
`local`	Loopback addresses (`localhost`, `127.0.0.1`, `::1`)
`dev-tools`	Popular CI/CD and developer tool services (Codecov, Shields.io, Snyk, Renovate, CircleCI, etc.)
`default-safe-outputs`	Compound: `defaults` + `dev-tools` + `github` + `local` — recommended baseline for `safe-outputs.allowed-domains`
`containers`	Docker Hub, GitHub Container Registry, Quay, GCR, MCR
`linux-distros`	Debian, Ubuntu, Alpine, Fedora, and other Linux package repositories
`playwright`	Playwright browser testing (see Playwright Reference)
`chrome`	Headless Chrome/Puppeteer (`.google.com`, `.googleapis.com`, `*.gvt1.com`)
`fonts`	Google Fonts (`fonts.googleapis.com`, `fonts.gstatic.com`)
`terraform`	HashiCorp registry, apt/yum releases
`bazel`	Bazel build system (`releases.bazel.build`, `bcr.bazel.build`)
`clojure`	Clojure packages (`clojars.org`)
`copilot-vendor`	Plan-specific Copilot API hosts (`api.business.githubcopilot.com`, `api.enterprise.githubcopilot.com`, `api.individual.githubcopilot.com`) and Copilot telemetry (`telemetry.enterprise.githubcopilot.com`) — not enabled by default, since agents route inference through the firewall gateway
`threat-detection`	Compatibility alias for Copilot threat-detection network access (`api.githubcopilot.com`, Copilot plan APIs, telemetry, `api.github.com`, `github.com`, `host.docker.internal`, `registry.npmjs.org`)
`dart`	Dart/Flutter packages (`pub.dev`, `storage.googleapis.com`)
`deno`	Deno runtime (`deno.land`, `jsr.io`, `googleapis.deno.dev`)
`dotnet`	NuGet packages and .NET SDK
`elixir`	Elixir packages (`hex.pm`)
`go`	Go modules and toolchain downloads (`proxy.golang.org`, `sum.golang.org`, `go.dev`)
`haskell`	Haskell packages (`hackage.haskell.org`, GHCup)
`java`	Maven Central, Gradle, Adoptium
`julia`	Julia packages (`pkg.julialang.org`, `storage.julialang.net`)
`kotlin`	Kotlin/JetBrains packages (`download.jetbrains.com`)
`latex`	CTAN, TUG, MiKTeX packages — note: TeX Live’s `tlmgr` uses redirected CTAN mirrors not reachable through the firewall; prefer `apt-get install texlive-full` (covered by `defaults`) or MiKTeX (`packages.miktex.org`)
`lean`	Lean packages (`lean-lang.org`, `reservoir.lean-lang.org`)
`lua`	Lua packages (`luarocks.org`)
`node`	npm, yarn, pnpm, Node.js, Bun
`node-cdns`	Node.js CDN assets (jsDelivr, jQuery CDN)
`ocaml`	OCaml packages (`opam.ocaml.org`)
`perl`	Perl/CPAN packages (`cpan.org`, `metacpan.org`)
`php`	PHP Composer packages (`packagist.org`, `getcomposer.org`)
`powershell`	PowerShell Gallery (`powershellgallery.com`)
`python`	PyPI, conda, pythonhosted.org
`python-native`	PyPI + crates.io — for Python packages with native extensions (pyo3/maturin)
`r`	R/CRAN packages (`cran.r-project.org`)
`ruby`	RubyGems, Bundler
`rust`	Rust crates (`crates.io`, `static.rust-lang.org`, `sh.rustup.rs`)
`scala`	Scala packages (`repo.scala-sbt.org`, `jitpack.io`)
`swift`	Swift packages (`swift.org`, `cocoapods.org`)
`zig`	Zig packages (`ziglang.org`)

Automatic Engine Domain Sets

Each engine automatically receives the domain set it requires in addition to network.allowed. These named sets are maintained by the compiler for analysis and reporting; they are not valid network.allowed identifiers, except for the legacy threat-detection compatibility alias listed above.

Engine set	Included domains
`copilot`	`api.github.com`, `api.githubcopilot.com`, `github.com`, `host.docker.internal`, `raw.githubusercontent.com`
`claude`	Anthropic APIs, GitHub transport, certificate/OCSP services, Ubuntu package metadata, Playwright downloads, and `host.docker.internal`
`codex`	`172.30.0.1`, `api.github.com`, `api.openai.com`, `chatgpt.com`, `github.com`, `host.docker.internal`, `openai.com`
`gemini`	`*.googleapis.com`, `generativelanguage.googleapis.com`, `github.com`, `host.docker.internal`, `raw.githubusercontent.com`
`pi`	`api.githubcopilot.com`, `github.com`, `host.docker.internal`, `raw.githubusercontent.com`; provider-scoped models replace the API host with the selected provider endpoint
`pi-base`	`github.com`, `host.docker.internal`, `raw.githubusercontent.com`; applied as the provider-independent baseline before a provider prefix is resolved
`threat-detection`	Applied automatically only to Copilot threat-detection runs: Copilot API and telemetry hosts, `api.github.com`, `github.com`, `host.docker.internal`, and `registry.npmjs.org` for read-only lockfile validation. External Claude, Codex, Gemini, and other detection runs use their own engine defaults.

Ecosystem Identifier Validation

Single-word entries in network.allowed that match the ecosystem identifier pattern ([a-z][a-z0-9-]*) are validated against the known ecosystem list at compile time. An unrecognized identifier produces a compilation error with the full list of valid options:

# ✗ Compilation error: 'rustxxxx' is not a valid ecosystem identifier
network:
  allowed:
    - defaults
    - rustxxxx

# ✓ Use the correct identifier
network:
  allowed:
    - defaults
    - rust

# ✓ Dotted domain names are validated as domains, not ecosystem identifiers
network:
  allowed:
    - defaults
    - crates.io

Strict Mode Validation

When strict mode is enabled (default), strict mode warns when you list individual ecosystem member domains (e.g., pypi.org, npmjs.org) and recommends the ecosystem identifier instead (e.g., python, node). Custom domains outside known ecosystems are allowed without warnings.

# ! Warns: recommend 'python' instead of 'pypi.org'
strict: true
network:
  allowed:
    - defaults
    - "pypi.org"
    - "npmjs.org"

# ✓ No warnings
strict: true
network:
  allowed:
    - defaults
    - python
    - node
    - "api.example.com"  # Custom domain

The emitted message takes the form:

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

Implementation

All engines (Copilot, Claude, Codex, Gemini) enforce network permissions through AWF (Agent Workflow Firewall) — a wrapper sourced from github.com/github/gh-aw-firewall that enforces domain-based access controls via --allow-domains. AWF automatically includes all subdomains (e.g., github.com allows api.github.com), supports wildcard patterns, and logs all network activity for audit.

engine: copilot          # or claude, codex, gemini
network:
  allowed:
    - defaults             # Basic infrastructure
    - python              # Python ecosystem
    - "api.example.com"   # Custom domain

Each engine has a built-in default domain list for its CLI authentication and model API transport. These lists are merged with your network.allowed entries and never include the node or python ecosystem registries: selecting an engine does not grant the agent access to registry.npmjs.org, pypi.org, or files.pythonhosted.org. Engine CLIs and SDKs are installed by workflow steps that run on the runner before the sandboxed agent starts, and containerized npx/uvx MCP servers are launched by the MCP gateway outside the agent firewall, so registry access inside the sandbox is not required for them.

This guarantee is scoped to the node and python ecosystems. Some engine defaults still include unrelated infrastructure domains needed by the CLI itself (e.g., ghcr.io, packagecloud.io, packages.microsoft.com for OS-level package/container installation) — those are not language package registries and are not gated by network.allowed.

To let the agent itself reach the node or python registries, opt in explicitly with the matching ecosystem identifier (node, python, …) in network.allowed, or declare the corresponding entry under runtimes:. With network: {} or network: { allowed: [defaults, github] }, those registries stay blocked.

See domains.go for the full lists. This invariant is enforced by TestEngineDefaultDomainsDoNotOverlapEcosystems in domains_package_registry_test.go, which fails the build if any engine’s static default domain list overlaps with the full node or python ecosystem domain sets — including registry entries added after this was written.

Firewall Log Level

Control the verbosity of AWF firewall logs using log-level. Options: debug (verbose), info (default), warn, error.

network:
  firewall:
    log-level: info
  allowed:
    - defaults
    - python

SSL Bump for HTTPS Inspection

Enable SSL bump to filter HTTPS traffic by URL path patterns instead of just domain names — useful when you need to allow specific API endpoints while blocking others on the same domain. Use allow-urls to specify the permitted HTTPS patterns.

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

Security: SSL bump intercepts and decrypts HTTPS as a man-in-the-middle — only enable when URL-level filtering is necessary, and craft allow-urls patterns carefully to avoid breaking legitimate connections. Requires AWF v0.9.0+ and does not apply to Sandbox Runtime (SRT). See Sandbox Configuration for full AWF options.

Disabling the Firewall

The firewall is enabled by default via sandbox.agent: awf. When 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.

Caller-Extensible Allowlist (`network.allowed-input`)

Reusable workflows compiled to .lock.yml bake their network.allowed into the lock file, so consumers normally can’t extend it without forking. Set network.allowed-input: true to expose a workflow_call input named network_allowed that lets callers add domains or ecosystems at runtime.

The compiled network.allowed remains the baseline; the caller’s value is unioned in before AWF starts, with ecosystem shorthands expanded to their concrete domain sets and the result deduplicated.

# source workflow (compiled to a reusable .lock.yml)
on:
  workflow_call:
network:
  allowed:
    - defaults
  allowed-input: true

# consumer workflow
jobs:
  run:
    uses: owner/repo/.github/workflows/worker.lock.yml@v1
    with:
      network_allowed: rust,github.com

The network_allowed input is a string accepting comma-separated ecosystem identifiers and/or domains. The behavior of the source workflow is unchanged when allowed-input is omitted or false.

Wildcard Domain Patterns

Wildcard patterns (*.example.com) match the base domain and all subdomains at any depth, making subdomain intent explicit. Only a single leading wildcard is allowed (*.*.example.com is invalid), and it must be followed by a dot and domain. Both example.com and *.example.com match all subdomains.

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

Troubleshooting

If network access is blocked, confirm the required domains or ecosystems are in allowed. Start with network: defaults, then add only what the workflow needs. Violations appear in workflow logs.

Use gh aw logs --run-id <run-id> to identify blocked domains. For deeper analysis, run gh aw audit <run-id>; the Firewall Analysis section shows each domain request with its allow/deny status, request volume, and policy attribution. Pass two run IDs to compare runs:

gh aw audit 12345678              # Single run
gh aw audit 12345678 12345679     # Compare two runs

See the Network Configuration Guide and Audit Commands for more.