Armis Security Scanner

Plugin MCP Armis AppSec

Varredura de segurança com IA para Claude Code, Cursor, VS Code (GitHub Copilot), Gemini CLI, GitHub Copilot CLI, Codex CLI e Cline. Escaneia código, arquivos e diffs do git em busca de vulnerabilidades em tempo real usando a API de varredura da Armis.

Recursos

• scan_code — Escaneia um trecho de código em busca de vulnerabilidades
• scan_file — Escaneia um arquivo no disco
• scan_diff — Escaneia alterações do git (staged, unstaged ou diff contra um branch)
• approve_findings — Aprova descobertas após o consentimento do usuário (para envio com riscos conhecidos)
• debug_config — Verifica o status da configuração do scanner
• Commit gate — Hook de pre-commit do git que bloqueia commits até o código ser escaneado
• /security-scan — Comando de barra do Claude Code para varredura sob demanda

Configuração rápida (qualquer cliente)

# 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

Entre em contato com a equipe Armis AppSec se você não tiver credenciais.

Configuração do cliente

Cursor

Execute make setup CLIENT=cursor e copie a saída para ~/.cursor/mcp.json (nível de usuário) ou .cursor/mcp.json (nível de workspace).

Ou adicione manualmente à sua configuração:

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

VS Code (GitHub Copilot)

Execute make setup CLIENT=vscode e copie a saída para .vscode/mcp.json em seu projeto.

Ou adicione manualmente:

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

Ative o MCP nas configurações do VS Code, se ainda não estiver: github.copilot.chat.mcp.enabled: true.

Gemini CLI

Execute make setup CLIENT=gemini e copie a saída para ~/.gemini/settings.json (nível de usuário) ou .gemini/settings.json (nível de projeto).

Ou adicione manualmente o bloco mcpServers ao seu settings.json:

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

GitHub Copilot CLI

Execute make setup CLIENT=copilot e copie a saída para .mcp.json (workspace) ou ~/.copilot/mcp-config.json (nível de usuário).

O Copilot CLI requer os campos command e args. Uma configuração sem args será ignorada.

Codex CLI

Adicione o servidor MCP à configuração do seu Codex CLI conforme a documentação. Em seguida, conecte o hook do commit gate:

make setup CLIENT=codex   # prints the hook config JSON

Mescle o bloco hooks impresso no arquivo de configuração de hooks do seu Codex CLI (o caminho varia conforme a instalação), substituindo /absolute/path/to/armis-appsec-mcp pelo caminho real do clone.

Cline

Adicione o servidor MCP pelo painel de configurações MCP do Cline. Em seguida, conecte o hook do commit gate:

make setup CLIENT=cline   # prints the hook config JSON

Mescle o bloco hooks impresso no settings.json do seu Cline, substituindo /absolute/path/to/armis-appsec-mcp pelo caminho real do clone.

Claude Code (integração completa)

Instale pelo marketplace de plugins para a experiência completa (hooks + comando de barra):

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

Em seguida, defina as credenciais:

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"

Comparação de recursos

Recurso	Claude Code	Cursor	VS Code	Gemini	Copilot CLI	Codex CLI	Cline
Ferramentas MCP (todas as 5)	Sim	Sim	Sim	Sim	Sim	Sim	Sim
Commit gate (rígido)	Hook nativo	Hook nativo	Hook git	Hook nativo	Hook nativo	Hook nativo	Hook nativo
Commit gate (flexível)	Hook nativo	.cursor/rules	instructions	AGENTS.md	—	AGENTS.md	—
/security-scan	Sim	—	—	—	—	—	—

"Hook nativo" = hook PreToolUse conectado ao pipeline de ferramentas do cliente (bloqueia o comando antes de executá-lo e injeta uma instrução de varredura). "Hook git" = script portátil pre-commit (instalado via make install-hooks). O VS Code é o único cliente sem um template de hook nativo.

Opcional: Hook de pre-commit do Git

Para um commit gate independente de cliente que funcione com qualquer ferramenta de IA que você use:

make install-hooks

Isso instala um hook de pre-commit do git que verifica a aprovação da varredura (armazenada dentro de .git/, para nunca poluir sua árvore de trabalho) antes de permitir commits. Ele falha aberto por padrão (bugs de plugins nunca bloqueiam desenvolvedores). Defina APPSEC_HOOK_STRICT=1 para comportamento de falha fechada.

Para remover: make uninstall-hooks

Desenvolvimento local

Para testar alterações não confirmadas de um clone de ponta a ponta no Claude Code (ou em qualquer cliente que carregue o plugin instalado), aponte o plugin instalado para sua árvore de trabalho:

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 faz backup do plugin real em latest.bak, cria um symlink de latest para este repositório e copia o .env instalado (credenciais) para que a verificação prévia do iniciador ainda passe. Reinicie o Claude Code após cada instalação/desinstalação — os servidores MCP são iniciados no início da sessão. Sobrescreva o local do cache com PLUGIN_CACHE=... se seus plugins residirem em outro lugar.

Uso

Escanear alterações staged (padrão)

/security-scan

Ou peça ao seu assistente de IA: "escaneie alterações staged em busca de problemas de segurança"

Escanear um arquivo específico

/security-scan path/to/file.py

Escanear diff contra um branch

/security-scan ref=main

Escanear código colado

Cole o código na conversa e peça:

Is this code secure?

Comportamento do commit gate

Quando o hook de pre-commit do git está instalado, ou quando você usa os hooks nativos do Claude Code:

1. Bloqueia o comando até o código ser escaneado
2. O assistente de IA escaneia as alterações automaticamente
3. Permite o comando após uma varredura limpa (sem descobertas HIGH/CRITICAL)

Se forem encontradas descobertas HIGH/CRITICAL, o assistente tentará corrigi-las. Se restarem descobertas após a remediação, ele pede sua aprovação antes de prosseguir.

Configuração

Variável de Ambiente	Padrão	Descrição
ARMIS_CLIENT_ID	(obrigatório)	Client ID para autenticação
ARMIS_CLIENT_SECRET	(obrigatório)	Client secret para autenticação
APPSEC_ENV	prod	dev ou prod — seleciona o endpoint da API
APPSEC_API_URL	(auto)	Sobrescreve a URL base da API
APPSEC_DEBUG	(não definido)	Defina para qualquer valor para ativar o log de depuração
APPSEC_TRANSPORT	stdio	Transporte MCP (stdio, sse)
APPSEC_HOOK_STRICT	(não definido)	Defina para 1 para hook git com falha fechada

Transporte SSE (servidor compartilhado)

Para equipes que querem uma única instância de scanner compartilhada:

APPSEC_TRANSPORT=sse ./run.sh

Em seguida, configure os clientes para conectarem via HTTP em vez de iniciar um processo local.

Suporte de plataforma

Requer macOS ou Linux. No Windows, use WSL2.

Executando testes

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

Arquitetura

              +---------------------+
              |  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

Licença

Apache License 2.0 — veja LICENSE para detalhes.