Gemini CLI Security Extension

When handling file system access, avoid direct concatenation or simple joining of user input with a base directory. Use the 'Resolve + Prefix Check' pattern instead.

Vulnerable Pattern (Do Not Use): Using path.join() with user input allows attackers to use ../ sequences to escape the intended directory.

Secure Pattern:

1. Resolve the safeRoot to an absolute path.
2. Resolve the targetPath using the safeRoot and userInput.
3. Use .startsWith() to ensure targetPath is contained within safeRoot (including the path separator).

### Vulnerable (Do Not Use)
```typescript
// VULNERABLE: Direct concatenation allows inputs like "../../etc/passwd"
const targetPath = path.join('/var/www/uploads', userInput);
return fs.readFile(targetPath, 'utf-8');

Secure

// SECURE: Resolve + Prefix Check
const safeRoot = path.resolve('/var/www/uploads');
const targetPath = path.resolve(safeRoot, userInput);

if (!targetPath.startsWith(safeRoot + path.sep)) {
  throw new Error('Path traversal detected');
}
return fs.readFile(targetPath, 'utf-8');

The extension scans for several categories of security risks:

Secrets Management

• Hardcoded secrets: API keys, private keys, passwords, connection strings, and symmetric encryption keys.

Insecure Data Handling

• Weak cryptographic algorithms: Use of DES, Triple DES, RC4, or ECB mode.
• Logging of sensitive information: Writing PII, passwords, or API keys to logs.
• PII handling violations: Improper storage or transmission of personally identifiable information.
• Insecure deserialization: Deserializing untrusted data without validation.

Injection Vulnerabilities

• Cross-site scripting (XSS): Unsanitized user input rendered in HTML.
• SQL injection (SQLi): Unparameterized string concatenation in database queries.
• Command injection: Executing system commands using unsanitized user input.
• Server-side request forgery (SSRF): Unvalidated network requests to user-provided URLs.
• Server-side template injection (SSTI): User input embedded directly into server-side templates.

Authentication

• Authentication bypass: Improper session validation or insecure 'remember me' logic.
• Weak session tokens: Predictable or low-entropy tokens.
• Insecure password reset: Predictable reset tokens or leakage in logs/URLs.

LLM Safety

• Insecure Prompt Handling (Prompt Injection): Risks from untrusted user data in prompts or embedding sensitive info in prompts.
• Improper Output Handling: Unsafe use of LLM-generated content (e.g., passing it to eval() or using it for XSS/SQLi).
• Insecure Plugin and Tool Usage: Overly permissive tools or unsafe data flows during LLM tool interaction.

You can automate security analysis in your CI/CD pipeline using GitHub Actions.

If you already use run-gemini-cli workflows:

Replace your existing gemini-review.yml with the updated workflow provided by the extension to include the Security Analysis step.

If you do NOT use [run-gemini-cli] workflows yet:

1. Follow the Quick Start for run-gemini-cli.
2. Create a .github/workflows directory in your repository root.
3. Copy the Example Workflow into that directory.
4. Commit and push the workflow file.
5. Open a new pull request or comment @gemini-cli /review on an existing PR to trigger both Code Review and Security Analysis.

Path traversal occurs when user input is used to construct file paths without validation, allowing access to arbitrary files (e.g., /etc/passwd). To prevent this, follow a three-step remediation strategy:

1. Resolve the Path: Use path.resolve() to create an absolute path combining a predefined safe root directory and the user input.
2. Validate the Path: Verify that the resulting absolute path starts with the safe root directory string.
3. Reject Invalid Paths: If the path is outside the safe root, throw an error or reject the request immediately.

Note: When performing the prefix check, append path.sep to the safe root to ensure you are matching a directory boundary and not just a partial directory name.

import path from 'path';
import fs from 'fs/promises';

async function safeReadFile(userInput: string) {
  const SAFE_ROOT = path.resolve('/var/www/uploads');
  const targetPath = path.resolve(SAFE_ROOT, userInput);

  // Critical: Check if the resolved path starts with the safe root
  if (!targetPath.startsWith(SAFE_ROOT + path.sep)) {
    throw new Error('Access denied: Invalid file path.');
  }

  return fs.readFile(targetPath, 'utf-8');
}

The security analysis uses a specific mental model to prevent missing vulnerabilities while maintaining speed. This is known as the Two-Pass Investigation Model.

1. The Reconnaissance Pass (SAST Recon)

In this phase, the analyst scans a file to identify Sources (where untrusted data enters, e.g., req.query.id) and Sinks (where data is used, e.g., db.run()).

• Goal: Identify all potential starting points.
• Action: Instead of tracing immediately, the tool creates a task in SECURITY_ANALYSIS_TODO.md to investigate that specific variable later.

2. The Investigation Pass

Once the scan is complete, the tool moves to the tasks created during Recon.

• Goal: Perform deep-dive data-flow tracing.
• Action: Trace the variable through function calls, reassignments, and object properties to see if it reaches a Sink without being sanitized, validated, or escaped.

Key Concepts

• Source: An entry point for untrusted or sensitive input.
• Sink: A location where data is executed, rendered, or stored.
• Taint Analysis: The process of tracing untrusted data from a Source to a Sink.

The analyze-github-pr command is designed exclusively for use with the run-gemini-cli GitHub Action. It performs a security and privacy audit of code changes within a GitHub Pull Request, looking for common vulnerabilities (like SQLi, XSS, and Command Injection) and privacy violations (like PII leaks).

Operational Workflow

The analysis follows a strict Two-Pass "Recon & Investigate" Workflow to ensure high coverage and minimize false positives:

1. Reconnaissance Pass (SAST Recon): A fast scan of the entire file to identify Sources (entry points for untrusted or sensitive data). When a source is found, the tool flags it for later investigation.
2. Investigation Pass: A deep-dive trace of the identified source to see if it reaches a Sink (an execution, rendering, or storage point) without proper sanitization or validation.

Integration Requirements

• Environment: Must run within a secure GitHub Actions environment.
• Required Action: run-gemini-cli GitHub Action.
• Output: Results are reported back to the GitHub Pull Request as a pending review containing inline comments, code suggestions, and a summary report.

# This command is a configuration for the run-gemini-cli GitHub Action.
# It is not a standalone CLI command you run manually in a terminal,
# but rather a definition for the automated security audit process.

The /security:analyze command (defined by the analyze-full.toml configuration) performs a comprehensive security and privacy audit of an entire repository. It uses a specialized Two-Pass "Recon & Investigate" Workflow to identify vulnerabilities like SQL injection, XSS, and command injection by tracing data from Sources (untrusted input) to Sinks (execution/storage points).

How the analysis works:

1. Scope Definition: The tool identifies files to audit and calculates the total line count. If the repository exceeds 20,000 lines, it will prompt for user confirmation before proceeding.
2. Reconnaissance Pass: The tool performs a high-speed scan of each file to flag potential Sources of untrusted data. It creates sub-tasks in a .gemini_security/SECURITY_ANALYSIS_TODO.md file for every suspicious entry point found.
3. Investigation Pass: The tool performs a deep-dive trace for each flagged source, following the data through function calls and assignments to see if it reaches a Sink without proper sanitization.
4. Reporting: Findings are compiled into a DRAFT_SECURITY_REPORT.md and then refined into a final report.

Output and Artifacts:

• .gemini_security/: A temporary directory created during analysis.
• security_report.json: If requested via the --json flag or natural language, a machine-readable version of the report is saved here.
• Final Report: The cleaned, reviewed findings are output directly to the user.
• Cleanup: Temporary files (SECURITY_ANALYSIS_TODO.md and DRAFT_SECURITY_REPORT.md) are removed after completion, but security_report.json is preserved if generated.

# Example of requesting a JSON report during analysis
gemini-cli /security:analyze --json