Cycode

официальный

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

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

Сканирование пути репозитория на наличие жестко заданных секретов — Попросите ассистента запустить cycode_secret_scan в локальной директории для обнаружения раскрытых учетных данных.
Проверка зависимостей на известные уязвимости — Запустите cycode_sca_scan по пути проекта, чтобы выявить уязвимые или несоответствующие требованиям пакеты с открытым исходным кодом.
Аудит файлов Infrastructure as Code на предмет неправильных конфигураций — Используйте cycode_iac_scan для директорий Terraform или CloudFormation, чтобы выявить рискованные настройки.
Проверка исходного кода на наличие уязвимостей безопасности — Запустите cycode_sast_scan на кодовой базе, чтобы найти слабые места на уровне кода и проблемы с качеством.
Проверка аутентификации CLI и статуса версии — Вызовите cycode_status, чтобы подтвердить подключение к Cycode и узнать, какая версия активна.

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

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

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

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

Содержание

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

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

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

Установка

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

[!ПРИМЕЧАНИЕ] Следующие шаги предполагают использование 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 и учетных данных (секрет клиента или OIDC ID токен):
- cycode auth (Рекомендуется)
- cycode configure
- Добавьте их в переменные окружения

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

[!ПРИМЕЧАНИЕ] Это рекомендуемый метод настройки локальной машины для аутентификации с Cycode CLI.

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

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

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

Successfully logged into cycode

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

[!ПРИМЕЧАНИЕ] Если вы уже настроили идентификатор клиента Cycode и секрет клиента через переменные окружения Linux или Windows, эти учетные данные будут иметь приоритет над этим методом.

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

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

Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com
Введите значение идентификатора клиента Cycode.

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

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
Введите значение OIDC ID токена 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, вы можете предоставить ID токен вместо (или в дополнение):

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 ID токена:
Вставьте cycode.exe в путь, чтобы завершить установку.

Установка pre-commit хука

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

[!ПРИМЕЧАНИЕ] pre-commit и pre-push хуки недоступны для IaC-сканирования.

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

Установка pre-commit хука

Установите фреймворк 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 для включения сканирования секретов. Используйте 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 хук в актуальном состоянии:
```
pre-commit autoupdate
```
Он автоматически обновит rev в .pre-commit-config.yaml до последней доступной версии Cycode CLI.

[!ПРИМЕЧАНИЕ] Срабатывание происходит по команде git commit. Хук срабатывает только на файлы, которые были подготовлены для коммита.

Установка pre-push хука

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

Добавьте 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 хук:

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

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

[!ПРИМЕЧАНИЕ] 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-secret TEXT`	Указать секрет клиента Cycode для этого конкретного выполнения сканирования.
`--id-token TEXT`	Указать OIDC ID токен 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 и выйти.

Команда 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`	Сканирование на предмет ошибок конфигурации Infrastructure as Code (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-сервер с потоковым 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"
    }
  }
}

Для потокового 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"
    }
  }
}

Для потокового 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. Используется низкоуровневым модулем `ssl` Python. Установите его вместе с `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

Команда платформы [БЕТА]

[!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

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

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

AI Guardrails [БЕТА]

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

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

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

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

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

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

Если сбор этих данных неприемлем в вашем окружении, не устанавливайте хуки guardrails (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`). По умолчанию выполняются оба.
`--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.

Чтобы прямая ссылка на этот отчёт Cycode была выведена в вашем CLI после завершения сканирования, добавьте аргумент --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

Опция восстановления lockfile

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

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

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

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

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

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

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

Опция остановки при ошибке

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

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

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

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

При использовании --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 Plan

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-сканирований команда истории коммитов фокусируется на сканировании различий/изменений между коммитами, что делает её идеальной для проверки pull request'ов и инкрементального сканирования.

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

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

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

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

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

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

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

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

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

Чтобы настроить pre-push hook с помощью pre-commit framework:

Установите pre-commit framework (если он ещё не установлен):
```
pip3 install pre-commit
```

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

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

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

Pre-push hook:

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

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

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

Переменная окружения: 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 hook работает корректно независимо от того, использует ли ваш репозиторий main, master, develop или любое другое имя ветки по умолчанию.

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

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

SKIP=cycode-pre-push git push

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

git push --no-verify

[!TIP] Pre-push hook запускается по команде 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 к любому типу сканирования.

В следующем примере выполняется сканирование пути (Path Scan) для подкаталога 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 правила секрета/ID правила IaC/ID правила 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 на ваше значение пути.

Игнорирование правила секрета, IaC, SCA или SAST

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

Пример реального 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`	Включить dev-зависимости	Нет	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-файла и сканировать только прямые зависимости. Подробнее см. Параметр восстановления блокировки.
`--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]`	Бизнес-влияние	Нет	Средний

Например:
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

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

cycode scan path --help

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

cycode ignore --help

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

cycode report --help

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

cycode scan {{option}} --help