Export API: 사양, 열 및 필터
Snyk Analytics에서 지원하는 Export API는 사용자가 CSV 파일을 생성하고 관리할 수 있도록 하여 데이터 내보내기를 더 쉽게 만들어 줍니다. 이 파일들은 Snyk에 의해 안전하게 저장됩니다. 효율성과 보안을 위해 설계된 Export API는 사용자가 대규모 데이터 세트의 내보내기를 구성하고 확장하는 데 도움을 주며, 이는 보고 및 분석 작업에 유용합니다.
Export API를 사용하여 Snyk 조직(Organization) 또는 Snyk 그룹(Group) 범위에서 Snyk 문제(issues) 및 사용(usage) 이벤트 데이터 세트를 내보낼 수 있습니다. 전체 목록을 보려면 사용 가능한 열 및 필터 섹션으로 이동하십시오.
첫 번째 내보내기를 실행하기 전에 모든 API 요청에 다음이 포함되어 있는지 확인하십시오.
API 버전 매개변수. 최신 버전은
2024-10-15입니다. API를 사용할 때 자동 업그레이드를 원하면 현재 날짜를 버전으로 포함할 수도 있습니다.인증 헤더. 사용자 또는 서비스 계정 Snyk API 토큰을 사용하십시오.
dataset매개변수. 유효한 값은issues또는usage뿐입니다. 이 매개변수는 내보낼 데이터 세트를 지정하는 데 필수적입니다.최소 하나 이상의 날짜 필터 (
issues데이터 세트의 경우introduced또는 두 데이터 세트 모두에 대해updated)
데이터 소비 프로세스
Export API에는 각 범위(Snyk 조직 또는 Snyk 그룹)에 대해 세 개의 엔드포인트가 포함되어 있습니다. 이 API를 사용하여 성공적으로 내보내기를 실행하려면 다음 워크플로우를 사용하십시오.
내보내기 시작 (Initiate the export) 내보내기 프로세스를 시작하여 시작하십시오. 해당 요청에 대한 응답은
export_id를 반환합니다. 기호에 따라 필터 및 열(filters and columns)을 설정하십시오.
POST /groups/{group_id}/export내보내기 상태 확인 (Validate the export status) 이전 단계에서 반환된
export_id와 내보내기 상태 엔드포인트를 사용하여 상태를 확인합니다. 사용 가능한 상태:PENDING- 내보내기 프로세스가 시작을 준비 중입니다.STARTED- 내보내기 프로세스가 시작되었습니다.FINISHED- 내보내기 프로세스가 성공적으로 완료되었습니다. 이 요청이 도착했을 때 프로세스가 성공적으로 종료되면 결과 데이터가 응답에 포함됩니다.ERROR- 내보내기 프로세스가 실패했습니다.
결과 가져오기 (Fetch results) 내보내기 프로세스가
FINISHED상태를 반환한 후, 내보내기 결과 엔드포인트를 사용하여 내보낸 파일을 가져옵니다. 첫 번째 단계에서 반환된export_id를 사용하십시오.
Export API 사양
데이터 최신성
Export API 서비스에서 제공하는 데이터는 약 2시간마다 업데이트됩니다. 데이터 최신성을 고려할 때 순환 내보내기는 2시간에 한 번보다 더 빈번하게 예약해서는 안 됩니다.
속도 제한
API는 다음에 의해 제한됩니다.
내보내기
POST엔드포인트는 시간당 최대 20개의 내보내기 요청을 허용하며, 상태 확인 및 결과 검색은 무제한입니다.
데이터가 일반적으로 2시간마다 갱신된다는 점을 감안할 때, Snyk은 적용된 속도 제한이 편안한 소비를 가능하게 할 것으로 예상합니다. Snyk은 관련 그룹당 몇 시간마다 한 번씩 또는 매일 내보내기를 요청할 것을 권장합니다.
데이터 보존
내보낸 CSV 파일은 지정된 S3 버킷에서 3일 동안 사용할 수 있습니다.
파일은 3일 동안 액세스할 수 있지만, 내보내기 결과를 검색하기 위한 자체 서명 링크는 기본적으로 생성 후 60분 동안만 사용할 수 있습니다. 사용자는 url_expiration_seconds 속성에 0에서 3600 사이의 값을 전달하여 링크 만료 시간을 제한할 수 있습니다.
사용 가능한 열 및 필터
기본 열
Export API 호출에서 특정 열을 정의하지 않으면 반환된 데이터에는 기본적으로 사용 가능한 모든 열이 포함됩니다.
사용 가능한 필터
요청된 필터 자체는 대소문자를 구분하지 않지만, 해당 필터의 값은 대소문자를 구분합니다.
Snyk 웹 UI에 표시된 것과 정확히 동일한 필터 값을 사용하십시오. 이 요구 사항을 명확히 하기 위해 대소문자를 구분하는 필터는 사용 가능한 필터 표에 표시되어 있습니다.
요청에 최소 하나 이상의 날짜 필터(issues 데이터 세트의 경우 introduced 또는 두 데이터 세트 모두에 대해 updated)가 포함되어야 합니다.
updated (from 및 to)
issues, usage
데이터 세트의 속성에 영향을 준 마지막 업데이트 날짜와 시간입니다.
순환 내보내기 중에 이 필터를 사용하여 마지막 내보내기 이후 업데이트된 데이터만 내보냅니다.
허용되는 형식: YYYY-MM-DDTHH:MM:SSZ
(예: 2024-11-28T09:10:00Z)
introduced (from 및 to)
issues
문제가 도입된 날짜입니다.
허용되는 형식: YYYY-MM-DDTHH:MM:SSZ
(예: 2024-11-28T09:10:00Z)
orgs
issues, usage
Snyk Organization ID (그룹 엔드포인트에서만 사용 가능).
environment
issues
프로젝트의 환경(Environment) (대소문자 구분 안 함).
lifecycle
issues
프로젝트의 수명 주기(Lifecycle) (대소문자 구분 안 함).
product_name
issues
문제를 생성한 Snyk 제품의 이름 (대소문자 구분).
project_type
issues
특정 프로젝트에 사용할 스캔 방법 (대소문자 구분).
project_tags
issues
이 프로젝트에 할당된 모든 태그(key:value 쌍) (대소문자 구분).
empty_project_tags
issues
다음 세 가지 값 중 하나를 가집니다:
include-project_tags필터를 사용할 때 프로젝트 태그가 null/비어 있는 문제를 포함합니다.exclude- 프로젝트 태그가 null/비어 있는 문제를 제외합니다. (project_tags필터를 사용할 때는 암시적으로 필터링되므로 필요하지 않습니다.)only- 프로젝트 태그가 null/비어 있는 문제만 반환합니다.project_tags필터도 채워진 경우 요청은 0개의 문제를 반환합니다.
문제(Issues) 데이터 세트 열
사용 가능한 열
심각도
score
분석 모델을 기반으로 한 점수입니다. 우선순위 점수(Priority score)는 정식 버전(GA)으로 출시되었으며, 위험 점수(Risk Score)는 Early Access 단계입니다.
issue_severity
평가된 위험 수준(critical, high, medium, low)을 나타냅니다.
snyk_cvss_score
Snyk에서 권장하는 CVSS(Common Vulnerability Scoring System) 점수입니다.
nvd_severity
NVD에서 평가한 취약점의 심각도입니다.
nvd_score
NVD에서 계산한 취약점의 점수입니다.
가능성
exploit_maturity
Snyk에서 정의하고 검증한 공개 익스플로잇(Exploit)의 레거시 존재 여부 및 성숙도(예: Mature 또는 Proof of Concept)를 나타냅니다.
exploit_maturity_cvss_v4
Snyk에서 검증한 공개 익스플로잇의 존재 여부 및 성숙도를 CVSS v4 값(Not Defined, POC, Attacked)을 사용하여 나타냅니다.
snyk_cvss_vector
CVSS 점수를 결정하는 데 사용된 메트릭 값의 벡터 문자열입니다.
epss_score
향후 30일 이내에 실제로 악용될 확률입니다.
epss_percentile
동일하거나 낮은 EPSS 점수를 가진 모든 취약점 중의 비율입니다.
reachability
문제가 애플리케이션에서 호출되는 함수와 관련이 있어 악용 가능성이 더 높은지 여부를 나타냅니다.
project_is_private_target
대상(Target)의 소스가 비공개인지 또는 공개적으로 접근 가능한지 여부를 나타냅니다.
영향
asset_class
고객이 구성한 자산의 비즈니스 중요도(A: 가장 중요함 ~ D: 가장 낮음)입니다.
project_target_runtime
대상이 실행되고 작동하는 환경입니다.
project_criticalities
비즈니스 중요도를 나타내는 프로젝트 속성입니다. 예: low, medium, high, critical.
project_lifecycles
프로젝트 속성입니다. 예: production, development, sandbox.
asset_lifecycle
자산의 수명 주기 상태입니다.
project_environments
프로젝트 속성입니다. 예: frontend, backend, internal, external, mobile, saas, onprem, hosted, distributed.
SCA 수정 가능성
computed_fixability
취약점 조치 경로를 기반으로 문제를 수정할 수 있는지 여부를 나타냅니다.
fixed_in_available
해당 취약점이 원인 소스의 다른 버전에서 수정되었는지 여부를 나타냅니다.
fixed_in_version
해당 취약점이 수정된 첫 번째 버전입니다.
exists_in_direct_dependency
취약점이 직접 종속성(Direct Dependency)에 존재하는지 여부를 나타냅니다. false인 경우 취약점은 전이적 종속성(Transitive Dependency)에만 존재합니다.
Snyk 계층 구조
group_public_id
레코드의 소스 데이터베이스에서 할당된 그룹의 범용 고유 식별자(UUID)입니다.
org_public_id
레코드의 소스 데이터베이스에서 할당된 조직의 범용 고유 식별자(UUID)입니다.
group_display_name
이 그룹에 설정된 표시 이름입니다.
group_slug
Snyk 내에서의 그룹 이름입니다.
org_display_name
이 조직에 설정된 표시 이름입니다.
org_slug
Snyk 내에서의 조직 이름입니다.
문제 컨텍스트 (Issue context)
problem_id
취약점을 고유하게 식별하는 Snyk 취약점 데이터베이스 ID입니다.
product_name
문제를 처음 식별한 Snyk 제품입니다.
problem_title
Snyk에서 발견한 취약점의 이름입니다.
vuln_db_url
Snyk 취약점 데이터베이스로 연결되는 URL입니다.
issue_type
문제가 취약점, 라이선스 또는 구성과 관련이 있는지 여부를 나타냅니다.
issue_sub_type
문제 유형의 더 세분화된 변형입니다.
issue_url
Snyk 웹사이트에서 이 취약점의 특정 프로젝트 인스턴스로 연결되는 URL입니다.
issue_status
문제가 열려 있는지(open), 해결되었는지(resolved) 또는 무시되었는지(ignored)를 나타냅니다.
issue_severity
평가된 위험 수준(critical, high, medium, low)을 나타냅니다.
commit_id
고유하게 식별될 수 있는 ID입니다. Snyk은 Snyk Code 문제에 대해서만 커밋 ID를 제공합니다.
file_path
Snyk Code가 특정 문제를 식별한 파일 경로입니다.
code_region
파일 내에서 문제가 발견된 행 번호 및 열 범위입니다.
code_region_display_value
파일 내에서 문제가 발견된 행 번호 및 열 범위의 표시 형태입니다.
asset_finding_id
리포지토리 수준의 고유한 문제 ID이며, Snyk Code 문제에만 적용됩니다.
cve
CVE ID 목록입니다.
cwe
CWE ID 목록입니다.
introduction_category
취약점이 도입된 방식의 카테고리입니다.
vulnerability_publication_date
취약점이 공개된 날짜입니다.
package_name_and_version
해당 취약점이 있는 패키지의 이름과 버전입니다.
fixed_in_version
해당 취약점이 수정된 패키지 버전입니다.
semver_vulnerable_range
취약한 것으로 간주되는 버전 범위(SemVer 형식)입니다.
first_introduced
문제가 처음 발견된 날짜입니다.
last_introduced
문제가 마지막으로 발견된 날짜입니다.
last_ignored
문제가 마지막으로 무시된 날짜입니다.
last_resolved
문제가 해결된 날짜입니다.
issue_deleted_at
문제가 삭제된 날짜와 시간입니다.
updated_at
데이터 세트의 속성에 영향을 준 마지막 업데이트 날짜와 시간입니다.
프로젝트 및 대상 컨텍스트 (Project and Target context)
project_public_id
레코드 또는 소스 데이터베이스에서 할당된 프로젝트의 범용 고유 식별자(UUID)입니다.
project_name
Snyk에 추가될 때 이 프로젝트에 부여된 이름입니다.
project_url
Snyk 플랫폼의 프로젝트 URL입니다.
project_is_monitored
프로젝트가 활발하게 모니터링되도록 설정되었는지 여부입니다. 기본적으로 API는 모니터링되는 프로젝트의 문제만 반환합니다. 비활성화된 프로젝트의 문제를 가져오려면 API 매개변수를 확인하십시오.
project_type
Snyk Code를 사용한 스캔의 경우 SAST(Static Application Security Testing), Snyk Open Source를 사용한 Maven 프로젝트의 경우 Maven 등 특정 프로젝트에 사용할 스캔 방법입니다. 이는 스캔 구성의 일부입니다.
project_type_display_name
Snyk 내부 프로젝트 유형 값에 할당된 표시 이름입니다.
project_test_frequency
특정 프로젝트의 테스트 빈도(예: Daily, Weekly 등)입니다.
project_origin
CLI, GitHub, 또는 Kubernetes와 같이 대상 생태계를 정의합니다. Origin은 대상의 속성입니다.
project_target_ref
이 프로젝트를 차별화하는 참조(예: 브랜치 이름 또는 버전)입니다. 동일한 참조를 가진 프로젝트는 해당 참조를 기준으로 그룹화할 수 있습니다.
project_target_runtime
대상이 실행되고 작동하는 환경입니다.
project_target_display_name
프로젝트 대상의 표시 이름입니다.
project_is_private_target
대상의 소스가 비공개인지 또는 공개적으로 접근 가능한지 여부를 나타냅니다.
project_target_source_type
대상의 소스 유형입니다.
project_target_source_type_display_value
대상의 소스 유형 표시 값입니다.
project_target_upstream_url
대상의 업스트림 URL입니다.
project_target_file
프로젝트의 대상 파일입니다.
project_owner_username
프로젝트 소유자의 사용자 이름입니다.
project_owner_email
프로젝트 소유자의 이메일입니다.
project_collections
프로젝트가 속한 컬렉션 목록입니다.
project_deleted_at
프로젝트가 삭제된 날짜와 시간입니다.
group_deleted_at
그룹이 삭제된 날짜와 시간입니다.
자산 및 애플리케이션 컨텍스트 (Assets and application context)
asset_id
자산 ID입니다.
parent_asset_id
상위 자산 ID입니다.
asset_name
자산의 표시 이름입니다.
parent_asset_name
상위 자산의 표시 이름입니다.
asset_class
고객이 구성한 자산의 비즈니스 중요도(A: 가장 중요함 ~ D: 가장 낮음)입니다.
asset_type
자산의 특정 유형(Repository, Package, Container Image, Image Package, 또는 Scanned Artifact)입니다.
asset_tags
가져온 데이터 또는 사용자 입력을 기반으로 자산에 할당된 태그 배열입니다.
repository_freshness
마지막 커밋 날짜를 기반으로 한 리포지토리 활성 상태입니다.
asset_application
자산과 관련된 애플리케이션 또는 서비스입니다.
asset_owner
자산의 코드 소유자(일반적으로 개발팀)입니다.
asset_category
Backstage 및 Roadie와 같이 통합된 개발 플랫폼에서의 카테고리입니다.
asset_catalog_name
애플리케이션 컨텍스트(ServiceNow, DataDog 등)에 언급된 카탈로그 이름입니다.
asset_lifecycle
자산의 수명 주기 상태입니다.
사용(Usage) 이벤트 데이터 세트 열
사용 가능한 열
상호 작용 컨텍스트
id
상호 작용 이벤트의 고유 식별자입니다.
product_display_name
이 상호 작용 중에 사용된 Snyk 제품(예: Snyk Open Source, Snyk IaC, Snyk Code, Snyk Container)입니다.
interaction_type
상호 작용 유형입니다. "Scan done"일 수 있으며, 이는 CLI 또는 IDE에서 실행 여부에 관계없이 테스트가 수행되었음을 나타냅니다. 다른 유형은 자유롭게 선택할 수 있는 유형입니다.
interaction_categories
상호 작용을 상세하게 설명하는 데 사용되는 카테고리 벡터(예: "oss", "test")입니다.
interaction_timestamp
상호 작용이 시작된 UTC 시간입니다.
interaction_status
상태는 "success" 또는 "failure"일 수 있습니다. success는 작업이 실행되었음을 의미하고, failure는 실행되지 않았음을 의미합니다.
interaction_stage
상호 작용이 발생한 SDLC 단계(예: "dev" | "cicd" | "prchecks" | "unknown")입니다.
interaction_exit_code
실행 중인 프로세스에서 반환한 상호 작용의 종료 코드입니다. 종료 코드와 그 의미에 대한 자세한 정보는 지정된 상호 작용(test, monitor 등)별 Snyk 문서에서 확인할 수 있습니다.
interaction_target_id
purl은 7개의 구성 요소(scheme:type/namespace/name@version?qualifiers#subpath)로 구성된 URL입니다. purl 사양은 여기서 확인할 수 있습니다: https://github.com/package-url/purl-spec 몇 가지 purl 예시: pkg:github/package-url/purl-spec@244fd47e07d1004f0aed9c pkg:npm/%40angular/[email protected] pkg:pypi/[email protected]
updated_at
상호 작용 이벤트 또는 관련 컨텍스트가 마지막으로 업데이트된 시간입니다.
런타임 컨텍스트
runtime_application_name
Snyk 상호 작용을 실행하는 데 사용된 애플리케이션(예: PyCharm, Visual Studio, snyk-ls, snyk-cli)입니다.
runtime_application_version
통합(Integration) 버전입니다.
runtime_application_data_schema_version
Snyk 런타임 상호 작용의 데이터 스키마 버전입니다. 현재 버전(v2)은 2024년 2분기에 출시되었습니다. 이전 버전의 데이터는 다르게 작동할 수 있습니다.
runtime_platform_os
통합을 위한 운영 체제(darwin, windows, linux 등)입니다.
runtime_platform_arch
통합을 위한 아키텍처(AMD64, ARM64, 386, ALPINE)입니다.
runtime_environment_name
통합을 위한 환경(예: IntelliJ Ultimate, Pycharm)입니다.
environment_display_name
이 상호 작용 중에 사용된 환경(예: CLI, Eclipse, Jetbrains IDE, Visual Studio, Visual Studio Code 등)입니다.
runtime_environment_version
통합 환경 버전(예: 2023.3)입니다.
runtime_integration_name
통합 이름이며, 플러그인 또는 확장 프로그램일 수 있습니다.
runtime_integration_version
통합 버전(예: 2.3.4)입니다.
runtime_performance_duration_ms
상호 작용 지속 시간(밀리초)입니다.
Snyk 계층 구조
group_public_id
레코드의 소스 데이터베이스에서 할당된 그룹의 범용 고유 식별자(UUID)입니다.
org_public_id
레코드의 소스 데이터베이스에서 할당된 조직의 범용 고유 식별자(UUID)입니다.
group_display_name
이 그룹에 설정된 표시 이름입니다.
group_slug
Snyk 내에서의 그룹 이름입니다.
org_display_name
이 조직에 설정된 표시 이름입니다.
org_slug
Snyk 내에서의 조직 이름입니다.
user_email
상호 작용 중에 인증된 사용자의 이메일입니다.
user_name
상호 작용 중에 인증된 사용자의 이름입니다.
Last updated