docs(readme): add Network behavior section documenting every endpoint#270
Open
veetihietasalo wants to merge 1 commit intosuperagent-ai:mainfrom
Open
docs(readme): add Network behavior section documenting every endpoint#270veetihietasalo wants to merge 1 commit intosuperagent-ai:mainfrom
veetihietasalo wants to merge 1 commit intosuperagent-ai:mainfrom
Conversation
Document which hosts Grok connects to, when, and why. Useful for network-restricted environments, compliance reviews, and users who see unexpected endpoints in packet captures or allowlist audits. Covers: - Always-on: api.x.ai (provider), api.github.com (updates) - Feature-gated: Telegram, payments/brin, AI Gateway, Coinbase AgentKit (wallet + Solidity tooling), IPFS/Arweave (generated media), sigstore - Explicitly notes that brin.sh is scoped to the x402 payments feature (not general URL scanning) and sees only the domain being checked - Affirms no analytics/telemetry in default config Traces every host back to the specific source file or dependency that invokes it so maintainers can update this table mechanically as deps change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
brin-security-scanner
Bot
added
the
contributor:verified
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “Network behavior” section to the README to document Grok CLI’s outbound network surface area for compliance/restricted-network use cases.
Changes:
- Introduces an “Always on” table of core endpoints (provider + update checks).
- Introduces a “Feature-gated” table mapping optional features to additional endpoints.
- Adds guidance on what data is (and is not) sent, plus a minimal allowlist suggestion.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `mainnet.base.org`, `basescan.org`, `api.basescan.org`, `sepolia.base.org` | Coinbase AgentKit tools — Ethereum/Base wallet operations. Only reached when the agent invokes wallet/on-chain functions. | `@coinbase/agentkit` | | ||
| | `abitype.dev`, `openchain.xyz`, `4byte.sourcify.dev`, `docs.soliditylang.org` | Solidity ABI lookups and contract decoding (Coinbase AgentKit). Only reached when decoding on-chain data. | `@coinbase/agentkit` | | ||
| | `ipfs.io`, `arweave.net` | Decentralized storage for generated media (images, videos) via the built-in `generate_image` / `generate_video` tools | agent tools | | ||
| | `fulcio.sigstore.dev` | Sigstore verification for signed release artifacts | `@npmcli/arborist` | |
| | `abitype.dev`, `openchain.xyz`, `4byte.sourcify.dev`, `docs.soliditylang.org` | Solidity ABI lookups and contract decoding (Coinbase AgentKit). Only reached when decoding on-chain data. | `@coinbase/agentkit` | | ||
| | `ipfs.io`, `arweave.net` | Decentralized storage for generated media (images, videos) via the built-in `generate_image` / `generate_video` tools | agent tools | | ||
| | `fulcio.sigstore.dev` | Sigstore verification for signed release artifacts | `@npmcli/arborist` | | ||
| | `api.github.com/repos/*`, `raw.githubusercontent.com` | Skill installs, release artifact downloads, MCP server fetches | `@modelcontextprotocol/sdk` and skill subsystem | |
| | Host | Purpose | Source | | ||
| | --- | --- | --- | | ||
| | `api.x.ai` | xAI Grok API — the model provider. This is where your prompts and model responses travel. | `src/grok/client.ts` | | ||
| | `api.github.com` | Version resolution for `grok update` and release-manifest checks. | `src/utils/install-manager.ts` | |
Comment on lines
+429
to
+435
| If you operate behind an allowlist, the minimum viable set is: | ||
|
|
||
| - `api.x.ai` (provider) | ||
| - `api.github.com` (if `grok update` is used) | ||
|
|
||
| Everything else is feature-gated — only allowlist the hosts above that correspond to features you actually use. The [Sandbox](#sandbox) mode additionally restricts outbound connections at the microVM level (see `--allow-host` and `--allow-net` flags). | ||
|
|
|
|
||
| ## Network behavior | ||
|
|
||
| Grok connects to a small, well-defined set of HTTPS endpoints. This section documents what hits the network and when, so you know what to expect — especially useful for network-restricted environments, compliance reviews, or running Grok in sensitive repos. |
| | `ai-gateway.vercel.sh`, `ai-sdk.dev` | AI Gateway routing when configured as an alternative to direct xAI access | `@ai-sdk/*` dependencies | | ||
| | `mainnet.base.org`, `basescan.org`, `api.basescan.org`, `sepolia.base.org` | Coinbase AgentKit tools — Ethereum/Base wallet operations. Only reached when the agent invokes wallet/on-chain functions. | `@coinbase/agentkit` | | ||
| | `abitype.dev`, `openchain.xyz`, `4byte.sourcify.dev`, `docs.soliditylang.org` | Solidity ABI lookups and contract decoding (Coinbase AgentKit). Only reached when decoding on-chain data. | `@coinbase/agentkit` | | ||
| | `ipfs.io`, `arweave.net` | Decentralized storage for generated media (images, videos) via the built-in `generate_image` / `generate_video` tools | agent tools | |
Contributor
|
@veetihietasalo this is good but makes the README a bit bloated. Mind making a much more condensed version of this? |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a "Network behavior" section to the README that documents every host Grok connects to, when, and why.
Why
While evaluating Grok CLI I ran
stringson the compiled binary to understand its network surface before wiring it into sensitive workflows. I was initially surprised to see Coinbase AgentKit hosts (basescan.org,mainnet.base.org), the brin.sh endpoint, and several blockchain-tooling domains (abitype.dev,openchain.xyz,4byte.sourcify.dev). All of them turned out to be legitimate — but tracing each one back to its triggering code path took time that would be better spent once, in docs.This PR captures that research so the next curious user (or compliance reviewer) doesn't have to redo it.
Structure
Two tables, grouped by trigger:
api.x.ai(provider),api.github.com(updates)Each row traces back to a source file or dependency so the table can be mechanically updated as code evolves.
Notable specifics
api.brin.shis explained correctly: it's scoped to the x402 payments feature and only sees the target domain of a payment operation — not prompts, not code. First-party threat-detection from the same team. Having this documented upfront preempts "why is this binary calling an unknown endpoint" concerns.@coinbase/agentkitso users understand they're dormant unless wallet/on-chain tools are invoked.Non-goals
GROK_DISABLE_BRIN=1, that's a separate PR I'm happy to send.Test plan
stringsof the binary + source grep; bundled deps may reach additional hosts I didn't catch)Note
Low Risk
Low risk because this PR only updates documentation and does not change runtime behavior. The main risk is documentation drift or inaccurate endpoint listings that could mislead compliance/network-allowlist setups.
Overview
Adds a new
Network behaviorsection toREADME.mdthat documents which HTTPS hosts Grok may contact, split into always-on vs feature-gated traffic, with pointers to the triggering codepaths/dependencies.Also clarifies what is not sent (no default telemetry; prompts/code stay within the model provider channel) and provides guidance for network-restricted/allowlist environments, including the minimum required hosts and how sandbox flags further constrain egress.
Reviewed by Cursor Bugbot for commit 7943680. Bugbot is set up for automated code reviews on this repo. Configure here.