Cycode

oficial

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

Documentação

Guia do Usuário da CLI Cycode

A Interface de Linha de Comando (CLI) Cycode é um aplicativo que você pode instalar localmente para escanear 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 orienta você tanto na instalação quanto no uso.

Índice

Pré-requisitos
Instalação
1. Instalar a CLI Cycode
2. Instalar Hook de Pre-Commit
Comandos da CLI Cycode
Comando MCP
Comando Platform
Comando Scan
Comando Report
1. Gerando Relatório SBOM
Comando Import
Logs de Scan
Ajuda de Sintaxe

Pré-requisitos

O aplicativo CLI Cycode requer Python versão 3.9 ou posterior. 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-se no Cycode com a CLI
- Alternativamente, você pode obter um Client ID e Client Secret Key do Cycode seguindo as etapas detalhadas 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 presumem o uso de python3 e pip3 para comandos relacionados ao Python; no entanto, alguns sistemas podem usar os comandos python e pip, dependendo da configuração do seu ambiente Python.

Instalar a CLI Cycode

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

Abra sua linha de comando ou aplicativo de 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 das GitHub Releases, navegue e baixe o executável para seu sistema operacional e arquitetura, então execute o seguinte comando:
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
Finalmente, autentique a CLI. Existem três métodos para definir o client ID e as credenciais do Cycode (client secret ou token OIDC ID):
- cycode auth (Recomendado)
- cycode configure
- Adicioná-los às suas variáveis de ambiente

Usando o Comando Auth

[!NOTE] Este é o método recomendado para configurar sua máquina local para autenticar-se com a CLI Cycode.

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

cycode auth
Uma janela do navegador aparecerá, solicitando que você faça login no Cycode (como visto abaixo):
Insira suas credenciais de login nesta página e faça login.
Eventualmente, você será 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 autenticação com a CLI Cycode.
Clique no botão Permitir para autorizar a CLI Cycode no grupo de negócios selecionado.
Uma vez concluído, você verá a seguinte tela se a seleção foi bem-sucedida:
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 Cycode Client ID e Client Secret através das variáveis de ambiente do Linux ou Windows, essas credenciais terão precedência sobre este método.

