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_files — Scan up to 20 files in one call (one approval prompt in editors that confirm each tool call)
• 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 << '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"

Feature Comparison

Feature	Claude Code	Cursor	VS Code	Gemini	Copilot CLI	Codex CLI	Cline
MCP tools (all 5)	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Commit gate (hard)	Native hook	Native hook	Git hook	Native hook	Native hook	Native hook	Native hook
Commit gate (soft)	Native hook	.cursor/rules	instructions	AGENTS.md	—	AGENTS.md	—
/security-scan	Yes	—	—	—	—	—	—

"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

Environment Variable	Default	Description
ARMIS_CLIENT_ID	(required)	Client ID for authentication
ARMIS_CLIENT_SECRET	(required)	Client secret for authentication
APPSEC_ENV	prod	dev or prod — selects API endpoint
APPSEC_API_URL	(auto)	Override the API base URL
APPSEC_SCAN_TIMEOUT	180	Seconds one scan may take (auth + API) before it fails with the step that stalled
APPSEC_MAX_CONCURRENT_SCANS	3	Scan requests in flight at once (1–16); extra scans wait. Rate-limit (429) and 5xx responses are retried with backoff
APPSEC_DEBUG	(unset)	Set to any value to enable debug logging
APPSEC_TRANSPORT	stdio	MCP transport (stdio, sse)
APPSEC_HOOK_STRICT	(unset)	Set to 1 for fail-closed git hook
SSL_CERT_FILE / SSL_CERT_DIR / REQUESTS_CA_BUNDLE	(unset)	Explicit CA bundle; overrides the OS certificate store
HTTPS_PROXY / ALL_PROXY / NO_PROXY	(unset)	Explicit proxy config; overrides the OS proxy settings

Where credentials must live

Put ARMIS_CLIENT_ID / ARMIS_CLIENT_SECRET in the plugin's .env. Variables exported in a terminal are not inherited by servers an editor launches (VS Code started from the Start menu or Dock never sees them), and the server then falls back to browser sign-in. Run debug_config to see which credentials were found and from where, and check logs/server.log in the plugin directory for the startup report.

Slow starts and long scans

• Antivirus real-time scanning of the plugin's .venv can add several seconds to startup. If your editor gives up before the server is ready, ask IT to exclude the plugin directory.
• A scan that does not finish within APPSEC_SCAN_TIMEOUT fails with a message naming the stage (obtaining a token, waiting for the API, or a pending browser sign-in, including its URL and code). logs/server.log records each stage with timings.

Corporate networks (TLS inspection, proxies)

The server trusts the OS certificate store (Windows cert store, macOS Keychain) via truststore, so TLS-inspecting proxies such as Zscaler or Netskope work without extra setup. CA precedence: SSL_CERT_FILE > SSL_CERT_DIR > REQUESTS_CA_BUNDLE > OS store > certifi (used if truststore is unavailable).

With no proxy env vars set, the static system proxy (Windows Internet Options registry, macOS System Settings) is used, honoring NO_PROXY and the OS bypass list. PAC/WPAD auto-config scripts are not evaluated; on such networks set HTTPS_PROXY explicitly.

Logs

The server logs to stderr and to <plugin dir>/logs/server.log (rotated at ~1 MB, 3 backups): startup config (version, Python, CA source, proxy, API URL), each tool call with duration and outcome, and unhandled exceptions. Credentials, tokens, and proxy passwords are never logged. The debug_config tool reports the CA source, proxy, and log file path.

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

macOS and Linux are fully supported. On native Windows, Claude Code launches the plugin through run.cmd, which finds Git for Windows' bash.exe (Git for Windows is already required by Claude Code) and runs run.sh. Set CLAUDE_CODE_GIT_BASH_PATH if Git is installed somewhere unusual. WSL2 also works. For other MCP clients (Cursor, VS Code, etc.), make setup launches natively via Git Bash — see make setup CLIENT=....

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.