Cycode MCP Server

официальный

Повысьте безопасность вашего жизненного цикла разработки с помощью SAST, SCA, сканирования секретов и IaC с Cycode.

Документация

Руководство пользователя Cycode CLI

Cycode Command Line Interface (CLI) — это приложение, которое можно установить локально для сканирования репозиториев на наличие секретов, ошибок конфигурации инфраструктуры как кода, уязвимостей анализа состава программного обеспечения и проблем статического тестирования безопасности приложений.

Это руководство проведет вас через установку и использование.

Содержание

Предварительные требования
Установка
1. Установка Cycode CLI
2. Установка Pre-Commit Hook
Команды Cycode CLI
Команда MCP
Команда Platform
Команда Scan
Команда Report
1. Генерация отчета SBOM
Команда Import
Журналы сканирования
Справка по синтаксису

Предварительные требования

Приложение Cycode CLI требует Python версии 3.9 или новее. Команда MCP доступна только для Python 3.10 и выше. Если вы используете более раннюю версию Python, эта команда будет недоступна.
Используйте команду cycode auth для аутентификации в Cycode с помощью CLI
- В качестве альтернативы вы можете получить Cycode Client ID и Client Secret Key, следуя инструкциям на страницах Service Account Token и Personal Access Token, которые содержат подробности о получении этих значений.

Установка

Следующие шаги по установке применимы как к операционным системам Windows, так и к UNIX / Linux.

[!NOTE] Следующие шаги предполагают использование python3 и pip3 для команд, связанных с Python; однако некоторые системы могут вместо этого использовать команды python и pip, в зависимости от конфигурации вашего окружения Python.

Установка Cycode CLI

Чтобы установить приложение Cycode CLI на ваш локальный компьютер, выполните следующие шаги:

Откройте командную строку или приложение терминала.
Выполните одну из следующих команд:
- Для установки из PyPI:
```
pip3 install cycode
```
- Для установки из Homebrew:
```
brew install cycode
```
- Для установки из GitHub Releases перейдите и загрузите исполняемый файл для вашей операционной системы и архитектуры, затем выполните следующую команду:
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
Наконец, аутентифицируйте CLI. Существует три метода установки Cycode client ID и учетных данных (client secret или OIDC ID token):
- cycode auth (Рекомендуется)
- cycode configure
- Добавьте их в переменные окружения

Использование команды Auth

[!NOTE] Это рекомендуемый метод настройки вашего локального компьютера для аутентификации в Cycode CLI.

Введите следующую команду в окно терминала/командной строки:

cycode auth
Появится окно браузера с предложением войти в Cycode (как показано ниже):
Введите свои учетные данные для входа на этой странице и войдите.
В конечном итоге вы попадете на страницу ниже, где вам будет предложено выбрать бизнес-группу, для которой вы хотите авторизовать Cycode (если применимо):

[!NOTE] Это будет методом по умолчанию для аутентификации в Cycode CLI.
Нажмите кнопку Allow, чтобы авторизовать Cycode CLI для выбранной бизнес-группы.
После завершения вы увидите следующий экран, если выбор был успешным:
В окне терминала/командной строки вы увидите следующее при выходе из окна браузера:

Successfully logged into cycode

Использование команды Configure

[!NOTE] Если вы уже настроили свой Cycode Client ID и Client Secret через переменные окружения Linux или Windows, эти учетные данные будут иметь приоритет над этим методом.

Введите следующую команду в окно терминала/командной строки:
```
cycode configure
```
Введите значение вашего Cycode API URL (можно оставить пустым, чтобы использовать значение по умолчанию).

