feat: output security reports as JSON when requested

[jajanet]

(Clone of #136, which couldn't be merged due to CLA issues that came from applying a suggestion from the GitHub bot)

This PR adds the ability to output security report results in JSON. This enables programmatic parsing for accuracy checks, standardization, and integration with SCM tools and CI/CD pipelines (e.g., GitHub Actions, Jenkins)

Example of original markdown report and corresponding JSON:

- **Vulnerability:** Path Traversal and Command Injection
- **Vulnerability Type:** Security
- **Severity:** Critical
- **Source Location:** `lib/router.js`
- **Line Content:** `full_path = "" + dispatch.static_route + (unescape(pathname));`
- **Description:** The `pathname` variable, derived from the URL, is not sanitized before being used to construct a file path. An attacker can use URL-encoded characters like `../` to traverse the file system and access arbitrary files. This vulnerability is further escalated to command injection because the `full_path` is used in a `spawn` call, allowing an attacker to execute arbitrary commands on the system.
- **Recommendation:** Sanitize the `pathname` variable by removing any directory traversal characters before using it to construct a file path. Use `path.normalize()` or a similar function to resolve the path and ensure it stays within the intended directory.

turns into

[
    {
        "vulnerability": "Path Traversal and Command Injection",
        "vulnerabilityType": "Security",
        "severity": "Critical",
        "sourceLocation": {
             "File": "lib/router.js",
             "startLine": null,
             "endLine": null
         },
         "sinkLocation": {
             "File": null,
             "startLine": null,
             "endLine": null
         },
         "dataType": null
        "lineContent": "`full_path = \"\" + dispatch.static_route + (unescape(pathname));`",
        "description": "The `pathname` variable, derived from the URL, is not sanitized before being used to construct a file path. An attacker can use URLencoded characters like `../` to traverse the file system and access arbitrary files. This vulnerability is further escalated to command injection because the `full_path` is used in a `spawn` call, allowing an attacker to execute arbitrary commands on the system.",
        "recommendation": "Sanitize the `pathname` variable by removing any directory traversal characters before using it to construct a file path. Use `path.normalize()` or a similar function to resolve the path and ensure it stays within the intended directory."
    },
...
]

Fields are optional and written as null if not present, as the tool assumes that the DRAFT_SECURITY_REPORT.md file is well-formed and has the expected fields

This is an initial implementation to help improve processes, and we may iterate using Vertex calls in the future. There is an upcoming PR on adding a subfield for code changes sometimes present under recommendation as well

[github-actions]

🤖 Hi @jajanet, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

[gemini-code-assist]

Summary of Changes

Hello @jajanet, 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 introduces a significant enhancement by allowing security analysis reports to be generated in JSON format. This change facilitates automated processing of security findings, making it easier to integrate with external systems for accuracy checks, standardization, and pipeline automation. The implementation includes a new parsing utility, a server-side tool to perform the conversion, and updates to the analysis workflow and user documentation to support this new functionality.

Highlights

• JSON Output for Security Reports: The system now supports outputting security analysis reports in JSON format, enabling programmatic parsing and integration with CI/CD pipelines.
• New convert_report_to_json Tool: A new tool has been introduced to convert the Markdown-based security report (DRAFT_SECURITY_REPORT.md) into a structured JSON file (security_report.json).
• Markdown Parsing Logic: A dedicated parser (parser.ts) was added to accurately extract vulnerability details from Markdown reports, including source/sink locations, severity, and descriptions.
• Updated Workflow and Documentation: The security analysis workflow (analyze.toml) has been updated to conditionally generate JSON reports, and the README.md now includes instructions on how to request JSON output.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• README.md
  • Added instructions for requesting security reports in JSON format using a --json flag or natural language.
• commands/security/analyze.toml
  • Modified the 'Final Reporting & Cleanup' phase to conditionally call the convert_report_to_json tool if JSON output is requested.
  • Updated cleanup actions to ensure the generated security_report.json file is retained.
  • Added a new task to the initial plan to generate a JSON report if requested by the user.
• mcp-server/src/index.ts
  • Imported the new parseMarkdownToDict function from ./parser.js.
  • Registered a new server.tool named convert_report_to_json to handle the conversion of Markdown security reports to JSON, including file reading, parsing, and writing the output.
• mcp-server/src/parser.test.ts
  • Added a new file containing comprehensive unit tests for the parseMarkdownToDict function, covering various scenarios for parsing security findings from Markdown.
• mcp-server/src/parser.ts
  • Added a new file defining Location and Finding interfaces for structured security report data.
  • Implemented helper functions buildPattern and extractFromSection for robust regex-based extraction of fields from Markdown.
  • Implemented the core parseMarkdownToDict function to convert a Markdown string containing security findings into an array of structured Finding objects, handling different formatting and missing data gracefully.

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]

📋 Review Summary

This PR introduces a useful feature to output security reports in JSON format. The overall implementation is well-structured, with the addition of a new tool for JSON conversion, comprehensive tests, and updated documentation.

🔍 General Feedback

• One potential bug was identified in mcp-server/src/parser.ts where some fields were missing from the FIELD_NAMES constant, which could lead to parsing issues. A specific comment with a suggested fix has been provided for this.
• The error handling in the new convert_report_to_json tool is well-implemented.
• The changes in the analyze.toml and README.md are clear and correctly reflect the new functionality.

Once the suggested change is addressed, this PR will be in great shape.

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature for outputting security reports in JSON format, which will greatly improve integration with other tools. The implementation is solid, with a new tool for conversion and a new markdown parser. The addition of unit tests for the parser is also great to see.

I've found a few areas for improvement in the new parser code (mcp-server/src/parser.ts) related to maintainability and code style. Specifically, there's an incorrect JSDoc, a fragile implementation detail in how fields are parsed, and a minor style issue. Please see my detailed comments.

[github-actions]

## 📋 Security Analysis Summary

This PR introduces a new feature to output security reports in JSON format. The implementation looks good overall, but I've found one potential low-severity vulnerability related to regular expression denial of service in the markdown parser.

🔍 General Feedback

• The code is well-structured and easy to understand.
• The new feature is a valuable addition to the tool.

[github-actions]

LOW Potential Regular Expression Denial of Service (ReDoS)

The markdown parser uses regular expressions to parse the security report. If the report is very large or contains certain complex patterns, these regular expressions could be slow and lead to a denial of service. The likelihood of this is low since the report is generated by the AI, but it's still a possibility.

Suggested change

	const sections = cleanContent.split(/\n(?=#{1,6} |\s*Vulnerability:)/);
	Implement safeguards such as input length limits and complexity checks on the markdown content before parsing. Consider using a more robust markdown parser library if performance becomes an issue.

[jajanet]

added as Todo!