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.
- Reserved Managed Domains
- OpenAI Integration
- Claude Integration
- xAI Integration
- AWS Bedrock Integration
- GitHub Integration
- Python Packages Integration
- NPM Packages Integration
- Domain Rule
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.
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.
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.
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.
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 pinnedcli-chat-proxy.grok.comrequest 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 requiresaction: "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 onapi.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: atoolsentry, and asearch_parametersobject that is not an explicitmode: "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.
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.
{
"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.
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.
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.
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 underrefs/pending/<id>in the quarantine, apending_pushesrow is written, and the agent's push is answered with a synthesized gitreport-statusthat rejects each ref with "queued for approval as push-" (network event reasongithub_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.
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.
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.
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.
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.
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.