Cycode API URL [https://api.cycode.com]: https://api.onpremise.com
Введите значение вашего Cycode APP URL (можно оставить пустым, чтобы использовать значение по умолчанию).

Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com
Введите значение вашего Cycode Client ID.

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
Введите значение вашего Cycode Client Secret (пропустите, если планируете использовать OIDC ID token).

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Введите значение вашего Cycode OIDC ID Token (необязательно).

Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Если значения были введены успешно, вы увидите следующее сообщение:

Successfully configured CLI credentials!

и/или

Successfully configured Cycode URLs!

Если вы перейдете в папку .cycode в вашей пользовательской папке, вы обнаружите, что эти учетные данные были созданы и помещены в файл credentials.yaml в этой папке. URL-адреса были помещены в файл config.yaml в этой папке.

Добавление в переменные окружения

В Unix/Linux:

export CYCODE_CLIENT_ID={your Cycode ID}

export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

Если ваша организация использует аутентификацию OIDC, вы можете предоставить ID token вместо (или в дополнение):

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

В Windows

В Панели управления перейдите в меню «Система»:
Затем нажмите «Дополнительные параметры системы»:
В открывшемся окне «Свойства системы» нажмите кнопку «Переменные среды»:
Создайте переменные CYCODE_CLIENT_ID и CYCODE_CLIENT_SECRET со значениями, соответствующими вашему ID и Secret Key соответственно. Если вы аутентифицируетесь через OIDC, добавьте также CYCODE_ID_TOKEN со значением вашего OIDC ID token:
Добавьте cycode.exe в путь, чтобы завершить установку.

Установка Pre-Commit Hook

Pre-commit и pre-push хуки Cycode можно настроить в вашем локальном репозитории, чтобы приложение Cycode CLI автоматически выявляло любые проблемы с вашим кодом до того, как вы закоммитите или отправите его в вашу кодовую базу.

[!NOTE] Pre-commit и pre-push хуки недоступны для сканирования IaC.

Выполните следующие шаги для установки pre-commit hook:

Установка Pre-Commit Hook

Установите фреймворк pre-commit (должен быть установлен Python 3.9 или выше):
```
pip3 install pre-commit
```
Перейдите в корневой каталог локального репозитория Git, который вы хотите настроить.
Создайте новый YAML-файл с именем .pre-commit-config.yaml (включая начальный .) в корневом каталоге репозитория, содержащий следующее:
```
repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]
```
Измените созданный файл в соответствии с вашими потребностями. Используйте ID хука cycode для включения сканирования Secrets. Используйте ID хука cycode-sca для включения сканирования SCA. Используйте ID хука cycode-sast для включения сканирования SAST. Если вы хотите включить все типы сканирования, используйте эту конфигурацию:
```
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]
```
Установите хук Cycode:
```
pre-commit install
```
Успешная установка хука приведет к сообщению: Pre-commit installed at .git/hooks/pre-commit.
Поддерживайте pre-commit hook в актуальном состоянии:
```
pre-commit autoupdate
```
Это автоматически обновит rev в .pre-commit-config.yaml до последней доступной версии Cycode CLI.

[!NOTE] Триггер срабатывает при выполнении команды git commit. Хук срабатывает только для файлов, подготовленных для коммита.

Установка Pre-Push Hook

Чтобы установить pre-push hook в дополнение или вместо pre-commit hook:

Добавьте pre-push хуки в ваш файл .pre-commit-config.yaml:

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

Установите pre-push hook:

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

Для использования обоих хуков, pre-commit и pre-push:
```
pre-commit install
pre-commit install --hook-type pre-push
```

[!NOTE] Pre-push хуки срабатывают при выполнении команды git push и сканируют только коммиты, которые должны быть отправлены.

Команды Cycode CLI

Ниже приведены опции и команды, доступные в приложении Cycode CLI:

Опция	Описание
`-v`, `--verbose`	Показывать подробные журналы.
`--no-progress-meter`	Не показывать индикатор выполнения.
`--no-update-notifier`	Не проверять наличие обновлений CLI.
`-o`, `--output [rich\|text\|json\|table]`	Указать тип вывода. По умолчанию `rich`.
`--client-id TEXT`	Указать Cycode client ID для данного конкретного выполнения сканирования.
`--client-secret TEXT`	Указать Cycode client secret для данного конкретного выполнения сканирования.
`--id-token TEXT`	Указать Cycode OIDC ID token для данного конкретного выполнения сканирования.
`--install-completion`	Установить автодополнение для текущей оболочки.
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Показать автодополнение для указанной оболочки, чтобы скопировать его или настроить установку.
`-h`, `--help`	Показать опции для указанной команды.
Команда	Описание
-------------------------------------------	-------------------------------------------------------------------------------------------------------------------------------------------------------
auth	Аутентифицируйте вашу машину, чтобы связать CLI с вашей учетной записью Cycode.
configure	Начальная команда для настройки аутентификации вашего CLI-клиента.
ignore	Игнорировать определенное значение, путь или ID правила.
mcp	Запустить сервер Model Context Protocol (MCP) для интеграции ИИ с возможностями сканирования Cycode.
scan	Сканировать содержимое на наличие нарушений Secrets/IaC/SCA/SAST. Вам нужно будет указать тип сканирования: commit-history/path/repository/etc.
report	Создать отчет. Вам нужно будет указать тип отчета, например SBOM.
status	Показать статус CLI и выйти.

Команда MCP [ЭКСПЕРИМЕНТАЛЬНАЯ]

[!WARNING] Команда MCP доступна только для Python 3.10 и выше. Если вы используете более раннюю версию Python, эта команда будет недоступна.

Команда Model Context Protocol (MCP) позволяет запустить MCP-сервер, который предоставляет возможности сканирования Cycode системам и приложениям ИИ. Это позволяет моделям ИИ взаимодействовать с инструментами Cycode CLI через стандартизированный протокол.

[!TIP] Для наилучшего опыта установите Cycode CLI глобально в вашей системе, используя pip install cycode или brew install cycode, затем один раз пройдите аутентификацию с помощью cycode auth. После глобальной установки и аутентификации вам не потребуется настраивать переменные окружения CYCODE_CLIENT_ID и CYCODE_CLIENT_SECRET в ваших конфигурационных файлах MCP.

Запуск MCP-сервера

Чтобы запустить MCP-сервер, используйте следующую команду:

cycode mcp

По умолчанию сервер запускается с использованием транспорта stdio, который подходит для локальных интеграций и приложений ИИ, способных порождать подпроцессы.

Доступные параметры

Параметр	Описание
`-t, --transport`	Тип транспорта для MCP-сервера: `stdio`, `sse` или `streamable-http` (по умолчанию: `stdio`)
`-H, --host`	Адрес хоста для привязки сервера (используется только для транспорта, отличного от stdio) (по умолчанию: `127.0.0.1`)
`-p, --port`	Номер порта для привязки сервера (используется только для транспорта, отличного от stdio) (по умолчанию: `8000`)
`--help`	Показать справочное сообщение и доступные параметры

Инструменты MCP

MCP-сервер предоставляет следующие инструменты, которые могут использовать системы ИИ:

Имя инструмента	Описание
`cycode_secret_scan`	Сканирование на наличие жестко закодированных секретов
`cycode_sca_scan`	Сканирование для анализа состава ПО (SCA) — уязвимости и проблемы с лицензиями
`cycode_iac_scan`	Сканирование на наличие неправильных конфигураций «Инфраструктура как код» (IaC)
`cycode_sast_scan`	Сканирование для статического тестирования безопасности приложений (SAST) — качество кода и уязвимости
`cycode_status`	Получить версию Cycode CLI, статус аутентификации и информацию о конфигурации

Каждый инструмент сканирования принимает два взаимоисключающих режима ввода:

paths (предпочтительный) — один или несколько путей к файлам или каталогам, существующим на диске. Каталоги сканируются рекурсивно. Движок Cycode сам выполняет обнаружение и фильтрацию файлов, как это делает cycode scan -t <type> path ./src из CLI.
files (запасной) — словарь, сопоставляющий пути к файлам с их полным содержимым в виде строк. Используйте это только тогда, когда файлы недоступны на диске (например, изменения в памяти, еще не сохраненные).

[!TIP] По возможности используйте paths. Передача больших файлов (например, package-lock.json) в виде встроенного содержимого может превысить лимиты токенов и замедлить работу ИИ-клиента. С paths движок Cycode читает файлы напрямую с диска.

Все инструменты сканирования возвращают объект JSON, который включает поле "summary" с удобочитаемым количеством нарушений (например, "Cycode found 3 violations: 1 CRITICAL, 2 HIGH.") в дополнение к полному массиву "detections".

Примеры использования

Примеры основных команд

Запустить MCP-сервер с настройками по умолчанию (транспорт stdio):

cycode mcp

Запустить MCP-сервер с явным указанием транспорта stdio:

cycode mcp -t stdio

Запустить MCP-сервер с транспортом Server-Sent Events (SSE):

cycode mcp -t sse -p 8080

Запустить MCP-сервер с транспортом streamable HTTP на пользовательском хосте и порту:

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

Узнайте больше о типах транспорта MCP в Спецификации протокола MCP – Транспорты.

Примеры конфигурации

Использование MCP с Cursor/VS Code/Claude Desktop и др. (mcp.json)

[!NOTE] Для сред Cycode в EU обязательно установите соответствующие значения CYCODE_API_URL и CYCODE_APP_URL в переменных окружения (например, https://api.eu.cycode.com и https://app.eu.cycode.com).

Следуйте этому руководству, чтобы настроить MCP-сервер в вашем VS Code/GitHub Copilot. Имейте в виду, что в settings.json есть объект mcp, содержащий вложенный подобъект servers, а не отдельный объект mcpServers.

Для транспорта stdio (прямое выполнение):

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

Для транспорта stdio с установкой 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"
      }
    }
  }
}

