취약점 검사를 위한 SBOM 문서 테스트

기능 가용성

Snyk REST API는 엔터프라이즈(Enterprise) 플랜에서만 사용할 수 있습니다. 자세한 내용은 플랜 및 가격 책정을 참조하십시오.

이러한 엔드포인트는 베타(beta) API 버전입니다. 일부 기능이 변경될 수 있습니다. 자세한 내용은 REST API의 버전 관리 정보를 참조하십시오.

Snyk은 소프트웨어 자재 명세서(SBOM, Software Bill of Materials) 문서를 비동기적으로 테스트하기 위한 API 엔드포인트 모음을 제공합니다. 이러한 엔드포인트를 사용하여 SBOM 및 해당 패키지에 영향을 미치는 취약점에 대해 자세히 알아볼 수 있습니다.

지원되는 SBOM 형식은 CycloneDX 1.4/1.5/1.6 JSON 및 SPDX 2.3 JSON입니다.

Snyk은 SBOM 내의 구성 요소를 패키지 URL(purl)로 식별합니다. 구성 요소에 purl이 포함되어 있지 않거나 purl 유형이 지원되지 않는 경우, Snyk은 해당 구성 요소에 대한 취약점 분석을 건너뜁니다. 지원되는 purl 유형은 apk, cargo, cocoapods, conan, composer, deb, gem, golang, hex, maven, npm, nuget, pub, pypi, rpm, swift, 그리고 관리되지 않는 C/C++ 종속성을 위한 generic입니다.

SBOM 문서 테스트 방법

SBOM 엔드포인트를 사용하여 SBOM 테스트를 생성하고, 상태를 확인하고, 결과를 확인하십시오. 다음 단계를 따릅니다.

1. Snyk에 SBOM을 전송하여 테스트를 생성합니다.

2. 테스트 상태를 확인합니다. (선택 사항)

3. 테스트가 완료되면 테스트 결과를 확인합니다.

Snyk에 SBOM을 전송하여 테스트 생성

SBOM 테스트는 시간이 오래 걸리는 작업일 수 있습니다. Snyk은 테스트 결과가 준비될 때까지 응답을 기다리는 대신, SBOM을 전송하는 초기 요청 후에 job_id를 반환합니다. 그런 다음 Snyk은 요청을 비동기적으로 처리합니다.

SBOM을 테스트하려면 다음 단계를 따르십시오.

1. Snyk 웹 UI에 로그인하여 조직 ID(UUID 형식), 프로젝트 ID(UUID), 그리고 API 키를 가져옵니다. 이러한 값을 찾는 데 도움이 필요한 경우, 조직 일반 설정, 프로젝트 설정 보기 및 편집, 그리고 API 인증을 참조하십시오.

2. curl 또는 Postman과 같은 HTTP 클라이언트를 사용하여 SBOM 테스트 실행 생성 엔드포인트에 요청을 보냅니다.

SBOM 문서는 요청 본문의 일부로 JSON 객체 형식으로 포함됩니다. 이 요청은 SBOM 문서에 대한 테스트 실행을 생성합니다.

HTTP 요청

curl --request POST \
    -H "Authorization: token <SNYK_TOKEN>" \
    -H "Content-Type: application/vnd.api+json" \
    --data-binary '@request_body.json' \
    'https://api.snyk.io/rest/orgs/<ORG_ID>/sbom_tests?version=2023-08-31~beta'

request_body.json

{
    "data": {
        "type": "sbom_test",
        "attributes":{
            "sbom": {
            <SBOM_CONTENTS>
            }
        }
    }
}

1. 응답에서 다음 단계에 사용될 job_id를 가져옵니다. 이는 SBOM 문서에서 수행되는 테스트 실행에 대한 고유 식별자입니다.

JSON 응답 본문

{
    "data": {
        "id": "<JOB_ID>",
        "type": "sbom_tests"
    },
    "jsonapi": {
        "version": "1.0"
    },
    "links": {
        "self": "/rest/orgs/<ORG_ID>/sbom_tests?version=2023-08-31~beta",
        "related": "/rest/orgs/<ORG_ID>/sbom_tests/<JOB_ID>?version=2023-08-31~beta"
    }
}

테스트 상태 확인 (Check the status of the test, 선택 사항)

초기 요청 이후 언제든지 테스트 상태를 확인할 수 있습니다.

1. SBOM 테스트 실행 생성 엔드포인트의 초기 요청에서 반환된 job_id를 사용하여 SBOM 테스트 실행 상태 가져오기 엔드포인트에 요청을 보냅니다.

2. 이 엔드포인트에 대한 요청이 성공하면 테스트 상태가 반환되며, 상태는 processing 또는 finished일 수 있습니다. 호출이 성공하지 않으면 오류가 반환됩니다.

  curl --get \
      -H "Authorization: token <SNYK_TOKEN>" \
      'https://api.snyk.io/rest/orgs/<ORG_ID>/sbom_tests/<TEST_ID>?version=2024-09-03~beta'

테스트 결과 확인

테스트가 완료되면 테스트된 SBOM에 대한 결과를 볼 수 있습니다.

1. 반환된 테스트 상태가 finished이면, SBOM 테스트 실행 결과 가져오기 엔드포인트에 요청을 보냅니다.

2. 반환된 정보를 확인합니다. 여기에는 테스트된 SBOM에 대한 요약 수준의 정보와 상세 결과가 포함됩니다.

curl --get \
    -H "Authorization: token <SNYK_TOKEN>" \
    'https://api.snyk.io/rest/orgs/<ORG_ID>/sbom_tests/<TEST_ID>/results?version=2023-08-31~beta'

SBOM 테스트 실행 생성 엔드포인트 문제 해결

다음 응답 코드는 성공을 나타냅니다.

201 Created

SBOM 테스트 실행이 성공적으로 생성되었습니다. 응답 본문에는 테스트 실행의 job ID가 포함됩니다.

다음은 API를 사용할 때 발생할 수 있는 오류 상태입니다. 여기에 언급되지 않은 문제가 발생하거나 해결에 어려움이 있는 경우 솔루션 엔지니어 또는 기술 성공 관리자에게 문의하거나 Snyk 지원팀에 요청을 제출하십시오.

400 Bad Request

잘못되었거나 손상된 데이터로 인해 서버가 요청을 처리할 수 없습니다. 요청 내용을 검토하고 다시 시도하십시오.

401 Unauthorized

인증 방법(API 토큰 또는 Bearer 토큰)이 유효하지 않습니다. Authorization 헤더를 올바르게 설정했는지 확인하십시오.

403 Forbidden

요청을 수행하는 데 필요한 권한이 없습니다. 요청된 조직의 구성원이 아니거나, 조직에 Snyk API 사용 권한이 없거나, 요청된 프로젝트에 대해 충분한 읽기 권한이 없는 경우에 발생할 수 있습니다.

429 Too Many Requests

Snyk API는 속도 제한이 있으므로 과도한 수의 요청은 결국 거부되기 시작합니다. 추가 요청을 하기 전에 잠시 기다려야 합니다.

500 Internal Server Error

서비스에 내부 시스템 오류가 발생했습니다.