Cycode

официальный

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

Что можно делать с Cycode MCP?

Поиск секретов — Попросите ассистента проверить файлы или каталоги на наличие жестко заданных секретов с помощью cycode_secret_scan.
Поиск проблем SCA — Запросите анализ состава программного обеспечения на наличие уязвимостей и проблем с лицензиями с помощью cycode_sca_scan.
Поиск ошибок конфигурации IaC — Попросите ассистента проверить инфраструктуру как код на наличие ошибок конфигурации с помощью cycode_iac_scan.
Поиск проблем SAST — Запустите статический анализ безопасности приложений для выявления проблем с качеством кода и уязвимостей с помощью cycode_sast_scan.
Проверка состояния CLI — Запросите версию Cycode CLI, статус аутентификации и сведения о конфигурации с помощью cycode_status.

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

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

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

В этом руководстве описаны установка и использование приложения.

Содержание

Предварительные требования
Установка
1. Установка Cycode CLI
2. Установка pre-commit hook
Команды Cycode CLI
Сертификаты и прокси
Команда MCP
Команда Platform
Защитные механизмы ИИ
1. Данные, собираемые защитными механизмами ИИ
Команда Scan
Команда Report
1. Создание отчета SBOM
Команда Import
Журналы сканирования
Справка по синтаксису

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

Для приложения Cycode CLI требуется Python версии 3.10 или более поздней.
Используйте команду cycode auth, чтобы пройти аутентификацию в Cycode через CLI.
- Также можно получить Cycode Client ID и Client Secret Key, выполнив инструкции на страницах Токен учетной записи службы и Персональный токен доступа, где описано, как получить эти значения.

Установка

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

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

Установка 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 и учетные данные (секрет клиента или токен идентификатора OIDC):
- 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).

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

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, вместо этого (или дополнительно) можно указать токен идентификатора:

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

В Windows

На панели управления перейдите в меню System:
Затем нажмите Advanced system settings:
В открывшемся окне System Properties нажмите кнопку Environment Variables:
Создайте переменные CYCODE_CLIENT_ID и CYCODE_CLIENT_SECRET со значениями, соответствующими вашему идентификатору и секретному ключу. Если вы проходите аутентификацию через OIDC, также добавьте CYCODE_ID_TOKEN со значением токена идентификатора OIDC:
Добавьте cycode.exe в путь, чтобы завершить установку.

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

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

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

Выполните следующие действия, чтобы установить pre-commit hook:

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

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

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

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

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

Добавьте pre-push hooks в файл .pre-commit-config.yaml:

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

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

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

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

