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

Интеграционный API

Интеграционный API используется для интеграции AppSec.Hub с различными инструментами и приложениями.

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

Данный программный интерфейс реализует загрузку результатов сканирования из инструмента (например, Checkmarx) в AppSec.Hub. При этом, на стороне AppSec.Hub создаются все необходимые объекты и связи (приложение, кодовая база, артефакт, пайплайн и т. д.), запускается импорт уязвимостей, осуществляется проверка прохождения QG. Однако само сканирование НЕ ВЫПОЛНЯЕТСЯ.

Примечание

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

Запрос

POST /import/results

Параметры

Примечание

Обязательные параметры отмечены *.

Параметр Тип Описание
application* Object Идентифицирует объект приложения application
unitRequest Object Связывает артефакт/кодовую базу/экземпляр приложения со структурной единицей. Если указанная структурная единица отсутствует, она создается
unit String Связывает артефакт/кодовую базу/экземпляр приложения со структурной единицей. Если указанная структурная единица отсутствует, она создается. Данный параметр является устаревшим (deprecated). Вместо него рекомендуется использовать параметр unitRequest
source* List<Object> Перечень исходных объектов source (одного и того же типа), которые были просканированы
scans* List<Object> Перечень объектов сканирования scan, содержащих результаты (уязвимости) для импорта
qualityGateCode String Код идентификации объекта Quality Gate (QG) в AppSec.Hub. При отсутствии используется QG из настроек пайплайна
scanInitiator Object Идентифицирует объект Scan initiator
releaseObject Object Идентифицирует объект Release object
Application
Параметр Тип Описание
code* String Код приложения в БД AppSec.Hub
externalId String Внешний ID нового приложения. Этот параметр используется при onboarding и впоследствии может игнорироваться
name String Имя приложения
Unitrequest
Параметр Тип Описание
code* String Код структурной единицы
name String Имя структурной единицы
Source
Codebase
Параметр Тип Описание
type* String Тип анализируемого объекта
Значение: codebase
name String Имя кодовой базы в AppSec.Hub. При отсутствии генерируется имя на основе appcode, url и branch
url* String Внешний URL для копирования репозитория кодовой базы
checkoutPath* String Директория расположения кодовой базы
branch String Ветвь или тег репозитория для основной кодовой базы.
Значение по умолчанию: master
commit String Ветвь или тег репозитория для основной кодовой базы.
Значение по умолчанию: master
buildTool String Инструмент сборки кодовой базы.
Доступные значения: maven
branchFilter String Фильтр сканируемых ветвей. Применяется для основной и дополнительных кодовых баз.
Значение по умолчанию: аналогично параметру ––branch
Artifact
Параметр Тип Описание
artifact* String Параметры артефакта
<adtifact-url>;<artifact-name>;
Имя артефакта в AppSec.Hub
type* String Тип сканируемого объекта
Значение: artifact
Instance
Параметр Тип Описание
type* String Тип сканируемого объекта
Значение: instance
name String Имя инстанса в AppSec.Hub. При отсутствии генерируется на основе appcode и url
url* String URL установленного приложения
Scan

Каждый объект представлен в одном из следующих форматов.

Checkmarx
Параметр Тип Описание
url* String URL инструмента
product* String Идентификатор инструмента сканирования, который содержит импортируемые уязвимости
Значение: checkmarx
cxProject* String Имя проекта в Checkmarx
cxTeam String Имя команды Checkmarx
Значение: CxServer
cxScanId String ID сканирования в проекте Checkmarx. При отсутствии импортируются результаты последнего сканирования
Scan initiator
Параметр Тип Описание
initiator String Информация об инициаторе сканирования, например ссылка на задачу сканирования в TeamCity
environment String Рабочая среда инициатора сканирования
Release object
Параметр Тип Описание
url String URL-адрес артефакта (в Repository manager инструменте), который рассматривается как релизный объект
Примеры

Checkmarx

{
   "application": {
      "code": "09022021_cli",
      "externalId": "c361b656-fb8f-11eb-9a03-0242ac130003"
   },
   "unit": "core",
   "source": [
      {
        "type": "codebase",
        "name": "java-web-project-master",
        "url": "http://gitlab.service.swordfishsecurity.com/test/java-web-project",
        "checkoutPath": "/",
        "branch": "master",
        "buildTool": "maven"
      }
    ],
    "scans": [
      {
         "url": "https://cx93.dev.swordfishsecurity.com",
         "product": "checkmarx",
         "cxProject": "kgr_19082021_2_-master_1",
         "cxTeam": "/CxServer/asdfsadfASDFASDF/kgr_19082021_2"
      }
   ],
   "qualityGateCode": "No_Critical",
   "scanInitiator": {
     "initiator": "https://teamcity.your.company.com/buildConfiguration/Dvja_SecurityChecks/59863",
     "environment": "{ \"ci\": {\"type\": \"Teamcity\", \"url\": \"https://teamcity.your.company.com\"}, \"trigger\": {\"type\": \"dependency\", \"link\": \"https://teamcity.your.company.com/buildConfiguration/Dvja_SecurityChecks/59863\"}"
   },
   "releaseObject": {
     "url": "https://nexus.your.company.com/repository/docker-private/v2/java-web-project/manifests/1.17"
   }
}

Checkmarx (несколько кодовых баз)

