Skip to content

Latest commit

 

History

History
774 lines (666 loc) · 47.8 KB

NetworkControls.md

File metadata and controls

774 lines (666 loc) · 47.8 KB

Network Policy Reference

This page is the policy schema: the integrations and domain rules an operator or API client can set. How the host enforces them is in Network controls.

Network controls are runtime policy managed through the admin UI/API, not deployment config. By default, all network access for the agent is closed. The host opens network access incrementally through PUT /v1/network/policy.

Network controls govern the agent and host service users, not root-owned host bootstrap and maintenance work. At the host firewall, root (uid 0) has outbound access for package installation, security updates, and ordinary root-owned system traffic. The dedicated kern-proxy uid has outbound access only so it can make policy-approved upstream connections on behalf of the agent. The separate kern-tools uid has DNS and HTTPS access for bundled tool packages; tool calls follow each action's data policy and approval contract, not the agent's domain policy. The separate kern-host-inference service also has direct DNS/HTTPS egress for its fixed host-owned provider calls; see Host AI inference. The separate kern-browser service has DNS and public TCP 443/7000 egress for connected browsers; private-address destinations are blocked. When a Cloudflare Tunnel operator endpoint is configured, the dedicated cloudflared uid has outbound access only for DNS, TCP 443, and TCP/UDP 7844. The host does not install or configure the AWS SSM agent, and snapd is stopped and masked during bootstrap. Root, proxy, tools, host-inference, browser, and optional cloudflared egress are still bounded by the EC2 security group, which keeps TCP/UDP 7844 open only when a cloudflare_tunnel operator endpoint is configured. That 7844 rule is outbound-only and nftables allows it only for the cloudflared uid, not for the agent, admin API, or proxy users; it does not expose an inbound EC2 port. The agent runs as a non-root user with no sudo, so it reaches root's broader path only if it first escalates to root.

Policy is one object: network_integrations, keyed by integration id. The managed provider integrations own exact provider rules and guards; the custom integration holds operator-defined domains for destinations no provider integration owns. Every reachable host belongs to exactly one integration.

{
  "network_integrations": {
    "openai": {"enabled": true},
    "claude": {"enabled": true},
    "bedrock": {"enabled": true},
    "github": {
      "enabled": true,
      "write_repositories": [
        {"owner": "infiloop2", "repo": "kern"},
        {"owner": "infiloop2", "repo": "infibot"}
      ]
    },
    "python_packages": {"enabled": true},
    "npm_packages": {"enabled": true},
    "custom": {
      "domains": {
        "api.example.com": {"allow_http_methods": ["GET"], "path_guards": ["^/v1(?:/.*)?$"]}
      }
    }
  }
}
Field Required Type Behavior
network_integrations No object Integration configs keyed by integration id. Known ids are openai, claude, xai, bedrock, github, python_packages, npm_packages, and custom. The provider integrations take an enabled boolean; custom has no enabled field and is enabled exactly while its domains map is non-empty (passing enabled to custom is rejected). A missing key or enabled: false disables a provider; a disabled integration carries no other state, and serialization omits it entirely.
network_integrations.custom.domains No object Map of operator-defined domain rules. Keys are exact domains or wildcard suffix domains. Wildcards must start with *., such as *.example.com; * matches any non-empty hostname prefix ending at that dot. Embedded globs and regex keys are not supported. Domains owned by a provider integration are always rejected here. The custom integration is enabled exactly while this map is non-empty.

Integration entries are stored exactly as configured. The host parses each entry directly into that integration's typed config. The proxy selects one integration for a host and asks its guard to decide the request; it does not generate a parallel domain-rule or guard-field representation.

Direct agent HTTP requests are controlled by the route rules, plus a content guard on request URL values for the managed integrations. Those headers are not inspected: GitHub, PyPI and npm reflect no header back, so a header sent there cannot reach an attacker, while a requested package name can — npm and PyPI publish per-package download statistics — which is what the URL guard answers.

What the proxy removes is what a header can do. Authorization and Cookie are stripped on the package registries, where the agent holds no credential those destinations should receive; on GitHub the agent's Authorization is replaced with the host-held token. User-Agent is replaced with a fixed host value — PyPI publishes a public download dataset whose installer name and version come from it, so unlike the rest of a request there it does have a reader. The Host header is validated against the connected host but forwarded as sent.

Custom domains enforce the operator's domain, method and path rule. The optional guard_request_content flag also applies the standard parameter guard without exceptions to hostnames, URL paths/query strings, all header names and values, and supported request bodies. It defaults to false, preserving APIs that need credentials or opaque payloads. When enabled, unsupported bodies and WebSockets are blocked. This heuristic does not prevent all exfiltration; adding a domain still means trusting that destination with host data.

This is separate from bundled tool-call filtering and does not apply to integrations that use provider-specific request controls.

Contents

Reserved Managed Domains