Для транспорта stdio с установкой 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"
      }
    }
  }
}

Для транспорта SSE (Server-Sent Events):

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

Для транспорта SSE на пользовательском порту:

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

Для транспорта streamable HTTP:

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

Запуск MCP-сервера в фоновом режиме

Для транспорта SSE (сначала запустите сервер, затем настройте клиент):

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

Для транспорта streamable HTTP:

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

Расширенная конфигурация

Пользовательские сертификаты и тайм-ауты (среды с прокси)

Если ваша организация использует корпоративный прокси или пользовательский пакет CA для проверки HTTPS, вам нужно указать Cycode CLI (и базовому стеку TLS Python), где найти доверенный пакет сертификатов. Вы также можете увеличить тайм-аут вызова инструмента MCP, если сканирование прерывается.

Переменная окружения	Описание
`REQUESTS_CA_BUNDLE`	Путь к файлу пользовательского пакета CA (`.pem` или `.crt`). Используется библиотекой `requests` для всех HTTPS-вызовов, совершаемых Cycode CLI.
`SSL_CERT_FILE`	Путь к файлу пользовательского пакета CA. Используется низкоуровневым модулем Python `ssl`. Установите вместе с `REQUESTS_CA_BUNDLE` для полного охвата.
`MCP_TOOL_TIMEOUT`	Тайм-аут (в секундах), в течение которого MCP-клиенты, такие как Claude и GitHub Copilot, ожидают завершения вызова инструмента. Увеличьте, если длительные сканирования прерываются до завершения.

[!TIP] Установите и REQUESTS_CA_BUNDLE, и SSL_CERT_FILE на один и тот же путь к пакету CA. REQUESTS_CA_BUNDLE покрывает уровень HTTP; SSL_CERT_FILE покрывает низкоуровневый уровень TLS. Использование только одного может по-прежнему вызывать ошибки сертификата в некоторых средах.

Пример конфигурации mcp.json с пользовательскими сертификатами и увеличенным тайм-аутом:

{
  "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] Для работы MCP-серверу требуется корректная аутентификация Cycode CLI. Убедитесь, что вы прошли аутентификацию с помощью cycode auth или настроили свои учетные данные перед запуском MCP-сервера.

Предварительная авторизация инструментов для субагентов (Claude Code)

Когда Claude Code делегирует работу фоновым субагентам (например, для параллельного запуска сканирования), эти субагенты не могут отображать интерактивные запросы на разрешение. Если инструменты Cycode не были предварительно одобрены, сканирование будет молча завершаться ошибкой в контексте субагентов.

Чтобы предварительно авторизовать инструменты Cycode MCP для работы во всех контекстах, включая субагентов, добавьте их в список allowedTools в настройках 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"
  ]
}

После добавления Claude Code не будет запрашивать подтверждение при вызове этих инструментов, и они будут корректно работать внутри субагентов.

Устранение неполадок MCP

Если у вас возникли проблемы с MCP-сервером, вы можете включить журналирование отладки, чтобы получить более подробную информацию о происходящем. Есть два способа включить журналирование отладки:

Использование флага -v или --verbose:

cycode -v mcp

Использование переменной окружения CYCODE_CLI_VERBOSE:

CYCODE_CLI_VERBOSE=1 cycode mcp

Журналы отладки покажут подробную информацию о:

Запуске и конфигурации сервера
Попытках подключения и статусе
Выполнении инструментов и результатах
Любых возникающих ошибках или предупреждениях

Эта информация может быть полезна при:

Диагностике проблем с подключением
Понимании, почему определенные инструменты не работают
Выявлении проблем с аутентификацией
Отладке проблем, специфичных для транспорта

Конфигурация MCP

Команда Platform [БЕТА]

[!WARNING] Команда platform находится в бета-версии. Команды, аргументы и форматы вывода генерируются динамически из спецификации Cycode API и могут изменяться между выпусками без предупреждения. Пока не полагайтесь на них в производственной автоматизации.

Команда cycode platform предоставляет API чтения платформы Cycode в виде команд CLI. Она группирует конечные точки по ресурсам (например, projects, violations, workflows) и превращает параметры каждой конечной точки в типизированные аргументы CLI и флаги --option.

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

Спецификация OpenAPI извлекается из Cycode API при первом использовании и кэшируется в ~/.cycode/openapi-spec.json на 24 часа. Несвязанные команды (cycode scan, cycode status и т.д.) не инициируют извлечение.

[!NOTE] Вы должны быть аутентифицированы (cycode auth или переменные окружения CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET), чтобы cycode platform мог обнаруживать и выполнять команды. Другие команды Cycode CLI работают без аутентификации.

Обнаружение команд

Поскольку команды генерируются из спецификации, источником истины о доступных командах является --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

Примеры Platform

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

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

# Count violations across the tenant
cycode platform violations count

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

Весь вывод по умолчанию в формате JSON — передайте его через jq для специальной фильтрации:

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

Примечания и ограничения Platform

Только чтение на сегодня. В этой бета-версии доступны только конечные точки GET.
На основе спецификации. Добавление новой конечной точки в API автоматически делает ее доступной при следующем обновлении кэша.
Нет встроенной спецификации. Первый вызов cycode platform после установки (или после истечения 24-часового кэша) выполняет сетевую загрузку. При медленном соединении этот первый вызов может занять несколько секунд; последующие вызовы выполняются почти мгновенно до истечения срока действия кэша.
Переопределите TTL кэша с помощью CYCODE_SPEC_CACHE_TTL=<seconds>.

