Cycode
oficialAumente a segurança no seu ciclo de vida de desenvolvimento com varredura SAST, SCA, Secrets e IaC com Cycode.
O que você pode fazer com Cycode MCP?
- Verificar segredos — Peça ao assistente para verificar arquivos ou diretórios em busca de segredos codificados diretamente usando
cycode_secret_scan. - Verificar problemas de SCA — Solicite uma verificação de Análise de Composição de Software em busca de vulnerabilidades e problemas de licença por meio de
cycode_sca_scan. - Verificar configurações incorretas de IaC — Peça ao assistente para verificar se há configurações incorretas na infraestrutura como código usando
cycode_iac_scan. - Verificar problemas de SAST — Execute uma verificação de Teste Estático de Segurança de Aplicações em busca de problemas de qualidade e falhas de segurança no código usando
cycode_sast_scan. - Verificar o status da CLI — Peça a versão da CLI do Cycode, o status da autenticação e os detalhes da configuração por meio de
cycode_status.
Documentação
Guia do usuário da CLI do Cycode
A interface de linha de comando (CLI) do Cycode é um aplicativo que você pode instalar localmente para verificar seus repositórios em busca de segredos, configurações incorretas de infraestrutura como código, vulnerabilidades de análise de composição de software e problemas de teste de segurança de aplicações estáticas.
Este guia apresenta a instalação e o uso.
Sumário
- Pré-requisitos
- Instalação
- Comandos da CLI do Cycode
- Certificados e proxies
- Comando MCP
- Comando Platform
- Proteções de IA
- Comando Scan
- Comando Report
- Comando Import
- Logs de verificação
- Ajuda de sintaxe
Pré-requisitos
- O aplicativo CLI do Cycode requer Python versão 3.10 ou posterior.
- Use o comando
cycode authpara autenticar no Cycode com a CLI- Como alternativa, você pode obter um ID de cliente e uma chave secreta de cliente do Cycode seguindo as etapas detalhadas nas páginas Token de conta de serviço e Token de acesso pessoal, que explicam como obter esses valores.
Instalação
As etapas de instalação a seguir se aplicam aos sistemas operacionais Windows e UNIX / Linux.
[!NOTE] As etapas a seguir pressupõem o uso de
python3epip3para comandos relacionados ao Python; no entanto, alguns sistemas podem usar os comandospythonepip, dependendo da configuração do ambiente Python.
Instalar a CLI do Cycode
Para instalar o aplicativo CLI do Cycode na sua máquina local, siga estas etapas:
-
Abra o terminal ou aplicativo de linha de comando.
-
Execute um dos seguintes comandos:
-
Para instalar do PyPI:
pip3 install cycode -
Para instalar do Homebrew:
brew install cycode -
Para instalar do GitHub Releases, acesse a página e baixe o executável para seu sistema operacional e arquitetura. Em seguida, execute o seguinte comando:
cd /path/to/downloaded/cycode-cli chmod +x cycode ./cycode -
-
Por fim, autentique a CLI. Há três métodos para definir o ID e as credenciais do cliente Cycode (segredo do cliente ou token de ID OIDC):
- cycode auth (Recomendado)
- cycode configure
- Adicione-os às suas variáveis de ambiente
Usando o comando Auth
[!NOTE] Este é o método recomendado para configurar sua máquina local para autenticação com a CLI do Cycode.
-
Digite o seguinte comando na janela do terminal/linha de comando:
cycode auth -
Uma janela do navegador será exibida, solicitando que você entre no Cycode (como mostrado abaixo):
-
Insira suas credenciais de login nesta página e entre.
-
Você será direcionado à página abaixo, onde deverá escolher o grupo empresarial com o qual deseja autorizar o Cycode (se aplicável):
[!NOTE] Este será o método padrão de autenticação na CLI do Cycode.
-
Clique no botão Allow para autorizar a CLI do Cycode no grupo empresarial selecionado.
-
Após a conclusão, a tela a seguir será exibida se a seleção tiver sido bem-sucedida:
-
Na janela do terminal/linha de comando, você verá o seguinte ao fechar a janela do navegador:
Successfully logged into cycode
Usando o comando Configure
[!NOTE] Se você já configurou o ID e o segredo do cliente Cycode por meio das variáveis de ambiente do Linux ou do Windows, essas credenciais terão precedência sobre este método.
-
Digite o seguinte comando na janela do terminal/linha de comando:
cycode configure -
Insira o valor da URL da API do Cycode (você pode deixar em branco para usar o valor padrão).
Cycode API URL [https://api.cycode.com]: https://api.onpremise.com -
Insira o valor da URL do aplicativo Cycode (você pode deixar em branco para usar o valor padrão).
Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com -
Insira o valor do ID do cliente Cycode.
Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d -
Insira o valor do segredo do cliente Cycode (ignore esta etapa se pretende usar um token de ID OIDC).
Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e -
Insira o valor do token de ID OIDC do Cycode (opcional).
Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... -
Se os valores forem inseridos com sucesso, você verá a seguinte mensagem:
Successfully configured CLI credentials!ou/e
Successfully configured Cycode URLs!
Se você acessar a pasta .cycode dentro da sua pasta de usuário, encontrará as credenciais criadas e armazenadas no arquivo credentials.yaml dessa pasta.
As URLs foram armazenadas no arquivo config.yaml dessa pasta.
Adicionar às variáveis de ambiente
No Unix/Linux:
export CYCODE_CLIENT_ID={your Cycode ID}
e
export CYCODE_CLIENT_SECRET={your Cycode Secret Key}
Se sua organização usa autenticação OIDC, você pode fornecer o token de ID em vez disso (ou também):
export CYCODE_ID_TOKEN={your Cycode OIDC ID token}
No Windows
-
No Painel de Controle, acesse o menu Sistema:
-
Em seguida, clique em Configurações avançadas do sistema:
-
Na janela Propriedades do Sistema que será aberta, clique no botão Variáveis de Ambiente:
-
Crie as variáveis
CYCODE_CLIENT_IDeCYCODE_CLIENT_SECRETcom valores correspondentes ao seu ID e à sua chave secreta, respectivamente. Se você autenticar via OIDC, adicione tambémCYCODE_ID_TOKENcom o valor do seu token de ID OIDC:
-
Insira o
cycode.exeno caminho para concluir a instalação.
Instalar o hook Pre-Commit
Os hooks pre-commit e pre-push do Cycode podem ser configurados no repositório local para que o aplicativo CLI do Cycode identifique automaticamente quaisquer problemas no seu código antes de você fazer commit ou push para sua base de código.
[!NOTE] Os hooks pre-commit e pre-push não estão disponíveis para verificações de IaC.
Siga estas etapas para instalar o hook pre-commit:
Instalando o hook Pre-Commit
-
Instale a estrutura pre-commit (é necessário ter o Python 3.10 ou superior instalado):
pip3 install pre-commit -
Acesse o diretório raiz do repositório Git local que deseja configurar.
-
Crie um novo arquivo YAML chamado
.pre-commit-config.yaml(inclua o início.) no diretório raiz do repositório, com o seguinte conteúdo:repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode stages: [pre-commit] -
Modifique o arquivo criado conforme suas necessidades. Use o ID de hook
cycodepara habilitar a verificação de segredos. Use o ID de hookcycode-scapara habilitar a verificação de SCA. Use o ID de hookcycode-sastpara habilitar a verificação de SAST. Para habilitar todos os tipos de verificação, use esta configuração:repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode stages: [pre-commit] - id: cycode-sca stages: [pre-commit] - id: cycode-sast stages: [pre-commit] -
Instale o hook do Cycode:
pre-commit installSe a instalação do hook for bem-sucedida, será exibida a mensagem:
Pre-commit installed at .git/hooks/pre-commit. -
Mantenha o hook pre-commit atualizado:
pre-commit autoupdateIsso atualizará automaticamente
revem.pre-commit-config.yamlpara a versão mais recente disponível da CLI do Cycode.
[!NOTE] O acionamento ocorre no comando
git commit. O hook é acionado somente nos arquivos preparados para commit.
Instalando o hook Pre-Push
Para instalar o hook pre-push além do hook pre-commit ou em vez dele:
-
Adicione os hooks pre-push ao arquivo
.pre-commit-config.yaml:repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push stages: [pre-push] -
Instale o hook pre-push:
pre-commit install --hook-type pre-push -
Para os hooks pre-commit e pre-push, use:
pre-commit install pre-commit install --hook-type pre-push
[!NOTE] Os hooks pre-push são acionados no comando
git pushe verificam somente os commits prestes a serem enviados.
Comandos da CLI do Cycode
A seguir estão as opções e os comandos disponíveis no aplicativo CLI do Cycode:
| Opção | Descrição |
|---|---|
-v, --verbose | Mostrar logs detalhados. |
--no-progress-meter | Não mostrar o indicador de progresso. |
--no-update-notifier | Não verificar se há atualizações da CLI. |
-o, --output [rich|text|json|table] | Especificar o tipo de saída. O padrão é rich. |
--client-id TEXT | Especificar um ID de cliente Cycode para esta execução de verificação específica. |
--client-secret TEXT | Especificar um segredo de cliente Cycode para esta execução de verificação específica. |
--id-token TEXT | Especificar um token de ID OIDC do Cycode para esta execução de verificação específica. |
--install-completion | Instalar o preenchimento automático para o shell atual.. |
--show-completion [bash|zsh|fish|powershell|pwsh] | Mostrar o preenchimento automático para o shell especificado, para copiá-lo ou personalizar a instalação. |
-h, --help | Mostrar opções para o comando fornecido. |
| Comando | Descrição |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| auth | Autentique sua máquina para associar a CLI à sua conta Cycode. |
| configure | Comando inicial para configurar a autenticação do cliente da CLI. |
| ignore | Ignore um valor, caminho ou ID de regra específico. |
| mcp | Inicie o servidor Model Context Protocol (MCP) para habilitar a integração de IA com os recursos de varredura do Cycode. |
| scan | Faça a varredura do conteúdo em busca de violações de Secrets/IaC/SCA/SAST. Você precisará especificar o tipo de varredura a ser realizado: commit-history/path/repository/etc. |
| report | Gere um relatório. Você precisará especificar o tipo de relatório a ser gerado, como SBOM. |
| status | Mostre o status da CLI e saia. |
Certificados e proxies
Por padrão, a CLI do Cycode verifica as conexões HTTPS usando o pacote de CAs fornecido com a CLI.
Se sua organização usa um proxy que inspeciona o tráfego HTTPS ou uma instalação local com sua própria CA, você tem duas opções.
Opção 1 — usar os certificados já instalados na máquina. Se sua CA estiver no repositório de certificados da máquina (como costuma acontecer em um dispositivo gerenciado), habilite essa opção:
export CYCODE_CLI_ENABLE_TRUSTSTORE=1
A CLI então verifica os certificados usando o repositório de certificados do Windows, o Keychain do macOS ou o diretório de CAs do sistema no Linux, sem necessidade de configurar caminhos de certificados.
[!IMPORTANT] Essa opção é desabilitada por padrão intencionalmente. Confiar no repositório da máquina significa confiar em todos os certificados raiz presentes nela, inclusive os instalados por um administrador ou por software malicioso. Habilite essa opção quando souber que o repositório de certificados da sua máquina é confiável.
Opção 2 — apontar a CLI para um arquivo de pacote de CAs. Funciona sem habilitar a opção:
| Variável de ambiente | Descrição |
|---|---|
REQUESTS_CA_BUNDLE | Caminho para um arquivo de pacote de CAs (.pem ou .crt) a ser confiado. |
CURL_CA_BUNDLE | Alias de REQUESTS_CA_BUNDLE, usado quando este não está definido. |
As duas opções podem ser combinadas: com CYCODE_CLI_ENABLE_TRUSTSTORE=1, os certificados de
REQUESTS_CA_BUNDLE são confiados além dos certificados do repositório da máquina, e não em substituição a eles.
[!TIP] Execute qualquer comando com
-vpara ver qual fonte de confiança está em uso, por exemplo,cycode -v status.
Observações:
- No Windows, a CLI sempre recorreu ao repositório de certificados do sistema quando nem
REQUESTS_CA_BUNDLEnemCURL_CA_BUNDLEestão definidos. Esse comportamento não mudou. - Os próprios proxies são configurados com as variáveis de ambiente padrão
HTTP_PROXY,HTTPS_PROXYeNO_PROXY.
Comando MCP [EXPERIMENT]
O comando Model Context Protocol (MCP) permite iniciar um servidor MCP que expõe os recursos de varredura do Cycode a sistemas e aplicativos de IA. Isso permite que modelos de IA interajam com as ferramentas da CLI do Cycode por meio de um protocolo padronizado.
[!TIP] Para obter a melhor experiência, instale a CLI do Cycode globalmente no sistema usando
pip install cycodeoubrew install cycodee autentique-se uma vez comcycode auth. Após a instalação global e a autenticação, não será necessário configurar as variáveis de ambienteCYCODE_CLIENT_IDeCYCODE_CLIENT_SECRETnos arquivos de configuração do MCP.
Iniciar o servidor MCP
Para iniciar o servidor MCP, use o seguinte comando:
cycode mcp
Por padrão, isso inicia o servidor usando o transporte stdio, adequado para integrações locais e aplicativos de IA que podem iniciar subprocessos.
Opções disponíveis
| Opção | Descrição |
|---|---|
-t, --transport | Tipo de transporte do servidor MCP: stdio, sse ou streamable-http (padrão: stdio) |
-H, --host | Endereço do host ao qual vincular o servidor (usado somente para transporte diferente de stdio) (padrão: 127.0.0.1) |
-p, --port | Número da porta à qual vincular o servidor (usado somente para transporte diferente de stdio) (padrão: 8000) |
--help | Exibe a mensagem de ajuda e as opções disponíveis |
Ferramentas MCP
O servidor MCP fornece as seguintes ferramentas que os sistemas de IA podem usar:
| Nome da ferramenta | Descrição |
|---|---|
cycode_secret_scan | Procura segredos codificados diretamente no código |
cycode_sca_scan | Faz a varredura de Software Composition Analysis (SCA) — vulnerabilidades e problemas de licença |
cycode_iac_scan | Faz a varredura de configurações incorretas de Infrastructure as Code (IaC) |
cycode_sast_scan | Faz a varredura de Static Application Security Testing (SAST) — problemas de qualidade e segurança do código |
cycode_status | Obtém a versão da CLI do Cycode, o status da autenticação e informações de configuração |
Cada ferramenta de varredura aceita dois modos de entrada mutuamente exclusivos:
paths(preferencial) — um ou mais caminhos de arquivos ou diretórios existentes no disco. Os diretórios são verificados recursivamente. O mecanismo do Cycode cuida da descoberta e filtragem de arquivos, assim comocycode scan -t <type> path ./srcfaz na CLI.files(alternativo) — um dicionário que associa caminhos de arquivos ao conteúdo completo deles como strings. Use essa opção somente quando os arquivos não estiverem disponíveis no disco (por exemplo, edições em memória ainda não salvas).
[!TIP] Use
pathssempre que possível. Passar arquivos grandes (comopackage-lock.json) como conteúdo embutido pode exceder os limites de tokens e deixar o cliente de IA mais lento. Compaths, o mecanismo do Cycode lê os arquivos diretamente do disco.
Todas as ferramentas de varredura retornam um objeto JSON que inclui um campo "summary" com uma contagem de violações legível por humanos (por exemplo, "Cycode found 3 violations: 1 CRITICAL, 2 HIGH."), além do array completo "detections".
Exemplos de uso
Exemplos básicos de comandos
Inicie o servidor MCP com as configurações padrão (transporte stdio):
cycode mcp
Inicie o servidor MCP com o transporte stdio explícito:
cycode mcp -t stdio
Inicie o servidor MCP com o transporte Server-Sent Events (SSE):
cycode mcp -t sse -p 8080
Inicie o servidor MCP com o transporte HTTP streamable em um host e uma porta personalizados:
cycode mcp -t streamable-http -H 0.0.0.0 -p 9000
Saiba mais sobre os tipos de transporte do MCP em MCP Protocol Specification – Transports.
Exemplos de configuração
Usar MCP com Cursor/VS Code/Claude Desktop/etc. (mcp.json)
[!NOTE] Para ambientes Cycode da UE, defina os valores apropriados de
CYCODE_API_URLeCYCODE_APP_URLnas variáveis de ambiente (por exemplo,https://api.eu.cycode.comehttps://app.eu.cycode.com).
Siga este guia para configurar o servidor MCP no VS Code/GitHub Copilot. Lembre-se de que em settings.json há um objeto mcp que contém um subobjeto aninhado servers, em vez de um objeto mcpServers independente.
Para transporte stdio (execução direta):
{
"mcpServers": {
"cycode": {
"command": "cycode",
"args": ["mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
Para transporte stdio com instalação de pipx:
{
"mcpServers": {
"cycode": {
"command": "pipx",
"args": ["run", "cycode", "mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
Para transporte stdio com instalação de uvx:
{
"mcpServers": {
"cycode": {
"command": "uvx",
"args": ["cycode", "mcp"],
"env": {
"CYCODE_CLIENT_ID": "your-cycode-id",
"CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
"CYCODE_API_URL": "https://api.cycode.com",
"CYCODE_APP_URL": "https://app.cycode.com"
}
}
}
}
Para transporte SSE (Server-Sent Events):
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
Para transporte SSE em uma porta personalizada:
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8080/sse"
}
}
}
Para transporte HTTP streamable:
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/mcp"
}
}
}
Executar o servidor MCP em segundo plano
Para transporte SSE (inicie o servidor primeiro e depois configure o cliente):
# Start the MCP server in the background
cycode mcp -t sse -p 8000 &
# Configure in mcp.json
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
Para transporte HTTP streamable:
# Start the MCP server in the background
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &
# Configure in mcp.json
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.2:9000/mcp"
}
}
}
Configuração avançada
Tempos limite e certificados personalizados (ambientes com proxy)
Se o cliente MCP interromper varreduras de longa duração antes que sejam concluídas, aumente o tempo limite da chamada da ferramenta.
| Variável de ambiente | Descrição |
|---|---|
MCP_TOOL_TIMEOUT | Tempo limite (em segundos) que clientes MCP, como Claude e GitHub Copilot, aguardam a conclusão de uma chamada de ferramenta. Aumente esse valor se varreduras de longa duração forem interrompidas antes de terminar. |
Em uma rede com proxy corporativo, defina as variáveis de certificado no bloco env do servidor MCP. Consulte
Certificados e proxies para ver as opções: use
CYCODE_CLI_ENABLE_TRUSTSTORE=1 para utilizar os certificados já instalados na máquina ou
REQUESTS_CA_BUNDLE para apontar para um arquivo de pacote de CAs.
Exemplo de configuração mcp.json com um pacote de CAs personalizado e um tempo limite maior:
{
"mcpServers": {
"cycode": {
"command": "cycode",
"args": ["mcp"],
"env": {
"REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
"MCP_TOOL_TIMEOUT": "1800"
}
}
}
}
[!NOTE] O servidor MCP requer autenticação válida da CLI do Cycode para funcionar. Autentique-se usando
cycode authou configure suas credenciais antes de iniciar o servidor MCP.
Pré-autorizar ferramentas para subagentes (Claude Code)
Quando o Claude Code delega tarefas a subagentes em segundo plano (por exemplo, para executar varreduras em paralelo), esses subagentes não podem exibir solicitações interativas de permissão. Se as ferramentas do Cycode não tiverem sido pré-aprovadas, as varreduras falharão silenciosamente nos contextos de subagentes.
Para pré-autorizar as ferramentas MCP do Cycode para que funcionem em todos os contextos, inclusive nos subagentes, adicione-as à lista allowedTools nas configurações do Claude Code (~/.claude/settings.json):
{
"allowedTools": [
"mcp__cycode__cycode_secret_scan",
"mcp__cycode__cycode_sca_scan",
"mcp__cycode__cycode_iac_scan",
"mcp__cycode__cycode_sast_scan",
"mcp__cycode__cycode_status"
]
}
Depois de adicionadas, o Claude Code não solicitará aprovação quando essas ferramentas forem chamadas, e elas funcionarão corretamente nos subagentes.
Solução de problemas do MCP
Se você encontrar problemas com o servidor MCP, poderá habilitar o registro de depuração para obter informações mais detalhadas sobre o que está acontecendo. Há duas maneiras de habilitar o registro de depuração:
- Usando a opção
-vou--verbose:
cycode -v mcp
- Usando a variável de ambiente
CYCODE_CLI_VERBOSE:
CYCODE_CLI_VERBOSE=1 cycode mcp
Os registros de depuração mostrarão informações detalhadas sobre:
- Inicialização e configuração do servidor
- Tentativas e status de conexão
- Execução e resultados das ferramentas
- Erros ou avisos que ocorrerem
Essas informações podem ser úteis para:
- Diagnosticar problemas de conexão
- Entender por que determinadas ferramentas não estão funcionando
- Identificar problemas de autenticação
- Depurar problemas específicos do transporte
Configuração do MCP
Comando Platform [BETA]
[!WARNING] O comando
platformestá em beta. Os comandos, argumentos e formatos de saída são gerados dinamicamente a partir da especificação da API do Cycode e podem mudar entre versões sem aviso prévio. Ainda não dependa deles em automações de produção.
O comando cycode platform expõe as APIs de leitura da plataforma Cycode como comandos da CLI. Ele agrupa endpoints por recurso (por exemplo, projects, violations, workflows) e transforma os parâmetros de cada endpoint em argumentos tipados da CLI e sinalizadores --option.
cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>
A especificação OpenAPI é obtida da API do Cycode no primeiro uso e armazenada em cache em ~/.cycode/openapi-spec.json por 24 horas. Comandos não relacionados (cycode scan, cycode status etc.) não iniciam uma busca.
[!NOTE] Você precisa estar autenticado (
cycode authou pelas variáveis de ambienteCYCODE_CLIENT_ID/CYCODE_CLIENT_SECRET) para quecycode platformdescubra e execute comandos. Outros comandos da CLI do Cycode funcionam sem autenticação.
Descobrir comandos
Como os comandos são gerados a partir da especificação, a fonte de verdade sobre o que está disponível é --help:
cycode platform --help # list all resource groups
cycode platform projects --help # list actions on a resource
cycode platform projects list --help # list options/arguments for an action
Exemplos de plataforma
# List projects with pagination
cycode platform projects list --page-size 25
# View a single project by ID
cycode platform projects view <project-id>
# Count violations across the tenant
cycode platform violations count
# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL
Por padrão, toda a saída é JSON — use um pipe para enviá-la a jq e fazer filtragens pontuais:
cycode platform projects list --page-size 100 | jq '.items[].name'
Observações e limitações da plataforma
- Somente leitura por enquanto. Apenas endpoints
GETsão expostos nesta versão beta. - Orientado pela especificação. A inclusão de um novo endpoint na API o disponibiliza automaticamente na próxima atualização do cache.
- Sem especificação incluída. A primeira invocação de
cycode platformapós a instalação (ou após a expiração do cache de 24 h) busca os dados pela rede. Em conexões lentas, essa primeira chamada pode levar alguns segundos; as chamadas seguintes são quase instantâneas até o cache expirar. - Substitua o TTL do cache com
CYCODE_SPEC_CACHE_TTL=<seconds>.
Proteções de IA [BETA]
O AI Guardrails instala hooks em agentes de programação com IA compatíveis (Claude Code, Cursor, Copilot, Codex) para que prompts, arquivos lidos pelo agente e argumentos de ferramentas MCP sejam verificados em busca de segredos antes de chegarem ao modelo.
Dados coletados pelo AI Guardrails
A verificação ocorre no servidor, portanto, o conteúdo verificado sai da máquina: o texto do prompt, o conteúdo dos arquivos lidos pelo agente e os argumentos das ferramentas MCP são enviados ao seu tenant do Cycode para verificar se contêm segredos.
Cada evento também é relatado com informações contextuais sobre o desenvolvedor e a máquina, para que uma descoberta possa ser atribuída ao dispositivo e ao usuário de origem. Algumas dessas informações são dados pessoais:
- Identificadores do dispositivo — o nome do host da máquina e o número de série do hardware.
- Identificadores do usuário — o endereço de e-mail do usuário conectado ao agente de programação com IA e o nome de usuário do sistema operacional local.
- Detalhes do ambiente — sistema operacional e versão, agente de IA, versão e modelo em uso, conteúdo dos arquivos de configuração MCP do agente e plugins habilitados.
O número de série do hardware é armazenado em cache em um arquivo temporário local, legível apenas pelo usuário que executou o comando, para que invocações repetidas do hook não consultem o hardware novamente.
Se a coleta desses dados não for aceitável no seu ambiente, não instale os hooks do guardrails
(cycode ai-guardrails uninstall remove os hooks já instalados).
Comando de verificação
Executar uma verificação
O aplicativo Cycode CLI oferece vários tipos de verificação para que você escolha a opção mais adequada ao seu caso. Estas são as opções e os comandos disponíveis atualmente:
| Opção | Descrição |
|---|---|
-t, --scan-type [secret|iac|sca|sast] | Especifique a verificação que deseja executar (secret/iac/sca/sast); o padrão é secret. |
--show-secret BOOLEAN | Exiba segredos em texto simples. Consulte a seção Mostrar/ocultar segredos para mais detalhes. |
--soft-fail BOOLEAN | Execute a verificação sem falhar; sempre retorne um código de status sem erro. Consulte a seção Falha flexível para mais detalhes. |
--severity-threshold [INFO|LOW|MEDIUM|HIGH|CRITICAL] | Exiba apenas violações no nível especificado ou acima dele. |
--sca-scan | Especifique a verificação SCA que deseja executar (package-vulnerabilities/license-compliance/unmaintained-packages/malicious-packages). O padrão é todas. |
--monitor | Quando especificado, os resultados da verificação serão registrados no Cycode. |
--cycode-report | Exiba um link para o relatório da verificação na plataforma Cycode na saída do console. |
--no-restore | Quando especificado, o Cycode não executará o comando de restauração. Isso verificará SOMENTE as dependências diretas! |
--stop-on-error | Interrompa a verificação se ocorrer uma falha na coleta de arquivos ou na restauração de dependências, em vez de ignorar o arquivo com falha e continuar. |
--gradle-all-sub-projects | Execute o comando de restauração do gradle para todos os subprojetos. Isso deve ser executado a partir de |
--maven-settings-file | Somente para Maven, permite usar um arquivo settings.xml personalizado ao verificar dependências |
--help | Exiba as opções do comando especificado. |
| Comando | Descrição |
|---|---|
| commit-history | Verifique o histórico de commits ou faça uma verificação de diferenças entre commits específicos |
| path | Verifique os arquivos no caminho fornecido no comando |
| pre-commit | Verifique o conteúdo ainda não confirmado; também oferece suporte à verificação de diferenças locais por meio de flags (compatível com IDEs) |
| repository | Verifique o repositório git, incluindo o histórico |
Opções
Opção de gravidade
Para limitar os resultados da verificação a um limite de gravidade específico, adicione o argumento --severity-threshold ao comando de verificação.
Por exemplo, o comando a seguir verificará o repositório em busca de violações de políticas com gravidade Média ou superior:
cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase
Opção de monitoramento
[!NOTE] Esta opção está disponível apenas para verificações SCA.
Para enviar ao Cycode os resultados da verificação associados às políticas SCA encontradas em uma verificação do tipo SCA, adicione o argumento --monitor ao comando de verificação.
Por exemplo, o comando a seguir verificará o repositório em busca de violações de políticas SCA e as enviará à plataforma Cycode:
cycode scan -t sca --monitor repository ~/home/git/codebase
Opção de relatório do Cycode
Para cada verificação realizada com a CLI do Cycode, um relatório é gerado automaticamente e seus resultados são enviados ao Cycode. Esses resultados são associados às políticas relevantes (por exemplo, políticas SCA para verificações de repositório) na plataforma Cycode.
Para que o URL direto desse relatório do Cycode seja exibido na saída da CLI após a conclusão da verificação, adicione o argumento --cycode-report ao comando de verificação.
cycode scan --cycode-report repository ~/home/git/codebase
Todos os resultados das verificações da CLI aparecerão na seção CLI Logs do Cycode. Se você incluiu a flag --cycode-report no comando, um link direto para o relatório específico será exibido no terminal após os resultados da verificação.
[!WARNING] Você precisa ter a função
ownerouadminno Cycode para visualizar esta página.

A página do relatório será semelhante à imagem abaixo:

Opção de vulnerabilidades de pacotes
[!NOTE] Esta opção está disponível apenas para verificações SCA.
Para verificar uma vulnerabilidade específica de pacote no seu repositório local, adicione o argumento --sca-scan package-vulnerabilities após a opção -t sca ou --scan-type sca.
No exemplo anterior, se você quisesse executar uma verificação SCA apenas para vulnerabilidades de pacotes, poderia executar o seguinte:
cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase
Opção de conformidade de licenças
[!NOTE] Esta opção está disponível apenas para verificações SCA.
Para verificar uma branch específica do seu repositório local, adicione o argumento --sca-scan license-compliance seguido do nome da branch que deseja verificar.
No exemplo anterior, se você quisesse verificar apenas uma branch chamada dev, poderia executar o seguinte:
cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev
Opção de pacotes sem manutenção
[!NOTE] Esta opção está disponível apenas para verificações SCA.
Para verificar apenas pacotes sem manutenção (pacotes cuja verificação Maintained do OpenSSF Scorecard tem pontuação baixa, indicando pouca ou nenhuma atividade recente de commits e issues), adicione o argumento --sca-scan unmaintained-packages após a opção -t sca ou --scan-type sca.
[!NOTE] A política da sua organização controla se pacotes sem manutenção são relatados. Esta opção restringe o que uma verificação relata; ela não pode habilitar uma política desativada para o seu tenant.
No exemplo anterior, se você quisesse executar uma verificação SCA apenas para pacotes sem manutenção, poderia executar o seguinte:
cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase
Opção de pacotes maliciosos
[!NOTE] Esta opção está disponível apenas para verificações SCA.
Para verificar apenas pacotes maliciosos (dependências identificadas como malware por um aviso de segurança, em vez de apenas vulneráveis), adicione o argumento --sca-scan malicious-packages após a opção -t sca ou --scan-type sca.
As violações relacionadas a pacotes maliciosos são sempre relatadas como Critical e não têm pontuação CVSS nem versão com correção: a única medida corretiva é remover a dependência.
[!NOTE] A política da sua organização controla se pacotes maliciosos são relatados. Esta opção restringe o que uma verificação relata; ela não pode habilitar uma política desativada para o seu tenant.
No exemplo anterior, se você quisesse executar uma verificação SCA apenas para pacotes maliciosos, poderia executar o seguinte:
cycode scan -t sca --sca-scan malicious-packages repository ~/home/git/codebase
Opção de restauração de lockfile
[!NOTE] Esta opção está disponível apenas para verificações SCA.
Ao executar uma verificação SCA, a CLI do Cycode tenta automaticamente restaurar (gerar) um lockfile de dependências para cada arquivo de manifesto compatível encontrado. Isso permite verificar dependências transitivas, não apenas as listadas diretamente no manifesto. Para ignorar esta etapa e verificar apenas as dependências diretas, use a flag --no-restore.
Os seguintes ecossistemas oferecem suporte à restauração automática de lockfiles:
| Ecossistema | Arquivo de manifesto | Lockfile gerado | Ferramenta invocada (quando o lockfile não existe) |
|---|---|---|---|
| npm | package.json | package-lock.json | npm install --package-lock-only --ignore-scripts --no-audit |
| Yarn | package.json | yarn.lock | yarn install --ignore-scripts |
| pnpm | package.json | pnpm-lock.yaml | pnpm install --ignore-scripts |
| Deno | deno.json / deno.jsonc | deno.lock | (somente leitura do lockfile existente) |
| Go | go.mod | go.mod.graph | go list -m -json all + go mod graph |
| Maven | pom.xml | bcde.mvndeps | mvn dependency:tree |
| Gradle | build.gradle / build.gradle.kts | gradle-dependencies-generated.txt | gradle dependencies -q --console plain |
| SBT | build.sbt | build.sbt.lock | sbt dependencyLockWrite |
| NuGet | *.csproj | packages.lock.json | dotnet restore --use-lock-file |
| Ruby | Gemfile | Gemfile.lock | bundle --quiet |
| Poetry | pyproject.toml | poetry.lock | poetry lock |
| pip | pyproject.toml / requirements.txt | pylock.toml | pip lock . / pip lock -r requirements.txt -o pylock.toml |
| Pipenv | Pipfile | Pipfile.lock | pipenv lock |
| PHP Composer | composer.json | composer.lock | composer update --no-cache --no-install --no-scripts --ignore-platform-reqs |
Se já existir um lockfile junto ao manifesto, o Cycode o lê diretamente sem executar nenhum comando de instalação.
Pré-requisito do SBT: O plugin sbt-dependency-lock deve estar instalado. Adicione a seguinte linha a project/plugins.sbt:
addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")
Opção de interrupção em caso de erro
Por padrão, o Cycode continua a verificação mesmo que não seja possível ler um arquivo (por exemplo, devido a um erro de permissão) ou gerar um arquivo de bloqueio de dependências durante uma verificação SCA. O item com falha é ignorado com um aviso, e a verificação continua com os arquivos restantes.
Use --stop-on-error para alterar esse comportamento: a verificação é interrompida imediatamente na primeira falha desse tipo e informa o erro.
cycode scan -t sca --stop-on-error path ~/home/git/codebase
Isso é útil em pipelines de CI, nos quais uma falha silenciosa produziria um resultado de verificação incompleto. Quando --stop-on-error for acionado, você poderá corrigir o problema subjacente ou, especificamente no caso de falhas de restauração de SCA, adicionar --no-restore para ignorar a geração do arquivo de bloqueio e verificar apenas as dependências diretas.
Quando --stop-on-error é usado, a CLI diferencia erros de verificação e violações de políticas por meio de códigos de saída:
| Código de saída | Significado |
|---|---|
0 | Verificação concluída sem violações |
1 | Verificação concluída e violações encontradas |
2 | Verificação interrompida devido a um erro (somente quando --stop-on-error está definido) |
Verificação de repositório
Uma verificação de repositório examina um repositório local inteiro em busca de segredos expostos ou configurações incorretas inseguras. Esse tipo de verificação mais abrangente analisa tudo: o estado atual do repositório e o histórico de commits. Ela procura não apenas segredos atualmente expostos no repositório, mas também segredos excluídos anteriormente.
Para executar uma verificação completa do repositório, execute o seguinte:
cycode scan repository {{path}}
Por exemplo, se você quiser verificar um repositório armazenado em ~/home/git/codebase, poderá executar o seguinte:
cycode scan repository ~/home/git/codebase
A seguinte opção está disponível para uso com este comando:
| Opção | Descrição |
|---|---|
-b, --branch TEXT | Branch a verificar; se não for definida, será verificada a branch padrão |
Opção de branch
Para verificar uma branch específica do seu repositório local, adicione o argumento -b (ou, alternativamente, --branch), seguido do nome da branch que deseja verificar.
Considerando o exemplo anterior, se você quiser verificar apenas uma branch chamada dev, poderá executar o seguinte:
cycode scan repository ~/home/git/codebase -b dev
Verificação de caminho
Uma verificação de caminho examina um diretório local específico e todo o seu conteúdo, em vez de se concentrar apenas em um repositório GIT.
Para executar uma verificação de diretório, execute o seguinte:
cycode scan path {{path}}
Por exemplo, imagine que você queira verificar o diretório localizado em ~/home/git/codebase. Nesse caso, você poderá executar o seguinte:
cycode scan path ~/home/git/codebase
Verificação de plano do Terraform
A CLI do Cycode oferece suporte à verificação de planos do Terraform (compatível com Terraform 0.12 e versões posteriores).
O arquivo de plano do Terraform deve estar no formato JSON (com a extensão .json).
Se você tiver apenas um arquivo de configuração, poderá gerar um plano da seguinte forma:
-
Inicialize um diretório de trabalho que contenha um arquivo de configuração do Terraform:
terraform init -
Crie um plano de execução do Terraform e salve a saída binária:
terraform plan -out={tfplan_output} -
Converta o arquivo de saída binária em JSON legível:
terraform show -json {tfplan_output} > {tfplan}.json -
Verifique seu
{tfplan}.jsoncom a CLI do Cycode:cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json
Verificação do histórico de commits
[!NOTE] A verificação do histórico de commits não está disponível para verificações de IaC.
O comando de verificação do histórico de commits oferece dois recursos principais:
- Verificação do histórico completo: analisa todos os commits do histórico do repositório
- Verificação de diferenças: verifica apenas as alterações entre commits específicos
A verificação de segredos pode analisar todos os commits do histórico do repositório, pois segredos introduzidos e removidos posteriormente ainda podem vazar ou ficar expostos. Para verificações de SCA e SAST, o comando de histórico de commits se concentra em verificar as diferenças/alterações entre commits, sendo ideal para revisões de pull requests e verificações incrementais.
Uma verificação do histórico de commits examina o histórico de commits do seu repositório Git e pode ser usada tanto para uma análise histórica abrangente quanto para verificar diferenças específicas.
Para executar uma verificação do histórico de commits, execute o seguinte:
cycode scan commit-history {{path}}
Por exemplo, imagine que você queira verificar o histórico de commits de um repositório armazenado em ~/home/git/codebase. Nesse caso, você poderá executar o seguinte:
cycode scan commit-history ~/home/git/codebase
As seguintes opções estão disponíveis para uso com este comando:
| Opção | Descrição |
|---|---|
-r, --commit-range TEXT | Verifica um intervalo de commits neste repositório git; por padrão, o cycode verifica todo o histórico de commits (exemplo: HEAD~1) |
Opção de intervalo de commits (verificação de diferenças)
A opção de intervalo de commits permite verificar diferenças — verificar apenas as alterações entre commits específicos, em vez de todo o histórico do repositório. Isso é especialmente útil para:
- Validação de pull requests: verificar apenas as alterações introduzidas em um PR
- Verificação incremental de CI/CD: concentrar-se nas alterações recentes, em vez de em toda a base de código
- Revisão de branches de recursos: comparar alterações com a branch main/master
- Otimização de desempenho: verificações mais rápidas ao limitar o escopo às alterações relevantes
Sintaxe do intervalo de commits
A opção --commit-range (-r) oferece suporte à sintaxe padrão de revisões do Git:
| Sintaxe | Descrição | Exemplo |
|---|---|---|
commit1..commit2 | Alterações do commit1 ao commit2 | abc123..def456 |
commit1...commit2 | Alterações em commit2 que não estão em commit1 | main...feature-branch |
commit | Alterações do commit até HEAD | HEAD~1 |
branch1..branch2 | Alterações da branch1 à branch2 | main..feature-branch |
Exemplos de verificação de diferenças
Verificar as alterações do último commit:
cycode scan commit-history -r HEAD~1 ~/home/git/codebase
Verificar as alterações entre dois commits específicos:
cycode scan commit-history -r abc123..def456 ~/home/git/codebase
Verificar as alterações da sua branch de recursos em comparação com main:
cycode scan commit-history -r main..HEAD ~/home/git/codebase
Verificar as alterações entre main e uma branch de recursos:
cycode scan commit-history -r main..feature-branch ~/home/git/codebase
Verificar todas as alterações dos últimos 3 commits:
cycode scan commit-history -r HEAD~3..HEAD ~/home/git/codebase
[!TIP] Para pipelines de CI/CD, você pode usar variáveis de ambiente como
${{ github.event.pull_request.base.sha }}..${{ github.sha }}(GitHub Actions) ou$CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA(GitLab CI) para verificar apenas as alterações de PR/MR.
Verificação pré-commit
Uma verificação pré-commit identifica automaticamente problemas antes de você confirmar alterações no repositório. Não é necessário executar essa verificação manualmente; configure o hook pré-commit conforme detalhado na seção Instalação deste guia.
Depois de instalar o hook pré-commit, talvez você queira ocasionalmente ignorar a verificação durante um commit específico. Para isso, adicione o seguinte ao comando git para ignorar a verificação em um único commit:
SKIP=cycode git commit -m <your commit message>`
As seguintes opções estão disponíveis para uso com este comando:
| Opção | Descrição |
|---|---|
-b, --base-ref TEXT | Referência Git (commit, branch ou tag) para comparação; o padrão é HEAD, correspondendo ao comportamento do hook pré-commit |
--include-unstaged | Também verifica alterações não preparadas em arquivos rastreados, não apenas o que está preparado; desativado por padrão |
--path PATH | Caminho(s) opcional(is) para limitar o escopo da verificação de diferenças; pode ser repetido; o padrão é todo o diretório de trabalho |
Verificação de diferenças locais (integrações com IDEs)
--base-ref e --include-unstaged transformam pre-commit em uma verificação de diferenças locais de uso geral: comparam qualquer commit (por padrão, HEAD) com o diretório de trabalho atual, incluindo alterações que ainda não foram preparadas. Esse recurso foi criado para plugins de IDE e outras ferramentas que precisam fornecer feedback contínuo e em tempo real enquanto você trabalha, em vez de seguir o fluxo do hook do git. Em conjunto com --include-unstaged, --path permite que uma IDE limite a verificação apenas ao arquivo aberto no editor.
[!NOTE] A verificação de diferenças locais (por meio dessas flags) não está disponível para verificações de IaC.
Verificar tudo o que foi alterado até o momento (preparado e não preparado) em comparação com o último commit:
cycode scan pre-commit --include-unstaged
Verificar alterações em comparação com um commit ou uma branch específica:
cycode scan pre-commit --include-unstaged --base-ref main
Verificar apenas um arquivo específico (por exemplo, o arquivo aberto no momento na sua IDE):
cycode scan pre-commit --include-unstaged --path src/app.py
Verificação pré-push
Uma verificação pré-push identifica automaticamente problemas antes de você enviar alterações para o repositório remoto. Esse hook é executado no lado do cliente e verifica apenas os commits que estão prestes a ser enviados, tornando eficiente a detecção de problemas antes que cheguem ao repositório remoto.
[!NOTE] O hook pré-push não está disponível para verificações de IaC.
O hook pré-push integra-se à estrutura pre-commit e pode ser configurado para ser executado antes de qualquer operação git push.
Instalação do hook pré-push
Para configurar o hook pré-push usando a estrutura pre-commit:
-
Instale a estrutura pre-commit (se ainda não estiver instalada):
pip3 install pre-commit -
Crie ou atualize seu arquivo
.pre-commit-config.yamlpara incluir os hooks pré-push:repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push stages: [pre-push] -
Para vários tipos de verificação, use esta configuração:
repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push # Secrets scan stages: [pre-push] - id: cycode-sca-pre-push # SCA scan stages: [pre-push] - id: cycode-sast-pre-push # SAST scan stages: [pre-push] -
Instale o hook pré-push:
pre-commit install --hook-type pre-pushUma instalação bem-sucedida exibirá a mensagem:
Pre-push installed at .git/hooks/pre-push. -
Mantenha o hook pré-push atualizado:
pre-commit autoupdate
Como funciona a verificação pré-push
O hook verifica cada commit enviado, um de cada vez, para que um segredo adicionado em um commit e removido em outro posterior ainda seja detectado. Quando instalado por meio da estrutura pre-commit, o intervalo enviado é obtido da estrutura: novos commits desde a branch remota para branches existentes e commits ainda não presentes no remoto para branches novas (todos os commits ao enviar para um remoto vazio). Quando executado a partir de um .git/hooks/pre-push escrito manualmente, o intervalo é obtido da entrada do hook do git, e branches novas são verificadas a partir da base de mesclagem com a branch padrão (veja abaixo).
Envios sem nada a verificar, como tags, exclusões de branches e envios já atualizados, são aceitos sem verificação. Se o hook não conseguir determinar o que está sendo enviado, ele falhará e bloqueará o envio, em vez de prosseguir silenciosamente.
Os hooks pré-push do Cycode definem always_run: true e pass_filenames: false, pois a verificação abrange os commits enviados, e não uma lista de arquivos. Sem always_run, a estrutura pre-commit ignora o hook quando os commits enviados não resultam em arquivos alterados, como no caso de um segredo adicionado em um commit e excluído no seguinte. Sem pass_filenames: false, a estrutura passa nomes de arquivos alterados que a verificação não usa e, em envios grandes, divide esses arquivos em lotes e executa a verificação completa uma vez por lote. Se você definir o hook por conta própria (por exemplo, como um hook repo: local), defina ambas as opções.
Detecção inteligente da branch padrão
Quando executada a partir de um hook escrito manualmente, a verificação pré-push detecta a branch padrão para calcular a base de mesclagem usando esta ordem de prioridade:
- Variável de ambiente:
CYCODE_DEFAULT_BRANCH— permite substituição manual - HEAD remoto do Git: usa
git symbolic-ref refs/remotes/origin/HEADpara detectar a branch padrão real do remoto - Informações do remoto do Git: recorre a
git remote show originse symbolic-ref falhar - Alternativas fixas: usa nomes comuns de branches padrão (origin/main, origin/master, main, master)
Definir uma branch padrão personalizada:
export CYCODE_DEFAULT_BRANCH=origin/develop
Esta detecção inteligente garante que o hook pre-push funcione corretamente, independentemente de o seu repositório usar main, master, develop ou qualquer outro nome de branch padrão.
Ignorar verificações pre-push
Para ignorar a verificação pre-push em uma operação de push específica, use:
SKIP=cycode-pre-push git push
Ou, para ignorar todos os hooks pre-push:
git push --no-verify
[!TIP] O hook pre-push é acionado no comando
git pushe verifica apenas os commits que estão prestes a ser enviados, tornando-o mais eficiente do que verificar o repositório inteiro.
Excluir caminhos das verificações
Você pode usar um arquivo .cycodeignore para informar à CLI do Cycode quais arquivos e diretórios devem ser excluídos das verificações.
Ele funciona como um arquivo .gitignore. Isso ajuda você a concentrar as verificações no código relevante e a impedir que determinados caminhos gerem violações localmente.
Como funciona
- Crie um arquivo chamado
.cycodeignorena sua pasta de trabalho. - Liste os arquivos e diretórios que deseja excluir, usando os mesmos padrões de
.gitignore. - Coloque esse arquivo no diretório em que você pretende executar o comando cycode scan.
[!WARNING]
- Arquivos inválidos: se o arquivo
.cycodeignorecontiver um erro de sintaxe, a verificação da CLI falhará e retornará um erro.- Ignorar caminhos vs. violações: este arquivo serve para excluir caminhos. Ele é diferente da capacidade da CLI de ignorar violações específicas (por exemplo, usando a flag --ignore-violation).
Scanners compatíveis
- SAST
- IaC (em breve)
- SCA (em breve)
Resultados da verificação
Cada verificação será concluída com uma mensagem informando se foram encontrados problemas.
Se nenhum problema for encontrado, a verificação terminará com a seguinte mensagem de sucesso:
Good job! No issues were found!!! 👏👏👏
Se um problema for encontrado, um cartão de violação será exibido ao final. Nesse caso, revise o arquivo em questão e a linha específica destacada pela mensagem de resultado. Faça as alterações necessárias para resolver o problema e execute a verificação novamente.
Mostrar/ocultar segredos
Nos exemplos abaixo, um segredo foi encontrado no arquivo secret_test, localizado na subpasta cli. A segunda parte da mensagem mostra a linha específica em que o segredo aparece, que, neste caso, contém um valor atribuído a googleApiKey.
Observe que o exemplo oculta o valor real do segredo, substituindo a maior parte dele por asteriscos. Por padrão, as verificações ocultam os segredos, mas você pode desativar esse recurso para ver o segredo completo (desde que a máquina em que você está visualizando o resultado da verificação esteja suficientemente protegida contra olhares indiscretos).
Para desativar a ofuscação de segredos, adicione o argumento --show-secret a qualquer tipo de verificação.
No exemplo a seguir, uma verificação de caminho é executada no subdiretório cli com a opção de exibir por completo os segredos encontrados ativada:
cycode scan --show-secret path ./cli
O resultado não será ofuscado.
Falha flexível
Em condições normais, a CLI retorna o código de saída 1 quando são encontrados problemas nos resultados da verificação. Dependendo da configuração de CI/CD, isso geralmente resultará em uma falha geral. Se não quiser que isso aconteça, você pode usar o recurso de falha flexível.
Ao adicionar a opção --soft-fail a qualquer tipo de verificação, o código de saída será definido como 0, independentemente de haver resultados.
Exemplos de resultados de verificação
Exemplo de resultado de Secrets
╭─────────────────────────────────────────────────────────────── Hardcoded generic-password is used ───────────────────────────────────────────────────────────────╮
│ Violation 12 of 12 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 34 }; │ │
│ │ In file /Users/cycodemacuser/NodeGoat/test/s │ │ 35 │ │
│ │ ecurity/profile-test.js │ │ 36 var sutUserName = "user1"; │ │
│ │ Secret SHA b4ea3116d868b7c982ee6812cce61727856b │ │ ❱ 37 var sutUserPassword = "Us*****23"; │ │
│ │ 802b3063cd5aebe7d796988552e0 │ │ 38 │ │
│ │ Rule ID 68b6a876-4890-4e62-9531-0e687223579f │ │ 39 chrome.setDefaultService(service); │ │
│ ╰────────────────────────────────────────────────────╯ │ 40 │ │
│ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ A generic secret or password is an authentication token used to access a computer or application and is assigned to a password variable. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Exemplo de resultado de IaC
╭──────────── Enable Content Encoding through the attribute 'MinimumCompressionSize'. This value should be greater than -1 and smaller than 10485760. ─────────────╮
│ Violation 45 of 110 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 20 BinaryMediaTypes: │ │
│ │ In file ...ads-copy/iac/cft/api-gateway/ap │ │ 21 - !Ref binaryMediaType1 │ │
│ │ i-gateway-rest-api/deploy.yml │ │ 22 - !Ref binaryMediaType2 │ │
│ │ IaC Provider CloudFormation │ │ ❱ 23 MinimumCompressionSize: -1 │ │
│ │ Rule ID 33c4b90c-3270-4337-a075-d3109c141b │ │ 24 EndpointConfiguration: │ │
│ │ 53 │ │ 25 Types: │ │
│ ╰────────────────────────────────────────────────────╯ │ 26 - EDGE │ │
│ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ This policy validates the proper configuration of content encoding in AWS API Gateway. Specifically, the policy checks for the attribute │ │
│ │ 'minimum_compression_size' in API Gateway REST APIs. Correct configuration of this attribute is important for enabling content encoding of API responses for │ │
│ │ improved API performance and reduced payload sizes. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Exemplo de resultado de SCA
╭─────────────────────────────────────────────────────── [CVE-2019-10795] Prototype Pollution in undefsafe ────────────────────────────────────────────────────────╮
│ Violation 172 of 195 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 26758 "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=", │ │
│ │ In file /Users/cycodemacuser/Node │ │ 26759 "dev": true │ │
│ │ Goat/package-lock.json │ │ 26760 }, │ │
│ │ CVEs CVE-2019-10795 │ │ ❱ 26761 "undefsafe": { │ │
│ │ Package undefsafe │ │ 26762 "version": "2.0.2", │ │
│ │ Version 2.0.2 │ │ 26763 "resolved": "https://registry.npmjs.org/undefsafe/-/undefsafe-2.0.2.tgz", │ │
│ │ First patched version Not fixed │ │ 26764 "integrity": "sha1-Il9rngM3Zj4Njnz9aG/Cg2zKznY=", │ │
│ │ Dependency path nodemon 1.19.1 -> │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │ undefsafe 2.0.2 │ │
│ │ Rule ID 9c6a8911-e071-4616-86db-4 │ │
│ │ 943f2e1df81 │ │
│ ╰────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ undefsafe before 2.0.3 is vulnerable to Prototype Pollution. The 'a' function could be tricked into adding or modifying properties of Object.prototype using │ │
│ │ a __proto__ payload. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Exemplo de resultado de SAST
╭───────────────────────────────────────────── [CWE-208: Observable Timing Discrepancy] Observable Timing Discrepancy ─────────────────────────────────────────────╮
│ Violation 24 of 49 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Severity 🟠 MEDIUM │ │ 173 " including numbers, lowercase and uppercase letters."; │ │
│ │ In file /Users/cycodemacuser/NodeGoat/app │ │ 174 return false; │ │
│ │ /routes/session.js │ │ 175 } │ │
│ │ CWE CWE-208 │ │ ❱ 176 if (password !== verify) { │ │
│ │ Subcategory Security │ │ 177 errors.verifyError = "Password must match"; │ │
│ │ Language js │ │ 178 return false; │ │
│ │ Security Tool Bearer (Powered by Cycode) │ │ 179 } │ │
│ │ Rule ID 19fbca07-a8e7-4fa6-92ac-a36d15509 │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │ fa9 │ │
│ ╰────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Observable Timing Discrepancy occurs when the time it takes for certain operations to complete can be measured and observed by attackers. This vulnerability │ │
│ │ is particularly concerning when operations involve sensitive information, such as password checks or secret comparisons. If attackers can analyze how long │ │
│ │ these operations take, they might be able to deduce confidential details, putting your data at risk. │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Diretrizes personalizadas de correção da empresa
Se a sua empresa tiver definido diretrizes personalizadas de correção na política relevante pelo portal do Cycode, você verá um campo “Diretrizes da empresa” com as diretrizes de correção adicionadas. Se você não tiver adicionado diretrizes da empresa, esse campo não aparecerá na ferramenta de CLI.
Ignorar resultados da verificação
É possível adicionar regras de ignorar para valores específicos de segredos, valores SHA512 específicos, caminhos específicos e IDs de regras específicas de Secrets e IaC do Cycode. Isso fará com que a verificação não gere alertas para esses valores. As regras de ignorar são escritas e salvas localmente no arquivo ./.cycode/config.yaml.
[!WARNING] A inclusão de valores a serem ignorados deve ser feita com cuidado, considerando os valores, caminhos e políticas, para garantir que as verificações detectem os verdadeiros positivos.
Estas são as opções disponíveis para o comando cycode ignore:
| Opção | Descrição |
|---|---|
--by-value TEXT | Ignora um valor específico durante a verificação de segredos. Consulte Ignorar um valor de segredo para mais detalhes. |
--by-sha TEXT | Ignora uma representação SHA512 específica de uma string durante a verificação de segredos. Consulte Ignorar um valor SHA de segredo para mais detalhes. |
--by-path TEXT | Evita a verificação de um caminho específico. É necessário especificar o tipo de verificação. Consulte Ignorar um caminho para mais detalhes. |
--by-rule TEXT | Ignora a verificação de um ID de regra específico de Secrets/IaC/SCA. Consulte Ignorar uma regra de Secrets ou IaC para mais detalhes. |
--by-package TEXT | Ignora a verificação de uma versão específica de pacote durante uma verificação de SCA. Padrão esperado - name@version. Consulte Ignorar um pacote para mais detalhes. |
--by-cve TEXT | Ignora a verificação de um CVE específico durante uma verificação de SCA. Padrão esperado: CVE-YYYY-NNN. |
-t, --scan-type [secret|iac|sca|sast] | Especifica a verificação que você deseja executar (secret/iac/sca/sast). O valor padrão é secret. |
-g, --global | Adiciona uma regra de ignorar e a atualiza no arquivo de configuração global .cycode. |
Ignorar um valor de segredo
Para ignorar um valor de segredo específico, use a flag --by-value. Isso fará com que o valor de segredo fornecido seja ignorado em todas as verificações futuras. Use o seguinte comando para adicionar um valor de segredo à lista de ignorados:
cycode ignore --by-value {{secret-value}}
No exemplo no início desta seção, o comando para ignorar um valor de segredo específico é:
cycode ignore --by-value h3110w0r1d!@#$350
No exemplo acima, substitua o valor h3110w0r1d!@#$350 pelo valor do seu segredo sem máscara. Consulte as opções de verificação do Cycode para saber como exibir os valores dos segredos nos resultados da verificação.
Ignorar um valor SHA de segredo
Para ignorar um valor SHA de segredo específico, use a flag --by-sha. Isso fará com que o valor SHA de segredo fornecido seja ignorado em todas as verificações futuras. Use o seguinte comando para adicionar um valor SHA de segredo à lista de ignorados:
cycode ignore --by-sha {{secret-sha-value}}
No exemplo no início desta seção, o comando para ignorar um valor SHA de segredo específico é:
cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
No exemplo acima, substitua o valor a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 pelo valor SHA do seu segredo.
Ignorar um caminho
Para ignorar um caminho específico nas verificações de Secrets, IaC ou SCA, use a flag --by-path junto com a flag -t, --scan-type (é necessário especificar o tipo de verificação). Isso fará com que o caminho fornecido seja ignorado em todas as verificações futuras do tipo especificado. Use o seguinte comando para adicionar um caminho à lista de ignorados:
cycode ignore -t {{scan-type}} --by-path {{path}}
No exemplo no início desta seção, o comando para ignorar um caminho específico em uma verificação de Secrets é:
cycode ignore -t secret --by-path ~/home/my-repo/config
No exemplo acima, substitua o valor ~/home/my-repo/config pelo caminho desejado.
No exemplo no início desta seção, o comando para ignorar um caminho específico nas verificações de IaC é:
cycode ignore -t iac --by-path ~/home/my-repo/config
No exemplo acima, substitua o valor ~/home/my-repo/config pelo caminho desejado.
No exemplo no início desta seção, o comando para ignorar um caminho específico nas verificações de SCA é:
cycode ignore -t sca --by-path ~/home/my-repo/config
No exemplo acima, substitua o valor ~/home/my-repo/config pelo caminho desejado.
Ignorar uma regra de Secrets, IaC, SCA ou SAST
Para ignorar uma regra específica de Secrets, IaC, SCA ou SAST, use a flag --by-rule junto com a flag -t, --scan-type (é necessário especificar o tipo de verificação). Isso fará com que o ID da regra fornecido seja ignorado em todas as verificações futuras. Use o seguinte comando para adicionar um ID de regra à lista de ignorados:
cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}
No exemplo no início desta seção, o comando para ignorar o ID de uma regra específica de Secrets é:
cycode ignore -t secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710
No exemplo acima, substitua o valor ce3a4de0-9dfc-448b-a004-c538cf8b4710 pelo ID da regra que deseja ignorar.
No exemplo no início desta seção, o comando para ignorar o ID de uma regra específica de IaC é:
cycode ignore -t iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c
No exemplo acima, substitua o valor bdaa88e2-5e7c-46ff-ac2a-29721418c59c pelo ID da regra que deseja ignorar.
No exemplo no início desta seção, o comando para ignorar o ID de uma regra específica de SCA é:
cycode ignore -t sca --by-rule dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b
No exemplo acima, substitua o valor dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b pelo ID da regra que deseja ignorar.
Ignorar um pacote
[!NOTE] Esta opção está disponível apenas para verificações de SCA.
Para ignorar um pacote específico nas verificações de SCA, use a flag --by-package junto com a flag -t, --scan-type (é necessário especificar o tipo de verificação sca). Isso fará com que o pacote fornecido, usando o formato {{package_name}}@{{package_version}}, seja ignorado em todas as verificações futuras. Use o seguinte comando para adicionar um pacote e uma versão à lista de ignorados:
cycode ignore --scan-type sca --by-package {{package_name}}@{{package_version}}
OU
cycode ignore -t sca --by-package {{package_name}}@{{package_version}}
No exemplo abaixo, o comando para ignorar um pacote específico de SCA é:
cycode ignore --scan-type sca --by-package pyyaml@5.3.1
No exemplo acima, substitua pyyaml pelo nome do pacote e 5.3.1 pela versão do pacote que deseja ignorar.
Ignorar por meio de um arquivo de configuração
As regras de ignorar aplicadas são armazenadas no arquivo de configuração chamado config.yaml.
Esse arquivo pode ser facilmente compartilhado entre desenvolvedores ou até mesmo enviado para um repositório Git remoto.
Esses arquivos estão sempre localizados na pasta .cycode.
O nome da pasta começa com um ponto (.), e você deve habilitar a exibição de arquivos ocultos para vê-la.
Caminho dos arquivos de configuração
Por padrão, todos os comandos cycode ignore salvam a regra de ignorar no diretório atual em que a CLI foi executada.
Exemplo: executar um comando de ignorar da CLI em /Users/name/projects/backend criará config.yaml em /Users/name/projects/backend/.cycode
➜ backend pwd
/Users/name/projects/backend
➜ backend cycode ignore --by-value test-value
➜ backend tree -a
.
└── .cycode
└── config.yaml
2 directories, 1 file
A segunda opção é salvar as regras de ignorar nos arquivos de configuração globais.
O caminho da configuração global é ~/.cycode/config.yaml,
em que ~ significa users home directory, for example, /Users/name` no macOS.
É possível salvar no espaço global usando a flag -g do comando cycode ignore.
Por exemplo: cycode ignore -g --by-value test-value.
Diretório de trabalho correto
É extremamente importante colocar a pasta .cycode e executar a CLI no mesmo local.
Verifique isso com atenção ao trabalhar em diferentes ambientes, como CI/CD (GitHub Actions, Jenkins etc.).
Você pode enviar a pasta .cycode para a raiz do seu repositório. Nesse caso, execute as verificações da CLI a partir da raiz do repositório. Se isso não atender aos seus requisitos, você pode copiar temporariamente a pasta .cycode para o local desejado e executar uma verificação da CLI a partir dessa pasta.
Regras de ignorar estrutura na configuração
É importante entender como a CLI armazena as regras ignoradas para poder ler esses arquivos de configuração ou até mesmo modificá-los sem a CLI.
A estrutura YAML abstrata:
exclusions:
{scanTypeName}:
{ignoringType}:
- someIgnoringValue1
- someIgnoringValue2
Valores possíveis de scanTypeName: iac, sca, sast, secret.
Valores possíveis de ignoringType: paths, values, rules, packages, shas, cves.
[!WARNING] Os valores de "ignorar por valor" não são armazenados como texto simples! A CLI armazena hashes sha256 dos valores. Ao modificar o arquivo de configuração manualmente, você deve inserir hashes da string.
Exemplo real de config.yaml:
exclusions:
iac:
rules:
- bdaa88e2-5e7c-46ff-ac2a-29721418c59c
sca:
packages:
- pyyaml@5.3.1
secret:
paths:
- /Users/name/projects/build
rules:
- ce3a4de0-9dfc-448b-a004-c538cf8b4710
shas:
- a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
values:
- a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
- 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752
Comando Report
Gerar relatório SBOM
Uma lista de materiais de software (SBOM) é um inventário de todos os componentes constituintes e dependências de software envolvidos no desenvolvimento e na entrega de um aplicativo. Com este comando, você pode criar um relatório SBOM para seu projeto local ou para o URI do seu repositório.
As opções a seguir estão disponíveis para uso com este comando:
| Opção | Descrição | Obrigatório | Padrão |
|---|---|---|---|
-f, --format [spdx-2.2|spdx-2.3|cyclonedx-1.4] | Formato SBOM | Sim | |
-o, --output-format [JSON] | Especificar o formato do arquivo de saída | Não | json |
--output-file PATH | Arquivo de saída | Não | nome de arquivo gerado automaticamente, salvo no diretório atual |
--include-vulnerabilities | Incluir vulnerabilidades | Não | False |
--include-dev-dependencies | Incluir dependências de desenvolvimento | Não | False |
Os comandos a seguir estão disponíveis para uso com este comando:
| Comando | Descrição |
|---|---|
path | Gerar relatório SBOM para o caminho fornecido no comando |
repository-url | Gerar relatório SBOM para o URI do repositório fornecido no comando |
Repositório
Para criar um relatório SBOM para um URI de repositório:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>
Por exemplo:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git
Projeto local
Para criar um relatório SBOM para um caminho:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>
Por exemplo:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project
O subcomando path oferece suporte às seguintes opções adicionais:
| Opção | Descrição |
|---|---|
--no-restore | Ignorar a restauração do arquivo de lock e verificar apenas as dependências diretas. Consulte Opção de restauração do lock para obter detalhes. |
--gradle-all-sub-projects | Executar o comando de restauração do Gradle para todos os subprojetos (use na raiz de uma compilação Gradle com vários projetos). |
--maven-settings-file | Somente para Maven, permite usar um arquivo settings.xml personalizado ao criar a árvore de dependências. |
Comando Import
Importar SBOM
Uma lista de materiais de software (SBOM) é um inventário de todos os componentes constituintes e dependências de software envolvidos no desenvolvimento e na entrega de um aplicativo. Com este comando, você pode importar um arquivo SBOM do seu sistema de arquivos para o Cycode.
As opções a seguir estão disponíveis para uso com este comando:
| Opção | Descrição | Obrigatório | Padrão |
|---|---|---|---|
-n, --name TEXT | Nome de exibição do SBOM | Sim | |
-v, --vendor TEXT | Nome da entidade que forneceu o SBOM | Sim | |
-l, --label TEXT | Anexar rótulo ao SBOM | Não | |
-o, --owner TEXT | Endereço de e-mail do usuário do Cycode que serve como ponto de contato para este SBOM | Não | |
-b, --business-impact [High | Medium | Low] | Impacto nos negócios | Não | Médio |
Por exemplo:
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner example@cycode.com /path/to/local/project
Logs de verificação
Todas as verificações da CLI são registradas no Cycode. Os logs podem ser encontrados em Configurações > Logs da CLI.
Ajuda de sintaxe
Você pode adicionar o argumento --help a qualquer comando a qualquer momento para ver uma mensagem de ajuda que exibirá as opções disponíveis e sua sintaxe.
Para ver a ajuda geral, basta inserir o comando:
cycode --help
Para ver as opções de verificação, insira:
cycode scan --help
Para ver as opções disponíveis para um tipo específico de verificação, insira:
cycode scan {{option}} --help
Por exemplo, para ver as opções disponíveis para uma verificação de caminho, você deve inserir:
cycode scan path --help
Para ver as opções disponíveis para a função de ignorar verificação, use este comando:
cycode ignore --help
Para ver as opções disponíveis para um relatório, use este comando:
cycode report --help
Para ver as opções disponíveis para um tipo específico de relatório, insira:
cycode scan {{option}} --help