feat(security): implement robust IP validation and safeFetch foundation

[alisa-alisa]

Summary

This PR establishes the security foundation for safe remote agent communication by implementing robust IP address validation and a connection-level SSRF protection layer. It is a prerequisite for enabling gRPC and remote agent discovery.

Details

• Robust IP Address Validation: Replaces fragile regex-based IP range checks with the ipaddr.js library. This ensures reliable SSRF protection by correctly handling various IP notations (IPv4, IPv6, and IPv4-mapped IPv6) and matching them against standardized CIDR ranges.
• SafeFetch Implementation: Introduces a standard-compliant safeFetch utility that mirrors the native fetch API but enforces connection-level IP filtering and DNS rebinding protection using a custom DNS lookup implementation (safeLookup).
• Standardized Error Mapping: Introduced a PrivateIpError class and a centralized handleFetchError helper. This ensures that security-related connection blocks are consistently mapped to a descriptive FetchError with a dedicated ERR_PRIVATE_NETWORK code across the entire codebase.
• Automated SSRF Enforcement: Added a global ESLint rule (no-restricted-syntax) that restricts the use of the global fetch() function. This guides contributors toward using safeFetch() for all new network logic, ensuring the security layer cannot be easily bypassed. Existing calls have been annotated for future migration.
• Benchmark Range Protection: Explicitly blocks the IANA benchmark testing range (198.18.0.0/15) which is often incorrectly classified as public unicast by networking libraries.

Why this is needed

To safely support remote agents, the CLI must ensure that it cannot be used as a proxy to probe internal networks or access sensitive metadata services (like AWS/GCP metadata endpoints). This PR provides the "secure pipe" that all subsequent A2A features will use.

Related Issues

Related to issue #18642.

[gemini-cli]

Hi @alisa-alisa, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[alisa-alisa]

It is part of a split PR: #21348

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes a critical security foundation for safe remote agent communication within the CLI. It introduces robust IP address validation and a connection-level SSRF protection layer, which are essential prerequisites for enabling future features like gRPC and remote agent discovery. The changes ensure the CLI cannot be exploited to probe internal networks or access sensitive metadata services, providing a secure communication pipe for all subsequent agent-to-agent functionalities.

Highlights

• Robust IP Validation: Replaced regex-based IP range checks with the ipaddr.js library for more reliable and comprehensive Server-Side Request Forgery (SSRF) protection, handling various IP notations (IPv4, IPv6, IPv4-mapped IPv6) and standardized CIDR ranges.
• SafeFetch Implementation: Introduced a new safeFetch utility that mirrors the native fetch API but enforces connection-level IP filtering and DNS rebinding protection through a custom DNS lookup (safeLookup).
• Benchmark Range Protection: Explicitly blocks the IANA benchmark testing range (198.18.0.0/15) to prevent its incorrect classification as public unicast, enhancing security.

Changelog

• docs/cli/tutorials/shell-commands.md
  • Updated the explanation of how shell command output is handled, clarifying that the AI does not automatically 'see' this output unless explicitly provided.
• package-lock.json
  • Updated @a2a-js/sdk from 0.3.8 to 0.3.10.
  • Added @bufbuild/protobuf (2.11.0) and @grpc/grpc-js (1.14.3) as optional peer dependencies for @a2a-js/sdk.
  • Added ipaddr.js (1.9.1) as a direct dependency.
  • Updated @grpc/grpc-js from 1.13.4 to 1.14.3 and its nested @grpc/proto-loader dependency.
• packages/core/package.json
  • Updated @a2a-js/sdk from ^0.3.8 to ^0.3.10.
  • Added @bufbuild/protobuf (^2.11.0) and @grpc/grpc-js (^1.14.3) as dependencies.
  • Added ipaddr.js (^1.9.1) as a dependency.
• packages/core/src/utils/fetch.test.ts
  • Added a new test file with comprehensive unit tests for isAddressPrivate, isPrivateIp, isPrivateIpAsync, safeLookup, and safeFetch utilities.
  • Included tests covering various private, reserved, loopback, and public IPv4/IPv6 addresses, IPv4-mapped IPv6, and the IANA benchmark range for IP validation.
  • Validated filtering of private IPs during DNS resolution and proper handling of localhost in safeLookup.
  • Verified safeFetch dispatcher integration and error re-mapping for private network access.
• packages/core/src/utils/fetch.ts
  • Imported node:dns, node:dns/promises, and ipaddr.js for network and IP address handling.
  • Removed the previous regex-based PRIVATE_IP_RANGES for IP validation.
  • Defined NodeFetchInit interface to extend RequestInit with dispatcher support.
  • Introduced sanitizeHostname and isLoopbackHost helper functions.
  • Implemented safeLookup, a custom DNS lookup function for undici agents, which filters out private IP addresses and throws an error if only private IPs are resolved.
  • Created safeDispatcher, an undici Agent configured with safeLookup for connection-level SSRF protection.
  • Updated isPrivateIp to leverage the new isAddressPrivate function.
  • Added isPrivateIpAsync to perform asynchronous private IP checks, including DNS resolution to prevent DNS rebinding attacks.
  • Developed isAddressPrivate using ipaddr.js to robustly identify private, reserved, and special-use IP ranges (including the IANA benchmark range 198.18.0.0/15) for both IPv4 and IPv6, and IPv4-mapped IPv6 addresses.
  • Introduced safeFetch, a wrapper around global.fetch that automatically applies the safeDispatcher for SSRF protection and re-maps private network access errors.
  • Added createSafeProxyAgent to create undici ProxyAgent instances with safeLookup.
  • Modified fetchWithTimeout to utilize the safeDispatcher and to catch and re-throw ERR_PRIVATE_NETWORK errors.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +89.2 kB (+0.34%)

Total Size: 26.1 MB

Filename	Size	Change
./bundle/gemini.js	25.6 MB	+89.2 kB (+0.35%)

ℹ️ View Unchanged

Filename	Size
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	221 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	227 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	11.5 kB
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B
./bundle/sandbox-macos-permissive-open.sb	890 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB
./bundle/sandbox-macos-strict-open.sb	4.82 kB
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces robust Server-Side Request Forgery (SSRF) protection to the application's fetch operations by integrating the ipaddr.js library for accurate identification of private and reserved IP ranges, replacing a previous regex-based approach. A custom DNS lookup function (safeLookup) is implemented for undici agents, which filters out private IP addresses during DNS resolution and prevents connections to them, while explicitly allowing localhost requests. A new safeFetch function is provided that automatically uses this SSRF-protected dispatcher, and fetchWithTimeout is updated to leverage this protection, including re-mapping connection errors to a specific ERR_PRIVATE_NETWORK code. An asynchronous function isPrivateIpAsync was also added for more comprehensive private IP checks via DNS resolution. Comprehensive unit tests for these new utilities have been added. Additionally, the documentation for shell commands (docs/cli/tutorials/shell-commands.md) was updated to clarify that the AI model does not automatically 'see' the output of these commands unless explicitly provided. Finally, several dependencies, including @a2a-js/sdk, @grpc/grpc-js, and @bufbuild/protobuf, were updated or added in package-lock.json and packages/core/package.json.

[gundermanc]

Looks fine to me but I don't have much context on this item. Gal might be a good point of contact.