Cycode

oficial

Mejora la seguridad en tu ciclo de desarrollo mediante escaneo SAST, SCA, Secretos e IaC con Cycode.

¿Qué puedes hacer con Cycode MCP?

Escanear una ruta de repositorio en busca de secretos hardcodeados — Pídele al asistente que ejecute cycode_secret_scan en un directorio local para detectar credenciales expuestas.
Verificar dependencias en busca de vulnerabilidades conocidas — Activa cycode_sca_scan en una ruta de proyecto para identificar paquetes de código abierto vulnerables o no conformes.
Auditar archivos de Infrastructure as Code en busca de configuraciones incorrectas — Usa cycode_iac_scan en directorios de Terraform o CloudFormation para revelar configuraciones riesgosas.
Revisar el código fuente en busca de fallos de seguridad — Ejecuta cycode_sast_scan en un código base para encontrar debilidades a nivel de código y problemas de calidad.
Verificar la autenticación de la CLI y el estado de la versión — Llama a cycode_status para confirmar la conexión con Cycode y qué versión está activa.

Documentación

Guía de usuario de Cycode CLI

La interfaz de línea de comandos (CLI) de Cycode es una aplicación que puede instalar localmente para escanear sus repositorios en busca de secretos, configuraciones incorrectas de infraestructura como código, vulnerabilidades de análisis de composición de software y problemas de pruebas de seguridad de aplicaciones estáticas.

Esta guía le guía a través de la instalación y el uso.

Tabla de contenidos

Requisitos previos
Instalación
1. Instalar Cycode CLI
2. Instalar el hook de pre-commit
Comandos de Cycode CLI
Comando MCP
Comando Platform
Salvaguardas de IA
1. Datos recopilados por las salvaguardas de IA
Comando Scan
Comando Report
1. Generando informe SBOM
Comando Import
Registros de escaneo
Ayuda de sintaxis

Requisitos previos

La aplicación Cycode CLI requiere Python versión 3.9 o posterior. El comando MCP está disponible solo para Python 3.10 y superior. Si está utilizando una versión anterior de Python, este comando no estará disponible.
Use el comando cycode auth para autenticarse en Cycode con la CLI
- Alternativamente, puede obtener un ID de cliente de Cycode y una clave secreta de cliente siguiendo los pasos detallados en las páginas Service Account Token y Personal Access Token, que contienen detalles sobre cómo obtener estos valores.

Instalación

Los siguientes pasos de instalación son aplicables tanto a sistemas operativos Windows como UNIX/Linux.

[!NOTA] Los siguientes pasos asumen el uso de python3 y pip3 para comandos relacionados con Python; sin embargo, algunos sistemas pueden usar en su lugar los comandos python y pip, dependiendo de la configuración de su entorno Python.

Instalar Cycode CLI

Para instalar la aplicación Cycode CLI en su máquina local, realice los siguientes pasos:

Abra su aplicación de línea de comandos o terminal.
Ejecute uno de los siguientes comandos:
- Para instalar desde PyPI:
```
pip3 install cycode
```
- Para instalar desde Homebrew:
```
brew install cycode
```
- Para instalar desde GitHub Releases, navegue y descargue el ejecutable para su sistema operativo y arquitectura, luego ejecute el siguiente comando:
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
Finalmente, autentique la CLI. Hay tres métodos para configurar el ID de cliente de Cycode y las credenciales (secreto de cliente o token de ID OIDC):
- cycode auth (Recomendado)
- cycode configure
- Agréguelos a sus variables de entorno

Usando el comando Auth

[!NOTA] Este es el método recomendado para configurar su máquina local para autenticarse con Cycode CLI.

Escriba el siguiente comando en su ventana de terminal/línea de comandos:

cycode auth
Aparecerá una ventana del navegador pidiéndole que inicie sesión en Cycode (como se ve a continuación):
Ingrese sus credenciales de inicio de sesión en esta página e inicie sesión.
Eventualmente será llevado a la página siguiente, donde se le pedirá que elija el grupo empresarial con el que desea autorizar Cycode (si corresponde):

[!NOTA] Este será el método predeterminado para autenticarse con Cycode CLI.
Haga clic en el botón Permitir para autorizar Cycode CLI en el grupo empresarial seleccionado.
Una vez completado, verá la siguiente pantalla si se seleccionó correctamente:
En la pantalla de terminal/línea de comandos, verá lo siguiente al salir de la ventana del navegador:

Successfully logged into cycode

Usando el comando Configure

[!NOTA] Si ya configuró su ID de cliente de Cycode y su secreto de cliente a través de las variables de entorno de Linux o Windows, esas credenciales tendrán prioridad sobre este método.

Escriba el siguiente comando en su ventana de terminal/línea de comandos:
```
cycode configure
```
Ingrese el valor de la URL de la API de Cycode (puede dejarlo en blanco para usar el valor predeterminado).

