Cycode

oficial

Aumente a segurança no seu ciclo de vida de desenvolvimento com varredura SAST, SCA, Secrets e IaC com Cycode.

GitHub

Experimente este MCPPatrocinado

O que você pode fazer com Cycode MCP?

Escanear um caminho de repositório em busca de segredos hardcoded — Peça ao assistente para executar cycode_secret_scan em um diretório local para detectar credenciais expostas.
Verificar dependências em busca de vulnerabilidades conhecidas — Acione cycode_sca_scan em um caminho de projeto para identificar pacotes de código aberto vulneráveis ou não conformes.
Auditar arquivos de Infrastructure as Code para configurações incorretas — Use cycode_iac_scan em diretórios do Terraform ou CloudFormation para revelar configurações arriscadas.
Revisar o código-fonte em busca de falhas de segurança — Execute cycode_sast_scan em uma base de código para encontrar fraquezas no nível do código e problemas de qualidade.
Verificar a autenticação da CLI e o status da versão — Chame cycode_status para confirmar a conexão com a Cycode e qual versão está ativa.

Documentação

Guia do Usuário do Cycode CLI

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ção estática.

Este guia orienta você pela instalação e uso.

Sumário

Pré-requisitos
Instalação
1. Instalar o Cycode CLI
2. Instalar o hook de pré-commit
Comandos do Cycode CLI
Comando MCP
Comando Platform
Proteções de IA
1. Dados coletados pelas Proteções de IA
Comando Scan
Comando Report
1. Gerando relatório SBOM
Comando Import
Logs de varredura
Ajuda de sintaxe

Pré-requisitos

O aplicativo Cycode CLI requer a versão 3.9 ou posterior do Python. O comando MCP está disponível apenas para Python 3.10 e superior. Se você estiver usando uma versão anterior do Python, este comando não estará disponível.
Use o comando cycode auth para autenticar no Cycode com a CLI
- Alternativamente, você pode obter um ID de Cliente e uma Chave Secreta de Cliente do Cycode seguindo os passos detalhados nas páginas Token de Conta de Serviço e Token de Acesso Pessoal, que contêm detalhes sobre como obter esses valores.

Instalação

As etapas de instalação a seguir são aplicáveis tanto para sistemas operacionais Windows quanto UNIX/Linux.

[!NOTE] As etapas a seguir pressupõem o uso de python3 e pip3 para comandos relacionados ao Python; no entanto, alguns sistemas podem usar os comandos python e pip em vez disso, dependendo da configuração do seu ambiente Python.

Instalar o Cycode CLI

Para instalar o aplicativo Cycode CLI na sua máquina local, execute as seguintes etapas:

Abra seu aplicativo de linha de comando ou terminal.
Execute um dos seguintes comandos:
- Para instalar a partir do PyPI:
```
pip3 install cycode
```
- Para instalar a partir do Homebrew:
```
brew install cycode
```
- Para instalar a partir do GitHub Releases, navegue e baixe o executável para seu sistema operacional e arquitetura, e então execute o seguinte comando:
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
Por fim, autentique a CLI. Existem três métodos para definir o ID do cliente e as credenciais (segredo do cliente ou token de ID OIDC) do Cycode:
- 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 autenticar com o Cycode CLI.

Digite o seguinte comando na sua janela de terminal/linha de comando:

cycode auth
Uma janela do navegador aparecerá, pedindo que você faça login no Cycode (como visto abaixo):
Insira suas credenciais de login nesta página e faça login.
Você será eventualmente levado à página abaixo, onde será solicitado a escolher o grupo de negócios que deseja autorizar com o Cycode (se aplicável):

[!NOTE] Este será o método padrão para autenticar com o Cycode CLI.
Clique no botão Permitir para autorizar o Cycode CLI no grupo de negócios selecionado.
Após a conclusão, você verá a seguinte tela se foi selecionado com sucesso:
Na tela do terminal/linha de comando, você verá o seguinte ao sair da janela do navegador:

Successfully logged into cycode

Usando o comando Configure

[!NOTE] Se você já configurou seu ID de Cliente e Segredo de Cliente do Cycode por meio das variáveis de ambiente do Linux ou Windows, essas credenciais terão precedência sobre este método.

Digite o seguinte comando na sua janela de 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 App do 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 seu ID de Cliente do Cycode.

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
Insira o valor do seu Segredo de Cliente do Cycode (pule se você planeja usar um token de ID OIDC).

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Insira o valor do seu Token de ID OIDC do Cycode (opcional).

Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Se os valores foram inseridos com sucesso, você verá a seguinte mensagem:

Successfully configured CLI credentials!

ou/e

Successfully configured Cycode URLs!

Se você entrar na pasta .cycode na sua pasta de usuário, verá que essas credenciais foram criadas e colocadas no arquivo credentials.yaml nessa pasta. As URLs foram colocadas no arquivo config.yaml nessa pasta.

Adicionar às variáveis de ambiente

No Unix/Linux:

export CYCODE_CLIENT_ID={your Cycode ID}

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 adicionalmente):

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

No Windows