Every domain owned by a provider integration is reserved: it is rejected in network_integrations.custom.domains whether or not the integration is enabled, so a custom rule can never be broader than the integration's guard. The reserved suffixes are openai.com, chatgpt.com, anthropic.com, claude.ai, claude.com, x.ai, grok.com, bedrock-runtime.us-east-1.amazonaws.com, bedrock-runtime.us-east-2.amazonaws.com, bedrock-runtime.us-west-2.amazonaws.com, github.com, githubusercontent.com, pypi.org, pythonhosted.org, npmjs.org, and nodejs.org, including all their subdomains. The Bedrock integration deliberately reserves only these regional runtime endpoints, so custom rules for other AWS services under amazonaws.com stay possible. Manual rules also cannot set provider-specific guard configuration.

OpenAI Integration

When network_integrations.openai.enabled is true, Codex, Codex 2, and Codex 3 turns can run after their separate OAuth logins. The OpenAI integration directly enforces:

{
  "api.openai.com": {
    "allow_http_methods": ["POST"]
  },
  "auth.openai.com": {
    "allow_http_methods": ["GET", "POST"]
  },
  "chatgpt.com": {
    "allow_http_methods": ["GET", "POST"]
  }
}

The OpenAI external URL request guard (cache-only web search, no remote MCP) and account guard are always applied to the managed API/data-plane domains. The host infers each approved OpenAI account id from its Codex runtime's login status instead of accepting it in config. OpenAI data-plane requests are denied unless their header and OAuth token identify one of those approved accounts; auth.openai.com stays available for login. Disabling the integration deactivates all three Codex runtimes, clears each of their account pins, closes live runtime processes, and fails running Codex turns.

All three Codex runtimes use the same local network proxy and Unix service account, so the approved account ids form one OpenAI allowlist. Runtime selection chooses which Codex home and OAuth login the launcher uses during normal operation; it is not a security boundary between the three subscriptions. Code already running as kern-agent can read every Codex home. Enforcing hostile separation between the accounts would require separate OS identities and independently authenticated proxy paths rather than this shared-proxy design.

Claude Integration

When network_integrations.claude.enabled is true, Claude Code turns can run after Claude OAuth login. The Claude integration directly enforces:

{
  "api.anthropic.com": {
    "allow_http_methods": ["GET", "POST"]
  },
  "platform.claude.com": {
    "allow_http_methods": ["GET", "POST"],
    "path_guards": ["^/v1/oauth(?:/.*)?$"]
  }
}

The managed bundle opens only platform.claude.com OAuth paths plus api.anthropic.com; claude.ai stays closed unless a future Claude Code version proves, by a live denial, that it requires it. The host verifies claude auth status, infers the Claude account metadata from the agent user's Claude config, and anchors the account with provider attestation. The proxy hashes each presented bearer and uses a bounded cache of provider-attested account identities; a cache miss triggers a fixed-endpoint profile check. Data-plane requests pass only when the attested account matches the operator-approved account. Raw tokens are never cached or logged. See provider lifecycle. The unauthenticated /api/hello readiness probe remains available for Claude Code startup.

xAI Integration

When network_integrations.xai.enabled is true, the Grok and Grok 2 runtimes can reach xAI after their separate OAuth logins. The xAI integration directly enforces:

{
  "auth.x.ai": {
    "allow_http_methods": ["GET", "POST"]
  },
  "cli-chat-proxy.grok.com": {
    "allow_http_methods": ["GET", "POST"]
  },
  "api.x.ai": {
    "allow_http_methods": ["GET", "POST"]
  }
}

The managed bundle opens login, the subscription chat proxy, and Grok Build Imagine stills and video under the reserved x.ai and grok.com apexes. auth.x.ai is the OAuth issuer (discovery, device code, authorize, and token exchange) and is unpinned by construction, because it is the endpoint that establishes which account exists and it carries no model traffic. cli-chat-proxy.grok.com is the subscription data plane: inference, model catalog, remote settings, and billing.

Grok Build Imagine uses the same grok.com OAuth token on api.x.ai for POST /v1/images/generations, POST /v1/images/edits, POST /v1/videos/generations, and GET /v1/videos/<id>. Images need no storage configuration. Video creation and polling require the separately saved S3 configuration. Kern overwrites output.upload_url with a signed PUT URL for a random grok-videos/<uuid>.mp4 object, then verifies that URL in a completed response and replaces it with a signed GET URL for the same object. The operator must separately allow the bucket hostname through Custom Domain Access, as described in the Grok integration guide. Downloads authenticate to AWS with their signature, not the Grok bearer. Both URLs expire after 15 minutes. The ordinary custom rule controls download methods and paths; Grok does not claim any S3 hostname or override existing network rules. Inline image inputs and named voice references are allowed; external media inputs and unknown top-level fields are denied. Chat completions, tokenize-text, and other developer-API paths stay closed. code.grok.com stays closed; conversation state stays local because the chat proxy's session routes are denied.