Команда Scan

Запуск сканирования

Приложение Cycode CLI предлагает несколько типов сканирования, чтобы вы могли выбрать вариант, наилучшим образом соответствующий вашему случаю. Ниже приведены доступные на данный момент опции и команды:

Параметр	Описание
`-t, --scan-type [secret\|iac\|sca\|sast]`	Укажите сканирование, которое хотите выполнить (`secret`/`iac`/`sca`/`sast`), по умолчанию — `secret`.
`--show-secret BOOLEAN`	Показывать секреты в открытом виде. Подробнее см. в разделе Показать/Скрыть секреты.
`--soft-fail BOOLEAN`	Выполнять сканирование без ошибок, всегда возвращать код статуса без ошибки. Подробнее см. в разделе Мягкая ошибка.
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	Показывать только нарушения указанного уровня или выше.
`--sca-scan`	Укажите SCA-сканирование, которое хотите выполнить (`package-vulnerabilities`/`license-compliance`). По умолчанию выполняются оба.
`--monitor`	Если указано, результаты сканирования будут записаны в Cycode.
`--cycode-report`	Отображать ссылку на отчёт о сканировании на платформе Cycode в выводе консоли.
`--no-restore`	Если указано, Cycode не будет выполнять команду восстановления. При этом будут сканироваться ТОЛЬКО прямые зависимости!
`--stop-on-error`	Прерывать сканирование при любой ошибке сбора файлов или восстановления зависимостей, вместо того чтобы пропускать проблемный файл и продолжать.
`--gradle-all-sub-projects`	Запускать команду восстановления gradle для всех подпроектов. Это следует запускать из
`--maven-settings-file`	Только для Maven, позволяет использовать пользовательский файл settings.xml при сканировании зависимостей
`--help`	Показать параметры для указанной команды.

Команда	Описание
commit-history	Сканировать историю коммитов или выполнить дифф-сканирование между конкретными коммитами
path	Сканировать файлы по пути, указанному в команде
pre-commit	Используйте эту команду для сканирования содержимого, которое ещё не было закоммичено
repository	Сканировать git-репозиторий, включая его историю

Параметры

Параметр серьёзности

Чтобы ограничить результаты сканирования определённым порогом серьёзности, к команде сканирования можно добавить аргумент --severity-threshold.

Например, следующая команда просканирует репозиторий на предмет нарушений политик с серьёзностью Medium или выше:

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

Параметр мониторинга

[!NOTE] Этот параметр доступен только для SCA-сканирований.

Чтобы отправить результаты сканирования, связанные с SCA-политиками, найденными при SCA-сканировании, в Cycode, добавьте аргумент --monitor к команде сканирования.

Например, следующая команда просканирует репозиторий на предмет нарушений SCA-политик и отправит их на платформу Cycode:

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

Параметр отчёта Cycode

При каждом сканировании с помощью Cycode CLI автоматически генерируется отчёт, и его результаты отправляются в Cycode. Эти результаты привязываются к соответствующим политикам (например, SCA-политикам для сканирования репозитория) на платформе Cycode.

Чтобы после завершения сканирования в выводе CLI отобразился прямой URL-адрес этого отчёта Cycode, добавьте аргумент --cycode-report к команде сканирования.

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

Все результаты сканирования из CLI появятся в разделе CLI Logs в Cycode. Если вы включили флаг --cycode-report в свою команду, прямая ссылка на конкретный отчёт будет отображена в вашем терминале после результатов сканирования.

[!WARNING] Для просмотра этой страницы у вас должна быть роль owner или admin в Cycode.

cli-report

Страница отчёта будет выглядеть примерно так:

Параметр уязвимостей пакетов

[!NOTE] Этот параметр доступен только для SCA-сканирований.

Чтобы просканировать конкретную уязвимость пакета в вашем локальном репозитории, добавьте аргумент --sca-scan package-vulnerabilities после параметра -t sca или --scan-type sca.

В предыдущем примере, если бы вы хотели выполнить только SCA-сканирование на предмет уязвимостей пакетов, вы могли бы выполнить следующее:

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

Параметр соответствия лицензий

[!NOTE] Этот параметр доступен только для SCA-сканирований.

Чтобы просканировать конкретную ветку вашего локального репозитория, добавьте аргумент --sca-scan license-compliance, за которым следует имя ветки, которую вы хотите просканировать.

В предыдущем примере, если бы вы хотели просканировать только ветку с именем dev, вы могли бы выполнить следующее:

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

Параметр восстановления блокировки

[!NOTE] Этот параметр доступен только для SCA-сканирований.

При запуске SCA-сканирования Cycode CLI автоматически пытается восстановить (сгенерировать) файл блокировки зависимостей для каждого найденного поддерживаемого файла манифеста. Это позволяет сканировать транзитивные зависимости, а не только те, которые перечислены непосредственно в манифесте. Чтобы пропустить этот шаг и сканировать только прямые зависимости, используйте флаг --no-restore.

Следующие экосистемы поддерживают автоматическое восстановление файлов блокировки:

Экосистема	Файл манифеста	Генерируемый файл блокировки	Вызываемый инструмент (при отсутствии файла блокировки)
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`	(только чтение существующего файла блокировки)
Go	`go.mod`	`go.mod.graph`	`go list -m -json all` + `go mod graph`
Maven	`pom.xml`	`bcde.mvndeps`	`mvn dependency:tree`
Gradle	`build.gradle` / `build.gradle.kts`	`gradle-dependencies-generated.txt`	`gradle dependencies -q --console plain`
SBT	`build.sbt`	`build.sbt.lock`	`sbt dependencyLockWrite`
NuGet	`*.csproj`	`packages.lock.json`	`dotnet restore --use-lock-file`
Ruby	`Gemfile`	`Gemfile.lock`	`bundle --quiet`
Poetry	`pyproject.toml`	`poetry.lock`	`poetry lock`
Pipenv	`Pipfile`	`Pipfile.lock`	`pipenv lock`
PHP Composer	`composer.json`	`composer.lock`	`composer update --no-cache --no-install --no-scripts --ignore-platform-reqs`

Если файл блокировки уже существует рядом с манифестом, Cycode читает его напрямую, не запуская никаких команд установки.

Предварительное требование для SBT: Должен быть установлен плагин sbt-dependency-lock. Добавьте следующую строку в project/plugins.sbt:

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

Параметр остановки при ошибке

По умолчанию Cycode продолжает сканирование, даже если файл не может быть прочитан (например, из-за ошибки прав доступа) или файл блокировки зависимостей не может быть сгенерирован во время SCA-сканирования. Проблемный элемент пропускается с предупреждением, и сканирование продолжается с оставшимися файлами.

Используйте --stop-on-error, чтобы изменить это поведение: сканирование немедленно прерывается при первой такой ошибке и сообщает об ошибке.

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

Это полезно в CI-пайплайнах, где скрытая ошибка может привести к неполным результатам сканирования. При срабатывании --stop-on-error вы можете либо исправить основную проблему, либо, специально для ошибок восстановления SCA, добавить --no-restore, чтобы пропустить генерацию файла блокировки и сканировать только прямые зависимости.

При использовании --stop-on-error CLI различает ошибки сканирования и нарушения политик с помощью кодов выхода:

Код выхода	Значение
`0`	Сканирование завершено, нарушений нет
`1`	Сканирование завершено, найдены нарушения
`2`	Сканирование прервано из-за ошибки (только если установлен `--stop-on-error`)

Сканирование репозитория

Сканирование репозитория проверяет весь локальный репозиторий на наличие раскрытых секретов или небезопасных конфигураций. Этот более целостный тип сканирования проверяет всё: текущее состояние вашего репозитория и его историю коммитов. Он будет искать не только секреты, которые в настоящее время раскрыты в репозитории, но и ранее удалённые секреты.

Чтобы выполнить полное сканирование репозитория, выполните следующее:

cycode scan repository {{path}}

Например, если вы хотите просканировать репозиторий, хранящийся в ~/home/git/codebase, вы можете выполнить следующее:

cycode scan repository ~/home/git/codebase

С этой командой можно использовать следующий параметр:

Параметр	Описание
`-b, --branch TEXT`	Ветка для сканирования, если не задано, сканируется ветка по умолчанию

Параметр ветки

Чтобы просканировать конкретную ветку вашего локального репозитория, добавьте аргумент -b (альтернативно, --branch), за которым следует имя ветки, которую вы хотите просканировать.

Учитывая предыдущий пример, если бы вы хотели просканировать только ветку с именем dev, вы могли бы выполнить следующее:

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

Сканирование пути

Сканирование пути проверяет конкретную локальную директорию и всё её содержимое, вместо того чтобы фокусироваться исключительно на GIT-репозитории.

Чтобы выполнить сканирование директории, выполните следующее:

cycode scan path {{path}}

Например, рассмотрим сценарий, в котором вы хотите просканировать директорию, расположенную по адресу ~/home/git/codebase. Тогда вы можете выполнить следующее:

cycode scan path ~/home/git/codebase

Сканирование плана Terraform

Cycode CLI поддерживает сканирование плана Terraform (поддерживается Terraform 0.12 и новее)

Файл плана Terraform должен быть в формате JSON (иметь расширение .json)

Если у вас есть только файл конфигурации, вы можете сгенерировать план, выполнив следующие действия:

Инициализируйте рабочую директорию, содержащую файл конфигурации Terraform:

terraform init
Создайте план выполнения Terraform и сохраните бинарный вывод:

terraform plan -out={tfplan_output}
Преобразуйте бинарный файл вывода в читаемый JSON:

terraform show -json {tfplan_output} > {tfplan}.json
Просканируйте ваш {tfplan}.json с помощью Cycode CLI:

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

Сканирование истории коммитов

[!NOTE] Сканирование истории коммитов недоступно для IaC-сканирований.

Команда сканирования истории коммитов предоставляет две основные возможности:

Полное сканирование истории: Анализ всех коммитов в истории репозитория
Дифф-сканирование: Сканирование только изменений между конкретными коммитами

Сканирование секретов может анализировать все коммиты в истории репозитория, поскольку секреты, внедрённые и позже удалённые, всё равно могут быть раскрыты или скомпрометированы. Для SCA и SAST сканирований команда истории коммитов фокусируется на сканировании различий/изменений между коммитами, что делает её идеальной для проверки запросов на включение и инкрементального сканирования.

Сканирование истории коммитов проверяет историю коммитов вашего Git-репозитория и может использоваться как для всестороннего исторического анализа, так и для целевого дифф-сканирования конкретных изменений.

Чтобы выполнить сканирование истории коммитов, выполните следующее:

cycode scan commit-history {{path}}

Например, рассмотрим сценарий, в котором вы хотите просканировать историю коммитов для репозитория, хранящегося в ~/home/git/codebase. Тогда вы можете выполнить следующее:

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

С этой командой можно использовать следующие параметры:

Параметр	Описание
`-r, --commit-range TEXT`	Сканировать диапазон коммитов в этом git-репозитории; по умолчанию cycode сканирует всю историю коммитов (пример: HEAD~1)

Параметр диапазона коммитов (дифференциальное сканирование)

Параметр диапазона коммитов включает дифференциальное сканирование – сканирование только изменений между конкретными коммитами, а не всей истории репозитория. Это особенно полезно для:

Проверки pull request'ов: Сканирование только изменений, внесённых в PR
Инкрементального сканирования в CI/CD: Фокус на недавних изменениях, а не на всей кодовой базе
Ревью feature-веток: Сравнение изменений с веткой main/master
Оптимизации производительности: Более быстрое сканирование за счёт ограничения области проверки релевантными изменениями

Синтаксис диапазона коммитов

Параметр --commit-range (-r) поддерживает стандартный синтаксис Git-ревизий:

Синтаксис	Описание	Пример
`commit1..commit2`	Изменения от коммита1 до коммита2	`abc123..def456`
`commit1...commit2`	Изменения в коммите2, отсутствующие в коммите1	`main...feature-branch`
`commit`	Изменения от коммита до HEAD	`HEAD~1`
`branch1..branch2`	Изменения от ветки1 до ветки2	`main..feature-branch`

Примеры дифференциального сканирования

Сканирование изменений в последнем коммите:

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

Сканирование изменений между двумя конкретными коммитами:

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

Сканирование изменений в вашей feature-ветке по сравнению с main:

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

Сканирование изменений между main и feature-веткой:

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

Сканирование всех изменений в последних 3 коммитах:

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

[!TIP] Для CI/CD пайплайнов вы можете использовать переменные окружения, такие как ${{ github.event.pull_request.base.sha }}..${{ github.sha }} (GitHub Actions) или $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA (GitLab CI), чтобы сканировать только изменения из PR/MR.

Сканирование перед коммитом (Pre-Commit Scan)

Сканирование перед коммитом автоматически выявляет любые проблемы до того, как вы зафиксируете изменения в репозитории. Нет необходимости запускать это сканирование вручную; настройте pre-commit хук, как описано в разделе «Установка» этого руководства.

После установки pre-commit хука вы можете иногда захотеть пропустить сканирование для конкретного коммита. Для этого добавьте следующее к вашей команде git, чтобы пропустить сканирование для одного коммита:

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

Сканирование перед отправкой (Pre-Push Scan)

Сканирование перед отправкой автоматически выявляет любые проблемы до того, как вы отправите изменения в удалённый репозиторий. Этот хук выполняется на стороне клиента и сканирует только те коммиты, которые готовятся к отправке, что делает его эффективным для обнаружения проблем до того, как они попадут в удалённый репозиторий.

[!NOTE] Pre-push хук недоступен для IaC-сканирования.

Pre-push хук интегрируется с фреймворком pre-commit и может быть настроен для запуска перед любой операцией git push.

Установка Pre-Push хука

Чтобы настроить pre-push хук с использованием фреймворка pre-commit:

Установите фреймворк pre-commit (если он ещё не установлен):
```
pip3 install pre-commit
```

Создайте или обновите ваш файл .pre-commit-config.yaml, чтобы включить pre-push хуки:

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

Для нескольких типов сканирования используйте эту конфигурацию:

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]

Установите pre-push хук:
```
pre-commit install --hook-type pre-push
```
При успешной установке появится сообщение: Pre-push installed at .git/hooks/pre-push.
Поддерживайте pre-push хук в актуальном состоянии:
```
pre-commit autoupdate
```

Как работает Pre-Push сканирование

Pre-push хук:

Получает информацию о том, какие коммиты отправляются
Вычисляет подходящий диапазон коммитов для сканирования
Для новых веток: сканирует все коммиты от точки слияния с веткой по умолчанию
Для существующих веток: сканирует только новые коммиты с момента последней отправки
Выполняет такое же комплексное сканирование, как и другие режимы Cycode

Умное определение ветки по умолчанию

Pre-push хук интеллектуально определяет ветку по умолчанию для вычисления точки слияния, используя следующий порядок приоритетов:

Переменная окружения: CYCODE_DEFAULT_BRANCH - позволяет переопределить вручную
Git Remote HEAD: Использует git symbolic-ref refs/remotes/origin/HEAD для определения фактической удалённой ветки по умолчанию
Git Remote Info: Откатывается к git remote show origin, если symbolic-ref не сработал
Жёстко заданные резервные варианты: Использует распространённые имена веток по умолчанию (origin/main, origin/master, main, master)

Установка пользовательской ветки по умолчанию:

export CYCODE_DEFAULT_BRANCH=origin/develop

Это умное определение гарантирует, что pre-push хук работает корректно, независимо от того, использует ли ваш репозиторий main, master, develop или любое другое имя ветки по умолчанию.

Пропуск Pre-Push сканирования

Чтобы пропустить pre-push сканирование для конкретной операции отправки, используйте:

SKIP=cycode-pre-push git push

Или чтобы пропустить все pre-push хуки:

git push --no-verify

[!TIP] Pre-push хук срабатывает при выполнении команды git push и сканирует только те коммиты, которые готовятся к отправке, что делает его более эффективным, чем сканирование всего репозитория.

Исключение путей из сканирования

Вы можете использовать файл .cycodeignore, чтобы указать CLI Cycode, какие файлы и директории следует исключить из сканирования. Он работает точно так же, как файл .gitignore. Это помогает сфокусировать сканирование на релевантном коде и предотвратить срабатывание нарушений на определённых путях локально.

Как это работает

Создайте файл с именем .cycodeignore в вашей рабочей директории.
Перечислите файлы и директории, которые вы хотите исключить, используя те же шаблоны, что и в .gitignore.
Поместите этот файл в директорию, где вы планируете запускать команду cycode scan.

[!WARNING]

Некорректные файлы: Если файл .cycodeignore содержит синтаксическую ошибку, сканирование CLI завершится сбоем и вернёт ошибку.

Игнорирование путей и нарушений: Этот файл предназначен для исключения путей. Он отличается от возможности CLI игнорировать конкретные нарушения (например, с помощью флага --ignore-violation).

Поддерживаемые сканеры

SAST
IaC (скоро)
SCA (скоро)

Результаты сканирования

Каждое сканирование завершается сообщением о том, были ли найдены какие-либо проблемы.

Если проблемы не найдены, сканирование заканчивается следующим сообщением об успехе:

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

Если проблема найдена, вместо этого по завершении появляется карточка нарушения. В этом случае вам следует просмотреть указанный файл на конкретной строке, выделенной в сообщении о результате. Внесите все необходимые изменения для устранения проблемы, затем выполните сканирование снова.

Показать/Скрыть секреты

В примерах ниже был найден секрет в файле secret_test, расположенном в подпапке cli. Вторая часть сообщения показывает конкретную строку, в которой встречается секрет, в данном случае это значение, присвоенное googleApiKey.

Обратите внимание, как в примере скрывается фактическое значение секрета, большая часть которого заменяется звёздочками. По умолчанию сканирование скрывает секреты, но вы можете дополнительно отключить эту функцию, чтобы увидеть полный секрет (при условии, что машина, на которой вы просматриваете результат сканирования, достаточно защищена от посторонних глаз).

Чтобы отключить сокрытие секретов, добавьте аргумент --show-secret к любому типу сканирования.

В следующем примере выполняется сканирование пути для поддиректории cli с включённой опцией отображения любых найденных секретов полностью:

cycode scan --show-secret path ./cli

В результате значение не будет скрыто.

Мягкий сбой (Soft Fail)

При обычной работе CLI возвращает код выхода 1, если в результатах сканирования обнаружены проблемы. В зависимости от вашей настройки CI/CD это обычно приводит к общей неудаче. Если вы не хотите, чтобы это происходило, вы можете использовать функцию мягкого сбоя.

Добавив опцию --soft-fail к любому типу сканирования, код выхода будет принудительно установлен в 0 независимо от того, найдены ли какие-либо результаты.

Примеры результатов сканирования

Пример результата поиска секретов

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

Пример результата 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.                                                                                                          │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Пример результата 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.                                                                                                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Пример результата 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.                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Корпоративные рекомендации по исправлению

Если ваша компания установила пользовательские рекомендации по исправлению в соответствующей политике через портал Cycode, вы увидите поле «Company Guidelines», содержащее добавленные вами рекомендации. Обратите внимание: если вы не добавляли никаких корпоративных рекомендаций, это поле не появится в инструменте CLI.

Игнорирование результатов сканирования

Можно добавить правила игнорирования, чтобы пропускать определённые значения секретов, определённые значения SHA512, определённые пути, а также определённые идентификаторы правил Cycode для секретов и IaC. Это приведёт к тому, что сканирование не будет предупреждать об этих значениях. Правила игнорирования записываются и сохраняются локально в файле ./.cycode/config.yaml.

[!WARNING] Добавление значений для игнорирования должно выполняться с тщательным учётом самих значений, путей и политик, чтобы гарантировать, что сканирование будет выявлять истинные срабатывания.

Ниже приведены параметры, доступные для команды cycode ignore:

Параметр	Описание
`--by-value TEXT`	Игнорировать определённое значение при сканировании секретов. Подробнее см. в разделе Игнорирование значения секрета.
`--by-sha TEXT`	Игнорировать определённое SHA512-представление строки при сканировании секретов. Подробнее см. в разделе Игнорирование SHA-значения секрета.
`--by-path TEXT`	Избегать сканирования определённого пути. Необходимо указать тип сканирования. Подробнее см. в разделе Игнорирование пути.
`--by-rule TEXT`	Игнорировать сканирование по определённому ID правила секрета/IaC/SCA. Подробнее см. в разделе Игнорирование правила секрета или IaC.
`--by-package TEXT`	Игнорировать сканирование определённой версии пакета при запуске SCA-сканирования. Ожидаемый шаблон - `name@version`. Подробнее см. в разделе Игнорирование пакета.
`--by-cve TEXT`	Игнорировать сканирование определённого CVE при запуске SCA-сканирования. Ожидаемый шаблон: CVE-YYYY-NNN.
`-t, --scan-type [secret\|iac\|sca\|sast]`	Указать тип сканирования, которое вы хотите выполнить (`secret`/`iac`/`sca`/`sast`). Значение по умолчанию — `secret`.
`-g, --global`	Добавить правило игнорирования и обновить его в глобальном конфигурационном файле `.cycode`.

Игнорирование значения секрета

Чтобы игнорировать определённое значение секрета, вам нужно использовать флаг --by-value. Это приведёт к игнорированию данного значения секрета при всех последующих сканированиях. Используйте следующую команду, чтобы добавить значение секрета в список игнорируемых:

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

В примере в начале этого раздела команда для игнорирования определённого значения секрета выглядит следующим образом:

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

В приведённом выше примере замените значение h3110w0r1d!@#$350 на ваше немаскированное значение секрета. Подробнее о том, как увидеть значения секретов в результатах сканирования, см. в параметрах сканирования Cycode.

Игнорирование SHA-значения секрета

Чтобы игнорировать определённое SHA-значение секрета, вам нужно использовать флаг --by-sha. Это приведёт к игнорированию данного SHA-значения секрета при всех последующих сканированиях. Используйте следующую команду, чтобы добавить SHA-значение секрета в список игнорируемых:

cycode ignore --by-sha {{secret-sha-value}} В примере в начале этого раздела команда для игнорирования конкретного значения SHA секрета выглядит следующим образом:

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

В приведённом выше примере замените значение a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 на ваше значение SHA секрета.

Игнорирование пути

Чтобы игнорировать конкретный путь для сканирования секретов, IaC или SCA, необходимо использовать флаг --by-path совместно с флагом -t, --scan-type (необходимо указать тип сканирования). Это приведёт к игнорированию указанного пути при всех последующих сканированиях данного типа. Используйте следующую команду для добавления игнорируемого пути:

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

В примере в начале этого раздела команда для игнорирования конкретного пути для секрета выглядит следующим образом:

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

В приведённом выше примере замените значение ~/home/my-repo/config на значение вашего пути.

В примере в начале этого раздела команда для игнорирования конкретного пути при сканировании IaC выглядит следующим образом:

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

В приведённом выше примере замените значение ~/home/my-repo/config на значение вашего пути.

В примере в начале этого раздела команда для игнорирования конкретного пути при сканировании SCA выглядит следующим образом:

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

В приведённом выше примере замените значение ~/home/my-repo/config на значение вашего пути.

Игнорирование правила Secret, IaC, SCA или SAST

Чтобы игнорировать конкретное правило Secret, IaC, SCA или SAST, необходимо использовать флаг --by-rule совместно с флагом -t, --scan-type (необходимо указать тип сканирования). Это приведёт к игнорированию указанного значения ID правила при всех последующих сканированиях. Используйте следующую команду для добавления игнорируемого значения ID правила:

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

В примере в начале этого раздела команда для игнорирования конкретного ID правила секрета выглядит следующим образом:

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

В приведённом выше примере замените значение ce3a4de0-9dfc-448b-a004-c538cf8b4710 на ID правила, которое вы хотите игнорировать.

В примере в начале этого раздела команда для игнорирования конкретного ID правила IaC выглядит следующим образом:

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

В приведённом выше примере замените значение bdaa88e2-5e7c-46ff-ac2a-29721418c59c на ID правила, которое вы хотите игнорировать.

В примере в начале этого раздела команда для игнорирования конкретного ID правила SCA выглядит следующим образом:

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

В приведённом выше примере замените значение dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b на ID правила, которое вы хотите игнорировать.

Игнорирование пакета

[!NOTE] Эта опция доступна только для сканирования SCA.

Чтобы игнорировать конкретный пакет при сканировании SCA, необходимо использовать флаг --by-package совместно с флагом -t, --scan-type (необходимо указать тип сканирования sca). Это приведёт к игнорированию указанного пакета в формате {{package_name}}@{{package_version}} при всех последующих сканированиях. Используйте следующую команду для добавления игнорируемого пакета и версии:

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

ИЛИ

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

В примере ниже команда для игнорирования конкретного пакета SCA выглядит следующим образом:

cycode ignore --scan-type sca --by-package [email protected]

В приведённом выше примере замените pyyaml на имя пакета, а 5.3.1 на версию пакета, которую вы хотите игнорировать.

Игнорирование через файл конфигурации

Применённые правила игнорирования хранятся в файле конфигурации с именем config.yaml. Этим файлом можно легко делиться между разработчиками или даже фиксировать его в удалённом Git-репозитории. Эти файлы всегда находятся в папке .cycode. Папка начинается с точки (.), и для её просмотра необходимо включить отображение скрытых файлов.

Путь к файлам конфигурации

По умолчанию все команды cycode ignore сохраняют правило игнорирования в текущую директорию, из которой был запущен CLI.

Пример: запуск команды игнорирования CLI из /Users/name/projects/backend создаст config.yaml в /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

Второй вариант — сохранять правила игнорирования в глобальные файлы конфигурации. Путь к глобальной конфигурации: ~/.cycode/config.yaml, где ~ означает users home directory, for example, /Users/name` на macOS.