[!NOTE] Pre-push hooks срабатывают при выполнении команды 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`	Указать токен идентификатора OIDC Cycode для этого запуска сканирования.
`--install-completion`	Установить автодополнение для текущей оболочки..
`--show-completion [bash\|zsh\|fish\|powershell\|pwsh]`	Показать настройки автодополнения для указанной оболочки, чтобы скопировать их или настроить установку.
`-h`, `--help`	Показать параметры указанной команды.
Команда	Описание
-------------------------------------------	----------------------------------------------------------------------------------------------------------------------------------------------
auth	Аутентифицируйте компьютер, чтобы связать CLI с вашей учетной записью Cycode.
configure	Начальная команда для настройки аутентификации клиента CLI.
ignore	Игнорировать определенное значение, путь или идентификатор правила.
mcp	Запустить сервер Model Context Protocol (MCP), чтобы обеспечить интеграцию ИИ с возможностями сканирования Cycode.
scan	Сканировать содержимое на нарушения Secrets/IaC/SCA/SAST. Вам нужно указать тип сканирования: commit-history/path/repository и т. д.
report	Создать отчет. Нужно указать тип отчета, например SBOM.
status	Показать состояние CLI и завершить работу.

Сертификаты и прокси

По умолчанию Cycode CLI проверяет HTTPS-соединения с помощью пакета сертификатов CA, поставляемого вместе с CLI.

Если в вашей организации используется прокси, проверяющий HTTPS-трафик, или локальная установка со собственным CA, доступны два варианта.

Вариант 1 — использовать сертификаты, уже установленные на компьютере. Если ваш CA находится в хранилище сертификатов компьютера (как обычно бывает на управляемом устройстве), включите этот режим:

export CYCODE_CLI_ENABLE_TRUSTSTORE=1

После этого CLI будет выполнять проверку с помощью хранилища сертификатов Windows, Keychain в macOS или системного каталога CA в Linux; настраивать пути к сертификатам не потребуется.

[!IMPORTANT] Этот режим намеренно отключен по умолчанию. Доверие к хранилищу компьютера означает доверие ко всем корневым сертификатам в нем, включая сертификаты, установленные администратором или вредоносным ПО. Включайте этот режим, только если уверены, что хранилищу сертификатов компьютера можно доверять.

Вариант 2 — указать CLI файл пакета CA. Работает без включения дополнительного режима:

Переменная среды	Описание
`REQUESTS_CA_BUNDLE`	Путь к файлу пакета CA (`.pem` или `.crt`), которому нужно доверять.
`CURL_CA_BUNDLE`	Псевдоним для `REQUESTS_CA_BUNDLE`; используется, если последняя переменная не задана.

Эти варианты можно сочетать: при использовании CYCODE_CLI_ENABLE_TRUSTSTORE=1 сертификаты из REQUESTS_CA_BUNDLE будут доверенными в дополнение к сертификатам из хранилища компьютера, а не вместо них.

[!TIP] Выполните любую команду с -v, чтобы узнать, какой источник доверия используется, например cycode -v status.

Примечания:

В Windows CLI всегда использовал системное хранилище сертификатов в качестве резервного варианта, если не заданы ни REQUESTS_CA_BUNDLE, ни CURL_CA_BUNDLE. Это поведение не изменилось.
Настройки прокси задаются с помощью стандартных переменных среды HTTP_PROXY, HTTPS_PROXY и NO_PROXY.

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

Команда 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`	Сканирование на наличие проблем Software Composition Analysis (SCA): уязвимостей и проблем с лицензиями
`cycode_iac_scan`	Сканирование на наличие ошибок конфигурации Infrastructure as Code (IaC)
`cycode_sast_scan`	Сканирование с помощью Static Application Security Testing (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 в ЕС задайте соответствующие значения 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"
    }
  }
}

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

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

Если клиент MCP прерывает длительное сканирование, увеличьте тайм-аут вызова инструмента.

Переменная среды	Описание
`MCP_TOOL_TIMEOUT`	Тайм-аут (в секундах), в течение которого клиенты MCP, например Claude и GitHub Copilot, ожидают завершения вызова инструмента. Увеличьте это значение, если длительное сканирование прерывается до завершения.

При работе через корпоративный прокси задайте переменные сертификатов в блоке env сервера MCP. В разделе Сертификаты и прокси описаны доступные варианты: использовать CYCODE_CLI_ENABLE_TRUSTSTORE=1 для сертификатов, уже установленных на компьютере, или REQUESTS_CA_BUNDLE для указания файла пакета CA.

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

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

[!NOTE] Для работы сервера MCP требуется корректная аутентификация Cycode CLI. Перед запуском сервера MCP выполните аутентификацию с помощью cycode auth или настройте учетные данные.

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

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

Чтобы предварительно разрешить инструменты MCP Cycode для работы во всех контекстах, включая субагентов, добавьте их в список 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 находится в бета-версии. Команды, аргументы и форматы вывода динамически генерируются на основе спецификации API Cycode и могут изменяться между выпусками без предупреждения. Пока не используйте их в автоматизации производственных процессов.

Команда 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 загружается из API Cycode и кэшируется в ~/.cycode/openapi-spec.json на 24 часа. Несвязанные команды (cycode scan, cycode status и т. д.) не инициируют загрузку.

[!NOTE] Для обнаружения и выполнения команд через cycode platform необходимо пройти аутентификацию (cycode auth или переменные окружения CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET). Остальные команды 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

Примеры для платформы

# 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'

Примечания и ограничения платформы

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

Защитные механизмы ИИ [BETA]

AI Guardrails устанавливает хуки в поддерживаемые агенты для написания кода с помощью ИИ (Claude Code, Cursor, Copilot, Codex), чтобы проверять запросы, файлы, которые читает агент, и аргументы инструментов MCP на наличие секретов до того, как они попадут в модель.

Данные, собираемые AI Guardrails

Проверка выполняется на стороне сервера, поэтому проверяемое содержимое покидает устройство: текст запроса, содержимое файлов, которые читает агент, и аргументы инструментов MCP отправляются в ваш тенант Cycode для проверки на наличие секретов.

Каждое событие также сопровождается контекстом о разработчике и устройстве, чтобы можно было связать обнаруженную проблему с устройством и пользователем, от которых она поступила. Некоторые из этих данных являются персональными:

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

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

