Cycode

oficial

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

GitHub

100

Experimente este MCPPatrocinado

O que você pode fazer com Cycode MCP?

Verificar segredos hardcoded — Peça ao assistente para executar cycode_secret_scan em caminhos de arquivos ou diretórios especificados para detectar credenciais expostas.
Verificar dependências de software — Use cycode_sca_scan para identificar vulnerabilidades e problemas de licença nos pacotes do seu projeto.
Auditar código de infraestrutura — Invoque cycode_iac_scan para encontrar configurações incorretas em arquivos Terraform, CloudFormation ou outros arquivos de IaC.
Detectar problemas de qualidade de código — Execute cycode_sast_scan para revelar fraquezas de segurança e problemas de qualidade de código em arquivos-fonte.
Verificar configuração da CLI — Chame cycode_status para verificar a versão da CLI Cycode, o estado de autenticação e os detalhes de configuração.

Documentação

Guia do Usuário da CLI Cycode

A Interface de Linha de Comando (CLI) da 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 estático de segurança de aplicações.

Este guia orienta você tanto na instalação quanto no uso.

Sumário

Pré-requisitos
Instalação
1. Instalar a CLI Cycode
2. Instalar o Hook de Pré-Commit
Comandos da CLI Cycode
Certificados e Proxies
Comando MCP
Comando Platform
AI Guardrails
1. Dados Coletados pelo AI Guardrails
Comando Scan
Comando Report
1. Gerando Relatório SBOM
Comando Import
Logs de Varredura
Ajuda de Sintaxe

Pré-requisitos

O aplicativo CLI da 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 na Cycode com a CLI
- Alternativamente, você pode obter um Client ID e uma Client Secret Key da Cycode seguindo os passos detalhados nas páginas Service Account Token e Personal Access Token, 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, dependendo da configuração do seu ambiente Python.

Instalar a CLI Cycode

Para instalar o aplicativo CLI da Cycode em sua máquina local, execute os seguintes passos:

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, em seguida, 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 client ID e as credenciais da Cycode (client secret ou OIDC ID token):
- 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 a CLI da Cycode.

Digite o seguinte comando na janela do seu terminal/linha de comando:

cycode auth
Uma janela do navegador aparecerá, solicitando que você faça login na 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 a Cycode (se aplicável):