Сохранение в глобальное пространство может быть выполнено с помощью флага -g команды cycode ignore. Например: cycode ignore -g --by-value test-value.

Правильная рабочая директория

Крайне важно размещать папку .cycode и запускать CLI из одного и того же места. Следует перепроверять это при работе с различными средами, такими как CI/CD (GitHub Actions, Jenkins и т. д.).

Вы можете зафиксировать папку .cycode в корне вашего репозитория. В этом случае вы должны запускать сканирование CLI из корня репозитория. Если это не соответствует вашим требованиям, вы можете временно скопировать папку .cycode в нужное место и выполнить сканирование CLI из этой папки.

Структура правил игнорирования в конфигурации

Важно понимать, как CLI хранит игнорируемые правила, чтобы иметь возможность читать эти файлы конфигурации или даже изменять их без использования CLI.

Абстрактная структура YAML:

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

Возможные значения scanTypeName: iac, sca, sast, secret.

Возможные значения ignoringType: paths, values, rules, packages, shas, cves.

[!WARNING] Значения для «игнорирования по значению» не хранятся в виде простого текста! Вместо этого CLI хранит хеши sha256 этих значений. При ручном изменении файла конфигурации следует вставлять хеши строк.

Пример реального config.yaml:

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

Команда Report

Генерация отчёта SBOM

