armis-appsec

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 << '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_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 |

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.

Summary

Install to Claude Code