Digite o seguinte comando em sua janela de terminal/linha de comando:
```
cycode configure
```
Insira o valor da sua Cycode API URL (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 sua Cycode APP URL (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 Cycode Client ID.

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

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

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

Successfully configured CLI credentials!

e/ou

Successfully configured Cycode URLs!

Se você acessar a pasta .cycode dentro da sua pasta de usuário, encontrará 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 ID token 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 se abre, 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 Secret Key, respectivamente. Se você se autentica via OIDC, adicione também CYCODE_ID_TOKEN com o valor do seu token OIDC ID:
Insira o cycode.exe no caminho para concluir a instalação.

Instalar Hook de Pre-Commit

Os hooks de pre-commit e pre-push do Cycode podem ser configurados dentro do seu repositório local para que o aplicativo CLI Cycode identifique automaticamente quaisquer problemas com seu código antes que você faça commit ou push para sua base de código.

[!NOTE] Hooks de pre-commit e pre-push não estão disponíveis para scans de IaC.

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

Instalando o Hook de Pre-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 ponto inicial .) 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 hook ID cycode para habilitar o scan de Segredos. Use o hook ID cycode-sca para habilitar o scan SCA. Use o hook ID cycode-sast para habilitar o scan SAST. Se você quiser habilitar todos os tipos de scan, 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 de hook bem-sucedida resultará na mensagem: Pre-commit installed at .git/hooks/pre-commit.
Mantenha o hook de pre-commit atualizado:
```
pre-commit autoupdate
```
Ele atualizará automaticamente o rev no .pre-commit-config.yaml para a versão mais recente disponível da CLI Cycode.

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

Instalando o Hook de Pre-Push

Para instalar o hook de pre-push adicionalmente ou em vez do hook de pre-commit:

Adicione os hooks de pre-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 pre-push:

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

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

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

[!NOTE] Os hooks de pre-push são acionados no comando git push e escaneiam apenas os commits prestes a serem enviados.

Comandos da CLI Cycode

A seguir estão as opções e comandos disponíveis com o aplicativo CLI Cycode:

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 Cycode client ID para esta execução de scan específica.
`--client-secret TEXT`	Especificar um Cycode client secret para esta execução de scan específica.
`--id-token TEXT`	Especificar um Cycode OIDC ID token para esta execução de scan específica.
`--install-completion`	Instalar autocompletar para o shell atual.
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Mostrar autocompletar 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	Autentica sua máquina para associar a CLI à sua conta Cycode.
configure	Comando inicial para configurar a autenticação do seu cliente CLI.
ignore	Ignora um valor, caminho ou ID de regra específico.
mcp	Inicia o servidor Model Context Protocol (MCP) para permitir a integração de IA com as capacidades de escaneamento do Cycode.
scan	Escaneia o conteúdo em busca de violações de Secrets/IaC/SCA/SAST. Você precisará especificar qual tipo de escaneamento realizar: commit-history/path/repository/etc.
report	Gera relatório. Você precisará especificar qual tipo de relatório realizar, 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 as capacidades de escaneamento do Cycode para sistemas e aplicações de IA. Isso permite que modelos de IA interajam com as ferramentas da CLI do Cycode por meio de um protocolo padronizado.

[!TIP] Para a melhor experiência, instale a CLI do Cycode globalmente em 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 e autenticação globais, você não precisará configurar as variáveis de ambiente CYCODE_CLIENT_ID e CYCODE_CLIENT_SECRET em seus arquivos de configuração 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`	Escaneia por segredos hardcoded
`cycode_sca_scan`	Escaneia por Análise de Composição de Software (SCA) - vulnerabilidades e problemas de licença
`cycode_iac_scan`	Escaneia por configurações incorretas de Infraestrutura como Código (IaC)
`cycode_sast_scan`	Escaneia por Testes de Segurança de Aplicações Estáticas (SAST) - qualidade de código e falhas de segurança
`cycode_status`	Obtém a versão da CLI do Cycode, status de autenticação e informações de configuração

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

paths (preferencial) — um ou mais caminhos de arquivo ou diretório que existem no disco. Diretórios são escaneados recursivamente. O motor do Cycode lida com a descoberta e filtragem de arquivos, assim como cycode scan -t <type> path ./src faz na CLI.
files (alternativo) — 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 (ex.: 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 tornar o cliente de IA mais lento. Com paths, o motor do Cycode lê os arquivos diretamente do disco.

Todas as ferramentas de escaneamento retornam um objeto JSON que inclui um campo "summary" com uma contagem de violações legível por humanos (ex.: "Cycode found 3 violations: 1 CRITICAL, 2 HIGH."), além do array completo "detections".

Exemplos de Uso

Exemplos de Comandos Básicos

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

cycode mcp

Inicia o servidor MCP com transporte stdio explícito:

cycode mcp -t stdio

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

cycode mcp -t sse -p 8080

Inicia o servidor MCP com transporte HTTP streamable 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 – Transportes.

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 (ex.: 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. Tenha em mente 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 streamable:

{
  "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 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

Certificados Personalizados e Timeouts (Ambientes com Proxy)

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

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

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

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

{
  "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 do Cycode para funcionar. Certifique-se de ter se 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 para subagentes em segundo plano (ex.: para executar escaneamentos em paralelo), esses subagentes não podem exibir prompts de permissão interativos. Se as ferramentas do Cycode não tiverem sido pré-aprovadas, os escaneamentos falharão silenciosamente em contextos de subagente.

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

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 habilitar o log de depuração para obter informações mais detalhadas sobre o que está acontecendo. Existem duas maneiras de habilitar o log 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 e status de conexão
Execução e resultados das ferramentas
Quaisquer erros ou avisos que ocorram

Esta informação pode ser útil ao:

Diagnosticar problemas de conexão
Entender por que certas ferramentas não estão funcionando
Identificar problemas de autenticação
Depurar problemas específicos de transporte

Configuração do MCP

Comando Platform [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 do Cycode e podem mudar entre lançamentos sem aviso prévio. Não confie neles em automação de produção ainda.

O comando cycode platform expõe as APIs de leitura da plataforma Cycode como comandos da CLI. Ele agrupa endpoints por recurso (ex.: projects, violations, workflows) e transforma os parâmetros de cada endpoint em argumentos de 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 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 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 do 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 do Platform

# 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 saída é JSON por padrão — canalize através de jq para filtragem ad-hoc:

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

Notas e Limitações do Platform

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

Comando Scan

Executando um Escaneamento

A aplicação CLI do Cycode oferece vários tipos de escaneamentos para que você possa escolher a opção que melhor se adapta ao seu caso. A seguir estão as opções e comandos atuais disponíveis:

Opção	Descrição
`-t, --scan-type [secret\|iac\|sca\|sast]`	Especifica a varredura que você deseja executar (`secret`/`iac`/`sca`/`sast`), o padrão é `secret`.
`--show-secret BOOLEAN`	Exibe os segredos em texto simples. Consulte a seção Mostrar/Ocultar Segredos para mais detalhes.
`--soft-fail BOOLEAN`	Executa a varredura sem falhar, sempre retornando um código de status sem erro. Consulte a seção Falha Suave para mais detalhes.
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	Exibe apenas violações no nível especificado ou superior.
`--sca-scan`	Especifica a varredura SCA que você deseja executar (`package-vulnerabilities`/`license-compliance`). O padrão é ambas.
`--monitor`	Quando especificado, os resultados da varredura serão registrados no Cycode.
`--cycode-report`	Exibe um link para o relatório da varredura na plataforma Cycode na saída do console.
`--no-restore`	Quando especificado, o Cycode não executará o comando de restauração. Isso irá escanear APENAS as dependências diretas!
`--stop-on-error`	Aborta a varredura se ocorrer alguma 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`	Executa o comando de restauração do Gradle para todos os subprojetos. Isso deve ser executado a partir de
`--maven-settings-file`	Apenas para Maven, permite usar um arquivo settings.xml personalizado ao escanear dependências
`--help`	Exibe opções para o comando fornecido.

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

Opções

Opção de Severidade

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

Por exemplo, o comando a seguir irá escanear 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 varreduras SCA.

Para enviar os resultados da varredura vinculados às políticas SCA encontradas em uma varredura do tipo SCA para o Cycode, adicione o argumento --monitor ao comando de varredura.

Por exemplo, o comando a seguir irá escanear o repositório em busca de violações de política SCA e enviá-las para a plataforma Cycode:

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

Opção de Relatório Cycode

Para cada varredura realizada usando a CLI do Cycode, um relatório é gerado automaticamente e seus resultados são enviados para o Cycode. Esses resultados são vinculados às políticas relevantes (por exemplo, políticas SCA para varreduras de Repositório) dentro da plataforma Cycode.

Para que a URL direta para este relatório do Cycode seja exibida na saída da sua CLI após a conclusão da varredura, adicione o argumento --cycode-report ao seu comando de varredura.

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

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

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

cli-report

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 varreduras SCA.

Para escanear 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 varredura 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 varreduras SCA.

Para escanear uma branch específica do seu repositório local, adicione o argumento --sca-scan license-compliance seguido pelo nome da branch que você deseja escanear.

No exemplo anterior, se você quisesse escanear 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 Restauração de Lock

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

Ao executar uma varredura SCA, a CLI do Cycode tenta automaticamente restaurar (gerar) um arquivo de lock de dependências para cada arquivo de manifesto suportado que encontrar. Isso permite escanear dependências transitivas, não apenas as listadas diretamente no manifesto. Para pular esta etapa e escanear apenas dependências diretas, use a flag --no-restore.

Os seguintes ecossistemas suportam a 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ê 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`
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 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 ao project/plugins.sbt:

addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")

Opção Parar em Caso de Erro

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

Use --stop-on-error para alterar este comportamento: a varredura é abortada imediatamente na primeira falha desse tipo e reporta 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 varredura incompleto. Quando --stop-on-error é acionado, você pode corrigir o problema subjacente ou, para falhas de restauração SCA especificamente, adicionar --no-restore para pular a geração do lockfile e escanear apenas dependências diretas.

Quando --stop-on-error é usado, a CLI distingue entre erros de varredura e violações de política por meio de códigos de saída:

Código de saída	Significado
`0`	Varredura concluída sem violações
`1`	Varredura concluída e violações foram encontradas
`2`	Varredura abortada devido a um erro (apenas quando `--stop-on-error` está definido)

Varredura de Repositório

Uma varredura de repositório examina um repositório local inteiro em busca de segredos expostos ou configurações incorretas inseguras. Este tipo de varredura mais holística analisa tudo: o estado atual do seu repositório e seu histórico de commits. Ela procurará não apenas por segredos que estão atualmente expostos no repositório, mas também por segredos excluídos anteriormente.

Para executar uma varredura completa de repositório, execute o seguinte:

cycode scan repository {{path}}

Por exemplo, se você quisesse escanear 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 escaneada, se não definido, escaneia a branch padrão

Opção de Branch

Para escanear uma branch específica do seu repositório local, adicione o argumento -b (alternativamente, --branch) seguido pelo nome da branch que você deseja escanear.

Dado o exemplo anterior, se você quisesse escanear apenas uma branch chamada dev, poderia executar o seguinte:

cycode scan repository ~/home/git/codebase -b dev

Varredura de Caminho

Uma varredura de caminho examina um diretório local específico e todo o seu conteúdo, em vez de focar apenas em um repositório GIT.

Para executar uma varredura de diretório, execute o seguinte:

cycode scan path {{path}}

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

cycode scan path ~/home/git/codebase

Varredura de Plano do Terraform

A CLI do Cycode suporta varredura de plano do Terraform (compatível com Terraform 0.12 e posteriores)

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

Se você tiver apenas um arquivo de configuração, poderá 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
Escaneie seu {tfplan}.json com a CLI do Cycode:

cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json

Varredura de Histórico de Commits

[!NOTE] A Varredura de Histórico de Commits não está disponível para varreduras IaC.

O comando de varredura de histórico de commits oferece duas capacidades principais:

Varredura de Histórico Completo: Analisa todos os commits no histórico do repositório
Varredura de Diff: Escaneia apenas as alterações entre commits específicos

A varredura de segredos pode analisar todos os commits no histórico do repositório porque segredos introduzidos e posteriormente removidos ainda podem ter vazado ou sido expostos. Para varreduras SCA e SAST, o comando de histórico de commits foca em escanear as diferenças/alterações entre commits, tornando-o perfeito para revisões de pull request e varredura incremental.

Uma varredura de 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 varredura de diff direcionada de alterações específicas.

Para executar uma varredura de histórico de commits, execute o seguinte:

cycode scan commit-history {{path}}

Por exemplo, considere um cenário em que você deseja escanear 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`	Escaneia um intervalo de commits neste repositório git; por padrão, o cycode escaneia todo o histórico de commits (exemplo: HEAD~1)

Opção de Intervalo de Commits (Escaneamento de Diff)

A opção de intervalo de commits habilita o escaneamento de diff – escaneando 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: Escaneia apenas as alterações introduzidas em um PR
Escaneamento incremental em CI/CD: Foca nas alterações recentes, em vez de toda a base de código
Revisão de branch de funcionalidade: Compara as alterações com a branch main/master
Otimização de desempenho: Escaneamentos mais rápidos ao limitar o escopo às alterações relevantes

Sintaxe do Intervalo de Commits

A opção --commit-range (-r) suporta a sintaxe de revisão padrão do Git:

Sintaxe	Descrição	Exemplo
`commit1..commit2`	Alterações de commit1 a 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 de branch1 a branch2	`main..feature-branch`

Exemplos de Escaneamento de Diff

Escaneia alterações no último commit:

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

Escaneia alterações entre dois commits específicos:

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

Escaneia alterações na sua branch de funcionalidade comparada à main:

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

Escaneia alterações entre a main e uma branch de funcionalidade:

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

Escaneia 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 escanear apenas alterações de PR/MR.

Escaneamento Pre-Commit

Um escaneamento pre-commit identifica automaticamente quaisquer problemas antes que você faça commit das alterações no seu repositório. Não é necessário executar este escaneamento manualmente; configure o hook de pre-commit conforme detalhado na seção de Instalação deste guia.

Após instalar o hook de pre-commit, você pode ocasionalmente desejar pular o escaneamento durante um commit específico. Para fazer isso, adicione o seguinte ao seu comando git para pular o escaneamento em um único commit:

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

Escaneamento Pre-Push

Um escaneamento pre-push identifica automaticamente quaisquer problemas antes que você envie (push) as alterações para o repositório remoto. Este hook é executado no lado do cliente e escaneia 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 de pre-push não está disponível para escaneamentos de IaC.

O hook de pre-push integra-se com o framework pre-commit e pode ser configurado para ser executado antes de qualquer operação git push.

Instalando o Hook Pre-Push

Para configurar o hook de pre-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 de pre-push:

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

Para múltiplos tipos de escaneamento, 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 de pre-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 de pre-push atualizado:
```
pre-commit autoupdate
```

Como o Escaneamento Pre-Push Funciona

O hook de pre-push:

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

Detecção Inteligente da Branch Padrão

O hook de pre-push detecta inteligentemente a branch padrão para o cálculo da 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/HEAD para detectar a branch padrão real do remoto
Informação do Remoto Git: Recorre a git remote show origin se symbolic-ref falhar
Fallbacks Fixos: Usa nomes de branch padrão comuns (origin/main, origin/master, main, master)

Definindo uma Branch Padrão Personalizada:

export CYCODE_DEFAULT_BRANCH=origin/develop

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

Pulando Escaneamentos Pre-Push

Para pular o escaneamento de pre-push em uma operação de push específica, use:

SKIP=cycode-pre-push git push

Ou para pular todos os hooks de pre-push:

git push --no-verify

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

Excluir Caminhos dos Escaneamentos

Você pode usar um arquivo .cycodeignore para informar à CLI do Cycode quais arquivos e diretórios excluir dos escaneamentos. Ele funciona exatamente como um arquivo .gitignore. Isso ajuda você a focar os escaneamentos no seu código relevante e evitar que certos caminhos acionem violações localmente.

Como Funciona

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

[!WARNING]

Arquivos inválidos: Se o arquivo .cycodeignore contiver um erro de sintaxe, o escaneamento da CLI falhará e retornará um erro.

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

Scanners Suportados

SAST
IaC (em breve)
SCA (em breve)

Resultados do Escaneamento

Cada escaneamento será concluído com uma mensagem informando se foram encontrados problemas ou não.

Se nenhum problema for encontrado, o escaneamento termina com a seguinte mensagem de sucesso:

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

Se um problema for encontrado, um cartão de violação aparecerá ao final. Neste caso, você deve revisar o arquivo em questão na linha específica destacada pela mensagem de resultado. Implemente quaisquer alterações necessárias para resolver o problema e execute o escaneamento 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. Os escaneamentos obscurecem segredos por padrão, mas você pode opcionalmente desabilitar este recurso para visualizar o segredo completo (assumindo que a máquina em que você está visualizando o resultado do escaneamento seja suficientemente segura contra olhares curiosos).

Para desabilitar a ofuscação de segredos, adicione o argumento --show-secret a qualquer tipo de escaneamento.

No exemplo a seguir, um Path Scan é executado no subdiretório 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 (Soft Fail)

Em operação normal, a CLI retornará um código de saída 1 quando problemas forem encontrados nos resultados do escaneamento. 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.

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

Exemplos de Resultados de Escaneamento

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 de Remediação Personalizadas da Empresa

Se sua empresa definiu diretrizes de remediação personalizadas na política relevante através do portal Cycode, você verá um campo para "Company Guidelines" que contém as diretrizes de remediação que você adicionou. Observe que, se você não adicionou nenhuma diretriz da empresa, este campo não aparecerá na ferramenta CLI.

Ignorando Resultados de Escaneamento

Regras de ignorar podem ser adicionadas para ignorar valores secretos específicos, valores SHA512 específicos, caminhos específicos e IDs de regras de segredos e IaC do Cycode específicos. Isso fará com que o escaneamento não alerte sobre 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 os escaneamentos detectem verdadeiros positivos.

A seguir estão as opções disponíveis para o comando cycode ignore:

Opção	Descrição
`--by-value TEXT`	Ignora um valor específico ao escanear segredos. Veja Ignorando um Valor de Segredo para mais detalhes.
`--by-sha TEXT`	Ignora uma representação SHA512 específica de uma string ao escanear segredos. Veja Ignorando um Valor SHA de Segredo para mais detalhes.
`--by-path TEXT`	Evita escanear um caminho específico. Precisa especificar o tipo de escaneamento. Veja Ignorando um Caminho para mais detalhes.
`--by-rule TEXT`	Ignora o escaneamento de um ID de regra de segredo/ID de regra de IaC/ID de regra de SCA específico. Veja Ignorando uma Regra de Segredo ou IaC para mais detalhes.
`--by-package TEXT`	Ignora o escaneamento de uma versão de pacote específica ao executar um escaneamento SCA. Padrão esperado - `name@version`. Veja Ignorando um Pacote para mais detalhes.
`--by-cve TEXT`	Ignora o escaneamento de um CVE específico ao executar um escaneamento SCA. Padrão esperado: CVE-YYYY-NNN.
`-t, --scan-type [secret\|iac\|sca\|sast]`	Especifica o escaneamento 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`.

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 todos os escaneamentos futuros. Use o seguinte comando para adicionar um valor de segredo a ser ignorado:

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

No exemplo no topo 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. Veja as opções de escaneamento do Cycode para detalhes sobre como ver os valores dos segredos nos resultados do escaneamento.

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 todos os escaneamentos futuros. 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 valor SHA do seu segredo.

Ignorando um Caminho

Para ignorar um caminho específico em verificações de segredos, IaC ou SCA, você precisará usar a flag --by-path em conjunto 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 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 valor do seu caminho.

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

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

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

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

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

No exemplo acima, substitua o valor ~/home/my-repo/config pelo valor do seu 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 (é necessário especificar o tipo de verificação). Isso fará com que o valor do ID da regra fornecido seja ignorado 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ífica é 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 de IaC específica é 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 de SCA específica é 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 de SCA.

Para ignorar um pacote específico nas verificações de SCA, você precisará usar a flag --by-package em conjunto com a flag -t, --scan-type (é necessário especificar o tipo de verificação sca). Isso fará com que o pacote fornecido, usando a formatação {{package_name}}@{{package_version}}, seja ignorado 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 [email protected]

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 em um 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 usuários home directory, for example, /Users/nome` 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 a partir do mesmo local. Você deve verificar isso cuidadosamente ao trabalhar com ambientes diferentes, 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 desejar e realizar uma verificação da CLI a partir dessa pasta.

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

Exemplo de um config.yaml real:

exclusions:
  iac:
    rules:
    - bdaa88e2-5e7c-46ff-ac2a-29721418c59c
  sca:
    packages:
    - [email protected]
  secret:
    paths:
    - /Users/name/projects/build
    rules:
    - ce3a4de0-9dfc-448b-a004-c538cf8b4710
    shas:
    - a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
    values:
    - a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
    - 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752

Comando Report

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 uma aplicação. Usando este comando, você pode criar um relatório SBOM para o seu projeto local ou para a 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 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 autogerado salvo no diretório atual
`--include-vulnerabilities`	Incluir vulnerabilidades	Não	False
`--include-dev-dependencies`	Incluir dependências de desenvolvimento	Não	False

Os seguintes comandos 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 a URI do repositório fornecida no comando

Repositório

Para criar um relatório SBOM para uma 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`	Pular a restauração do lockfile e verificar apenas dependências diretas. Veja Opção Lock Restore para detalhes.
`--gradle-all-sub-projects`	Executar o comando de restauração do Gradle para todos os subprojetos (use a partir da raiz de um build Gradle multi-projeto).
`--maven-settings-file`	Apenas para Maven, permite usar um arquivo settings.xml personalizado ao construir a árvore de dependências.

Comando Import

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 uma aplicação. 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 Cycode que serve como ponto de contato para este SBOM	Não
`-b, --business-impact [High \| Medium \| Low]`	Impacto no Negócio	Não	Medium

Por exemplo:
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner [email protected] /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 > CLI Logs.

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 digitar o comando:

cycode --help

Para ver as opções de verificação, digite:

cycode scan --help

Para ver as opções disponíveis para um tipo específico de verificação, digite:

cycode scan {{option}} --help

Por exemplo, para ver as opções disponíveis para uma Verificação de Caminho, você digitaria:

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, digite:

cycode scan {{option}} --help