Every request to the chat proxy or api.x.ai must carry exactly one Authorization: Bearer token whose JWT claims an approved account under sub (personal login) or principal_id (team login). The host infers each approved xAI account id from its Grok runtime's login status instead of accepting it in config. Requests are denied until at least one approved account id is available, and a token for any other account is denied.

Both Grok runtimes use the same local network proxy and Unix service account, so the approved account ids form one xAI allowlist. Runtime selection chooses which Grok home and OAuth login the launcher uses during normal operation; it is not a security boundary between the two subscriptions. Code already running as kern-agent can read both Grok homes. Enforcing hostile separation between the accounts would require separate OS identities and independently authenticated proxy paths rather than this shared-proxy design.

Video storage setup and download allowlisting are documented in the user-facing Grok integration guide and the internal xAI integration. The storage endpoint contract is in Admin API.

Server-side tools

Grok's hosted tools are declared as entries in a request's tools array, alongside the client-executed function tools the CLI runs locally on this host. The integration has no options and a fixed allowlist: x_search, image_generation, and video_generation. A config naming web_search for xAI is rejected at parse time rather than accepted and ignored.

Web search is denied rather than offered because Grok's has no narrow form. It searches and browses live pages as one capability, and xAI's servers do the fetching — so an allowed search could retrieve a model-chosen URL, carrying arbitrary agent-chosen data in its parameters, without any request to that domain crossing this host's network policy. There is no cache-backed mode (as OpenAI has) and no per-sub-operation control to allow instead. The full reasoning, including the sub-operations a search performs and why none of them is separately deniable, is in The xAI integration.

Allowed hosted declarations:

  • X search (x_search) — xAI performs keyword, semantic, user, and thread search against X data on its servers. The host sends only to the pinned cli-chat-proxy.grok.com request path; it does not contact x.com or a third-party search provider.
  • Image generation (image_generation) — an xAI Responses tool that runs on xAI servers. Kern requires action: "generate"; auto, edit, external input fields, and unknown options are denied. Grok Build 1.0.5 does not yet declare or decode it in the original capture; that observation does not establish support in later harness versions. The policy allowance remains separate from the Imagine REST flow.
  • Video generation (video_generation) — reserved for an xAI-hosted declaration. Grok Build Imagine video uses the S3-backed REST flow on api.x.ai, not this hosted tool. Only the bare declaration is admitted on the chat proxy; every option fails closed.

Denied hosted tools:

  • Web search (web_search) — denied with its own reason code, xai_web_search_denied, so an agent reads "this host does not offer it" rather than "unrecognised tool". Both of xAI's ways of asking for one are covered: a tools entry, and a search_parameters object that is not an explicit mode: "off".
  • Code execution (code_execution, code_interpreter) — runs code on xAI infrastructure. The agent has a local shell on this host, so nothing is lost.
  • Collections search (file_search, collections_search) — searches xAI-hosted document collections, which this host never populates.
  • Hosted browsing (browser, computer_use).
  • Remote MCP servers — they make xAI call an external server with request data.

Two of those are spelled differently on the wire and in xAI's SDK (code_interpreter/code_execution, file_search/collections_search); both spellings are denied.

Anything else appearing in a tools array that is not a client-executed function or one of the three allowed names is denied too. That is what keeps a hosted tool xAI ships later from being forwarded unreviewed: the denial follows from where the entry appears, not from it already being on a list. Replay history items — web_search_call, x_search_call, image_generation_call, video_generation_call, code_interpreter_call, file_search_call, mcp_call, mcp_list_tools — describe earlier calls rather than declaring new ones, and they and their whole subtrees are skipped so ordinary follow-up turns are not denied.

AWS Bedrock Integration

The Hermes runtime runs through an AWS Bedrock integration in the operator's own AWS account. One connection holds its region and IAM credential; one enabled flag controls access. The bedrock integration owns and guards the bedrock-runtime apexes:

{
  "enabled": true
}
Field Required Type Behavior
enabled Yes boolean Enables the Bedrock integration for Hermes. The validated AWS connection, including its region, remains stored independently when this is false.

The stored Bedrock config is not expanded into a generic domain-policy entry. The managed-integration registry assigns every supported Bedrock Runtime apex to the Bedrock guard. At request time that guard derives the one allowed host from the region stored with the connected credential, permits only POST, and applies ^/model/[^/]+/(?:converse|converse-stream)$ directly. Every other supported region remains owned by Bedrock and denied, so it cannot fall through to a custom-domain rule.

The Converse paths cover the request shapes used by Hermes. The agent never holds the operator's AWS credential. Hermes receives a fixed access-key id and a fixed dummy secret with no AWS capability. The proxy requires that dummy access-key id, the configured region, SigV4 service bedrock, and an allowed model invocation path, then discards the agent's signature and re-signs the exact request with the validated operator key. A request for another region is rejected at CONNECT; a request signed with any other access-key id is denied with bedrock_access_key_mismatch. The Bedrock control plane and every other AWS service stay closed. Query-string (presigned) authentication and temporary session credentials (X-Amz-Security-Token) are always denied.

