diff --git a/.mlc_config.json b/.mlc_config.json index 12e804010..321678703 100644 --- a/.mlc_config.json +++ b/.mlc_config.json @@ -8,6 +8,9 @@ }, { "pattern": "https://gitlab.com/-/*" + }, + { + "pattern": "^https://go.semgrep.dev/" } ], "timeout": "20s", diff --git a/docs/mcp.md b/docs/mcp.md index 62cc35a22..b368a6f94 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -16,28 +16,26 @@ import TabItem from '@theme/TabItem'; Semgrep's plugin integrates natively with AI coding agents like Claude Code and Cursor to catch security issues before they ship. It bundles the Semgrep MCP server, Hooks, and Skills into a single install, and scans every file an agent generates using Semgrep Code, Supply Chain, and Secrets. When findings are detected, the agent is prompted to regenerate code until Semgrep returns clean results or you choose to dismiss them. -This guide covers setup for Claude Code, Cursor, Windsurf, and Codex but the plugin works with any MCP client. +The plugin uses each IDE's native hook or MCP system: + +* **Claude Code**: [hooks](https://code.claude.com/docs/en/hooks) and [plugins](https://code.claude.com/docs/en/plugins) +* **Codex**: [MCP](https://developers.openai.com/codex/mcp) +* **Cursor**: [hooks](https://cursor.com/docs/hooks) and [MCP](https://cursor.com/docs/mcp) +* **GitHub Copilot** (Visual Studio, JetBrains, Xcode, Eclipse): [MCP](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp) +* **VS Code**: [MCP](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) +* **Windsurf**: [Cascade hooks](https://docs.windsurf.com/windsurf/cascade/hooks) + +This guide covers setup for each, but the plugin works with any MCP client. ## Prerequisites -* Python 3.10 or later +* Python 3.10 or later (the Semgrep CLI requires it at runtime regardless of how it was installed) * Homebrew, [`pipx`](https://pipx.pypa.io/stable/how-to/install-pipx/), or [`uv`](https://docs.astral.sh/uv/) to install Semgrep * A Semgrep account -## Installation +## Install the Semgrep CLI - - - +These steps are the same regardless of which IDE you use. 1. Install Semgrep using Homebrew, pipx, or uv: ```bash @@ -50,86 +48,129 @@ This guide covers setup for Claude Code, Cursor, Windsurf, and Codex but the plu # or, install using uv (https://docs.astral.sh/uv/) uv tool install semgrep ``` - -2. Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep by running the following: + +2. Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep: ```bash semgrep --version ``` -3. Start a new Claude Code instance in the terminal: +3. Sign in to your Semgrep account and install the Semgrep Pro engine: + ```bash + semgrep login && semgrep install-semgrep-pro + ``` + `semgrep login` launches a browser window. You can also use the activation link printed in the terminal. + +## Connect to your IDE + + + + + +1. Start a new Claude Code instance in the terminal: ```bash claude ``` -4. Open the plugin browser: +2. Open the plugin manager: ```bash /plugin ``` -5. Go to **Discover**, search for **Semgrep**, and click **Install**. +3. Go to **Discover**, search for **Semgrep**, and click **Install**. -6. Set up the Semgrep plugin by running the following skill. This also installs the Semgrep CLI: +4. Set up the Semgrep plugin: ```bash /setup-semgrep-plugin ``` - +The plugin registers a post-tool hook so Claude Code scans every file it writes. Learn more about [Claude Code plugins](https://code.claude.com/docs/en/plugins) and [hooks](https://code.claude.com/docs/en/hooks). - + -1. Install Semgrep using Homebrew, pipx, or uv: - ```bash - # install using Homebrew - brew install semgrep + - # or, install using pipx (https://pipx.pypa.io/stable/how-to/install-pipx/) - pipx install semgrep +1. Update your `~/.codex/config.toml` file and paste the following: - # or, install using uv (https://docs.astral.sh/uv/) - uv tool install semgrep + ```toml + [mcp_servers.semgrep] + command = "semgrep" + args = ["mcp"] ``` -1. Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep by running the following: - ```bash - semgrep --version - ``` +Codex does not expose a post-write hook, so Semgrep tools are surfaced through MCP and invoked when the agent calls them. Learn more about [Codex MCP configuration](https://developers.openai.com/codex/mcp). -1. Log in to Semgrep and install Semgrep Pro: + - ``` - semgrep login && semgrep install-semgrep-pro - ``` + 1. Find Semgrep in the [Cursor Plugin Marketplace](https://cursor.com/marketplace/semgrep), or open **Cursor > ⌘⇧J > Plugins**. Search "Semgrep" and click **Add to Cursor**. -1. Restart Cursor to apply configuration. +2. Restart Cursor to apply configuration. + +3. In Cursor's chat, run the `/setup-semgrep-plugin` skill to finish wiring up the plugin. + +The plugin uses [Cursor hooks](https://cursor.com/docs/hooks) (`afterFileEdit` and `stop`) to scan code as the agent writes it, and exposes Semgrep tools through [Cursor MCP](https://cursor.com/docs/mcp). - + -1. Install Semgrep using Homebrew, pipx, or uv: - ```bash - # install using Homebrew - brew install semgrep +Use this tab for GitHub Copilot in Visual Studio, JetBrains IDEs, Xcode, or Eclipse. (For Copilot in VS Code, use the **VS Code** tab.) - # or, install using pipx (https://pipx.pypa.io/stable/how-to/install-pipx/) - pipx install semgrep +1. Register the Semgrep MCP server with your IDE's Copilot configuration. The JSON shape is the same across IDEs: - # or, install using uv (https://docs.astral.sh/uv/) - uv tool install semgrep + ```json + { + "servers": { + "semgrep": { + "command": "semgrep", + "args": ["mcp"] + } + } + } ``` -1. Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep by running the following: - ```bash - semgrep --version - ``` + Follow your IDE's instructions for *where* to put this entry: [Extending Copilot Chat with MCP servers](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp) covers Visual Studio, JetBrains, Xcode, and Eclipse. -1. Log in to Semgrep and install Semgrep Pro: +2. Restart your IDE and open Copilot Chat. Semgrep tools become available in **Agent** mode. +Copilot does not expose a post-write hook, so Semgrep tools are invoked when the agent calls them through MCP. + + + + + +1. Add the Semgrep MCP server to VS Code. Create `.vscode/mcp.json` in your workspace (or run the **MCP: Open User Configuration** command from the Command Palette for a user-wide entry) and paste the following: + + ```json + { + "servers": { + "semgrep": { + "command": "semgrep", + "args": ["mcp"] + } + } + } ``` - semgrep login && semgrep install-semgrep-pro - ``` + +2. Reload VS Code. Semgrep tools become available in the Copilot Chat **Agent** mode. + +VS Code does not expose a post-write hook today, so Semgrep tools are invoked when the agent calls them through MCP. Learn more about [adding and managing MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). + + + + 1. Create a `hooks.json` file at `~/.codeium/windsurf/hooks.json` and paste the following configuration: @@ -146,81 +187,17 @@ This guide covers setup for Claude Code, Cursor, Windsurf, and Codex but the plu } ``` -1. Restart Windsurf to apply hook configuration. - - - - - -1. Install Semgrep using Homebrew, pipx, or uv: - ```bash - # install using Homebrew - brew install semgrep - - # or, install using pipx (https://pipx.pypa.io/stable/how-to/install-pipx/) - pipx install semgrep - - # or, install using uv (https://docs.astral.sh/uv/) - uv tool install semgrep - ``` - -2. Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep by running the following: - ```bash - semgrep --version - ``` - -3. Sign in to your Semgrep account. Running this command launches a browser window, but you can also use the link that's returned in the CLI to proceed: - ```bash - semgrep login - ``` - In the **Semgrep CLI login**, click **Activate** to proceed. - -4. Return to the CLI, and install the Semgrep Pro engine: - ```bash - semgrep install-semgrep-pro - ``` +2. Restart Windsurf to apply hook configuration. -5. Update your `~/.codex/config.toml` file and paste the following: - - ```toml - [mcp_servers.semgrep] - command = "semgrep" - args = ["mcp"] - ``` +The `post_write_code` event fires after Cascade writes or modifies any file. Learn more about [Windsurf Cascade hooks](https://docs.windsurf.com/windsurf/cascade/hooks). -1. Install Semgrep using Homebrew, pipx, or uv: - ```bash - # install using Homebrew - brew install semgrep - - # or, install using pipx (https://pipx.pypa.io/stable/how-to/install-pipx/) - pipx install semgrep - - # or, install using uv (https://docs.astral.sh/uv/) - uv tool install semgrep - ``` - -2. Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep by running the following: - ```bash - semgrep --version - ``` - -3. Sign in to your Semgrep account. Running this command launches a browser window, but you can also use the link that's returned in the CLI to proceed: - ```bash - semgrep login - ``` - In the **Semgrep CLI login**, click **Activate** to proceed. - -4. Return to the CLI, and install the Semgrep Pro engine: - ```bash - semgrep install-semgrep-pro - ``` +Add the Semgrep MCP Server to your IDE. Semgrep provides [sample configuration information](https://github.com/semgrep/semgrep/tree/develop/cli/src/semgrep/mcp#integrations) that you can use as a starting point. Refer to your IDE's documentation for specific details on where to add the MCP server configuration. -5. Add the Semgrep MCP Server to your IDE. Semgrep provides [sample configuration information](https://github.com/semgrep/semgrep/tree/develop/cli/src/semgrep/mcp#integrations) that you can use as a starting point for your configuration. Refer to your IDE's documentation for specific details on where to add the MCP server configuration information. +If your IDE supports a post-write or post-tool hook, point it at `semgrep mcp -k post-tool-cli-scan -a ` to scan generated code automatically. The Windsurf tab above shows this pattern.