Cycode API URL [https://api.cycode.com]: https://api.onpremise.com
Ingrese el valor de la URL de la aplicación de Cycode (puede dejarlo en blanco para usar el valor predeterminado).

Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com
Ingrese el valor de su ID de cliente de Cycode.

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
Ingrese el valor de su secreto de cliente de Cycode (omita si planea usar un token de ID OIDC).

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Ingrese el valor de su token de ID OIDC de Cycode (opcional).

Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Si los valores se ingresaron correctamente, verá el siguiente mensaje:

Successfully configured CLI credentials!

o/y

Successfully configured Cycode URLs!

Si va a la carpeta .cycode en su carpeta de usuario, encontrará que estas credenciales se crearon y se colocaron en el archivo credentials.yaml en esa carpeta. Las URL se colocaron en el archivo config.yaml en esa carpeta.

Agregar a variables de entorno

En Unix/Linux:

export CYCODE_CLIENT_ID={your Cycode ID}

export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

Si su organización utiliza autenticación OIDC, puede proporcionar el token de ID en su lugar (o además):

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

En Windows

Desde el Panel de control, navegue al menú Sistema:
A continuación, haga clic en Configuración avanzada del sistema:
En la ventana Propiedades del sistema que se abre, haga clic en el botón Variables de entorno:
Cree las variables CYCODE_CLIENT_ID y CYCODE_CLIENT_SECRET con valores que coincidan con su ID y clave secreta, respectivamente. Si se autentica mediante OIDC, agregue también CYCODE_ID_TOKEN con el valor de su token de ID OIDC:
Inserte el cycode.exe en la ruta para completar la instalación.

Instalar el hook de pre-commit

Los hooks de pre-commit y pre-push de Cycode se pueden configurar dentro de su repositorio local para que la aplicación Cycode CLI identifique automáticamente cualquier problema con su código antes de que lo confirme o lo envíe a su base de código.

[!NOTA] Los hooks de pre-commit y pre-push no están disponibles para escaneos de IaC.

Realice los siguientes pasos para instalar el hook de pre-commit:

Instalando el hook de pre-commit

Instale el framework de pre-commit (debe tener instalado Python 3.9 o superior):
```
pip3 install pre-commit
```
Navegue al directorio superior del repositorio Git local que desea configurar.
Cree un nuevo archivo YAML llamado .pre-commit-config.yaml (incluya el comienzo .) en el directorio superior del repositorio que contenga lo siguiente:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
Modifique el archivo creado según sus necesidades específicas. Use el ID de hook cycode para habilitar el escaneo de secretos. Use el ID de hook cycode-sca para habilitar el escaneo SCA. Use el ID de hook cycode-sast para habilitar el escaneo SAST. Si desea habilitar todos los tipos de escaneo, use esta configuración:
```
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 el hook de Cycode:
```
pre-commit install
```
Una instalación exitosa del hook resultará en el mensaje: Pre-commit installed at .git/hooks/pre-commit.
Mantenga el hook de pre-commit actualizado:
```
pre-commit autoupdate
```
Automáticamente actualizará rev en .pre-commit-config.yaml a la última versión disponible de Cycode CLI.

[!NOTA] El disparador ocurre en el comando git commit. El hook se activa solo en los archivos que están preparados para la confirmación.

Instalando el hook de pre-push

Para instalar el hook de pre-push además o en lugar del hook de pre-commit:

Agregue los hooks de pre-push a su archivo .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 el hook de pre-push:

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

Para ambos hooks de pre-commit y pre-push, use:

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

[!NOTA] Los hooks de pre-push se activan en el comando git push y escanean solo las confirmaciones que están a punto de enviarse.

Comandos de Cycode CLI

Las siguientes son las opciones y comandos disponibles con la aplicación Cycode CLI:

Opción	Descripción
`-v`, `--verbose`	Mostrar registros detallados.
`--no-progress-meter`	No mostrar el medidor de progreso.
`--no-update-notifier`	No verificar actualizaciones de la CLI.
`-o`, `--output [rich\|text\|json\|table]`	Especificar el tipo de salida. El valor predeterminado es `rich`.
`--client-id TEXT`	Especificar un ID de cliente de Cycode para esta ejecución de escaneo específica.
`--client-secret TEXT`	Especificar un secreto de cliente de Cycode para esta ejecución de escaneo específica.
`--id-token TEXT`	Especificar un token de ID OIDC de Cycode para esta ejecución de escaneo específica.
`--install-completion`	Instalar la finalización para el shell actual..
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Mostrar la finalización para el shell especificado, para copiarla o personalizar la instalación.
`-h`, `--help`	Mostrar opciones para el comando dado.
Comando	Descripción
-------------------------------------------	----------------------------------------------------------------------------------------------------------------------------------------------
auth	Autentica tu máquina para asociar la CLI con tu cuenta de Cycode.
configure	Comando inicial para configurar la autenticación de tu cliente CLI.
ignore	Ignora un valor, ruta o ID de regla específico.
mcp	Inicia el servidor del Protocolo de Contexto de Modelo (MCP) para habilitar la integración de IA con las capacidades de escaneo de Cycode.
scan	Escanea el contenido en busca de violaciones de Secrets/IaC/SCA/SAST. Deberás especificar qué tipo de escaneo realizar: commit-history/path/repository/etc.
report	Genera un informe. Deberás especificar qué tipo de informe realizar, como SBOM.
status	Muestra el estado de la CLI y sale.

Comando MCP [EXPERIMENT]

[!WARNING] El comando MCP está disponible solo para Python 3.10 y superior. Si usas una versión anterior de Python, este comando no estará disponible.

El comando del Protocolo de Contexto de Modelo (MCP) te permite iniciar un servidor MCP que expone las capacidades de escaneo de Cycode a sistemas y aplicaciones de IA. Esto permite que los modelos de IA interactúen con las herramientas CLI de Cycode mediante un protocolo estandarizado.

[!TIP] Para una mejor experiencia, instala Cycode CLI globalmente en tu sistema usando pip install cycode o brew install cycode, luego autentícate una vez con cycode auth. Después de la instalación global y la autenticación, no necesitarás configurar las variables de entorno CYCODE_CLIENT_ID y CYCODE_CLIENT_SECRET en tus archivos de configuración MCP.

Iniciando el servidor MCP

Para iniciar el servidor MCP, usa el siguiente comando:

cycode mcp

Por defecto, esto inicia el servidor usando el transporte stdio, que es adecuado para integraciones locales y aplicaciones de IA que pueden generar subprocesos.

Opciones disponibles

Opción	Descripción
`-t, --transport`	Tipo de transporte para el servidor MCP: `stdio`, `sse` o `streamable-http` (por defecto: `stdio`)
`-H, --host`	Dirección de host para vincular el servidor (solo se usa para transporte no stdio) (por defecto: `127.0.0.1`)
`-p, --port`	Número de puerto para vincular el servidor (solo se usa para transporte no stdio) (por defecto: `8000`)
`--help`	Muestra el mensaje de ayuda y las opciones disponibles

Herramientas MCP

El servidor MCP proporciona las siguientes herramientas que los sistemas de IA pueden usar:

Nombre de la herramienta	Descripción
`cycode_secret_scan`	Escanea en busca de secretos codificados
`cycode_sca_scan`	Escanea para Análisis de Composición de Software (SCA): vulnerabilidades y problemas de licencia
`cycode_iac_scan`	Escanea en busca de malas configuraciones de Infraestructura como Código (IaC)
`cycode_sast_scan`	Escanea para Pruebas de Seguridad de Aplicaciones Estáticas (SAST): calidad del código y fallos de seguridad
`cycode_status`	Obtén la versión de Cycode CLI, el estado de autenticación y la información de configuración

Cada herramienta de escaneo acepta dos modos de entrada mutuamente excluyentes:

paths (preferido) — una o más rutas de archivo o directorio que existen en el disco. Los directorios se escanean recursivamente. El motor de Cycode maneja el descubrimiento y filtrado de archivos, igual que cycode scan -t <type> path ./src desde la CLI.
files (respaldo) — un diccionario que mapea rutas de archivo a su contenido completo como cadenas. Úsalo solo cuando los archivos no estén disponibles en el disco (por ejemplo, ediciones en memoria aún no guardadas).

[!TIP] Usa paths siempre que sea posible. Pasar archivos grandes (como package-lock.json) como contenido en línea puede exceder los límites de tokens y ralentizar el cliente de IA. Con paths, el motor de Cycode lee los archivos directamente del disco.

Todas las herramientas de escaneo devuelven un objeto JSON que incluye un campo "summary" con un recuento de violaciones legible por humanos (por ejemplo, "Cycode found 3 violations: 1 CRITICAL, 2 HIGH.") además del array completo "detections".

Ejemplos de uso

Ejemplos básicos de comandos

Inicia el servidor MCP con la configuración predeterminada (transporte stdio):

cycode mcp

Inicia el servidor MCP con transporte stdio explícito:

cycode mcp -t stdio

Inicia el servidor MCP con transporte de Eventos Enviados por el Servidor (SSE):

cycode mcp -t sse -p 8080

Inicia el servidor MCP con transporte HTTP transmisible en host y puerto personalizados:

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

Aprende más sobre los tipos de transporte MCP en la Especificación del Protocolo MCP – Transports.

Ejemplos de configuración

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

[!NOTE] Para entornos Cycode de la UE, asegúrate de establecer los valores apropiados de CYCODE_API_URL y CYCODE_APP_URL en las variables de entorno (por ejemplo, https://api.eu.cycode.com y https://app.eu.cycode.com).

Sigue esta guía para configurar el servidor MCP en tu VS Code/GitHub Copilot. Ten en cuenta que en settings.json, hay un objeto mcp que contiene un subobjeto servers anidado, en lugar de un objeto mcpServers independiente.

Para transporte stdio (ejecución directa):

{
  "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 con instalación de pipx:

{
  "mcpServers": {
    "cycode": {
      "command": "pipx",
      "args": ["run", "cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

Para transporte stdio con instalación de uvx:

{
  "mcpServers": {
    "cycode": {
      "command": "uvx",
      "args": ["cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

Para transporte SSE (Eventos Enviados por el Servidor):

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

Para transporte SSE en puerto personalizado:

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

Para transporte HTTP transmisible:

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

Ejecutando el servidor MCP en segundo plano

Para transporte SSE (inicia el servidor primero, luego configura el 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 transmisible:

# 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"
    }
  }
}

Configuración avanzada

Certificados personalizados y tiempos de espera (entornos proxy)

Si tu organización usa un proxy corporativo o un paquete de CA personalizado para la inspección HTTPS, debes indicar a Cycode CLI (y a la pila TLS subyacente de Python) dónde encontrar el paquete de certificados de confianza. También puedes aumentar el tiempo de espera de las llamadas a las herramientas MCP si los escaneos se interrumpen.

Variable de entorno	Descripción
`REQUESTS_CA_BUNDLE`	Ruta a un archivo de paquete de CA personalizado (`.pem` o `.crt`). Usado por la librería `requests` para todas las llamadas HTTPS realizadas por Cycode CLI.
`SSL_CERT_FILE`	Ruta a un archivo de paquete de CA personalizado. Usado por el módulo de bajo nivel `ssl` de Python. Establece esto junto con `REQUESTS_CA_BUNDLE` para una cobertura completa.
`MCP_TOOL_TIMEOUT`	Tiempo de espera (en segundos) que los clientes MCP como Claude y GitHub Copilot esperan a que se complete una llamada a una herramienta. Auméntalo si los escaneos de larga duración se cortan antes de terminar.

[!TIP] Establece tanto REQUESTS_CA_BUNDLE como SSL_CERT_FILE a la misma ruta de paquete de CA. REQUESTS_CA_BUNDLE cubre la capa HTTP; SSL_CERT_FILE cubre la capa TLS de bajo nivel. Usar solo uno puede aún causar errores de certificado en algunos entornos.

Ejemplo de configuración de mcp.json con certificados personalizados y un tiempo de espera más largo:

{
  "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] El servidor MCP requiere una autenticación adecuada de Cycode CLI para funcionar. Asegúrate de haberte autenticado usando cycode auth o de haber configurado tus credenciales antes de iniciar el servidor MCP.

Preautorizando herramientas para subagentes (Claude Code)

Cuando Claude Code delega trabajo a subagentes en segundo plano (por ejemplo, para ejecutar escaneos en paralelo), esos subagentes no pueden mostrar avisos de permiso interactivos. Si las herramientas de Cycode no han sido preaprobadas, los escaneos fallarán silenciosamente en contextos de subagentes.

Para preautorizar las herramientas MCP de Cycode y que funcionen en todos los contextos, incluidos los subagentes, agrégalas a la lista allowedTools en la configuración de 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"
  ]
}

Una vez agregadas, Claude Code no solicitará aprobación cuando se llamen estas herramientas, y funcionarán correctamente dentro de los subagentes.

Solución de problemas de MCP

Si encuentras problemas con el servidor MCP, puedes habilitar el registro de depuración para obtener información más detallada sobre lo que está sucediendo. Hay dos formas de habilitar el registro de depuración:

Usando la bandera -v o --verbose:

cycode -v mcp

Usando la variable de entorno CYCODE_CLI_VERBOSE:

CYCODE_CLI_VERBOSE=1 cycode mcp

Los registros de depuración mostrarán información detallada sobre:

Inicio y configuración del servidor
Intentos de conexión y estado
Ejecución de herramientas y resultados
Cualquier error o advertencia que ocurra

Esta información puede ser útil cuando:

Diagnosticando problemas de conexión
Entendiendo por qué ciertas herramientas no funcionan
Identificando problemas de autenticación
Depurando problemas específicos del transporte

Configuración de MCP

Comando de Plataforma [BETA]

[!WARNING] El comando platform está en beta. Los comandos, argumentos y formatos de salida se generan dinámicamente a partir de la especificación de la API de Cycode y pueden cambiar entre versiones sin previo aviso. No confíes en ellos aún en automatización de producción.

El comando cycode platform expone las API de lectura de la plataforma Cycode como comandos CLI. Agrupa los endpoints por recurso (por ejemplo, projects, violations, workflows) y convierte los parámetros de cada endpoint en argumentos CLI tipados y banderas --option.

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

La especificación OpenAPI se obtiene de la API de Cycode en el primer uso y se almacena en caché en ~/.cycode/openapi-spec.json durante 24 horas. Los comandos no relacionados (cycode scan, cycode status, etc.) no activan una obtención.

[!NOTE] Debes estar autenticado (cycode auth o variables de entorno CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET) para que cycode platform descubra y ejecute comandos. Otros comandos de Cycode CLI funcionan sin autenticación.

Descubriendo comandos

Debido a que los comandos se generan a partir de la especificación, la fuente de verdad sobre lo que está disponible es --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

Ejemplos de plataforma

# List projects with pagination
cycode platform projects list --page-size 25

# View a single project by ID
cycode platform projects view <project-id>

# Count violations across the tenant
cycode platform violations count

# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL

Todo el resultado es JSON por defecto: pásalo por jq para filtrado ad-hoc:

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

Notas y limitaciones de la plataforma

Solo lectura por ahora. Solo se exponen los endpoints GET en esta beta.
Impulsado por especificación. Agregar un nuevo endpoint a la API lo muestra automáticamente la próxima vez que se actualice la caché.
Sin especificación incluida. La primera invocación de cycode platform después de la instalación (o después de que expire la caché de 24h) realiza una obtención de red. En conexiones lentas, esta primera llamada puede tardar unos segundos; las llamadas posteriores son casi instantáneas hasta que expire la caché.
Anula el TTL de la caché con CYCODE_SPEC_CACHE_TTL=<seconds>.

Salvaguardas de IA [BETA]

AI Guardrails instala ganchos en los agentes de codificación de IA compatibles (Claude Code, Cursor, Copilot, Codex) para que los prompts, los archivos que el agente lee y los argumentos de las herramientas MCP se escaneen en busca de secretos antes de que lleguen al modelo.

Datos recopilados por AI Guardrails

El escaneo ocurre en el servidor, por lo que el contenido escaneado sale de la máquina: el texto del prompt, el contenido de los archivos que el agente lee y los argumentos de las herramientas MCP se envían a tu tenant de Cycode para verificar si hay secretos.

Cada evento también se reporta con contexto sobre el desarrollador y la máquina, de modo que un hallazgo pueda atribuirse al dispositivo y al usuario del que proviene. Parte de esto son datos personales:

Identificadores de dispositivo — el nombre de host de la máquina y el número de serie del hardware.
Identificadores de usuario — la dirección de correo electrónico del usuario que inició sesión en el agente de codificación de IA, y el nombre de usuario local del sistema operativo.
Detalles del entorno — sistema operativo y versión, el agente de IA, su versión y el modelo en uso, el contenido de los archivos de configuración MCP del agente y sus plugins habilitados.

El número de serie del hardware se almacena en caché en un archivo temporal local, legible solo por el usuario que ejecutó el comando, para que las invocaciones repetidas de ganchos no vuelvan a consultar el hardware.

Si la recopilación de estos datos no es aceptable en tu entorno, no instales los ganchos de guardrails (cycode ai-guardrails uninstall elimina los ganchos que ya están instalados).

Comando de escaneo

Ejecutar un escaneo

La aplicación CLI de Cycode ofrece varios tipos de escaneos para que puedas elegir la opción que mejor se adapte a tu caso. Las siguientes son las opciones y comandos actualmente disponibles:

Opción	Descripción
`-t, --scan-type [secret\|iac\|sca\|sast]`	Especifica el escaneo que deseas ejecutar (`secret`/`iac`/`sca`/`sast`), el valor predeterminado es `secret`.
`--show-secret BOOLEAN`	Muestra los secretos en texto plano. Consulta la sección Mostrar/Ocultar secretos para más detalles.
`--soft-fail BOOLEAN`	Ejecuta el escaneo sin fallar, siempre devuelve un código de estado sin error. Consulta la sección Fallo suave para más detalles.
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	Muestra solo las violaciones en el nivel especificado o superior.
`--sca-scan`	Especifica el escaneo SCA que deseas ejecutar (`package-vulnerabilities`/`license-compliance`). El valor predeterminado es ambos.
`--monitor`	Cuando se especifica, los resultados del escaneo se registrarán en Cycode.
`--cycode-report`	Muestra un enlace al informe de escaneo en la plataforma Cycode en la salida de la consola.
`--no-restore`	Cuando se especifica, Cycode no ejecutará el comando de restauración. ¡Esto escaneará SOLO las dependencias directas!
`--stop-on-error`	Aborta el escaneo si ocurre algún fallo en la recopilación de archivos o en la restauración de dependencias, en lugar de omitir el archivo fallido y continuar.
`--gradle-all-sub-projects`	Ejecuta el comando de restauración de gradle para todos los subproyectos. Esto debe ejecutarse desde
`--maven-settings-file`	Solo para Maven, permite usar un archivo settings.xml personalizado al escanear dependencias.
`--help`	Muestra las opciones para el comando dado.

Comando	Descripción
commit-history	Escanea el historial de confirmaciones o realiza un escaneo de diferencias entre confirmaciones específicas
path	Escanea los archivos en la ruta proporcionada en el comando
pre-commit	Usa este comando para escanear el contenido que aún no se ha confirmado
repository	Escanea el repositorio git incluyendo su historial

Opciones

Opción de severidad

Para limitar los resultados del escaneo a un umbral de severidad específico, se puede agregar el argumento --severity-threshold al comando de escaneo.

Por ejemplo, el siguiente comando escaneará el repositorio en busca de violaciones de políticas que tengan una severidad de Media o superior:

cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

Opción de monitoreo

[!NOTE] Esta opción solo está disponible para escaneos SCA.

Para enviar los resultados del escaneo vinculados a las políticas de SCA encontradas en un escaneo de tipo SCA a Cycode, agrega el argumento --monitor al comando de escaneo.

Por ejemplo, el siguiente comando escaneará el repositorio en busca de violaciones de políticas SCA y las enviará a la plataforma Cycode:

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

Opción de informe de Cycode

Para cada escaneo realizado con la CLI de Cycode, se genera automáticamente un informe y sus resultados se envían a Cycode. Estos resultados están vinculados a las políticas relevantes (por ejemplo, políticas de SCA para escaneos de repositorio) dentro de la plataforma Cycode.

Para que la URL directa de este informe de Cycode se imprima en la salida de tu CLI después de que se complete el escaneo, agrega el argumento --cycode-report a tu comando de escaneo.

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

Todos los resultados de escaneo de la CLI aparecerán en la sección de Registros de CLI de Cycode. Si incluiste la bandera --cycode-report en tu comando, se mostrará un enlace directo al informe específico en tu terminal después de los resultados del escaneo.

[!WARNING] Debes tener el rol owner o admin en Cycode para ver esta página.

cli-report

La página del informe se verá algo como lo siguiente:

Opción de vulnerabilidades de paquetes

[!NOTE] Esta opción solo está disponible para escaneos SCA.

Para escanear una vulnerabilidad de paquete específica de tu repositorio local, agrega el argumento --sca-scan package-vulnerabilities después de la opción -t sca o --scan-type sca.

En el ejemplo anterior, si quisieras ejecutar solo un escaneo SCA sobre vulnerabilidades de paquetes, podrías ejecutar lo siguiente:

cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

Opción de cumplimiento de licencias

[!NOTE] Esta opción solo está disponible para escaneos SCA.

Para escanear una rama específica de tu repositorio local, agrega el argumento --sca-scan license-compliance seguido del nombre de la rama que deseas escanear.

En el ejemplo anterior, si quisieras escanear solo una rama llamada dev, podrías ejecutar lo siguiente:

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

Opción de restauración de bloqueo

[!NOTE] Esta opción solo está disponible para escaneos SCA.

Al ejecutar un escaneo SCA, la CLI de Cycode intenta automáticamente restaurar (generar) un archivo de bloqueo de dependencias para cada archivo de manifiesto compatible que encuentre. Esto permite escanear dependencias transitivas, no solo las que se enumeran directamente en el manifiesto. Para omitir este paso y escanear solo dependencias directas, usa la bandera --no-restore.

Los siguientes ecosistemas admiten la restauración automática de archivos de bloqueo:

Ecosistema	Archivo de manifiesto	Archivo de bloqueo generado	Herramienta invocada (cuando falta el archivo de bloqueo)
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`	(solo lee el archivo de bloqueo 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`

Si ya existe un archivo de bloqueo junto al manifiesto, Cycode lo lee directamente sin ejecutar ningún comando de instalación.

Requisito previo de SBT: El plugin sbt-dependency-lock debe estar instalado. Agrega la siguiente línea a project/plugins.sbt:

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

Opción de detenerse en caso de error

De forma predeterminada, Cycode continúa escaneando incluso si no se puede leer un archivo (por ejemplo, debido a un error de permisos) o si no se puede generar un archivo de bloqueo de dependencias durante un escaneo SCA. El elemento fallido se omite con una advertencia y el escaneo continúa con los archivos restantes.

Usa --stop-on-error para cambiar este comportamiento: el escaneo se aborta inmediatamente en el primer fallo de este tipo y reporta el error.

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

Esto es útil en canalizaciones de CI donde un fallo silencioso produciría un resultado de escaneo incompleto. Cuando se activa --stop-on-error, puedes corregir el problema subyacente o, específicamente para fallos de restauración de SCA, agregar --no-restore para omitir la generación del archivo de bloqueo y escanear solo dependencias directas.

Cuando se usa --stop-on-error, la CLI distingue entre errores de escaneo y violaciones de políticas mediante códigos de salida:

Código de salida	Significado
`0`	Escaneo completado sin violaciones
`1`	Escaneo completado y se encontraron violaciones
`2`	Escaneo abortado debido a un error (solo cuando `--stop-on-error` está configurado)

Escaneo de repositorio

Un escaneo de repositorio examina un repositorio local completo en busca de secretos expuestos o configuraciones incorrectas inseguras. Este tipo de escaneo más holístico analiza todo: el estado actual de tu repositorio y su historial de confirmaciones. Buscará no solo secretos que estén actualmente expuestos dentro del repositorio, sino también secretos eliminados anteriormente.

Para ejecutar un escaneo completo del repositorio, ejecuta lo siguiente:

cycode scan repository {{path}}

Por ejemplo, si quisieras escanear un repositorio almacenado en ~/home/git/codebase, podrías ejecutar lo siguiente:

cycode scan repository ~/home/git/codebase

La siguiente opción está disponible para usar con este comando:

Opción	Descripción
`-b, --branch TEXT`	Rama a escanear, si no se establece, se escanea la rama predeterminada

Opción de rama

Para escanear una rama específica de tu repositorio local, agrega el argumento -b (alternativamente, --branch) seguido del nombre de la rama que deseas escanear.

Dado el ejemplo anterior, si quisieras escanear solo una rama llamada dev, podrías ejecutar lo siguiente:

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

Escaneo de ruta

Un escaneo de ruta examina un directorio local específico y todo su contenido, en lugar de centrarse únicamente en un repositorio GIT.

Para ejecutar un escaneo de directorio, ejecuta lo siguiente:

cycode scan path {{path}}

Por ejemplo, considera un escenario en el que deseas escanear el directorio ubicado en ~/home/git/codebase. Entonces podrías ejecutar lo siguiente:

cycode scan path ~/home/git/codebase

Escaneo de plan de Terraform

La CLI de Cycode admite el escaneo de planes de Terraform (compatible con Terraform 0.12 y versiones posteriores)

El archivo de plan de Terraform debe estar en formato JSON (con extensión .json)

Si solo tiene un archivo de configuración, puede generar un plan de la siguiente manera:

Inicialice un directorio de trabajo que contenga el archivo de configuración de Terraform:

terraform init
Cree el plan de ejecución de Terraform y guarde la salida binaria:

terraform plan -out={tfplan_output}
Convierta el archivo de salida binario en JSON legible:

terraform show -json {tfplan_output} > {tfplan}.json
Escanee su {tfplan}.json con la CLI de Cycode:

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

Escaneo de Historial de Commits

[!NOTE] El escaneo de historial de commits no está disponible para escaneos de IaC.

El comando de escaneo de historial de commits proporciona dos capacidades principales:

Escaneo de historial completo: Analiza todos los commits en el historial del repositorio
Escaneo de diferencias: Escanea solo los cambios entre commits específicos

El escaneo de secretos puede analizar todos los commits en el historial del repositorio porque los secretos introducidos y luego eliminados aún pueden filtrarse o exponerse. Para los escaneos SCA y SAST, el comando de historial de commits se centra en escanear las diferencias/cambios entre commits, lo que lo hace perfecto para revisiones de solicitudes de extracción y escaneo incremental.

Un escaneo de historial de commits examina el historial de commits de su repositorio Git y puede usarse tanto para un análisis histórico exhaustivo como para un escaneo de diferencias específico de cambios concretos.

Para ejecutar un escaneo de historial de commits, ejecute lo siguiente:

cycode scan commit-history {{path}}

Por ejemplo, considere un escenario en el que desea escanear el historial de commits de un repositorio almacenado en ~/home/git/codebase. Entonces podría ejecutar lo siguiente:

cycode scan commit-history ~/home/git/codebase

Las siguientes opciones están disponibles para usar con este comando:

Opción	Descripción
`-r, --commit-range TEXT`	Escanee un rango de commits en este repositorio git; por defecto, cycode escanea todo el historial de commits (ejemplo: HEAD~1)

Opción de Rango de Commits (Escaneo de Diferencias)

La opción de rango de commits permite el escaneo de diferencias: escanear solo los cambios entre commits específicos en lugar de todo el historial del repositorio. Esto es particularmente útil para:

Validación de solicitudes de extracción: Escanee solo los cambios introducidos en un PR
Escaneo incremental en CI/CD: Concéntrese en cambios recientes en lugar de todo el código base
Revisión de ramas de características: Compare cambios con la rama principal/maestra
Optimización del rendimiento: Escaneos más rápidos al limitar el alcance a cambios relevantes

Sintaxis del Rango de Commits

La opción --commit-range (-r) admite la sintaxis estándar de revisión de Git:

Sintaxis	Descripción	Ejemplo
`commit1..commit2`	Cambios del commit1 al commit2	`abc123..def456`
`commit1...commit2`	Cambios en commit2 que no están en commit1	`main...feature-branch`
`commit`	Cambios desde el commit hasta HEAD	`HEAD~1`
`branch1..branch2`	Cambios de la rama1 a la rama2	`main..feature-branch`

Ejemplos de Escaneo de Diferencias

Escanee cambios en el último commit:

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

Escanee cambios entre dos commits específicos:

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

Escanee cambios en su rama de características en comparación con main:

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

Escanee cambios entre main y una rama de características:

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

Escanee todos los cambios en los últimos 3 commits:

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

[!TIP] Para pipelines de CI/CD, puede usar variables de entorno como ${{ github.event.pull_request.base.sha }}..${{ github.sha }} (GitHub Actions) o $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA (GitLab CI) para escanear solo cambios de PR/MR.

Escaneo Pre-Commit

Un escaneo pre-commit identifica automáticamente cualquier problema antes de que confirme cambios en su repositorio. No es necesario ejecutar este escaneo manualmente; configure el hook de pre-commit como se detalla en la sección de Instalación de esta guía.

Después de instalar el hook de pre-commit, es posible que ocasionalmente desee omitir el escaneo durante un commit específico. Para hacer esto, agregue lo siguiente a su comando git para omitir el escaneo de un solo commit:

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

Escaneo Pre-Push

Un escaneo pre-push identifica automáticamente cualquier problema antes de que envíe cambios al repositorio remoto. Este hook se ejecuta en el lado del cliente y escanea solo los commits que están a punto de enviarse, lo que lo hace eficiente para detectar problemas antes de que lleguen al repositorio remoto.

[!NOTE] El hook de pre-push no está disponible para escaneos de IaC.

El hook de pre-push se integra con el framework de pre-commit y puede configurarse para ejecutarse antes de cualquier operación git push.

Instalación del Hook Pre-Push

Para configurar el hook de pre-push usando el framework de pre-commit:

Instale el framework de pre-commit (si aún no está instalado):
```
pip3 install pre-commit
```

Cree o actualice su archivo .pre-commit-config.yaml para incluir los 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últiples tipos de escaneo, use esta configuración:

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 el hook de pre-push:
```
pre-commit install --hook-type pre-push
```
Una instalación exitosa dará como resultado el mensaje: Pre-push installed at .git/hooks/pre-push.
Mantenga el hook de pre-push actualizado:
```
pre-commit autoupdate
```

Cómo Funciona el Escaneo Pre-Push

El hook de pre-push:

Recibe información sobre qué commits se están enviando
Calcula el rango de commits apropiado para escanear
Para ramas nuevas: escanea todos los commits desde la base de fusión con la rama predeterminada
Para ramas existentes: escanea solo los commits nuevos desde el último push
Ejecuta el mismo escaneo exhaustivo que otros modos de escaneo de Cycode

Detección Inteligente de la Rama Predeterminada

El hook de pre-push detecta inteligentemente la rama predeterminada para el cálculo de la base de fusión usando este orden de prioridad:

Variable de entorno: CYCODE_DEFAULT_BRANCH - permite anulación manual
Git Remote HEAD: Usa git symbolic-ref refs/remotes/origin/HEAD para detectar la rama predeterminada remota real
Información remota de Git: Recurre a git remote show origin si symbolic-ref falla
Respaldo codificado: Usa nombres comunes de rama predeterminada (origin/main, origin/master, main, master)

Configuración de una rama predeterminada personalizada:

export CYCODE_DEFAULT_BRANCH=origin/develop

Esta detección inteligente asegura que el hook de pre-push funcione correctamente sin importar si su repositorio usa main, master, develop o cualquier otro nombre de rama predeterminada.

Omitir Escaneos Pre-Push

Para omitir el escaneo pre-push para una operación de push específica, use:

SKIP=cycode-pre-push git push

O para omitir todos los hooks de pre-push:

git push --no-verify

[!TIP] El hook de pre-push se activa en el comando git push y escanea solo los commits que están a punto de enviarse, lo que lo hace más eficiente que escanear todo el repositorio.

Excluir Rutas de los Escaneos

Puede usar un archivo .cycodeignore para indicar a la CLI de Cycode qué archivos y directorios excluir de los escaneos. Funciona igual que un archivo .gitignore. Esto le ayuda a enfocar los escaneos en su código relevante y evitar que ciertas rutas generen violaciones localmente.

Cómo Funciona

Cree un archivo llamado .cycodeignore en su carpeta de trabajo.
Enumere los archivos y directorios que desea excluir, usando los mismos patrones que .gitignore.
Coloque este archivo en el directorio donde planea ejecutar el comando de escaneo de cycode.

[!WARNING]

Archivos inválidos: Si el archivo .cycodeignore contiene un error de sintaxis, el escaneo de la CLI fallará y devolverá un error.

Ignorar rutas vs. violaciones: Este archivo es para excluir rutas. Es diferente de la capacidad de la CLI para ignorar violaciones específicas (por ejemplo, usando la bandera --ignore-violation).

Escáneres Compatibles

SAST
IaC (próximamente)
SCA (próximamente)

Resultados del Escaneo

Cada escaneo se completará con un mensaje que indica si se encontraron problemas o no.

Si no se encuentran problemas, el escaneo termina con el siguiente mensaje de éxito:

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

Si se encuentra un problema, aparece una tarjeta de violación al finalizar. En este caso, debe revisar el archivo en cuestión para la línea específica resaltada por el mensaje de resultado. Implemente los cambios necesarios para resolver el problema y luego ejecute el escaneo nuevamente.

Mostrar/Ocultar Secretos

En los ejemplos a continuación, se encontró un secreto en el archivo secret_test, ubicado en la subcarpeta cli. La segunda parte del mensaje muestra la línea específica en la que aparece el secreto, que en este caso es un valor asignado a googleApiKey.

Observe cómo el ejemplo oculta el valor real del secreto, reemplazando la mayor parte del secreto con asteriscos. Los escaneos ocultan los secretos por defecto, pero opcionalmente puede desactivar esta función para ver el secreto completo (asumiendo que la máquina en la que ve el resultado del escaneo es lo suficientemente segura contra miradas indiscretas).

Para desactivar la ofuscación de secretos, agregue el argumento --show-secret a cualquier tipo de escaneo.

En el siguiente ejemplo, se ejecuta un Escaneo de Ruta contra la subcarpeta cli con la opción habilitada para mostrar cualquier secreto encontrado en su totalidad:

cycode scan --show-secret path ./cli

El resultado entonces no estaría ofuscado.

Fallo Suave

En operación normal, la CLI devolverá un código de salida de 1 cuando se encuentren problemas en los resultados del escaneo. Dependiendo de su configuración de CI/CD, esto generalmente resultará en un fallo general. Si no desea que esto suceda, puede usar la función de fallo suave.

Al agregar la opción --soft-fail a cualquier tipo de escaneo, el código de salida se forzará a 0 independientemente de si se encuentran resultados.

Ejemplos de Resultados de Escaneo

Ejemplo de Resultado de Secretos

╭─────────────────────────────────────────────────────────────── 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.                     │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ejemplo 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.                                                                                                          │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ejemplo 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.                                                                                                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Ejemplo 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.                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Guías de Remediación Personalizadas de la Empresa

Si su empresa ha establecido guías de remediación personalizadas en la política correspondiente a través del portal de Cycode, verá un campo para “Guías de la Empresa” que contiene las guías de remediación que agregó. Tenga en cuenta que si no ha agregado ninguna guía de la empresa, este campo no aparecerá en la herramienta CLI.

Ignorar Resultados de Escaneo

Se pueden agregar reglas de ignorar para ignorar valores de secretos específicos, valores SHA512 específicos, rutas específicas e IDs de reglas específicos de secretos e IaC de Cycode. Esto hará que el escaneo no alerte sobre estos valores. Las reglas de ignorar se escriben y guardan localmente en el archivo ./.cycode/config.yaml.

[!WARNING] Agregar valores para ignorar debe hacerse con consideración cuidadosa de los valores, rutas y políticas para asegurar que los escaneos detecten verdaderos positivos.

Las siguientes son las opciones disponibles para el comando cycode ignore:

Opción	Descripción
`--by-value TEXT`	Ignora un valor específico al escanear secretos. Consulta Ignorar un valor de secreto para más detalles.
`--by-sha TEXT`	Ignora una representación SHA512 específica de una cadena al escanear secretos. Consulta Ignorar un valor SHA de secreto para más detalles.
`--by-path TEXT`	Evita escanear una ruta específica. Debes especificar el tipo de escaneo. Consulta Ignorar una ruta para más detalles.
`--by-rule TEXT`	Ignora el escaneo de un ID de regla de secreto/ID de regla IaC/ID de regla SCA específico. Consulta Ignorar una regla de secreto o IaC para más detalles.
`--by-package TEXT`	Ignora el escaneo de una versión de paquete específica al ejecutar un escaneo SCA. Patrón esperado: `name@version`. Consulta Ignorar un paquete para más detalles.
`--by-cve TEXT`	Ignora el escaneo de un CVE específico al ejecutar un escaneo SCA. Patrón esperado: CVE-YYYY-NNN.
`-t, --scan-type [secret\|iac\|sca\|sast]`	Especifica el escaneo que deseas ejecutar (`secret`/`iac`/`sca`/`sast`). El valor predeterminado es `secret`.
`-g, --global`	Agrega una regla de ignorar y actualízala en el archivo de configuración global `.cycode`.

Ignorar un valor de secreto

Para ignorar un valor de secreto específico, deberás usar la bandera --by-value. Esto ignorará el valor de secreto dado de todos los escaneos futuros. Usa el siguiente comando para agregar un valor de secreto a ignorar:

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

En el ejemplo al inicio de esta sección, el comando para ignorar un valor de secreto específico es el siguiente:

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

En el ejemplo anterior, reemplaza el valor h3110w0r1d!@#$350 con tu valor de secreto no enmascarado. Consulta las opciones de escaneo de Cycode para obtener detalles sobre cómo ver los valores de secreto en los resultados del escaneo.

Ignorar un valor SHA de secreto

Para ignorar un valor SHA de secreto específico, deberás usar la bandera --by-sha. Esto ignorará el valor SHA de secreto dado de todos los escaneos futuros. Usa el siguiente comando para agregar un valor SHA de secreto a ignorar:

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

En el ejemplo al inicio de esta sección, el comando para ignorar un valor SHA de secreto específico es el siguiente:

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

En el ejemplo anterior, reemplaza el valor a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 con tu valor SHA de secreto.

Ignorar una ruta

Para ignorar una ruta específica en escaneos de secretos, IaC o SCA, deberás usar la bandera --by-path junto con la bandera -t, --scan-type (debes especificar el tipo de escaneo). Esto ignorará la ruta dada de todos los escaneos futuros para el tipo de escaneo indicado. Usa el siguiente comando para agregar una ruta a ignorar:

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

En el ejemplo al inicio de esta sección, el comando para ignorar una ruta específica para un secreto es el siguiente:

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

En el ejemplo anterior, reemplaza el valor ~/home/my-repo/config con tu valor de ruta.

En el ejemplo al inicio de esta sección, el comando para ignorar una ruta específica de los escaneos IaC es el siguiente:

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

En el ejemplo anterior, reemplaza el valor ~/home/my-repo/config con tu valor de ruta.

En el ejemplo al inicio de esta sección, el comando para ignorar una ruta específica de los escaneos SCA es el siguiente:

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

En el ejemplo anterior, reemplaza el valor ~/home/my-repo/config con tu valor de ruta.

Ignorar una regla de secreto, IaC, SCA o SAST

Para ignorar una regla específica de secreto, IaC, SCA o SAST, deberás usar la bandera --by-rule junto con la bandera -t, --scan-type (debes especificar el tipo de escaneo). Esto ignorará el valor de ID de regla dado de todos los escaneos futuros. Usa el siguiente comando para agregar un valor de ID de regla a ignorar:

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

En el ejemplo al inicio de esta sección, el comando para ignorar el ID de regla de secreto específico es el siguiente:

cycode ignore -t secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710

En el ejemplo anterior, reemplaza el valor ce3a4de0-9dfc-448b-a004-c538cf8b4710 con el ID de regla que deseas ignorar.

En el ejemplo al inicio de esta sección, el comando para ignorar el ID de regla IaC específico es el siguiente:

cycode ignore -t iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c

En el ejemplo anterior, reemplaza el valor bdaa88e2-5e7c-46ff-ac2a-29721418c59c con el ID de regla que deseas ignorar.

En el ejemplo al inicio de esta sección, el comando para ignorar el ID de regla SCA específico es el siguiente:

cycode ignore -t sca --by-rule dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b

En el ejemplo anterior, reemplaza el valor dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b con el ID de regla que deseas ignorar.

Ignorar un paquete

[!NOTE] Esta opción solo está disponible para los escaneos SCA.

Para ignorar un paquete específico en los escaneos SCA, deberás usar la bandera --by-package junto con la bandera -t, --scan-type (debes especificar el tipo de escaneo sca). Esto ignorará el paquete dado, usando el formato {{package_name}}@{{package_version}}, de todos los escaneos futuros. Usa el siguiente comando para agregar un paquete y versión a ignorar:

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

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

En el ejemplo a continuación, el comando para ignorar un paquete SCA específico es el siguiente:

cycode ignore --scan-type sca --by-package pyyaml@5.3.1

En el ejemplo anterior, reemplaza pyyaml con el nombre del paquete y 5.3.1 con la versión del paquete que deseas ignorar.

Ignorar mediante un archivo de configuración

Las reglas de ignorar aplicadas se almacenan en el archivo de configuración llamado config.yaml. Este archivo se puede compartir fácilmente entre desarrolladores o incluso enviarse a un repositorio Git remoto. Estos archivos siempre se encuentran en la carpeta .cycode. La carpeta comienza con un punto (.) y deberías habilitar la visualización de archivos ocultos para verla.

Ruta de los archivos de configuración

De forma predeterminada, todos los comandos cycode ignore guardan la regla de ignorar en el directorio actual desde el cual se ha ejecutado la CLI.

Ejemplo: ejecutar el comando de ignorar de la CLI desde /Users/name/projects/backend creará config.yaml en /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

La segunda opción es guardar las reglas de ignorar en los archivos de configuración globales. La ruta de la configuración global es ~/.cycode/config.yaml, donde ~ significa users home directory, for example, /Users/name` en macOS.

Guardar en el espacio global se puede realizar con la bandera -g del comando cycode ignore. Por ejemplo: cycode ignore -g --by-value test-value.

Directorio de trabajo adecuado

Es increíblemente importante colocar la carpeta .cycode y ejecutar la CLI desde el mismo lugar. Debes verificarlo dos veces al trabajar con diferentes entornos como CI/CD (GitHub Actions, Jenkins, etc.).

Puedes enviar la carpeta .cycode a la raíz de tu repositorio. En este escenario, debes ejecutar los escaneos de la CLI desde la raíz del repositorio. Si eso no se ajusta a tus requisitos, podrías copiar temporalmente la carpeta .cycode a donde quieras y realizar un escaneo de la CLI desde esa carpeta.

Estructura de las reglas de ignorar en la configuración

Es importante entender cómo la CLI almacena las reglas ignoradas para poder leer estos archivos de configuración o incluso modificarlos sin la CLI.

La estructura YAML abstracta:

exclusions:
  {scanTypeName}:
    {ignoringType}:
    - someIgnoringValue1
    - someIgnoringValue2

Valores posibles de scanTypeName: iac, sca, sast, secret.

Valores posibles de ignoringType: paths, values, rules, packages, shas, cves.

[!WARNING] ¡Los valores para "ignorar por valor" no se almacenan como texto plano! La CLI almacena hashes sha256 de los valores en su lugar. Debes poner hashes de la cadena al modificar el archivo de configuración manualmente.

Ejemplo 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 Reporte

Generación de informe SBOM

Una lista de materiales de software (SBOM) es un inventario de todos los componentes constituyentes y dependencias de software involucrados en el desarrollo y la entrega de una aplicación. Con este comando, puedes crear un informe SBOM para tu proyecto local o para el URI de tu repositorio.

Las siguientes opciones están disponibles para usar con este comando:

Opción	Descripción	Requerido	Predeterminado
`-f, --format [spdx-2.2\|spdx-2.3\|cyclonedx-1.4]`	Formato SBOM	Sí
`-o, --output-format [JSON]`	Especifica el formato del archivo de salida	No	json
`--output-file PATH`	Archivo de salida	No	nombre de archivo autogenerado guardado en el directorio actual
`--include-vulnerabilities`	Incluir vulnerabilidades	No	False
`--include-dev-dependencies`	Incluir dependencias de desarrollo	No	False

Los siguientes comandos están disponibles para usar con este comando:

Comando	Descripción
`path`	Genera un informe SBOM para la ruta proporcionada en el comando
`repository-url`	Genera un informe SBOM para el URI de repositorio proporcionado en el comando

Repositorio

Para crear un informe SBOM para un URI de repositorio:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>

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

Proyecto local

Para crear un informe SBOM para una ruta:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>

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

El subcomando path admite las siguientes opciones adicionales:

Opción	Descripción
`--no-restore`	Omite la restauración del archivo de bloqueo y escanea solo las dependencias directas. Consulta Opción de restauración de bloqueo para obtener detalles.
`--gradle-all-sub-projects`	Ejecuta el comando de restauración de Gradle para todos los subproyectos (úsalo desde la raíz de una compilación Gradle de múltiples proyectos).
`--maven-settings-file`	Solo para Maven, permite usar un archivo settings.xml personalizado al construir el árbol de dependencias.

Comando de Importación

Importación de SBOM

Una lista de materiales de software (SBOM) es un inventario de todos los componentes constituyentes y dependencias de software involucrados en el desarrollo y la entrega de una aplicación. Con este comando, puedes importar un archivo SBOM desde tu sistema de archivos a Cycode.

Las siguientes opciones están disponibles para usar con este comando:

Opción	Descripción	Requerido	Predeterminado
`-n, --name TEXT`	Nombre para mostrar del SBOM	Sí
`-v, --vendor TEXT`	Nombre de la entidad que proporcionó el SBOM	Sí
`-l, --label TEXT`	Adjuntar etiqueta al SBOM	No
`-o, --owner TEXT`	Dirección de correo electrónico del usuario de Cycode que sirve como punto de contacto para este SBOM	No
`-b, --business-impact [High \| Medium \| Low]`	Impacto empresarial	No	Medio

Por ejemplo:
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner example@cycode.com /path/to/local/project

Registros de escaneo

Todos los escaneos de CLI se registran en Cycode. Los registros se pueden encontrar en Configuración > Registros de CLI.

Ayuda de sintaxis

Puede agregar el argumento --help a cualquier comando en cualquier momento para ver un mensaje de ayuda que mostrará las opciones disponibles y su sintaxis.

Para ver la ayuda general, simplemente ingrese el comando:

cycode --help

Para ver las opciones de escaneo, ingrese:

cycode scan --help

Para ver las opciones disponibles para un tipo específico de escaneo, ingrese:

cycode scan {{option}} --help

Por ejemplo, para ver las opciones disponibles para un escaneo de ruta, ingresaría:

cycode scan path --help

Para ver las opciones disponibles para la función de escaneo de ignorar, use este comando:

cycode ignore --help

Para ver las opciones disponibles para un informe, use este comando:

cycode report --help

Para ver las opciones disponibles para un tipo específico de informe, ingrese:

cycode scan {{option}} --help