No Painel de Controle, navegue até o menu Sistema:
Em seguida, clique em Configurações avançadas do sistema:
Na janela Propriedades do Sistema que abrir, clique no botão Variáveis de Ambiente:
Crie as variáveis CYCODE_CLIENT_ID e CYCODE_CLIENT_SECRET com valores correspondentes ao seu ID e Chave Secreta, respectivamente. Se você autenticar via OIDC, adicione também CYCODE_ID_TOKEN com o valor do seu token de ID OIDC:
Insira o cycode.exe no caminho para concluir a instalação.

Instalar o hook de pré-commit

Os hooks de pré-commit e pré-push do Cycode podem ser configurados no seu repositório local para que o aplicativo Cycode CLI identifique automaticamente quaisquer problemas no seu código antes de você fazer commit ou push para o seu codebase.

[!NOTE] Os hooks de pré-commit e pré-push não estão disponíveis para varreduras de IaC.

Execute as seguintes etapas para instalar o hook de pré-commit:

Instalando o hook de pré-commit

Instale o framework pre-commit (Python 3.9 ou superior deve estar instalado):
```
pip3 install pre-commit
```
Navegue até o diretório superior do repositório Git local que você deseja configurar.
Crie um novo arquivo YAML chamado .pre-commit-config.yaml (inclua o início .) no diretório superior do repositório que contenha o seguinte:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
Modifique o arquivo criado para suas necessidades específicas. Use o ID de hook cycode para habilitar a varredura de Segredos. Use o ID de hook cycode-sca para habilitar a varredura SCA. Use o ID de hook cycode-sast para habilitar a varredura SAST. Se você quiser habilitar todos os tipos de varredura, use esta configuração:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.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 install
```
Uma instalação bem-sucedida do hook resultará na mensagem: Pre-commit installed at .git/hooks/pre-commit.
Mantenha o hook de pré-commit atualizado:
```
pre-commit autoupdate
```
Ele atualizará automaticamente rev em .pre-commit-config.yaml para a versão mais recente disponível do Cycode CLI.

[!NOTE] O gatilho ocorre no comando git commit. O hook é acionado apenas nos arquivos que estão preparados para commit.

Instalando o hook de pré-push

Para instalar o hook de pré-push além ou em vez do hook de pré-commit:

Adicione os hooks de pré-push ao seu arquivo .pre-commit-config.yaml:

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

Instale o hook de pré-push:

pre-commit install --hook-type pre-push

Para ambos os hooks de pré-commit e pré-push, use:

pre-commit install
pre-commit install --hook-type pre-push

[!NOTE] Os hooks de pré-push são acionados no comando git push e varrem apenas os commits que estão prestes a ser enviados.

Comandos do Cycode CLI

As seguintes são as opções e comandos disponíveis com o aplicativo Cycode CLI:

Opção	Descrição
`-v`, `--verbose`	Mostrar logs detalhados.
`--no-progress-meter`	Não mostrar o medidor de progresso.
`--no-update-notifier`	Não verificar 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 do Cycode para esta execução de varredura específica.
`--client-secret TEXT`	Especificar um segredo de cliente do Cycode para esta execução de varredura específica.
`--id-token TEXT`	Especificar um token de ID OIDC do Cycode para esta execução de varredura específica.
`--install-completion`	Instalar a conclusão para o shell atual.
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Mostrar a conclusão para o shell especificado, para copiá-la 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 seu cliente CLI.
ignore	Ignore um valor, caminho ou ID de regra específico.
mcp	Inicie o servidor Model Context Protocol (MCP) para permitir a integração de IA com os recursos de varredura da Cycode.
scan	Varre o conteúdo em busca de violações de Secrets/IaC/SCA/SAST. Você precisará especificar qual tipo de varredura executar: histórico-de-commits/caminho/repositório/etc.
report	Gere relatório. Você precisará especificar qual tipo de relatório executar, como SBOM.
status	Mostra o status da CLI e sai.

Comando MCP [EXPERIMENTAL]

[!WARNING] O comando MCP está disponível apenas para Python 3.10 e superior. Se você estiver usando uma versão anterior do Python, este comando não estará disponível.

O comando Model Context Protocol (MCP) permite iniciar um servidor MCP que expõe os recursos de varredura da Cycode a sistemas e aplicações de IA. Isso permite que modelos de IA interajam com as ferramentas CLI da Cycode por meio de um protocolo padronizado.

[!TIP] Para a melhor experiência, instale a CLI da Cycode globalmente no seu sistema usando pip install cycode ou brew install cycode, e então autentique-se uma vez com cycode auth. Após a instalação global e autenticação, você não precisará configurar as variáveis de ambiente CYCODE_CLIENT_ID e CYCODE_CLIENT_SECRET nos seus arquivos de configuração do MCP.

Iniciando 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, que é adequado para integrações locais e aplicações de IA que podem gerar subprocessos.

Opções Disponíveis

Opção	Descrição
`-t, --transport`	Tipo de transporte para o servidor MCP: `stdio`, `sse` ou `streamable-http` (padrão: `stdio`)
`-H, --host`	Endereço do host para vincular o servidor (usado apenas para transporte não stdio) (padrão: `127.0.0.1`)
`-p, --port`	Número da porta para vincular o servidor (usado apenas para transporte não stdio) (padrão: `8000`)
`--help`	Mostra mensagem de ajuda e 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`	Varredura por segredos codificados
`cycode_sca_scan`	Varredura para Análise de Composição de Software (SCA) - vulnerabilidades e problemas de licença
`cycode_iac_scan`	Varredura por configurações incorretas de Infraestrutura como Código (IaC)
`cycode_sast_scan`	Varredura para Teste de Segurança de Aplicações Estáticas (SAST) - qualidade de código e falhas de segurança
`cycode_status`	Obter versão da CLI da Cycode, status de autenticação e informações de configuração