Если сбор этих данных неприемлем в вашей среде, не устанавливайте хуки защитных механизмов (cycode ai-guardrails uninstall удаляет уже установленные хуки).

Команда сканирования

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

Приложение 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`/`unmaintained-packages`/`malicious-packages`). По умолчанию используются все типы.
`--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	Сканировать ещё не закоммиченное содержимое; также поддерживается локальное сканирование различий с помощью флагов (удобно для IDE)
repository	Сканировать репозиторий git, включая его историю

Параметры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

Чтобы искать только неподдерживаемые пакеты (пакеты с низкой оценкой проверки Maintained в OpenSSF Scorecard, что означает отсутствие или малое количество недавних коммитов и активности по проблемам), добавьте аргумент --sca-scan unmaintained-packages после параметра -t sca или --scan-type sca.

[!NOTE] Наличие неподдерживаемых пакетов в отчётах определяется политикой вашей организации. Этот параметр сужает область результатов сканирования, но не может включить политику, отключённую для вашего тенанта.

В предыдущем примере, если нужно выполнить сканирование SCA только на наличие неподдерживаемых пакетов, можно использовать следующую команду:

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

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

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

Чтобы искать только вредоносные пакеты (зависимости, которые в рекомендациях по безопасности определены как вредоносное ПО, а не просто уязвимые), добавьте аргумент --sca-scan malicious-packages после параметра -t sca или --scan-type sca.

Нарушения, связанные с вредоносными пакетами, всегда отображаются как Critical; для них не указываются оценка CVSS и версия с исправлением, поскольку единственный способ устранения — удалить зависимость.

[!NOTE] Наличие вредоносных пакетов в отчётах определяется политикой вашей организации. Этот параметр сужает область результатов сканирования, но не может включить политику, отключённую для вашего тенанта.

В предыдущем примере, если нужно выполнить сканирование SCA только на наличие вредоносных пакетов, можно использовать следующую команду:

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

Параметр восстановления lock-файлов

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

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

Автоматическое восстановление lock-файлов поддерживается в следующих экосистемах:

Экосистема	Файл манифеста	Создаваемый lock-файл	Запускаемый инструмент (если lock-файл отсутствует)
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`	(только чтение существующего 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`
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`

Если рядом с файлом манифеста уже существует lock-файл, 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)

Параметр диапазона коммитов (сканирование различий)

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

Проверки запросов на слияние: сканирования только изменений, внесённых в PR
Инкрементального сканирования CI/CD: проверки недавних изменений вместо всей кодовой базы
Проверки функциональных веток: сравнения изменений с веткой main/master
Оптимизации производительности: ускорения сканирования за счёт ограничения области проверки релевантными изменениями

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

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

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

Примеры сканирования различий

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

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

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

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

Сканирование изменений в функциональной ветке по сравнению с main:

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

Сканирование изменений между main и функциональной веткой:

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 hook, как описано в разделе «Установка» этого руководства.

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

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

Для этой команды доступны следующие параметры:

Параметр	Описание
`-b, --base-ref TEXT`	Git-ссылка (коммит, ветка или тег) для сравнения; по умолчанию используется `HEAD`, как и в pre-commit hook
`--include-unstaged`	Также сканировать неиндексированные изменения отслеживаемых файлов, а не только проиндексированные; по умолчанию отключено
`--path PATH`	Необязательный путь или пути, ограничивающие область сканирования различий; параметр можно повторять; по умолчанию используется весь рабочий каталог

Локальное сканирование различий (интеграции с IDE)

--base-ref и --include-unstaged превращают pre-commit в универсальное локальное сканирование различий: сравнение любого коммита (по умолчанию HEAD) с текущим рабочим каталогом, включая ещё не проиндексированные изменения. Эта возможность предназначена для плагинов IDE и других инструментов, которым нужна непрерывная обратная связь в реальном времени во время работы, а не процесс с использованием git hook. В сочетании с --include-unstaged параметр --path позволяет IDE ограничить сканирование только файлом, открытым в редакторе.

[!NOTE] Локальное сканирование различий (с помощью этих флагов) недоступно для сканирования IaC.

Сканирование всех текущих изменений (проиндексированных и неиндексированных) относительно последнего коммита:

cycode scan pre-commit --include-unstaged

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

cycode scan pre-commit --include-unstaged --base-ref main

Сканирование только определённого файла (например, файла, открытого в IDE):

cycode scan pre-commit --include-unstaged --path src/app.py

Сканирование перед отправкой

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

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

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

Установка pre-push hook

Чтобы настроить pre-push hook с помощью фреймворка pre-commit:

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

Создайте или обновите файл .pre-commit-config.yaml, добавив в него pre-push hooks:

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

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

repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.25.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 hook:
```
pre-commit install --hook-type pre-push
```
При успешной установке появится сообщение: Pre-push installed at .git/hooks/pre-push.
Поддерживайте pre-push hook в актуальном состоянии:
```
pre-commit autoupdate
```

Как работает сканирование перед отправкой

Hook сканирует каждый отправляемый коммит по отдельности, поэтому секрет, добавленный в одном коммите и удалённый в следующем, всё равно будет обнаружен. При установке через фреймворк pre-commit диапазон отправляемых коммитов определяется фреймворком: для существующих веток это новые коммиты с момента последнего коммита в удалённой ветке, а для новых веток — коммиты, которых ещё нет в удалённом репозитории (при отправке в пустой удалённый репозиторий — все коммиты). При запуске из написанного вручную .git/hooks/pre-push диапазон считывается из входных данных hook Git, а новые ветки сканируются от точки слияния с веткой по умолчанию (см. ниже).

Отправки, для которых нечего сканировать, например отправка тегов, удаление веток и отправки без новых изменений, проходят без сканирования. Если hook не может определить, что именно отправляется, он завершает работу с ошибкой и блокирует отправку, а не пропускает её незаметно.

Pre-push hooks Cycode задают always_run: true и pass_filenames: false, поскольку сканирование охватывает отправляемые коммиты, а не список файлов. Без always_run фреймворк pre-commit пропускает hook, если в отправляемых коммитах в сумме нет изменённых файлов, например если секрет добавлен в одном коммите и удалён в следующем. Без pass_filenames: false фреймворк передаёт имена изменённых файлов, которые сканированию не нужны, а при больших отправках разбивает их на группы и запускает полное сканирование для каждой группы. Если вы определяете hook самостоятельно (например, как hook repo: local), задайте оба параметра.

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

При запуске из написанного вручную hook сканирование перед отправкой определяет ветку по умолчанию для вычисления точки слияния в следующем порядке:

Переменная окружения: CYCODE_DEFAULT_BRANCH — позволяет задать значение вручную
HEAD удалённого репозитория Git: используется git symbolic-ref refs/remotes/origin/HEAD для определения фактической ветки удалённого репозитория по умолчанию
Информация об удалённом репозитории Git: если symbolic-ref завершается ошибкой, используется git remote show origin
Жёстко заданные варианты: используются распространённые названия веток по умолчанию (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, чтобы указать Cycode CLI, какие файлы и каталоги следует исключить из проверок. Он работает так же, как файл .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

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

Мягкий отказ

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

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

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

Пример результата Secrets

╭─────────────────────────────────────────────────────────────── 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, вы увидите поле «Рекомендации компании» с добавленными вами рекомендациями. Если вы не добавляли рекомендации компании, это поле не будет отображаться в инструменте CLI.

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

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

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

Ниже перечислены параметры команды cycode ignore:

Параметр	Описание
`--by-value TEXT`	Игнорировать конкретное значение при поиске секретов. Подробнее см. в разделе Игнорирование значения секрета.
`--by-sha TEXT`	Игнорировать конкретное представление SHA512 строки при поиске секретов. Подробнее см. в разделе Игнорирование SHA-значения секрета.
`--by-path TEXT`	Не проверять конкретный путь. Необходимо указать тип проверки. Подробнее см. в разделе Игнорирование пути.
`--by-rule TEXT`	Не проверять конкретный идентификатор правила для секрета/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-значение секрета.

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

Чтобы игнорировать конкретный путь при проверках Secrets, 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 на нужный путь.

Игнорирование правила для Secrets, IaC, SCA или SAST

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

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

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

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

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

В примере в начале этого раздела команда для игнорирования конкретного идентификатора правила IaC выглядит так:

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

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

В примере в начале этого раздела команда для игнорирования конкретного идентификатора правила SCA выглядит так:

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

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

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

[!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 pyyaml@5.3.1

В примере выше замените 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 хранит хеши значений SHA-256. При ручном изменении файла конфигурации следует указывать хеши строк.

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

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

Команда 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`	Пропустить восстановление lockfile и сканировать только прямые зависимости. Подробнее см. в разделе Параметр восстановления 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 example@cycode.com /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