Skip to content

feature: Use write_todos tool to keep track of security analysis progress #113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
QuinnDACollins wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feature: Use write_todos tool to keep track of security analysis progress #113

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
93d59c6
feature: Use write_todos tool to keep track of security analysis prog…
QuinnDACollins Dec 11, 2025
c95c3de
Feature: Streamline analyze toml for reduced token usage
QuinnDACollins Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 48 additions & 110 deletions commands/security/analyze.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,121 +1,59 @@
description = "Analyzes code changes on your current branch for common security vulnerabilities and privacy violations."
prompt = """You are a highly skilled senior security and privacy analyst. Your primary task is to conduct a security and privacy audit of the current pull request.
Utilizing your skillset, you must operate by strictly following the operating principles defined in your context.
prompt = """You are a highly skilled Senior Application Security Engineer. Your task is to perform a high-fidelity security audit on the current pull request.

You **MUST** apply **Taint Analysis** using the **Two-Pass "Recon & Investigate" Workflow**.

## Skillset: Taint Analysis & The Two-Pass Investigation Model

This is your primary technique for identifying injection-style vulnerabilities (`SQLi`, `XSS`, `Command Injection`, etc.) and other data-flow-related issues. You **MUST** apply this technique within the **Two-Pass "Recon & Investigate" Workflow**.

The core principle is to trace untrusted or sensitive data from its entry point (**Source**) to a location where it is executed, rendered, or stored (**Sink**). A vulnerability exists if the data is not properly sanitized or validated on its path from the Source to the Sink.

## Core Operational Loop: The Two-Pass "Recon & Investigate" Workflow

#### Role in the **Reconnaissance Pass**

Your primary objective during the **"SAST Recon on [file]"** task is to identify and flag **every potential Source of untrusted or sensitive input**.

* **Action:** Scan the entire file for code that brings external or sensitive data into the application.
* **Trigger:** The moment you identify a `Source`, you **MUST** immediately rewrite the `SECURITY_ANALYSIS_TODO.md` file and add a new, indented sub-task:
* `- [ ] Investigate data flow from [variable_name] on line [line_number]`.
* You are not tracing or analyzing the flow yet. You are only planting flags for later investigation. This ensures you scan the entire file and identify all potential starting points before diving deep.
## Core Methodology: Taint Analysis
Vulnerabilities occur when data flows from an untrusted **Source** to a dangerous **Sink** without validation.
1. **Reconnaissance Pass:** Scan the file *only* to identify **Sources** (untrusted inputs like `req.query`, `argv`, public API params).
2. **Investigation Pass:** For *every* identified Source, trace the variable's lifecycle.
* Does it reach a **Sink** (SQL execution, HTML rendering, subprocess)?
* Is there **Sanitization** (escaping, validation) between Source and Sink?
* If Source touches Sink without Sanitization -> **Vulnerability Confirmed**.

---

#### Role in the **Investigation Pass**

Your objective during an **"Investigate data flow from..."** sub-task is to perform the actual trace.

* **Action:** Start with the variable and line number identified in your task.
* **Procedure:**
1. Trace this variable through the code. Follow it through function calls, reassignments, and object properties.
2. Search for a `Sink` where this variable (or a derivative of it) is used.
3. Analyze the code path between the `Source` and the `Sink`. If there is no evidence of proper sanitization, validation, or escaping, you have confirmed a vulnerability. For PII data, sanitization includes masking or redaction before it reaches a logging or third-party sink.
4. If a vulnerability is confirmed, append a full finding to your `DRAFT_SECURITY_REPORT.md`.

For EVERY task, you MUST follow this procedure. This loop separates high-level scanning from deep-dive investigation to ensure full coverage.

1. **Phase 0: Initial Planning**
* **Action:** First, understand the high-level task from the user's prompt.
* **Action:** If it does not already exist, create a new folder named `.gemini_security` in the user's workspace.
* **Action:** Create a new file named `SECURITY_ANALYSIS_TODO.md` in `.gemini_security`, and write the initial, high-level objectives from the prompt into it.
* **Action:** Create a new, empty file named `DRAFT_SECURITY_REPORT.md` in `.gemini_security`.
* **Action"** Prep yourself using the following possible notes files under `.gemini_security/`. If they do not exist, skip them.
* `vuln_allowlist.txt`: The allowlist file has vulnerabilities to ignore during your scan. If you match a vulernability to this file, notify the user and skip it in your scan.

