Armis AppSec MCP Plugin

AI-powered security scanning for Claude Code, Cursor, VS Code (GitHub Copilot), Gemini CLI, GitHub Copilot CLI, Codex CLI, and Cline. Scans code, files, and git diffs for vulnerabilities in real-time using the Armis scanning API.

Features

• `scan_code` — Scan a code snippet for vulnerabilities
• `scan_file` — Scan a file on disk
• `scan_diff` — Scan git changes (staged, unstaged, or diff against a branch)
• `approve_findings` — Approve findings after user consent (for shipping with known risks)
• `debug_config` — Check scanner configuration status
• Commit gate — Git pre-commit hook that blocks commits until code is scanned
• `/security-scan` — Claude Code slash command for on-demand scanning

Quick Setup (any client)

# 1. Clone the repository
git clone https://github.com/ArmisSecurity/armis-appsec-mcp.git
cd armis-appsec-mcp

# 2. Create credentials
cat > .env 
ARMIS_CLIENT_SECRET=
EOF
chmod 600 .env

# 3. Generate config for your client
make setup CLIENT=cursor    # or: vscode, gemini, copilot

Contact the Armis AppSec team if you don't have credentials.

Client Setup

Cursor

Run `make setup CLIENT=cursor` and copy the output to `~/.cursor/mcp.json` (user-level) or `.cursor/mcp.json` (workspace-level).

Or manually add to your config:

{
  "mcpServers": {
    "armis-scanner": {
      "command": "/path/to/armis-appsec-mcp/run.sh",
      "args": []
    }
  }
}

VS Code (GitHub Copilot)

Run `make setup CLIENT=vscode` and copy the output to `.vscode/mcp.json` in your project.

Or manually add:

{
  "servers": {
    "armis-scanner": {
      "type": "stdio",
      "command": "/path/to/armis-appsec-mcp/run.sh",
      "args": []
    }
  }
}

Enable MCP in VS Code settings if not already: `github.copilot.chat.mcp.enabled: true`.

Gemini CLI

Run `make setup CLIENT=gemini` and copy the output to `~/.gemini/settings.json` (user-level) or `.gemini/settings.json` (project-level).

Or manually add the `mcpServers` block to your `settings.json`:

{
  "mcpServers": {
    "armis-scanner": {
      "command": "/path/to/armis-appsec-mcp/run.sh",
      "args": []
    }
  }
}

GitHub Copilot CLI

Run `make setup CLIENT=copilot` and copy the output to `.mcp.json` (workspace) or `~/.copilot/mcp-config.json` (user-level).

Copilot CLI requires both `command` and `args` fields. A config without `args` will be ignored.

Codex CLI

Add the MCP server to your Codex CLI config per its documentation. Then wire in the commit gate hook:

make setup CLIENT=codex   # prints the hook config JSON

Merge the printed `hooks` block into your Codex CLI hooks config file (path varies by installation), replacing `/absolute/path/to/armis-appsec-mcp` with the actual clone path.

Cline

Add the MCP server via Cline's MCP settings panel. Then wire in the commit gate hook:

make setup CLIENT=cline   # prints the hook config JSON

Merge the printed `hooks` block into your Cline `settings.json`, replacing `/absolute/path/to/armis-appsec-mcp` with the actual clone path.

Claude Code (full integration)

Install via the plugin marketplace for the complete experience (hooks + slash command):

/plugin marketplace add ArmisSecurity/armis-appsec-mcp
/plugin install armis-appsec@armis-appsec-mcp

Then set credentials:

PLUGIN_DIR="$(ls -dt ~/.claude/plugins/cache/armis-appsec-mcp/armis-appsec/*/ | head -1)"
cat > "$PLUGIN_DIR/.env" 
ARMIS_CLIENT_SECRET=
EOF
chmod 600 "$PLUGIN_DIR/.env"

Feature Comparison

"Native hook" = PreToolUse hook wired into the client's tool pipeline (blocks the command before it runs, injects a scan instruction). "Git hook" = portable `pre-commit` script (installed via `make install-hooks`). VS Code is the only client without a native hook template.

Optional: Git Pre-Commit Hook

For a client-agnostic commit gate that works regardless of which AI tool you use:

make install-hooks

This installs a git pre-commit hook that verifies the scan-pass (stored inside `.git/`, so it never clutters your working tree) before allowing commits. It fails open by default (plugin bugs never block developers). Set `APPSEC_HOOK_STRICT=1` for fail-closed behavior.

To remove: `make uninstall-hooks`

Local Development

To test uncommitted changes from a clone end-to-end in Claude Code (or any client that loads the installed plugin), point the installed plugin at your working tree:

make dev-install     # backs up the installed plugin, symlinks it -> this repo
# ...restart Claude Code, then test...
make dev-uninstall   # restores the backed-up plugin exactly
make dev-status      # show whether dev mode is active

`dev-install` backs up the real plugin to `latest.bak`, symlinks `latest` to this repo, and copies the installed `.env` (credentials) over so the launcher's preflight still passes. Restart Claude Code after each install/uninstall — MCP servers launch at session start. Override the cache location with `PLUGIN_CACHE=...` if your plugins live elsewhere.

Usage

Scan staged changes (default)

/security-scan

Or ask your AI assistant: "scan staged changes for security issues"

Scan a specific file

/security-scan path/to/file.py

Scan diff against a branch

/security-scan ref=main

Scan pasted code

Paste code into the conversation and ask:

Is this code secure?

Commit gate behavior

When the git pre-commit hook is installed, or when using Claude Code's native hooks:

1. Blocks the command until code is scanned

2. The AI assistant scans the changes automatically

3. Allows the command after a clean scan (no HIGH/CRITICAL findings)

If HIGH/CRITICAL findings are found, the assistant will attempt to fix them. If findings remain after remediation, it asks for your approval before proceeding.

Configuration

SSE Transport (shared server)

For teams that want a single shared scanner instance:

APPSEC_TRANSPORT=sse ./run.sh

Then configure clients to connect via HTTP instead of launching a local process.

Platform Support

Requires macOS or Linux. On Windows, use WSL2.

Running Tests

make check          # full CI gate (format + lint + typecheck + test)
make test           # pytest only
pytest hooks/tests/test_pre_commit_scan.py -v  # specific test file

Architecture

+---------------------+
              |  Armis Cloud        |
              |  POST /scan/fast    |
              +--------+------------+
                       ^
                       | HTTPS (JWT Bearer)
              +--------+------------+
              |   Scanner Core       |
              |  scanner_core.py     |
              +--------+------------+
                 +-----+------+
                 |            |
           +-----v-----+ +---v---------+
           | MCP Server | | Git Hook    |
           | server.py  | | git-hooks/  |
           +------------+ +-------------+
                 |
    +------------+-------------+
    |            |             |
  Claude     Cursor      VS Code/
  Code       Gemini      Copilot

License

Apache License 2.0 — see LICENSE for details.