Allowed invocations are also metered: the proxy passively parses the token usage AWS reports in each relayed response and counts it per model and UTC day, which powers the live Hermes cost estimate in the admin UI. Metering never alters or gates the relayed bytes.

GitHub Integration

{
  "enabled": true,
  "write_repositories": [
    {"owner": "infiloop2", "repo": "kern"},
    {"owner": "infiloop2", "repo": "infibot"}
  ]
}
Field Required Type Behavior
enabled Yes boolean Enables the GitHub integration. When enabled, the agent may read any repository the injected token reaches (public repositories always; private ones as far as the token allows). When false, nothing else may be configured: a non-empty write_repositories is rejected, and disabling through the UI removes the configured list (the stored credential is kept).
write_repositories No array Repositories the agent may also write to — git push and mutating REST calls. Repository administration stays denied even for these (see below). Reads are universal and need no listing. Owner/repo are normalized to lowercase; duplicates are rejected. This is also the list the repository audit inspects. Enabling with an empty list gives a read-only agent.
write_repositories[].owner Yes string GitHub owner (user or organization) identifier.
write_repositories[].repo Yes string GitHub repository identifier.
block_direct_main_pushes No boolean Default true while GitHub is enabled. When true, the proxy rejects any git receive-pack transaction that updates refs/heads/main; no approval item is created. Feature-branch pushes and pull-request merges are unaffected. Set this to false to allow direct pushes to main.
require_dot_github_approval No boolean Default false. When true, a git push that changes any .github/ path is held for operator approval instead of reaching GitHub (see the .github approval gate). Requires the integration enabled.

The access model is all reads, scoped writes. An agent's utility comes from many data-in paths — reading any repository, sample, or reference it needs — so reads are not restricted. The controlled side is egress: a write must target a configured write_repositories entry, and even for those repositories the writes that reach past repository content are denied outright: repository administration (settings, access grants, protections — the full denylist is under Access Enforcement) and publishing to GitHub Pages. Dispatching an existing GitHub Actions workflow is treated as a scoped write: it is allowed only for a configured write repository. Other workflow and run administration remains denied.

When GitHub is enabled, the GitHub integration directly enforces the following host and method boundary. Its typed config carries the write-repository list and .github approval toggle:

{
  "github.com": {
    "allow_http_methods": ["GET", "HEAD", "POST"]
  },
  "api.github.com": {
    "allow_http_methods": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]
  },
  "uploads.github.com": {
    "allow_http_methods": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]
  },
  "codeload.github.com": {"allow_http_methods": ["GET", "HEAD"]},
  "raw.githubusercontent.com": {"allow_http_methods": ["GET", "HEAD"]},
  "objects.githubusercontent.com": {"allow_http_methods": ["GET", "HEAD"]},
  "release-assets.githubusercontent.com": {"allow_http_methods": ["GET", "HEAD"]},
  "github-cloud.githubusercontent.com": {"allow_http_methods": ["GET", "HEAD"]},
  "productionresultssa{0..19}.blob.core.windows.net": {"allow_http_methods": ["GET", "HEAD"]},
  "productionresultssa{30..49}.blob.core.windows.net": {"allow_http_methods": ["GET", "HEAD"]},
  "productionresultssa{100..199}.blob.core.windows.net": {"allow_http_methods": ["GET", "HEAD"]}
}

Only the three domains where writes are possible carry the repo guard. The remaining download hosts are GET/HEAD-only, so no write can ever reach them and there is nothing for a repo guard to gate: the archive and raw-blob hosts serve reads of any repository, and the signed-URL domains have no owner/repo in their presigned S3 paths anyway — access control there is the signed URL itself, and downloads-only closes the other direction (a signed URL can also authorize an upload).

GitHub Actions Azure Blob downloads are limited to GitHub's documented productionresultssa storage accounts numbered 0–19, 30–49, and 100–199. The added ranges are documented in GitHub’s October 22, 2026 announcement.

Access Enforcement

The guard only ever gates writes; every read passes through. One single write_repositories list drives every guarded GitHub domain. Request paths are canonicalized before the write check (the mechanics are described in ../architecture/network-controls.md), so an encoded traversal cannot collapse a write path onto a repository the policy did not list.

github.com decisions:

