Перейти к содержанию

Работа с использованием CLI

Сканирование SBOM в системе можно запустить как с использованием пользовательского интерфейса, так и с помощью командной строки. В состав AppSec.Track входит утилита track-cli, работающая в различных операционных системах.

Поддерживаемые языки и форматы

Язык Файл Поддержка
Ruby Gemfile.lock
gemspec		 ✅
Python Pipfile.lock
poetry.lock
requirements.txt
egg package
wheel package
conda package
 ✅
PHP composer.lock ✅
Node.js
JavaScript		 package-lock.json
yarn.lock
pnpm-lock.yaml
package.json		 ✅
.NET packages.lock.json
packages.config
.deps.json		 ✅
Java
Scala
Kotling		 JAR/WAR/PAR/EAR
pom.xml
*gradle.lockfile		 ✅
Go Бинарные артефакты Go
go.mod		 ✅
Rust Cargo.lock
Бинарные артефактс с флагом cargo-auditable		 ✅
C/C++ conan.lock ✅
Elixir mix.lock ✅
Dart pubspec.lock ✅
Swift Podfile.lock
Package.resolved		 ✅
Docker Удаленные образы
.tar
Dockerfile		 ✅

Для построения полного дерева транзитивных зависимостей рекомендуется использовать генерацию lock-файлов со стороны сборщика для требуемого языка программирования. К примеру, для Gradle: ./gradlew dependencies --write-locks.

Авторизация

Начиная с версии 3.19.0, утилита поддерживает авторизацию. track-cli воспринимает переменные окружения TRACK_REPO_USERNAME и TRACK_REPO_PASSWORD для аутентифицированного доступа к Docker-репозиторию:

  1. Для Linux:

    export TRACK_REPO_USERNAME={username}
export TRACK_REPO_PASSWORD={password}

  2. Для Windows:

    set TRACK_REPO_USERNAME={username}
set TRACK_REPO_PASSWORD={password}

  3. Пример переменных окружения в CI-pipeline:

    variables:
    TRACK_REPO_USERNAME: {username}
    TRACK_REPO_PASSWORD: {password}

Без доступа к Docker-репозиторию сканирование закончится ошибкой с сообщением об отсутствии прав доступа UNAUTHORIZED.

Режимы работы

Начиная с версии 3.14.0, утилита командной строки track-cli поддерживает два режима работы:

  1. Сканирование (scan). Если при этом не указан SBOM, то проводится генерация SBOM и последующая его отправка на сканирование, а затем выдача результатов сканирования. В этом режиме также существует возможность сгенерировать SBOM, указав параметр --sbom-output-file.
  2. Генерация SBOM (collect).

В обоих режимах поддерживается работа с тремя видами объектов (целей сканирования):

  1. SBOM (sbom).
  2. Файловая система – путь до каталога или файла (fs).
  3. Образ Docker (image).

Также утилита поддерживает анализ архива исходных кодов или артефактов.

Корректное завершение работы утилиты возможно, только если указаны все обязательные параметры.

Параметры

Параметры утилиты описаны в таблице ниже.

Примечание

При работе в закрытом контуре при сканировании необходимо задавать параметр --java-db-repository с указанием папки, в которой располагается локальная база trivy-java-db. Без этой информации сканирование maven-проектов будет завершаться с ошибкой.

Примечание

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

Параметр Обязательный
параметр		 Описание Пример
Режим работы: scan
Идентификация приложения
-a, --app-name + Имя приложения в AppSec.Track -a test_app
-t, --app-team + Имя команды приложения в AppSec.Track -t team_name
-v, --app-version + Версия приложения -v 1.3.9
-e, --app-env + Окружение.
Допустимые значения: dev, test, prod, stage, release
Если флаг не установлен, значение по умолчанию: dev		 -e dev
Идентификация сервера
-s, --server + Адрес сервера AppSec.Track -s https://localhost
--token + Токен подключения к серверу. В текущей версии этот параметр может иметь произвольное значение --token 111
Параметры сканирования
--commit-id - Идентификатор коммита для обратной ссылки из AppSec.Track --commit-id 7932314bd6d59f5s431d3e1f261dd639155004rg
--commit-url - URL коммита для обратной ссылки из AppSec.Track --commit-url https://path/to/7932314bd6d59f5s431d3e1f261dd639155004rg
-o, --sbom-output-file - Путь к файлу, куда будет сохранен полученный SBOM-файл -o "C:\Users\user123\app-go\in\sbom.json"
--no-report - Не выводить отчет о сканировании в консоль (по умолчанию false) --no-report
--report-max-components - Максимальное количество компонентов, которые будут выводиться (по умолчанию 10) --report-max-components 15
--report-max-vulnerabilies - Максимальное количество уязвимостей, которые будут выводиться (по умолчанию 1) --report-max-vulnerabilies 5
--no-fail - Если установлен, то утилита выходит с 0 кодом ответа в случае нарушения --no-fail
--skip-vulns-export - Если установлен, не заполняется блок c описанием уязвимостей "vulnerabilities":[] в SBOM-файле --skip-vulns-export
Цель сканирования (fs, sbom, image)
sbom <путь до файла> + Сканирование SBOM-файла sbom https://aquasecurity.github.io/trivy/v0.33/docs/sbom/
fs <путь до каталога/файла> - Сканирование файловой системы fs https://aquasecurity.github.io/trivy/v0.17.2/scanning/filesystem/
image <название образа> - Сканирование образа Docker image https://aquasecurity.github.io/trivy/v0.17.2/scanning/image/
image --input <название образа в формате .tar> - Сканирование образа в формате .tar image --input tomcat.tar.gz
Режим работы: collect
Параметры сканирования
-o, --sbom-output-file - Путь к файлу, куда будет сохранен полученный SBOM-файл -o "C:\Users\user123\app-go\in\sbom.json"
Цель сканирования (fs, sbom, image)
sbom <путь до файла> + Сканирование SBOM-файла sbom https://aquasecurity.github.io/trivy/v0.33/docs/sbom/
fs <путь до каталога/файла> - Сканирование файловой системы fs https://aquasecurity.github.io/trivy/v0.17.2/scanning/filesystem/
image <название образа> - Сканирование образа Docker image https://aquasecurity.github.io/trivy/v0.17.2/scanning/image/
image --input <название образа в формате .tar> - Сканирование образа в формате .tar image --input tomcat.tar.gz
Общие параметры
-V, --version - Печать информации о версии утилиты CLI -V
-X, --debug - Отладочный режим работы приложения -X
-h, --help - Вывод справочной документации -h
--insecure - Разрешить insecure подключение к серверу. Используется для любых подключений (для удалённых образов, загрузки баз и т.д.) --insecure
--java-db-repository - Путь к OCI-репозиторию для получения trivy-java-db --java-db-repository https://path/to/java-db-repository
--cache-dir - Путь к папке с кешем --cache-dir https://path/to/cache-dir

