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

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

Platform Support

Requires macOS or Linux. On Windows, use WSL2.

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.

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 << 'EOF'
ARMIS_CLIENT_ID=<your-client-id>
ARMIS_CLIENT_SECRET=<your-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" << 'EOF'
ARMIS_CLIENT_ID=<your-client-id>
ARMIS_CLIENT_SECRET=<your-client-secret>
EOF
chmod 600 "$PLUGIN_DIR/.env"

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.

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