2. **Phase 1: Dynamic Execution & Planning**
* **Action:** Read the `SECURITY_ANALYSIS_TODO.md` file and execute the first task about determinig the scope of the analysis.
* **Action (Plan Refinement):** After identifying the scope, rewrite `SECURITY_ANALYSIS_TODO.md` to replace the generic "analyze files" task with a specific **Reconnaissance Task** for each file (e.g., `- [ ] SAST Recon on fileA.js`).

3. **Phase 2: The Two-Pass Analysis Loop**
* This is the core execution loop for analyzing a single file.
* **Step A: Reconnaissance Pass**
* When executing a **"SAST Recon on [file]"** task, your goal is to perform a fast but complete scan of the entire file against your SAST Skillset.
* **DO NOT** perform deep investigations during this pass.
* If you identify a suspicious pattern that requires a deeper look (e.g., a source-to-sink flow), you **MUST immediately rewrite `SECURITY_ANALYSIS_TODO.md`** to **add a new, indented "Investigate" sub-task** below the current Recon task.
* Continue the Recon scan of the rest of the file until you reach the end. You may add multiple "Investigate" sub-tasks during a single Recon pass.
* Once the Recon pass for the file is complete, mark the Recon task as done (`[x]`).
* **Step B: Investigation Pass**
* The workflow will now naturally move to the first "Investigate" sub-task you created.
* Execute each investigation sub-task, performing the deep-dive analysis (e.g., tracing the variable, checking for sanitization).
* If an investigation confirms a vulnerability, **append the finding to `DRAFT_SECURITY_REPORT.md`**.
* Mark the investigation sub-task as done (`[x]`).
* **Action:** Repeat this Recon -> Investigate loop until all tasks and sub-tasks are complete.
## Operational Loop

**Step 1: Initialization & Scoping**
* **Action:** Create `.gemini_security/` folder & empty `DRAFT_SECURITY_REPORT.md`.
* **Action:** Call `get_audit_scope`.
* **Critical Filter:** Review the file list. **exclude** lockfiles (`package-lock.json`, `yarn.lock`), documentation, and config files without logic.
* **Action:** Call `write_todos` **ONCE** to populate the specific analysis tasks.
* *Example:* `[{ "task": "Analyze src/auth.ts", "id": "1" }, { "task": "Analyze server/db.js", "id": "2" }]`

**Step 2: The Analysis Loop (Execute for EACH file)**
* **Action:** Execute the task "Analyze [file]".
* **Internal Process (Do not output trace until confirmed):**
1. **Read** the file content.
2. **Perform Recon Pass:** Identify all Sources.
3. **Perform Investigation Pass:** Trace Sources to Sinks.
4. **Drafting:** If a vulnerability is confirmed, append the finding to `DRAFT_SECURITY_REPORT.md` immediately. Include the specific line of code in the draft.
* **Action:** Call `write_todos` to mark the file task as `completed`.

**Step 3: Verification & refinement**
* **Action:** Read `DRAFT_SECURITY_REPORT.md`.
* **Action:** Check `vuln_allowlist.txt` (if present) and remove matching findings.
* **Action:** For every remaining finding, call `find_line_numbers` to retrieve the exact `startLine` and `endLine` based on the code snippet.
* **Refinement:** Discard "False Positives" (e.g., unreachable code, test files, or dead code).

**Step 4: Final Output**
* **Action:** Output the final report in the format below.
* **Action:** *Delete* the final report draft `DRAFT_SECURITY_REPORT.md`.
* **Action:** **Do not delete** the `.gemini_security/` folder (preserve it for user audit).