Программная спецификация (SBOM) — это перечень всех составных компонентов и программных зависимостей, задействованных в разработке и поставке приложения. С помощью этой команды вы можете создать отчёт SBOM для вашего локального проекта или для URI вашего репозитория.

С этой командой можно использовать следующие параметры:

Параметр	Описание	Обязательный	По умолчанию
`-f, --format [spdx-2.2\|spdx-2.3\|cyclonedx-1.4]`	Формат SBOM	Да
`-o, --output-format [JSON]`	Указать формат выходного файла	Нет	json
`--output-file PATH`	Выходной файл	Нет	автосгенерированное имя файла, сохранённое в текущей директории
`--include-vulnerabilities`	Включить уязвимости	Нет	False
`--include-dev-dependencies`	Включить зависимости разработки	Нет	False

С этой командой можно использовать следующие подкоманды:

Команда	Описание
`path`	Сгенерировать отчёт SBOM для указанного в команде пути
`repository-url`	Сгенерировать отчёт SBOM для указанного в команде URI репозитория

Репозиторий

Создание отчёта SBOM для URI репозитория:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>

Например:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git

Локальный проект

Создание отчёта SBOM для пути:
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>

Например:
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project

Подкоманда path поддерживает следующие дополнительные параметры:

Параметр	Описание
`--no-restore`	Пропустить восстановление lock-файла и сканировать только прямые зависимости. Подробнее см. Опция восстановления lock-файла.
`--gradle-all-sub-projects`	Запустить команду восстановления Gradle для всех подпроектов (использовать из корня многопроектной сборки Gradle).
`--maven-settings-file`	Только для Maven, позволяет использовать пользовательский файл settings.xml при построении дерева зависимостей.