Cada ferramenta de varredura aceita dois modos de entrada mutuamente exclusivos:

paths (preferido) — um ou mais caminhos de arquivo ou diretório que existem no disco. Diretórios são varridos recursivamente. O mecanismo da Cycode lida com a descoberta e filtragem de arquivos, assim como cycode scan -t <type> path ./src faz pela CLI.
files (fallback) — um dicionário mapeando caminhos de arquivo para seu conteúdo completo como strings. Use isso apenas quando os arquivos não estiverem disponíveis no disco (por exemplo, edições em memória ainda não salvas).

[!TIP] Use paths sempre que possível. Passar arquivos grandes (como package-lock.json) como conteúdo inline pode exceder os limites de token e desacelerar o cliente de IA. Com paths, o mecanismo da 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 Comando

Inicie o servidor MCP com as configurações padrão (transporte stdio):

cycode mcp

Inicie o servidor MCP com transporte stdio explícito:

cycode mcp -t stdio

Inicie o servidor MCP com transporte Server-Sent Events (SSE):

cycode mcp -t sse -p 8080

Inicie o servidor MCP com transporte HTTP transmissível em host e porta personalizados:

cycode mcp -t streamable-http -H 0.0.0.0 -p 9000

Saiba mais sobre os tipos de transporte MCP na Especificação do Protocolo MCP – Transports.

Exemplos de Configuração

Usando MCP com Cursor/VS Code/Claude Desktop/etc (mcp.json)

[!NOTE] Para ambientes Cycode na UE, certifique-se de definir os valores apropriados de CYCODE_API_URL e CYCODE_APP_URL nas variáveis de ambiente (por exemplo, https://api.eu.cycode.com e https://app.eu.cycode.com).

Siga este guia para configurar o servidor MCP no seu VS Code/GitHub Copilot. Lembre-se de que em settings.json, há um objeto mcp contendo um sub-objeto servers aninhado, 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 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 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 porta personalizada:

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

Para transporte HTTP transmissível:

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Executando o Servidor MCP em Segundo Plano

Para transporte SSE (inicie o servidor primeiro, 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 transmissível:

# 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

Certificados Personalizados e Timeouts (Ambientes de Proxy)

Se sua organização usa um proxy corporativo ou um pacote de CA personalizado para inspeção HTTPS, você precisa informar à CLI da Cycode (e à pilha TLS subjacente do Python) onde encontrar o pacote de certificados confiáveis. Você também pode aumentar o timeout de chamada da ferramenta MCP se as varreduras estiverem sendo interrompidas.

Variável de Ambiente	Descrição
`REQUESTS_CA_BUNDLE`	Caminho para um arquivo de pacote de CA personalizado (`.pem` ou `.crt`). Usado pela biblioteca `requests` para todas as chamadas HTTPS feitas pela CLI da Cycode.
`SSL_CERT_FILE`	Caminho para um arquivo de pacote de CA personalizado. Usado pelo módulo de baixo nível `ssl` do Python. Defina isso junto com `REQUESTS_CA_BUNDLE` para cobertura completa.
`MCP_TOOL_TIMEOUT`	Timeout (em segundos) que clientes MCP como Claude e GitHub Copilot aguardam para que uma chamada de ferramenta seja concluída. Aumente isso se varreduras de longa duração estiverem sendo interrompidas antes de terminar.

[!TIP] Defina tanto REQUESTS_CA_BUNDLE quanto SSL_CERT_FILE para o mesmo caminho de pacote de CA. REQUESTS_CA_BUNDLE cobre a camada HTTP; SSL_CERT_FILE cobre a camada TLS de baixo nível. Usar apenas um pode ainda causar erros de certificado em alguns ambientes.

Exemplo de configuração mcp.json com certificados personalizados e um timeout maior:

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
        "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] O servidor MCP requer autenticação adequada da CLI da Cycode para funcionar. Certifique-se de ter autenticado usando cycode auth ou configurado suas credenciais antes de iniciar o servidor MCP.

Pré-autorizando Ferramentas para Subagentes (Claude Code)

Quando o Claude Code delega trabalho a subagentes em segundo plano (por exemplo, para executar varreduras em paralelo), esses subagentes não podem exibir prompts interativos de permissão. Se as ferramentas da Cycode não forem pré-aprovadas, as varreduras falharão silenciosamente em contextos de subagente.

Para pré-autorizar as ferramentas MCP da Cycode para que funcionem em todos os contextos, incluindo subagentes, adicione-as à lista allowedTools nas configurações do seu 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"
  ]
}

Uma vez adicionadas, o Claude Code não solicitará aprovação quando essas ferramentas forem chamadas, e elas funcionarão corretamente dentro de subagentes.

Solução de Problemas do MCP

Se você encontrar problemas com o servidor MCP, pode ativar o registro de depuração para obter informações mais detalhadas sobre o que está acontecendo. Há duas maneiras de ativar o registro de depuração:

Usando a flag -v ou --verbose:

cycode -v mcp