[!NOTE] Este será o método padrão para autenticar com a CLI da Cycode.
Clique no botão Allow para autorizar a CLI da Cycode 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 Client ID e Client Secret da 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 janela do seu terminal/linha de comando:
```
cycode configure
```
Insira o valor da sua URL da API da 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 sua URL do APP da 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 Client ID da Cycode.

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

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Insira o valor do seu OIDC ID Token da Cycode (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ê 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 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 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 Secret Key, respectivamente. Se você autenticar via OIDC, adicione também CYCODE_ID_TOKEN com o valor do seu OIDC ID token:
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 da Cycode podem ser configurados no seu repositório local para que o aplicativo CLI da Cycode 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 os seguintes passos 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 hook ID cycode para habilitar a varredura de Segredos. Use o hook ID cycode-sca para habilitar a varredura SCA. Use o hook ID 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 da 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 o rev no .pre-commit-config.yaml para a versão mais recente disponível da CLI da Cycode.

[!NOTE] O acionamento 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 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 da 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 client ID da Cycode para esta execução de varredura específica.
`--client-secret TEXT`	Especificar um client secret da Cycode para esta execução de varredura específica.
`--id-token TEXT`	Especificar um OIDC ID token da 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 realizar: commit-history/path/repository/etc.
report	Gera relatório. Você precisará especificar qual tipo de relatório gerar, como SBOM.
status	Mostra o status da CLI e sai.

Certificados e Proxies

Por padrão, a CLI da Cycode verifica conexões HTTPS em relação ao pacote de CAs enviado com a CLI.

Se sua organização usa um proxy que inspeciona o tráfego HTTPS, ou uma instalação on-premises com seu próprio CA, você tem duas opções.

Opção 1 — usar os certificados já instalados na máquina. Se o seu CA está no armazenamento de certificados da máquina (como geralmente é o caso em um dispositivo gerenciado), opte por isso:

export CYCODE_CLI_ENABLE_TRUSTSTORE=1

A CLI então verifica em relação ao armazenamento de certificados do Windows, ao Keychain do macOS ou ao diretório de CAs do sistema no Linux, e nenhum caminho de certificado precisa ser configurado.

[!IMPORTANT] Isso é opcional de propósito. Confiar no armazenamento da máquina significa confiar em todos os certificados raiz presentes nessa máquina, incluindo qualquer um que um administrador ou software malicioso tenha instalado. Ative-o quando você souber que o armazenamento de certificados da sua máquina é confiável.

Opção 2 — aponte a CLI para um arquivo de pacote de CAs. Funciona sem optar por isso:

Variável de Ambiente	Descrição
`REQUESTS_CA_BUNDLE`	Caminho para um arquivo de pacote de CAs (`.pem` ou `.crt`) a ser confiado.
`CURL_CA_BUNDLE`	Alias para `REQUESTS_CA_BUNDLE`, respeitado quando este último não está definido.

As duas opções se combinam: com CYCODE_CLI_ENABLE_TRUSTSTORE=1, certificados de REQUESTS_CA_BUNDLE são confiados além do armazenamento da máquina, não em vez dele.

[!TIP] Execute qualquer comando com -v para ver qual fonte de confiança está em uso, por exemplo cycode -v status.

Notas:

CYCODE_CLI_ENABLE_TRUSTSTORE requer Python 3.10 ou mais recente. No Python 3.9, a CLI registra um aviso e volta ao pacote de CAs incluído; use REQUESTS_CA_BUNDLE em vez disso, ou atualize o Python. Os executáveis independentes e a imagem Docker já incluem um Python suportado.
No Windows, a CLI sempre voltou ao armazenamento de certificados do sistema quando nem REQUESTS_CA_BUNDLE nem CURL_CA_BUNDLE está definido. Esse comportamento não mudou.
Os proxies em si são configurados com as variáveis de ambiente padrão HTTP_PROXY, HTTPS_PROXY e NO_PROXY.

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 da 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 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`	Varre em busca de segredos codificados
`cycode_sca_scan`	Varre em busca de Análise de Composição de Software (SCA) - vulnerabilidades e problemas de licença
`cycode_iac_scan`	Varre em busca de configurações incorretas de Infraestrutura como Código (IaC)
`cycode_sast_scan`	Varre em busca de Teste de Segurança de Aplicações Estáticas (SAST) - qualidade de código e falhas de segurança
`cycode_status`	Obtém 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 tokens 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 de "detections".

Exemplos de Uso

Exemplos de Comandos Básicos

Inicie o servidor MCP com 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 – 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 (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. 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 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

Timeouts e Certificados Personalizados (Ambientes com Proxy)

Se varreduras de longa duração estão sendo interrompidas pelo seu cliente MCP, aumente o timeout da chamada de ferramenta.

Variável de Ambiente	Descrição
`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 cortadas antes de terminar.

Atrás de um proxy corporativo, defina as variáveis de certificado no bloco env do servidor MCP. Veja Certificados e Proxies para as opções: ou CYCODE_CLI_ENABLE_TRUSTSTORE=1 para usar os certificados já na máquina, ou REQUESTS_CA_BUNDLE apontando para um arquivo de pacote de CAs.

Exemplo de configuração mcp.json com um pacote de CAs personalizado e um timeout mais longo:

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

[!NOTE] O servidor MCP requer autenticação 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 de permissão interativos. 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 o sinalizador -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 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 em automação de produção ainda. O comando cycode platform expõe as APIs de leitura da plataforma Cycode como comandos de CLI. Ele agrupa endpoints por recurso (por exemplo, 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 é obtida 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 a busca.

[!NOTE] Você deve estar autenticado (cycode auth ou variáveis de ambiente CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET) para que o 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 sobre o que está disponível é o --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 da 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 nesta versão beta.
Orientado por especificação. Adicionar um novo endpoint à API o torna disponível automaticamente na próxima vez que o cache for atualizado.
Sem especificação incluída. 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 na rede. Em conexões lentas, esta 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>.

AI Guardrails [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 acontece no lado do servidor, então 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 da 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. Parte disso são dados pessoais:

Identificadores de dispositivo — o nome do host da máquina e o número de série do hardware.
Identificadores de 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 de guardrails (cycode ai-guardrails uninstall remove hooks que já estão instalados).

Comando de Verificação

Executando uma Verificação

O aplicativo CLI da Cycode oferece vários tipos de verificação para que você possa escolher a opção que melhor se adequa ao seu caso. As seguintes são as opções e comandos atuais 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`/`unmaintained-packages`). O padrão é todos.
`--monitor`	Quando especificado, os resultados da verificação serão registrados na 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, a Cycode não executará o comando de restauração. Isso verificará SOMENTE dependências diretas!
`--stop-on-error`	Abortar a verificação se qualquer falha de coleta de arquivos ou restauração de dependências ocorrer, 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 o 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 o 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 que tenham 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 a 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 a CLI da Cycode, um relatório é gerado automaticamente e seus resultados são enviados para a Cycode. Esses resultados estão vinculados às políticas relevantes (por exemplo, políticas SCA para verificações de Repositório) dentro da plataforma Cycode.

Para ter a URL direta deste relatório Cycode impressa na saída da sua 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 da CLI aparecerão na seção Logs da CLI da 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 verificação.

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

cli-report

A página do relatório será semelhante ao 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 seguindo 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 Pacotes Não Mantidos

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

Para verificar apenas pacotes não mantidos (pacotes cuja verificação OpenSSF Scorecard Maintained é baixa, significando pouca ou nenhuma atividade recente de commits e issues), adicione o argumento --sca-scan unmaintained-packages seguindo a opção -t sca ou --scan-type sca.

[!NOTE] Se pacotes não mantidos são relatados ou não é controlado pela política da sua organização. Esta opção restringe o que uma verificação relata; ela não pode habilitar uma política que está desativada para o seu tenant.

No exemplo anterior, se você quisesse executar apenas uma verificação SCA em pacotes não mantidos, poderia executar o seguinte:

cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase

Opção de Restauração de Lockfile

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

Ao executar uma verificação SCA, a CLI da Cycode 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 a flag --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 junto ao manifesto, a 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 de Parar em Erro

Por padrão, a Cycode continua a verificação 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 verificação SCA. O item com falha é pulado com um aviso e a verificação prossegue com os arquivos restantes.

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

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

Isto é ú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, especificamente para falhas de restauração de SCA, adicionar --no-restore para pular a geração do arquivo de bloqueio e escanear apenas as 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 (somente 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 segredos atualmente expostos no repositório, mas também segredos anteriormente excluídos.

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

cycode scan repository {{path}}

Por exemplo, se você quisesse escanear um repositório armazenado em ~/home/git/codebase, você 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`	Ramo a ser escaneado; se não definido, escaneia o ramo padrão

Opção de Ramo

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

Dado o exemplo anterior, se você quisesse escanear apenas um ramo chamado dev, você 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 exclusivamente 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 Terraform

A CLI do Cycode suporta varredura de planos Terraform (com suporte ao Terraform 0.12 e versões posteriores)

O arquivo de plano 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 Terraform:

terraform init
Crie o plano de execução 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 de 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 ser vazados ou expostos. Para varreduras de 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 requests 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 (Varredura de Diff)

A opção de intervalo de commits permite a varredura 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 requests: Escaneie apenas as alterações introduzidas em um PR
Varredura incremental em CI/CD: Foque nas alterações recentes em vez de todo o código
Revisão de ramos de funcionalidade: Compare alterações com o ramo principal/master
Otimização de desempenho: Varreduras 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 ao 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 ramo1 ao ramo2	`main..feature-branch`

Exemplos de Varredura de Diff

Escaneie alterações no último commit:

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

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

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

Escaneie alterações no seu ramo de funcionalidade comparado ao main:

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

Escaneie alterações entre main e um ramo de funcionalidade:

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

Escaneie 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.

Varredura Pré-Commit

Uma varredura pré-commit identifica automaticamente quaisquer problemas antes de você commitar alterações no seu repositório. Não é necessário executar esta varredura 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 varredura durante um commit específico. Para fazer isso, adicione o seguinte ao seu comando git para pular a varredura de um único commit:

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

Varredura Pré-Push

Uma varredura 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 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 pré-push não está disponível para varreduras de IaC.

O hook pré-push integra-se ao framework pré-commit e pode ser configurado para executar antes de qualquer operação git push.

Instalando o Hook Pré-Push

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

Instale o framework pré-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 múltiplos tipos de varredura, 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 Varredura Pré-Push

O hook pré-push:

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

Detecção Inteligente do Ramo Padrão

O hook pré-push detecta inteligentemente o ramo 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 o ramo padrão remoto real
Informações Remotas do Git: Recorre a git remote show origin se symbolic-ref falhar
Substitutos Codificados: Usa nomes comuns de ramos padrão (origin/main, origin/master, main, master)

Definindo um Ramo Padrão Personalizado:

export CYCODE_DEFAULT_BRANCH=origin/develop

Esta 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 ramo padrão.

Pulando Varreduras Pré-Push

Para pular a varredura pré-push em 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 escaneia apenas os commits que estão prestes a ser enviados, tornando-o mais eficiente do que escanear todo o repositório.

Excluir Caminhos das Varreduras

Você pode usar um arquivo .cycodeignore para informar à CLI do Cycode quais arquivos e diretórios excluir das varreduras. Ele funciona exatamente como um arquivo .gitignore. Isso ajuda você a focar as varreduras 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 deseja excluir, usando os mesmos padrões do .gitignore.
Coloque este arquivo no diretório onde você planeja executar o comando de varredura do cycode.

[!WARNING]

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

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

Scanners Suportados

SAST
IaC (em breve)
SCA (em breve)

Resultados da Varredura

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

Se nenhum problema for encontrado, a varredura 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 quaisquer alterações necessárias para resolver o problema e execute a varredura 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 varreduras obscurecem segredos por padrão, mas você pode opcionalmente desativar esse recurso para visualizar o segredo completo (supondo que a máquina em que você está visualizando o resultado da varredura seja suficientemente segura contra olhares curiosos).

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

No exemplo a seguir, uma Varredura de Caminho é executada 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

Na operação normal, a CLI retornará um código de saída de 1 quando problemas forem encontrados nos resultados da varredura. 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 varredura, o código de saída será forçado a 0 independentemente de quaisquer resultados serem encontrados.

Exemplos de Resultados de Varredura

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 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 chamado "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 Varredura

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

[!WARNING] Adicionar valores para serem ignorados deve ser feito com consideração cuidadosa dos valores, caminhos e políticas para garantir que as varreduras detectem verdadeiros positivos.

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

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

Ignorando um Valor de Segredo

Para ignorar um valor de segredo específico, você precisará usar o sinalizador --by-value. Isso ignorará o valor de segredo fornecido em todas as varreduras futuras. 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. Consulte as opções de varredura da Cycode para obter detalhes sobre como ver valores de segredo nos resultados da varredura.

Ignorando um Valor SHA de Segredo

Para ignorar um valor SHA de segredo específico, você precisará usar o sinalizador --by-sha. Isso ignorará o valor SHA de segredo fornecido em todas as varreduras 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 topo 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 varreduras de segredos, IaC ou SCA, você precisará usar o sinalizador --by-path em conjunto com o sinalizador -t, --scan-type (você deve especificar o tipo de varredura). Isso ignorará o caminho fornecido em todas as varreduras futuras para o tipo de varredura fornecido. Use o seguinte comando para adicionar um caminho a ser ignorado:

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

No exemplo no topo desta seção, o comando para ignorar um caminho específico para segredos é 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 topo desta seção, o comando para ignorar um caminho específico das varreduras 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 topo desta seção, o comando para ignorar um caminho específico das varreduras 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 o sinalizador --by-rule em conjunto com o sinalizador -t, --scan-type (você deve especificar o tipo de varredura). Isso ignorará o valor do ID da regra fornecido em todas as varreduras 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 topo desta seção, o comando para ignorar o ID de 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 topo desta seção, o comando para ignorar o ID de 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 topo desta seção, o comando para ignorar o ID de 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 varreduras SCA.

Para ignorar um pacote específico nas varreduras SCA, você precisará usar o sinalizador --by-package em conjunto com o sinalizador -t, --scan-type (você deve especificar o tipo de varredura sca). Isso ignorará o pacote fornecido, usando a formatação {{package_name}}@{{package_version}}, em todas as varreduras 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 por meio de 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 CLI de ignorar 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 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/name` no macOS.

Salvar no espaço global pode ser realizado com o sinalizador -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 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 varreduras 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 varredura CLI a partir dessa pasta.

Estrutura das regras de ignorar na configuração

É importante entender como a CLI armazena 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] 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 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 SBOM	Sim
`-o, --output-format [JSON]`	Especificar o formato do arquivo de saída	Não	json
`--output-file PATH`	Arquivo de saída	Não	nome de arquivo gerado automaticamente salvo no diretório atual
`--include-vulnerabilities`	Incluir vulnerabilidades	Não	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`	Gerar relatório SBOM para o caminho fornecido no comando
`repository-url`	Gerar relatório SBOM para o URI do repositório fornecido no comando

Repositório

Para criar um relatório SBOM para um URI de repositório:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>

Por exemplo:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git

Projeto Local

Para criar um relatório SBOM para um caminho:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>

Por exemplo:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project

O subcomando path suporta as seguintes opções adicionais:

Opção	Descrição
`--no-restore`	Ignora a restauração do lockfile e escaneia apenas dependências diretas. Consulte Opção de Restauração de Lock para detalhes.
`--gradle-all-sub-projects`	Executa o comando de restauração do Gradle para todos os subprojetos (use a partir da raiz de um build Gradle multiprojeto).
`--maven-settings-file`	Apenas 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 Escaneamento

Todos os escaneamentos da CLI são registrados no Cycode. Os logs podem ser encontrados em Configurações > Logs da CLI.

Ajuda de Sintaxe

Você pode adicionar o argumento --help a qualquer comando a qualquer momento para ver uma mensagem de ajuda que exibirá as opções disponíveis e sua sintaxe.

Para ver a ajuda geral, basta inserir o comando:

cycode --help

Para ver as opções de escaneamento, insira:

cycode scan --help

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

cycode scan {{option}} --help

Por exemplo, para ver as opções disponíveis para um Escaneamento de Caminho, você inseriria:

cycode scan path --help

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