Request Class Allowed when
GET/HEAD /<owner>/<repo> and subpaths read always (integration enabled)
GET /<owner>/<repo>[.git]/info/refs?service=git-upload-pack, POST /<owner>/<repo>[.git]/git-upload-pack read (clone/fetch) always
GET /<owner>/<repo>[.git]/info/refs?service=git-receive-pack, POST /<owner>/<repo>[.git]/git-receive-pack write (push) repository is in write_repositories (github_write_repo_required)
POST /<owner>/<repo>[.git]/info/lfs/objects/batch body-inspected: LFS download is a read (always allowed); upload is always denied (github_lfs_push_unsupported) — the follow-up object uploads go to signed URLs whose opaque paths cannot be repo-checked, and the signed-URL domains are deliberately GET/HEAD-only — so a push with new LFS objects fails at the batch step with a crisp reason instead of mid-transfer; anything else fails closed (github_lfs_operation_unresolved) download always
Any other POST (web-form mutation) write denied (github_write_repo_required) — the API is the only mutation surface

Smart-HTTP git-upload-pack is a read even though its data leg uses POST (it only sends want/have negotiation and receives objects). git-receive-pack is always write.

api.github.com decisions:

Request Class Allowed when
GET/HEAD any path (/repos/..., /search/..., /orgs/..., /user, /rate_limit, ...) read always (integration enabled)
POST /graphql — always denied (github_graphql_denied)
POST/PUT/PATCH/DELETE /repos/<owner>/<repo>/... write repository is in write_repositories (github_write_repo_required)
POST /repos/<owner>/<repo>/actions/workflows/<workflow>/dispatches workflow execution repository is in write_repositories; no separate workflow-dispatch toggle is required
PUT /repos/<owner>/<repo>/pulls/<number>/merge pull-request merge (including merge_method values merge and squash; GitHub also supports rebase) repository is in write_repositories; this route may land .github/ changes without Kern's local push-approval queue
write methods on /repos/<owner>/<repo> exactly (the repo resource: PATCH changes settings including private→public, DELETE removes it), on {forks,generate,transfer} (escape the repository — fork into the caller's account, template to a new repo, transfer ownership), and on administration sub-resources: collaborators, invitations, keys, hooks, pages, environments, codespaces, dependabot, rulesets, properties (custom property values can steer which organization rulesets apply), interaction-limits, releases, immutable-releases, autolinks, topics, lfs (the repository LFS enable/disable toggle), vulnerability-alerts, automated-security-fixes, private-vulnerability-reporting, code-scanning, secret-scanning, dependency-graph, security-advisories, bypass-requests (approving a push-protection bypass approves the agent's own path around a security gate), actions/{secrets,variables,runners,permissions,oidc,cache,caches}, actions/workflows/*/{enable,disable}, repository-level dispatches, statuses, check-runs, check-suites, deployments, attestations (forge supply-chain provenance downstream verifiers trust), actions/runs/*/{cancel,force-cancel,approve,pending_deployments,deployment_protection_rule}, DELETE actions/runs/…, actions/artifacts/…, branches/*/protection…, tags/protection…, pulls/*/update-branch (writes the PR's head branch, which may live in an unlisted fork) — always denied, even for a write_repositories entry, under one unified reason (github_repo_admin_write_denied): these change who or what can reach the repository (access grants, deploy keys, webhooks), mint credentials, publish to the web, weaken branch/tag protections (classic protection, rulesets, and the custom properties that select rulesets), turn off security features, erase automation evidence (run and artifact deletion), or forge/stop automation signals (commit statuses, check runs, deployments, run cancellation) that humans and external systems act on — not repository content. Reads of all of them stay plain reads.
when require_dot_github_approval is true: write methods on contents/.github..., git/{refs,trees,commits}, merges, and merge-upstream content write with possible .github effect denied (github_dot_github_rest_write_denied) unless it goes through the git push approval queue
write methods that target no repository at all — POST /user/repos (create a repo), POST /gists (create a gist, a fresh egress surface), starring, org-level changes — denied (github_write_repo_required): the write is not one of the configured repositories

GraphQL is denied entirely: a POST /graphql can mutate, and repository references inside a GraphQL body cannot be verified with path rules — anything short of a real GraphQL parser can be evaded (argument order, aliased variables, fragments). gh commands that use GraphQL fail with a clear denial reason; their REST equivalents (gh api repos/..., plain git) keep working. A future GraphQL parser can lift this.

Other GitHub domain decisions:

Domain Flow and path shape Class Allowed when Notes
uploads.github.com Release-asset uploads (gh release upload, REST Upload a release asset) under /repos/<owner>/<repo>/... write repository is in write_repositories Decided by the same /repos/<owner>/<repo> write rule as api.github.com. Upload bodies use the normal proxy path, which buffers each request body and rejects bodies over the host-sized inspection cap (at most 1 GiB); very large release assets are not supported until the proxy has a streaming path for guard-clean hosts.
codeload.github.com Archive downloads such as /<owner>/<repo>/tar.gz/<ref> read always (integration enabled) Serves only GET/HEAD, so every request is an allowed read of any repository.
raw.githubusercontent.com Raw file reads such as /<owner>/<repo>/<ref>/<path> read always (integration enabled) Serves only GET/HEAD, so every request is an allowed read of any repository.
objects.githubusercontent.com Git object downloads through short-lived signed URLs whose paths are opaque read request method is GET or HEAD No repo guard is possible because the signed URL path has no owner/repo shape. Writes are never allowed.
release-assets.githubusercontent.com Release-asset downloads through short-lived signed URLs whose paths are opaque read request method is GET or HEAD No repo guard is possible because the signed URL path has no owner/repo shape. Writes are never allowed.
github-cloud.githubusercontent.com Git LFS object downloads: an allowed LFS download batch returns follow-up GET hrefs on this host read request method is GET or HEAD Same signed-URL shape: opaque paths, no repo guard possible, writes never allowed, Authorization strip-only.

Every GitHub write denial carries a specific reason in network events — github_write_repo_required, github_repo_admin_write_denied, github_graphql_denied, github_dot_github_rest_write_denied, github_lfs_push_unsupported, github_lfs_operation_unresolved — so an operator can see exactly which rule fired and which repository would need to be added to write_repositories. One more reason exists as a fail-closed default: github_repo_scope_required fires if the GitHub guard receives a host for which it has no access rules. It is unreachable with today's fixed dispatch table; it exists so a future wiring mistake denies instead of allowing.

Direct main push block

Before .github inspection, the proxy parses the receive-pack command list. When block_direct_main_pushes is enabled and any command updates refs/heads/main, the proxy returns a Git-native report-status rejection for the whole transaction with reason github_main_push_denied. The request body is not forwarded or indexed, and no approval item is created. A malformed command list fails closed with github_main_push_guard_unavailable. This control applies only to smart-HTTP Git pushes: pushing a feature branch and merging it with the pull-request API remains allowed for configured write repositories.

The .github approval gate

When require_dot_github_approval is set, a git push to a write repository that passes the write guard is inspected before it is forwarded. The proxy hands the buffered git-receive-pack body to the push-gate engine (host/network_integrations/github/push_gate/), which resolves the thin pack against a per-repo quarantine mirror (a bare clone under the proxy's state directory, fetched with the working token) and uses real git (index-pack + diff-tree) to list the changed paths:

  • No .github/ change — the original body is forwarded upstream unchanged. Clean pushes are transparent.
  • .github/ touched — the pushed objects are retained under refs/pending/<id> in the quarantine, a pending_pushes row is written, and the agent's push is answered with a synthesized git report-status that rejects each ref with "queued for approval as push-" (network event reason github_push_queued_for_approval). The push fails cleanly; nothing reaches GitHub.

At most ten pushes may await a decision. The proxy checks that global count before index-pack, so together with the 128 MiB gated-push limit the live pending payload is bounded. When the queue is full, gated pushes fail with github_push_queue_full until the operator approves or rejects one. There is no expiry or automatic eviction.

The operator lists, approves, or rejects held pushes through the admin API (/v1/network-tools/github-pending-pushes; see AdminAPI.md). Approve replays the quarantined objects to GitHub with the working token via the approve-github-push root helper (the admin service has no egress); reject drops the pending refs. Both decisions immediately run git gc while pack indexing is locked out, reclaiming objects that are no longer held. A replay failure marks the row failed with detail; the recovery is a fresh agent push. Only pkt-line command framing is parsed in the proxy; pack objects are only ever read by git, and any framing, mirror, or git failure fails closed (the push is denied with github_push_gate_unavailable, never forwarded un-inspected). The implementation note is in ../architecture/github-write-path-controls.md.

GitHub Credential

There is one fixed GitHub credential, managed through PUT /v1/network-tools/github-credential (see AdminAPI.md); it is separate from the write-repository list and authenticates both reads and writes. Two modes:

Mode Operator provides Behavior
pat A GitHub fine-grained personal access token. Its scope bounds which private repositories the agent can read and which it can write. The pasted token is installed as-is.
app A GitHub App id, installation id, and the App's PEM private key. The host mints short-lived, installation-wide tokens and refreshes them before their one-hour expiry. Which repositories the token can reach is bounded by where the App is installed (operator-managed on GitHub).

Secrets are write-only in both modes: the token and the private key are never echoed by the UI or returned by any API, and they are encrypted at rest in the admin database (see ../architecture/admin-state-storage.md). Reads return only metadata (configured, mode, app/installation ids, current app-token expiry, last update time, validation status).

Enablement and credential health are separate concerns: the policy decides whether GitHub domains are reachable, the credential decides what token the proxy injects, and the credential's validation status reports only its own health. Any credential failure fails closed: the error is recorded in validation, the working token is withdrawn, and the host retries every poller cycle until it converges. A policy publish never fails on credential problems; until the credential converges, GitHub requests simply run unauthenticated (public reads work, private access fails at GitHub).

The agent never holds the token. The network proxy authenticates GitHub requests itself: whatever Authorization the agent sends on GitHub domains is stripped, and the active working token is injected after the repository guard has passed (never on the signed-URL domains, where an Authorization header breaks the presigned download). There is nothing on the agent side to copy or exfiltrate, a token smuggled in through a prompt cannot substitute another identity, and revocation is instant — disabling the integration or clearing the credential stops injection from the very next request. The agent's git and gh (both preinstalled) work with no login and no configuration; without a credential, public repository reads still work. The wiring is described in ../architecture/network-controls.md.

The credential can be stored (or deleted) whether or not the integration is enabled — staging the credential first and then enabling the policy is the order that never leaves the proxy allowing writes with no working token.

Repository audit and warnings

Each configured write repository is audited with the working token (a root helper makes the GitHub API calls; the admin service has no egress). Reads are universal, so only write repositories are audited: the warnings are all about what the agent's pushes and PRs expose, which only write targets can. Facts are stored in an admin-owned table; warning derivation lives in code, so message changes need no re-audit. Warnings surface in the credential API response and as banners in the admin UI.

Fact Source Warning when
Pages visibility GET /repos/{o}/{r} → has_pages (authoritative only when false), then, unless Pages is known disabled, GET /repos/{o}/{r}/pages → public; a 403/404 on the Pages read leaves the visibility unknown instead of failing the audit, because GitHub answers 404 for missing Pages permission too Public Pages site on a private repo: a push to the Pages source publishes agent-written content to the internet — the same exfiltration sink as a public write repository. Unknown Pages visibility on a private repo: warning severity, because the audit could not verify whether Pages is a public leak vector.
Visibility GET /repos/{o}/{r} → private/visibility Public write repo: everything the agent pushes here (branches, commit messages, PRs and descriptions) is world-visible, and because reads are universal an injected agent can copy any private repo the token reaches into a commit, issue, or PR here — a public write target is an exfiltration sink. Highest severity when the token can reach private repositories.
Token permissions + default-branch protection GET /repos/{o}/{r} → permissions; GET /repos/{o}/{r}/branches/{default} → protected push present and the default branch unprotected (warning severity): the agent identity can push straight to the default branch. Recommend a ruleset/branch protection so the agent only opens PRs and a human merges.
Workflows and their triggers GET /repos/{o}/{r}/contents/.github/workflows, then a plain substring search of each file for the dangerous trigger names (false positives over-warn, which is fine) Any workflow: an agent push or PR can execute agent-written code with whatever secrets and network that repo grants. pull_request_target adds a warning to review the workflow carefully and ensure it does not run untrusted pull request code with base-repository privileges.

Audits warn, never gate: they tell the operator which server-side protections (rulesets, branch protection, workflow restrictions) to add on GitHub, which remain the stronger controls because they sit outside the agent's reach. A re-audit runs on credential set, on a policy publish that changes the GitHub integration, on a UI re-check, and on a slow daily poll — always with the same published working token every GitHub request uses. A failed or missing audit surfaces as a warning and retries on the next poll, and having no working token while the policy lists write repositories is itself recorded as a warning on every listed repository — the audit reports what this credential can do, so it never keeps reporting facts computed for a credential that no longer works.

The proxy is the write-enforcement boundary, whatever the credential itself would permit: an over-scoped token cannot push to or mutate a repository that is not in write_repositories, and cannot perform repository administration anywhere. This is why minted app tokens are deliberately not re-scoped to the write list — narrowing the credential bought little on top of the proxy guard. Every policy publish that changes the GitHub integration (enablement or the write-repository list, in either direction) does mint a fresh app token, though: an installation token covers exactly the repositories granted at mint time, so it must postdate the list it serves — one rule, no widening bookkeeping. Publishes that leave the GitHub integration untouched keep the healthy published token.

Python Packages Integration

When network_integrations.python_packages.enabled is true, its integration directly enforces:

{
  "pypi.org": {
    "allow_http_methods": ["GET", "HEAD"],
    "path_guards": ["^/simple(?:/.*)?$", "^/pypi/[^/]+(?:/[^/]+)?/json$"]
  },
  "files.pythonhosted.org": {
    "allow_http_methods": ["GET", "HEAD"],
    "path_guards": ["^/packages(?:/.*)?$"]
  }
}

Only GET and HEAD are allowed, so the integration is read-only by construction; package publishing is not part of it. JSON metadata supports /pypi/{project}/json and /pypi/{project}/{version}/json; the latter is used by pip-audit to retrieve release-specific advisories. No query string is allowed on these JSON routes. PyPI metadata URL values take the parameter guard. Distribution-file paths on files.pythonhosted.org remain exempt because they are returned by PyPI. Request headers are not inspected: credential headers are removed, User-Agent is replaced with a fixed host value, and the rest are forwarded as sent.

Version strings receive the same parameter checks as other metadata URL values. There are no version-specific exemptions: unusual releases containing long identifier-like numbers (including timestamps) may be denied.

NPM Packages Integration

When network_integrations.npm_packages.enabled is true, its integration enforces the following read routes, plus the narrowly guarded bulk-advisory POST described below:

{
  "registry.npmjs.org": {
    "allow_http_methods": ["GET", "HEAD"]
  },
  "nodejs.org": {
    "allow_http_methods": ["GET", "HEAD"],
    "path_guards": ["^/dist(?:/.*)?$"]
  }
}

POST is additionally allowed only to the exact https://registry.npmjs.org/-/npm/v1/security/advisories/bulk path, without query parameters. It requires application/json and a map of package names to nonempty arrays of bounded version strings. Plain JSON and npm gzip are accepted, with a 1 MiB compressed/decompressed limit. Duplicate keys, invalid shapes, optional gzip metadata, trailing members and other content encodings are rejected. Package names retain the parameter guard and its existing exact public-package exceptions; legacy names use the same guard length limit as metadata reads. Version values retain secret, personal-data and encoded-token checks, except valid YYYYMMDDhhmmss components in numeric version strings may pass the personal-identifier heuristic. Arbitrary numeric suffixes and opaque strings remain guarded. Publishing, login, quick-audit and every other POST route remain denied.

npm metadata and Node.js distribution URL values take the parameter guard. npm tarball paths under /-/ remain exempt because they are provider-returned. The exact public package metadata path /token-types skips path scanning because its name is a credential-language false positive, while its query values remain guarded. Request headers are not inspected: credential headers are removed, User-Agent is replaced with a fixed host value, and the rest are forwarded as sent.

Domain Rule

Each value in network_integrations.custom.domains is a domain rule.

Domain keys must be exact DNS names such as api.example.com or wildcard DNS names such as *.example.com. A wildcard must be the first character and must be followed by ., then a concrete DNS suffix. It matches any non-empty prefix before that suffix, including dots, so *.example.com matches api.example.com and a.b.example.com, but not example.com. If both the apex domain and its subdomains are needed, configure both example.com and *.example.com.

Domain keys are normalized to lowercase. Wildcard domain rules must not overlap: for example, *.example.com and *.api.example.com cannot both be configured, because x.api.example.com would match both. Exact domain rules may coexist with wildcards and override them for that exact hostname.

Prefer exact domains over wildcards. A wildcard lets the agent have the host resolve any subdomain it chooses (for example <data>.example.com), which leaks that label to the domain's DNS as a low-bandwidth side channel. Only use a wildcard for a domain whose nameservers you trust not to be an exfiltration sink.

{
  "allow_http_methods": ["GET", "HEAD"],
  "path_guards": ["^/dist(?:/.*)?$"],
  "allow_websocket": false,
  "guard_request_content": false
}
Field Required Type Behavior
allow_http_methods Yes enum array HTTP methods allowed for proxied requests to this domain. Valid values are GET, HEAD, POST, PUT, PATCH, and DELETE. An empty array keeps HTTP/HTTPS closed for this domain.
path_guards No string array Python re regular expressions for allowed request targets, evaluated with re.fullmatch against the path plus query string when present. If omitted, paths are not restricted beyond the domain and method rule.
guard_request_content No boolean Defaults to false. Applies the standard parameter guard without identifier, machine-token, or longer-text exceptions to the hostname, URL, all headers, and supported bodies. May reject credentials. Blocks WebSockets while enabled, even if allow_websocket is true. See content inspection below.
allow_websocket No boolean Defaults to false. When true and guard_request_content is false, permits a WebSocket after the handshake method/path passes this rule and the upstream returns a final 101. The proxy validates and bounds the client frame stream, but applies no provider-specific rule to message contents; enable this only for a destination the operator trusts with a long-lived bidirectional channel.

WebSockets are not inferred from ordinary HTTP access. On a custom domain, allow_websocket: true and guard_request_content: false are required in addition to GET and any matching path_guards. The option is intentionally explicit because custom-domain frames are opaque after the verified 101; each frame is not a separate HTTP request. Managed integrations are HTTP-only except OpenAI's guarded API and ChatGPT hosts, where each client-to-upstream message is inspected with the same external-URL/tool guard as HTTP request bodies. A failed upgrade returns the fixed websocket_upgrade_declined proxy error rather than entering a second general-purpose HTTP response path.

Path guards use Python re syntax and must match the full request target path. For example, ^/dist(?:/.*)?$ allows /dist and /dist/index.js. If query strings are allowed, include them in the regex, such as ^/simple(?:/.*)?(?:\?.*)?$.

Custom-domain requests must match the configured domain, method, and path. With guard_request_content: true, the guard checks URLs (including hostnames), all headers, and text, JSON, or form bodies. The URL, combined headers, and body each have a 1,024-byte limit. Unsupported bodies and WebSocket connections are blocked. Requests are either allowed unchanged or rejected.

This does not guarantee prevention of all data leakage and may hamper normal use. Use a managed integration where one exists.

For Codex, the host also restricts the agent runtime to cached web search, so the OpenAI proxy guard is the second layer rather than the only one.