Usando a variável de ambiente CYCODE_CLI_VERBOSE:

CYCODE_CLI_VERBOSE=1 cycode mcp

Os logs de depuração mostrarão informações detalhadas sobre:

Inicialização e configuração do servidor
Tentativas de conexão e status
Execução de ferramentas e resultados
Quaisquer erros ou avisos que ocorram

Essas informações podem ser úteis quando:

Diagnosticando problemas de conexão
Entendendo por que certas ferramentas não estão funcionando
Identificando problemas de autenticação
Depurando problemas específicos de transporte

Configuração do MCP

Comando de Plataforma [BETA]

[!WARNING] O comando platform está em beta. Comandos, argumentos e formatos de saída são gerados dinamicamente a partir da especificação da API da Cycode e podem mudar entre versões sem aviso. Não confie neles ainda em automação de produção.

O comando cycode platform expõe as APIs de leitura da plataforma Cycode como comandos CLI. Ele agrupa endpoints por recurso (por exemplo, projects, violations, workflows) e transforma os parâmetros de cada endpoint em argumentos CLI tipados e flags --option.

cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>

A especificação OpenAPI é buscada da API da 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 acionam uma busca.

[!NOTE] Você deve estar autenticado (cycode auth ou variáveis de ambiente CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET) para que cycode platform descubra e execute comandos. Outros comandos da CLI da Cycode funcionam sem autenticação.

Descobrindo Comandos

Como os comandos são gerados a partir da especificação, a fonte da verdade para 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

Toda a saída é JSON por padrão — canalize-a através de jq para filtragem ad-hoc:

cycode platform projects list --page-size 100 | jq '.items[].name'

Notas e Limitações da Plataforma

Somente leitura hoje. Apenas endpoints GET são expostos neste beta.
Orientado por especificação. Adicionar um novo endpoint à API o exibe automaticamente na próxima vez que o cache for atualizado.
Sem especificação embutida. A primeira invocação de cycode platform após a instalação (ou após a expiração do cache de 24h) realiza uma busca de rede. Em conexões lentas, essa primeira chamada pode levar alguns segundos; chamadas subsequentes são quase instantâneas até o cache expirar.
Substitua o TTL do cache com CYCODE_SPEC_CACHE_TTL=<seconds>.

Salvaguardas de IA [BETA]

O AI Guardrails instala hooks em agentes de codificação de IA suportados (Claude Code, Cursor, Copilot, Codex) para que prompts, arquivos que o agente lê 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 lado do servidor, portanto o conteúdo verificado sai da máquina: o texto do prompt, o conteúdo dos arquivos que o agente lê e os argumentos das ferramentas MCP são enviados ao seu tenant Cycode para serem verificados em busca de segredos.

Cada evento também é relatado com contexto sobre o desenvolvedor e a máquina, para que uma descoberta possa ser atribuída ao dispositivo e ao usuário de onde veio. Alguns desses dados são 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 codificação de IA e o nome de usuário local do sistema operacional.
Detalhes do ambiente — sistema operacional e versão, o agente de IA, sua versão e o modelo em uso, o conteúdo dos arquivos de configuração MCP do agente e seus 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 novamente o hardware.

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 hooks que já estão instalados).

Comando de Verificação

Executando uma Verificação

O aplicativo Cycode CLI oferece vários tipos de verificação para que você possa escolher a opção que melhor se adequa ao seu caso. A seguir estão as opções e comandos atualmente disponíveis:

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`	Mostrar segredos em texto simples. Consulte a seção Mostrar/Ocultar Segredos para mais detalhes.
`--soft-fail BOOLEAN`	Executar verificação sem falhar, sempre retornar um código de status sem erro. Consulte a seção Falha Suave para mais detalhes.
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	Mostrar apenas violações no nível especificado ou superior.
`--sca-scan`	Especifique a verificação SCA que deseja executar (`package-vulnerabilities`/`license-compliance`). O padrão é ambos.
`--monitor`	Quando especificado, os resultados da verificação serão registrados no Cycode.
`--cycode-report`	Exibir um link para o relatório de 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 dependências diretas!
`--stop-on-error`	Abortar a verificação se ocorrer qualquer falha na coleta de arquivos ou na restauração de dependências, em vez de pular o arquivo com falha e continuar.
`--gradle-all-sub-projects`	Executar 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`	Mostrar opções para o comando fornecido.

Comando	Descrição
commit-history	Verificar histórico de commits ou realizar verificação de diff entre commits específicos
path	Verificar os arquivos no caminho fornecido no comando
pre-commit	Use este comando para verificar o conteúdo que ainda não foi commitado
repository	Verificar repositório git incluindo seu histórico

Opções

Opção de Severidade

Para limitar os resultados da verificação a um limite de severidade específico, o argumento --severity-threshold pode ser adicionado ao comando de verificação.

Por exemplo, o seguinte comando verificará o repositório em busca de violações de política com severidade 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 os resultados da verificação vinculados às políticas SCA encontradas em uma verificação do tipo SCA para o Cycode, adicione o argumento --monitor ao comando de verificação.

Por exemplo, o seguinte comando verificará o repositório em busca de violações de política SCA e as enviará para a plataforma Cycode:

cycode scan -t sca --monitor repository ~/home/git/codebase

Opção de Relatório Cycode

