fix: mitigate antivirus false positive detections on generated JSON f…

[theshloksschauhan]

Summary

This PR resolves the issue of antivirus software flagging Gemini CLI error reports as malicious. It does this by moving the error reports out of the system's temporary directory (os.tmpdir()) and into a dedicated project directory (~/.gemini/tmp/<hash>/error-reports/), and by adding a _meta provenance header to the generated JSON files.

Details

Writing structured JSON to the system temporary directory is a common heuristic trigger for antivirus software. By relocating these files and adding clear metadata, we significantly reduce the likelihood of false positive detections. Troubleshooting documentation has also been added to assist users.

Reviewer Note: I have consolidated the error report directory path construction as requested by gemini-code-assist[bot] in the latest commit.

Related Issues

Fixes #15404
Related: #1907

How to Validate

1. Run a command using the Gemini CLI that intentionally generates an error report.
2. Verify that the error report is created in ~/.gemini/tmp/<hash>/error-reports/ instead of the system's temporary directory.
3. Open the generated JSON error report and verify the presence of the _meta provenance header.
4. Run npm test to ensure directory creation and _meta tests pass.
5. (Optional) Run via npx ./gemini-cli-<version>.tgz or inside a Docker container to verify home directory resolution (~/) works in isolated environments.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

Note: I manually validated on Windows and Docker/Linux. I am relying on the CI test matrix for native MacOS/Seatbelt validation.

[gemini-code-assist]

Summary of Changes

Hello @theshloksschauhan, 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 addresses the issue of antivirus software incorrectly flagging legitimate Gemini CLI error report JSON files as malware. It implements a two-pronged approach: enhancing the error reports themselves with a provenance header and relocating them to a less suspicious directory, and providing users with clear troubleshooting documentation to manage false positives. These changes aim to improve the user experience by preventing unnecessary security alerts and offering actionable solutions.

Highlights

• Antivirus False Positive Mitigation: Implemented a _meta provenance header in error report JSON files to help antivirus software identify them as legitimate Gemini CLI artifacts.
• Error Report Relocation: Changed the storage location for error reports from the system's temporary directory (os.tmpdir()) to a project-specific path (~/.gemini/tmp/<hash>/error-reports/) to reduce false positive detections.
• Directory Auto-Creation: Added logic to automatically create the designated error report directories before writing files.
• Troubleshooting Documentation: Introduced new troubleshooting documentation that provides guidance on antivirus exclusions and links for reporting false positives to various vendors.
• Test Enhancements: Expanded unit tests to verify the correct inclusion and ordering of the _meta field in error reports, as well as the functionality for creating necessary directories.

Changelog

• docs/troubleshooting.md
  • Added new documentation detailing how to resolve antivirus false positive detections, including exclusion instructions and vendor submission links.
• packages/core/src/agents/local-executor.ts
  • Updated the reportError call to pass a dynamically determined error report directory, prioritizing the project's temporary directory over the system's default.
• packages/core/src/core/baseLlmClient.ts
  • Modified reportError calls to include a specified error report directory, ensuring reports are saved in the project's designated temporary location.
• packages/core/src/core/client.ts
  • Updated reportError calls and the Turn constructor to accept and utilize a specific error report directory, moving away from system-wide temporary directories.
• packages/core/src/core/turn.test.ts
  • Adjusted the reportError expectation in tests to account for the newly added errorReportDir argument.
• packages/core/src/core/turn.ts
  • Modified the Turn class constructor to accept an optional errorReportDir and updated internal reportError calls to use this new directory.
• packages/core/src/utils/errorReporting.test.ts
  • Added new test cases to verify the presence and correct ordering of the _meta field in generated error reports.
  • Confirmed that the reporting directory is automatically created if it doesn't exist.
• packages/core/src/utils/errorReporting.ts
  • Introduced an _meta field to the ErrorReportData interface and implemented its inclusion in all generated error reports, providing provenance information.
  • Added logic to automatically create the specified reporting directory using fs.mkdir with recursive: true, falling back to os.tmpdir() if directory creation fails.

Activity

• The pull request was created to address antivirus false positive detections.
• New documentation was added to guide users on resolving these issues.
• Core logic for error reporting was updated to include provenance metadata and use a project-specific temporary directory.
• Tests were expanded to cover the new error reporting behavior and directory management.

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. ↩

[gemini-code-assist]

Code Review

This pull request effectively mitigates the issue of antivirus false positives by relocating error report files and adding a _meta provenance header. The changes are well-implemented across the affected files, and the addition of troubleshooting documentation is a great touch. I've identified a couple of opportunities to reduce code duplication that was introduced, which would improve the maintainability of the code.

[theshloksschauhan]

Hi maintainers, this PR has been rebased onto latest main and merge conflicts were resolved.

cla/google is now passing, but docs-pr-check (gemini-cli-extensions) is still queued for this fork PR.

Could a maintainer please approve/run the pending fork workflow and, if everything looks good, provide at least one human approval review?

cc @gundermanc @bdmorgan @abhipatel12 @scidomino