Примеры запуска утилиты track-cli:

  1. Пример сканирования SBOM (Windows):

    ./appsec-track-cli-1.0.0-23.exe scan -a testing_cli_app -t testing_cli_team -v 0.0.1 -e dev -s https://track.dev.your_company.ru --token 111 sbom "SCA SBOM_ytest.json"

  2. Пример сканирования файловой системы (Windows):

    ./appsec-track-cli-1.0.0-23.exe scan -a testing_cli_app -t testing_cli_team -v 0.0.1 -e dev -s https://track.dev.your_company.ru --token 111 fs "C:\Users\user123\Desktop\scanning\some-filesystem"

  3. Пример сканирования образа (Windows):

    .\appsec-track-cli-1.0.0-23.exe scan -a testing_cli_app -t testing_cli_team -v 0.0.1 -e dev -s https://track.dev.your_company.ru --token 111 image fedora

  4. Пример генерации SBOM файловой системы (Windows):

    .\appsec-track-cli-1.0.0-23.exe collect -o "C:\Users\user123\Desktop\cli-go\in\sbom-cli.json" fs "C:\Users\user123\Desktop\scanning\some-filesystem"

  5. Пример генерации SBOM образа (Windows):

    .\appsec-track-cli-1.0.0-23.exe collect -o "C:\Users\user123\Desktop\cli-go\in\sbom-cli.json" image friendica:stable-fpm-alpine

  6. Пример запуска из контейнера в Linux:

    docker run -v ./SCA_SBOM_ytest.json:/SBOM.json -it cr.yandex/crp7ttiiijphcnpukc93/sca-track-cli:latest scan -a testing_cli_app -t testing_cli_team -v 0.0.1 -e dev -s https://track.your_company.ru --token 111 sbom /SBOM.json

  7. Пример генерации SBOM образа в формате .tar:

    ./track-cli collect -o sbom.json image --input tomcat.tar.gz

Если в системе были включены политики, сработавшие на просканированные компоненты, результатом запуска утилиты будут:

  • Краткая сводка в командной строке в виде таблицы с результатами сканирования и информацией о сработавших политиках (ее печать может быть убрана с помощью параметра утилиты --no-report).

  • Ссылка на страницу с детальными результатами сканирования. По этой ссылке можно перейти в систему на страницу с полным отчетом о проведенном сканировании, см. раздел «Примеры лога задания при наличии блокирующих политик».

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

Примечание

Если в системе отсутствует команда и/или приложение, указанные как параметры при запуске утилиты track-cli, в случае корректного завершения сканирования с созданием отчета о сканировании они будут добавлены в список команд и приложений.

Если при запуске утилиты track-cli параметры имя команды (-t), окружение (-e) и версия приложения (-v) были оставлены пустыми (в качестве значения каждого параметра был указан пробел в кавычках: -t " " - e " " -v " "), в список команд и приложений будет добавлена команда с названием Команда не указана с окружением Окружение не указано и версией приложения Версия не указана.

Все параметры, указанные в строке запуска утилиты track-cli, в случае расхождения их значений с аналогичными параметрами, указанными в файле SBOM, имеют более высокий приоритет. Это относится к следующим параметрам:

Параметр Утилита track-cli Файл SBOM
Имя приложения -a, --app-name component name
Версия приложения -v, --app-version component version
Идентификатор коммита --commit-id commits uid
Имя команды -t, --app-team properties team_name
Окружение, стенд (environment) -e, --app-env properties environment

В приведенном ниже фрагменте файла SBOM эти параметры расположены в выделенных строках: 

{
    "bomFormat": "CycloneDX",
    "specVersion": "1.2",
    "serialNumber": "urn:uuid:1f860713-54b9-4253-ba5a-955485190455",
    "version": 2,
    "metadata": {
        "timestamp": "2023-06-22T03:20:53.771Z",
        "tools": [
            {
                "vendor": "CycloneDX",
                "name": "Node.js module",
                "version": "2.0.0"
            }
        ],
        "component": {
            "type": "library",
            "bom-ref": "",
            "name": "NiceTasks",
            "version": "1.0.10",
            "pedigree": {
                "commits": [
                    {
                        "uid": "7638417db6d59f3c431d3e1f261cc637155684ct",
                        "url": "https://location/to/7638417db6d59f3c431d3e1f261cc637155684ct"
                    }
                ]
            }
        },
        "properties": [
            {
                "name": "team_name",
                "value": "mobile"
            },
            {
                "name": "environment",
                "value": "stage"
            }
        ]
    },
    "components": [
…