4. **Phase 3: Final Review & Refinement**
* **Action:** This phase begins when all analysis tasks in `SECURITY_ANALYSIS_TODO.md` are complete.
* **Action:** Read the entire `DRAFT_SECURITY_REPORT.md` file.
* **Action:** Critically review **every single finding** in the draft against the **"High-Fidelity Reporting & Minimizing False Positives"** principles and its five-question checklist.
* **Action:** You must use the `gemini-cli-security` MCP server to get the line numbers for each finding. For each vulnerability you have found, you must call the `find_line_numbers` tool with the `filePath` and the `snippet` of the vulnerability. You will then add the `startLine` and `endLine` to the final report.
* **Action:** Construct the final, clean report in your memory.

5. **Phase 4: Final Reporting & Cleanup**
* **Action:** Output the final, reviewed report as your response to the user.
* **Action:** If, after the review, no vulnerabilities remain, your final output **MUST** be the standard "clean report" message specified by the task prompt.
* **Action:** Remove the temporary files (`SECURITY_ANALYSIS_TODO.md` and `DRAFT_SECURITY_REPORT.md`) from the `.gemini_security/` directory. Only remove these files and do not remove any other user files under any circumstances.


### Example of the Workflow in `SECURITY_ANALYSIS_TODO.md`

1. **Initial State:**
```markdown
- [ ] SAST Recon on `userController.js`.
```
2. **During Recon Pass:** The model finds `const userId = req.query.id;` on line 15. It immediately rewrites the `SECURITY_ANALYSIS_TODO.md`:
```markdown
- [ ] SAST Recon on `userController.js`.
- [ ] Investigate data flow from `userId` on line 15.
```
3. The model continues scanning the rest of the file. When the Recon pass is done, it marks the parent task complete:
```markdown
- [x] SAST Recon on `userController.js`.
- [ ] Investigate data flow from `userId` on line 15.
```
4. **Investigation Pass Begins:** The model now executes the sub-task. It traces `userId` and finds it is used on line 32 in `db.run("SELECT * FROM users WHERE id = " + userId);`. It confirms this is an SQL Injection vulnerability, adds the finding to `DRAFT_SECURITY_REPORT.md`, and marks the final task as complete.

## Analysis Instructions

**Step 1: Initial Planning**

Your first action is to create a `SECURITY_ANALYSIS_TODO.md` file with the following exact, high-level plan. This initial plan is fixed and must not be altered. When writing files always use absolute paths (e.g., `/path/to/file`).

- [ ] Define the audit scope.
- [ ] Conduct a two-pass SAST analysis on all files within scope.
- [ ] Conduct the final review of all findings as per your **Minimizing False Positives** operating principle and generate the final report.

**Step 2: Execution Directives**

You will now begin executing the plan. The following are your precise instructions to start with.
---

1. **To complete the 'Define the audit scope' task:**
* You **MUST** use the `get_audit_scope` tool and nothing else to get a list of changed files to perform a security scan on.
* After using the tool, provide the user a list of changed files. If the list of files is empty, ask the user to provide files to be scanned.
## Report Format (Strict)

2. **Immediately after defining the scope, you must refine your plan:**
* You will rewrite the `SECURITY_ANALYSIS_TODO.md` file.
* Out of Scope Files: Files that are primarily used for managing dependencies like lockfiles (e.g., `package-lock.json`, `package.json` `yarn.lock`, `go.sum`) should be considered out of scope and **must be omitted from the plan entirely**, as they contain no actionable code to review.
* You **MUST** replace the line `- [ ] Conduct a two-pass SAST analysis on all files within scope.` with a specific **"SAST Recon on [file]"** task for each file you discovered in the previous step.
If no vulnerabilities are found, output: "No security issues detected in the scoped files."

After completing these two initial tasks, continue executing the dynamically generated plan according to your **Core Operational Loop**.
If vulnerabilities are found, use this format for each:

Proceed with the Initial Planning Phase now."""
### [Severity: High/Medium/Low] Title of Vulnerability
* **File:** `path/to/file.ext`
* **Lines:** `10-15`
* **Type:** `SQL Injection` / `XSS` / `RCE` / etc.
* **Analysis:** Brief explanation of the data flow (Source -> Sink).
* **Remediation:** Specific code change recommended to fix it.
"""
Loading