{
   "application": {
      "code": "09022021_cli",
      "externalId": "c361b656-fb8f-11eb-9a03-0242ac130003"
   },
   "unit": "core",
   "source": [
      {
        "type": "codebase",
        "name": "java-web-project-master",
        "url": "http://gitlab.service.swordfishsecurity.com/test/java-web-project.git",
        "checkoutPath": "/",
        "branch": "master",
        "buildTool": "maven"
      },
      {
        "type": "codebase",
        "name": "java-web-config-master",
        "url": "http://gitlab.service.swordfishsecurity.com/test/java-web-config.git",
        "checkoutPath": "/conf",
        "branch": "master",
        "buildTool": "N/A"
      }
    ],
    "scans": [
      {
         "url": "https://cx93.dev.swordfishsecurity.com",
         "product": "checkmarx",
         "cxProject": "kgr_19082021_2_-master_1",
         "cxTeam": "/CxServer/asdfsadfASDFASDF/kgr_19082021_2"
      }
   ],
   "qualityGateCode": "No_Critical",
   "scanInitiator": {
     "initiator": "https://teamcity.your.company.com/buildConfiguration/Dvja_SecurityChecks/59863",
     "environment": "{ \"ci\": {\"type\": \"Teamcity\", \"url\": \"https://teamcity.your.company.com\"}, \"trigger\": {\"type\": \"dependency\", \"link\": \"https://teamcity.your.company.com/buildConfiguration/Dvja_SecurityChecks/59863\"}"
   },
   "releaseObject": {
     "url": "https://nexus.your.company.com/repository/docker-private/v2/java-web-project/manifests/1.17"
   }
}

Ответ

Body

Параметр Тип Описание
scanTaskId Integer Идентификатор сканирования
status String Статус процесса
Доступное значение: Import started

Пример

{
    "scanTaskId": "12345",
    "status": "Import started"
}

Получение статуса сканирования

Выполняет проверку статуса задачи на сканирование.

Запрос

GET /scan/{scanTaskId}/status

Параметры

Параметр Тип Описание
scanTaskId* Integer ID задачи на сканирование, полученный в результате Запуска импорта результатов сканирования

Ответ

Body

Параметр Тип Описание
status* String Статус процесса импорта
Доступные значения: PENDING, IN_PROCESS, BROKEN, IMPORTING,
SUCCESS, FAILED, CANCELLED.
details* String Подробная информация о возвращаемом статусе
qgCheckResult List Подробная информация о статусе прохождения Quality Gate в разрезе каждой практики (SAST, SCA, DAST) в запрошенном пайплайне.
Внимание: Необходим, если QG сконфигурирован, а статус сканирования SUCCESS или FAILED
summary Object Итоговая информация об импортированных уязвимостях.
Внимание: Необходим, если статус SUCCESS или FAILED
taggingHistoryRecord Object Информация о NXRM-тегировании
scanResultsUrl String URL для UI-страницы, с фильтрацией по ID сканирования
Quality Gate
Параметр Тип Описание
practice* String Имя практики
Доступные значения: SAST, SCA, DAST
status* String Статус прохождения QG
Доступные значения: PASSED, FAILED, N/A
violations List Перечень условий, по которым не был пройден QG
Summary
Параметр Тип Описание
new* Object Детальная информация о новых уязвимостях
repeated* Object Детальная информация о повторяющихся уязвимостях
fixed* Object Детальная информация об исправленных уязвимостях
total* Object Детальная информация об общем количестве открытых дефектов (новые и повторяющиеся)
Summary — детальная информация
Параметр Тип Описание
critical* Integer Количество критических импортированных уязвимостей с критическим уровнем серьезности
high* Integer Количество импортированных уязвимостей с высоким уровнем серьезности
medium* Integer Количество импортированных уязвимостей со средним уровнем серьезности
low* Integer Количество импортированных уязвимостей с низким уровнем серьезности
Тегирование
Параметр Тип Описание
status* String Статус тегирования
Возможные значения: SUCCESSFUL, FAILED
details* String Подробная информация о возвращенных статусах
appliedTags List Перечень примененных тегов в NXRM

Пример

{
    "status": "FAILED",
    "details": "QG is not passed. Import is finished. One ore more QG checks are not passed",
    "qgCheckResult": [{
            "practice": "SAST",
            "status": "N/A",
            "violations": null
        }, {
            "practice": "SCA",
            "status": "FAILED",
            "violations": ["Number of ALL SCA Security issues with HIGH severity (15) exceeds the limit (0)", "Number of ALL SCA Security issues with CRITICAL severity (29) exceeds the limit (0)"]
        }, {
            "practice": "DAST",
            "status": "N/A",
            "violations": null
        }
    ],
    "summary": {
        "new": {
            "critical": 29,
            "high": 15,
            "medium": 6,
            "low": 86
        },
        "repeated": {
            "critical": 0,
            "high": 0,
            "medium": 0,
            "low": 0
        },
        "fixed": {
            "critical": 0,
            "high": 0,
            "medium": 0,
            "low": 0
        },
        "total": {
            "critical": 29,
            "high": 15,
            "medium": 6,
            "low": 86
        }
    },
    "scanResultsUrl": "https://hub.dev.swordfishsecurity.com/#/appprofile/2905/issues?scanId=12374"
}

.

К началу