Команда Import

Импорт SBOM

Программная спецификация (SBOM) — это перечень всех составных компонентов и программных зависимостей, задействованных в разработке и поставке приложения. С помощью этой команды вы можете импортировать файл SBOM из вашей файловой системы в Cycode.

С этой командой можно использовать следующие параметры:

Параметр	Описание	Обязательный	По умолчанию
`-n, --name TEXT`	Отображаемое имя SBOM	Да
`-v, --vendor TEXT`	Имя организации, предоставившей SBOM	Да
`-l, --label TEXT`	Прикрепить метку к SBOM	Нет
`-o, --owner TEXT`	Адрес электронной почты пользователя Cycode, являющегося контактным лицом по данному SBOM	Нет
`-b, --business-impact [High \| Medium \| Low]`	Влияние на бизнес	Нет	Medium

Например:
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner [email protected] /path/to/local/project

Журналы сканирования

Все сканирования CLI регистрируются в Cycode. Журналы можно найти в разделе Settings > CLI Logs.

Справка по синтаксису

Вы можете добавить аргумент --help к любой команде в любое время, чтобы увидеть справочное сообщение, которое отобразит доступные параметры и их синтаксис.

Чтобы увидеть общую справку, просто введите команду:

cycode --help

Чтобы увидеть параметры сканирования, введите:

cycode scan --help

Чтобы увидеть параметры, доступные для конкретного типа сканирования, введите:

cycode scan {{option}} --help

Например, чтобы увидеть параметры, доступные для сканирования пути, введите:

cycode scan path --help

Чтобы увидеть параметры, доступные для функции игнорирования сканирования, используйте эту команду:

cycode ignore --help

Чтобы увидеть параметры, доступные для отчёта, используйте эту команду:

cycode report --help

Чтобы увидеть параметры, доступные для конкретного типа отчёта, введите:

cycode scan {{option}} --help