Para cada verificação realizada usando o Cycode CLI, um relatório é gerado automaticamente e seus resultados são enviados ao Cycode. Esses resultados estão vinculados às políticas relevantes (por exemplo, políticas SCA para verificações de Repositório) na plataforma Cycode.

Para que a URL direta deste relatório Cycode seja impressa na saída do seu CLI após a conclusão da verificação, adicione o argumento --cycode-report ao seu comando de verificação.

cycode scan --cycode-report repository ~/home/git/codebase

Todos os resultados de verificação do CLI aparecerão na seção Logs do CLI do Cycode. Se você incluiu o sinalizador --cycode-report no seu comando, um link direto para o relatório específico será exibido no seu terminal após os resultados da verificação.

[!WARNING] Você deve ter o papel owner ou admin no Cycode para visualizar esta página.

cli-report

A página do relatório será algo como abaixo:

Opção de Vulnerabilidades de Pacotes

[!NOTE] Esta opção está disponível apenas para verificações SCA.

Para verificar uma vulnerabilidade de pacote específica do 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 apenas uma verificação SCA em 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ça

[!NOTE] Esta opção está disponível apenas para verificações SCA.

Para verificar um branch específico do seu repositório local, adicione o argumento --sca-scan license-compliance seguido pelo nome do branch que deseja verificar.

No exemplo anterior, se você quisesse verificar apenas um branch chamado dev, poderia executar o seguinte:

cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

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, o Cycode CLI tenta automaticamente restaurar (gerar) um lockfile de dependências para cada arquivo de manifesto suportado que encontrar. Isso permite verificar dependências transitivas, não apenas as listadas diretamente no manifesto. Para pular esta etapa e verificar apenas dependências diretas, use o sinalizador --no-restore.

Os seguintes ecossistemas suportam restauração automática de lockfile:

Ecossistema	Arquivo de manifesto	Lockfile gerado	Ferramenta invocada (quando o lockfile está ausente)
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`	(apenas lê o 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 um lockfile já existir ao lado do 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 Parar em Erro

Por padrão, o Cycode continua a verificação mesmo se um arquivo não puder ser lido (por exemplo, devido a um erro de permissão) ou se um lockfile de dependências não puder ser gerado durante uma verificação SCA. O item com falha é ignorado com um aviso e a verificação prossegue com os arquivos restantes.

Use --stop-on-error para alterar esse comportamento: a verificação é abortada imediatamente na primeira falha desse tipo e relata o erro.

cycode scan -t sca --stop-on-error path ~/home/git/codebase

Isso é útil em pipelines de CI onde uma falha silenciosa produziria um resultado de verificação incompleto. Quando --stop-on-error é acionado, você pode corrigir o problema subjacente ou, especificamente para falhas de restauração SCA, adicionar --no-restore para pular a geração do lockfile e verificar apenas dependências diretas.

Quando --stop-on-error é usado, o CLI distingue entre erros de verificação e violações de política 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 foram encontradas
`2`	Verificação abortada 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 holística analisa tudo: o estado atual do seu repositório e seu histórico de commits. Ele procurará 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ê quisesse verificar um repositório armazenado em ~/home/git/codebase, poderia 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 ser verificado, se não definido, verifica o branch padrão

Opção de Branch

Para verificar um branch específico do seu repositório local, adicione o argumento -b (alternativamente, --branch) seguido pelo nome do branch que deseja verificar.

Dado o exemplo anterior, se você quisesse verificar apenas um branch chamado dev, poderia 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 conteúdo dentro dele, em vez de focar apenas em um repositório GIT.

Para executar uma verificação de diretório, execute o seguinte:

cycode scan path {{path}}

Por exemplo, considere um cenário em que você deseja verificar o diretório localizado em ~/home/git/codebase. Você poderia então executar o seguinte:

cycode scan path ~/home/git/codebase

Verificação de Plano Terraform

O CLI do Cycode suporta a verificação de planos do Terraform (com suporte ao Terraform 0.12 e posterior)

O arquivo de plano do Terraform deve estar no formato JSON (com extensão .json)

Se você tiver apenas um arquivo de configuração, pode gerar um plano fazendo o seguinte:

Inicialize um diretório de trabalho que contenha o arquivo de configuração do Terraform:

terraform init
Crie o 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}.json com o 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 duas capacidades principais:

Verificação do histórico completo: Analise todos os commits no histórico do repositório
Verificação de diff: Verifique apenas as alterações entre commits específicos

A verificação de segredos pode analisar todos os commits no histórico do repositório, pois segredos introduzidos e posteriormente removidos ainda podem ser vazados ou expostos. Para verificações de SCA e SAST, o comando de histórico de commits concentra-se em verificar as diferenças/alterações entre commits, tornando-o perfeito para revisões de pull requests e verificação incremental.

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 análise histórica abrangente quanto para verificação direcionada de diff de alterações específicas.

Para executar uma verificação do histórico de commits, execute o seguinte:

cycode scan commit-history {{path}}

Por exemplo, considere um cenário em que você deseja verificar o histórico de commits de um repositório armazenado em ~/home/git/codebase. Você poderia então 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`	Verifique 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 Diff)

A opção de intervalo de commits permite a verificação de diff – verificar apenas as alterações entre commits específicos em vez de todo o histórico do repositório. Isso é particularmente útil para:

Validação de pull request: Verifique apenas as alterações introduzidas em um PR
Verificação incremental em CI/CD: Concentre-se nas alterações recentes em vez de todo o código
Revisão de branch de recurso: Compare as alterações com o 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) suporta a sintaxe padrão de revisão do Git:

Sintaxe	Descrição	Exemplo
`commit1..commit2`	Alterações do commit1 para o commit2	`abc123..def456`
`commit1...commit2`	Alterações no commit2 que não estão no commit1	`main...feature-branch`
`commit`	Alterações do commit até HEAD	`HEAD~1`
`branch1..branch2`	Alterações do branch1 para o branch2	`main..feature-branch`

Exemplos de Verificação de Diff

Verifique as alterações no último commit:

cycode scan commit-history -r HEAD~1 ~/home/git/codebase

Verifique as alterações entre dois commits específicos:

cycode scan commit-history -r abc123..def456 ~/home/git/codebase

Verifique as alterações no seu branch de recurso em comparação com o main:

cycode scan commit-history -r main..HEAD ~/home/git/codebase

Verifique as alterações entre o main e um branch de recurso:

cycode scan commit-history -r main..feature-branch ~/home/git/codebase

Verifique todas as alterações nos ú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 alterações de PR/MR.

Verificação Pré-Commit

Uma verificação pré-commit identifica automaticamente quaisquer problemas antes de você commitar alterações no seu repositório. Não é necessário executar esta verificação manualmente; configure o hook pré-commit conforme detalhado na seção Instalação deste guia.

Após instalar o hook pré-commit, você pode ocasionalmente desejar pular a verificação durante um commit específico. Para fazer isso, adicione o seguinte ao seu comando git para pular a verificação de um único commit:

SKIP=cycode git commit -m <your commit message>`

Verificação Pré-Push

Uma verificação pré-push identifica automaticamente quaisquer problemas antes de você enviar alterações para o repositório remoto. Este hook é executado no lado do cliente e verifica apenas os commits que estão prestes a ser enviados, tornando-o eficiente para detectar problemas antes que eles 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 ao framework pre-commit e pode ser configurado para ser executado antes de qualquer operação git push.

Instalando o Hook Pré-Push

Para configurar o hook pré-push usando o framework pre-commit:

Instale o framework pre-commit (se ainda não estiver instalado):
```
pip3 install pre-commit
```

Crie ou atualize seu arquivo .pre-commit-config.yaml para incluir os hooks pré-push:

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.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.5.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-push
```
Uma instalação bem-sucedida resultará na 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 pré-push:

Recebe informações sobre quais commits estão sendo enviados
Calcula o intervalo de commits apropriado para verificar
Para novos branches: verifica todos os commits a partir da base de merge com o branch padrão
Para branches existentes: verifica apenas os novos commits desde o último push
Executa a mesma verificação abrangente que outros modos de verificação do Cycode

Detecção Inteligente do Branch Padrão

O hook pré-push detecta inteligentemente o branch padrão para o cálculo da base de merge usando esta ordem de prioridade:

Variável de ambiente: CYCODE_DEFAULT_BRANCH - permite substituição manual
Git Remote HEAD: Usa git symbolic-ref refs/remotes/origin/HEAD para detectar o branch padrão remoto real
Informações do Git Remote: Recorre a git remote show origin se symbolic-ref falhar
Fallbacks codificados: Usa nomes comuns de branch padrão (origin/main, origin/master, main, master)

Definindo um Branch Padrão Personalizado:

export CYCODE_DEFAULT_BRANCH=origin/develop

Essa detecção inteligente garante que o hook pré-push funcione corretamente independentemente de o seu repositório usar main, master, develop ou qualquer outro nome de branch padrão.

Pulando Verificações Pré-Push

Para pular a verificação pré-push para uma operação de push específica, use:

SKIP=cycode-pre-push git push

Ou para pular todos os hooks pré-push:

git push --no-verify

[!TIP] O hook pré-push é acionado no comando git push e verifica apenas os commits que estão prestes a ser enviados, tornando-o mais eficiente do que verificar todo o repositório.

Excluir Caminhos das Verificações

Você pode usar um arquivo .cycodeignore para informar ao CLI do Cycode quais arquivos e diretórios excluir das verificações. Funciona exatamente como um arquivo .gitignore. Isso ajuda você a concentrar as verificações no seu código relevante e evita que determinados caminhos acionem violações localmente.

Como Funciona

Crie um arquivo chamado .cycodeignore na sua pasta de trabalho.
Liste os arquivos e diretórios que deseja excluir, usando os mesmos padrões do .gitignore.
Coloque este arquivo no diretório onde você planeja executar o comando de verificação do cycode.

[!WARNING]

Arquivos inválidos: Se o arquivo .cycodeignore contiver um erro de sintaxe, a verificação do CLI falhará e retornará um erro.

Ignorar caminhos vs. violações: Este arquivo serve para excluir caminhos. É diferente da capacidade do CLI de ignorar violações específicas (por exemplo, usando a flag --ignore-violation).

Scanners Suportados

SAST
IaC (em breve)
SCA (em breve)

Resultados da Verificação

Cada verificação será concluída com uma mensagem informando se algum problema foi encontrado ou não.

Se nenhum problema for encontrado, a verificação termina com a seguinte mensagem de sucesso:

Good job! No issues were found!!! 👏👏👏

Se um problema for encontrado, um cartão de violação aparece ao concluir. Nesse caso, você deve revisar o arquivo em questão para a linha específica destacada pela mensagem de resultado. Implemente 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 é um valor atribuído a googleApiKey.

Observe como o exemplo obscurece o valor real do segredo, substituindo a maior parte do segredo por asteriscos. As verificações obscurecem segredos por padrão, mas você pode opcionalmente desativar esse recurso para ver o segredo completo (supondo que a máquina em que você está visualizando o resultado da verificação seja suficientemente segura contra olhares curiosos).

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 na subpasta cli com a opção habilitada para exibir quaisquer segredos encontrados por completo:

cycode scan --show-secret path ./cli

O resultado então não seria ofuscado.

Falha Suave

Na operação normal, o CLI retornará um código de saída de 1 quando problemas forem encontrados nos resultados da verificação. Dependendo da sua configuração de CI/CD, isso geralmente resultará em uma falha geral. Se você não quiser que isso aconteça, pode usar o recurso de falha suave.

Ao adicionar a opção --soft-fail a qualquer tipo de verificação, o código de saída será forçado a 0 independentemente de serem encontrados resultados.

Exemplos de Resultados de Verificação

Exemplo de Resultado de Segredos

╭─────────────────────────────────────────────────────────────── 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 Remediação da Empresa

Se a sua empresa definiu diretrizes personalizadas de remediação na política relevante por meio do portal Cycode, você verá um campo para “Diretrizes da Empresa” que contém as diretrizes de remediação que você adicionou. Observe que, se você não adicionou nenhuma diretriz da empresa, esse campo não aparecerá na ferramenta CLI.

Ignorando Resultados de Verificação

Regras de ignorar podem ser adicionadas para ignorar valores de segredo específicos, valores SHA512 específicos, caminhos específicos e IDs de regras específicas de segredo e IaC do Cycode. Isso fará com que a verificação não alerte esses valores. As regras de ignorar são escritas e salvas localmente no arquivo ./.cycode/config.yaml.

[!WARNING] A adição de valores a serem ignorados deve ser feita com consideração cuidadosa dos valores, caminhos e políticas para garantir que as verificações detectem verdadeiros positivos.

As seguintes são as opções disponíveis para o comando cycode ignore:

Opção	Descrição
`--by-value TEXT`	Ignore um valor específico ao verificar segredos. Consulte Ignorando um Valor de Segredo para mais detalhes.
`--by-sha TEXT`	Ignore uma representação SHA512 específica de uma string ao verificar segredos. Consulte Ignorando um Valor SHA de Segredo para mais detalhes.
`--by-path TEXT`	Evite verificar um caminho específico. É necessário especificar o tipo de verificação. Consulte Ignorando um Caminho para mais detalhes.
`--by-rule TEXT`	Ignore a verificação de um ID de regra de segredo específico/ID de regra IaC/ID de regra SCA. Consulte Ignorando uma Regra de Segredo ou IaC para mais detalhes.
`--by-package TEXT`	Ignore a verificação de uma versão de pacote específica ao executar uma verificação SCA. Padrão esperado - `name@version`. Consulte Ignorando um Pacote para mais detalhes.
`--by-cve TEXT`	Ignore a verificação de um CVE específico ao executar uma verificação SCA. Padrão esperado: CVE-YYYY-NNN.
`-t, --scan-type [secret\|iac\|sca\|sast]`	Especifique a verificação que deseja executar (`secret`/`iac`/`sca`/`sast`). O valor padrão é `secret`.
`-g, --global`	Adicione uma regra de ignorar e atualize-a no arquivo de configuração global `.cycode`.

Ignorando um Valor de Segredo

Para ignorar um valor de segredo específico, você precisará usar a flag --by-value. Isso ignorará o valor de segredo fornecido em todas as verificações futuras. Use o seguinte comando para adicionar um valor de segredo a ser ignorado:

cycode ignore --by-value {{secret-value}}

No exemplo no início desta seção, o comando para ignorar um valor de segredo específico é o seguinte:

cycode ignore --by-value h3110w0r1d!@#$350

No exemplo acima, substitua o valor h3110w0r1d!@#$350 pelo seu valor de segredo não mascarado. Consulte as opções de verificação do Cycode para obter detalhes sobre como ver os valores de segredo nos resultados da verificação.

Ignorando um Valor SHA de Segredo

Para ignorar um valor SHA de segredo específico, você precisará usar a flag --by-sha. Isso ignorará o valor SHA de segredo fornecido em todas as verificações futuras. Use o seguinte comando para adicionar um valor SHA de segredo a ser ignorado:

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 é o seguinte:

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

No exemplo acima, substitua o valor a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 pelo seu valor SHA de segredo.

Ignorando um Caminho

Para ignorar um caminho específico para verificações de segredo, IaC ou SCA, você precisará usar a flag --by-path em conjunto com a flag -t, --scan-type (você deve especificar o tipo de verificação). Isso ignorará o caminho fornecido em todas as verificações futuras para o tipo de verificação especificado. Use o seguinte comando para adicionar um caminho a ser ignorado:

cycode ignore -t {{scan-type}} --by-path {{path}}

No exemplo no início desta seção, o comando para ignorar um caminho específico para um segredo é o seguinte:

cycode ignore -t secret --by-path ~/home/my-repo/config

No exemplo acima, substitua o valor ~/home/my-repo/config pelo seu valor de caminho.

No exemplo no início desta seção, o comando para ignorar um caminho específico das verificações IaC é o seguinte:

cycode ignore -t iac --by-path ~/home/my-repo/config

No exemplo acima, substitua o valor ~/home/my-repo/config pelo seu valor de caminho.

No exemplo no início desta seção, o comando para ignorar um caminho específico das verificações SCA é o seguinte:

cycode ignore -t sca --by-path ~/home/my-repo/config

No exemplo acima, substitua o valor ~/home/my-repo/config pelo seu valor de caminho.

Ignorando uma Regra de Segredo, IaC, SCA ou SAST

Para ignorar uma regra específica de segredo, IaC, SCA ou SAST, você precisará usar a flag --by-rule em conjunto com a flag -t, --scan-type (você deve especificar o tipo de verificação). Isso ignorará o valor do ID da regra fornecido em todas as verificações futuras. Use o seguinte comando para adicionar um valor de ID de regra a ser ignorado:

cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}

No exemplo no início desta seção, o comando para ignorar o ID da regra de segredo específico é o seguinte:

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 você deseja ignorar.

No exemplo no início desta seção, o comando para ignorar o ID da regra IaC específico é o seguinte:

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 você deseja ignorar.

No exemplo no início desta seção, o comando para ignorar o ID da regra SCA específico é o seguinte:

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 você deseja ignorar.

Ignorando um Pacote

[!NOTE] Esta opção está disponível apenas para as verificações SCA.

Para ignorar um pacote específico nas verificações SCA, você precisará usar a flag --by-package em conjunto com a flag -t, --scan-type (você deve especificar o tipo de verificação sca). Isso ignorará o pacote fornecido, usando a formatação {{package_name}}@{{package_version}}, em todas as verificações futuras. Use o seguinte comando para adicionar um pacote e versão a serem ignorados:

cycode ignore --scan-type sca --by-package {{package_name}}@{{package_version}}

cycode ignore -t sca --by-package {{package_name}}@{{package_version}}

No exemplo abaixo, o comando para ignorar um pacote SCA específico é o seguinte:

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 você deseja ignorar.

Ignorando via um arquivo de configuração

As regras de ignorar aplicadas são armazenadas no arquivo de configuração chamado config.yaml. Este arquivo pode ser facilmente compartilhado entre desenvolvedores ou até mesmo commitado no Git remoto. Esses arquivos estão sempre localizados na pasta .cycode. A 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 a partir do qual a CLI foi executada.

Exemplo: executar o comando de ignorar da CLI a partir de /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, onde ~ significa users home directory, for example, /Users/name` no macOS.

Salvar no espaço global pode ser feito com a flag -g do comando cycode ignore. Por exemplo: cycode ignore -g --by-value test-value.

Diretório de trabalho adequado

É extremamente importante colocar a pasta .cycode e executar a CLI do mesmo local. Você deve verificar isso ao trabalhar com diferentes ambientes como CI/CD (GitHub Actions, Jenkins, etc.).

Você pode commitar a pasta .cycode na raiz do seu repositório. Nesse cenário, você deve executar 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 onde quiser e executar uma verificação da CLI a partir dessa pasta.

Estrutura das regras de ignorar no config

É 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 para "ignorar por valor" não são armazenados como texto simples! A CLI armazena hashes sha256 dos valores em vez disso. Você deve colocar hashes da string ao modificar o arquivo de configuração manualmente.

Exemplo de config.yaml real:

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 de Relatório

Gerando 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 entrega de um aplicativo. Usando este comando, você pode criar um relatório SBOM para o seu projeto local ou para o URI do seu repositório.

As seguintes opções 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 do SBOM	Sim
`-o, --output-format [JSON]`	Especifique 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	Falso
`--include-dev-dependencies`	Incluir dependências de desenvolvimento	Não	Falso

Os seguintes comandos estão disponíveis para uso com este comando:

Comando	Descrição
`path`	Gere o relatório SBOM para o caminho fornecido no comando
`repository-url`	Gere o 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 suporta as seguintes opções adicionais:

Opção	Descrição
`--no-restore`	Pule a restauração do lockfile e verifique apenas as dependências diretas. Consulte Opção de Restauração de Lock para detalhes.
`--gradle-all-sub-projects`	Execute o comando de restauração do Gradle para todos os subprojetos (use a partir da raiz de um build Gradle de múltiplos projetos).
`--maven-settings-file`	Somente para Maven, permite usar um arquivo settings.xml personalizado ao construir a árvore de dependências.

Comando de Importação

Importando 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 entrega de um aplicativo. Usando este comando, você pode importar um arquivo SBOM do seu sistema de arquivos para o Cycode.

As seguintes opções 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 Varredura

Todas as varreduras CLI são registradas no Cycode. Os logs podem ser encontrados em Configurações > Logs 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 varredura, insira:

cycode scan --help

Para ver as opções disponíveis para um tipo específico de varredura, insira:

cycode scan {{option}} --help

Por exemplo, para ver as opções disponíveis para um Path Scan, você digitaria:

cycode scan path --help

Para ver as opções disponíveis para a função de ignorar varredura, 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