의존성 방화벽 API
GitLab v19.6Offering: GitLab.com, GitLab Self-Managed
요약
이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 의존성 방화벽은 베타 단계입니다. 의존성 방화벽은 베타 기간에는 무료입니다. 이 API를 사용해 프로젝트의 의존성 방화벽을 다룰 수 있습니다. 지정한 프로젝트의 의존성 방화벽 상태를 조회합니다.
히스토리
- GitLab 19.4에서
dependency_firewall_phase1이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다. - GitLab 19.5에서 베타로 변경되었습니다.
- GitLab 19.6에서 기능 플래그
dependency_firewall_phase1이dependency_firewall_access로 대체되었습니다.
이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 기록을 참고합니다.
의존성 방화벽은 베타 단계입니다. 정책 스키마와 지원되는 에코시스템은 릴리스 사이에 변경될 수 있습니다.
의존성 방화벽은 베타 기간에는 무료입니다. 이후 GitLab 크레딧으로 과금되는 유료 기능이 될 예정입니다. 비용이 청구되기 전에 사용자가 옵트인해야 하며, GitLab이 먼저 사전에 안내합니다.
이 API를 사용해 프로젝트의 의존성 방화벽을 다룰 수 있습니다. 의존성 방화벽은 프로젝트의 보안 정책을 충족하지 않는 패키지를 가져오기 전에 차단합니다.
프로젝트의 의존성 방화벽 상태 조회#
지정한 프로젝트의 의존성 방화벽 상태를 조회합니다. 이 엔드포인트를 사용해
실행 전체에서 방화벽을 건너뛸지 판단합니다. 방화벽이 꺼져 있는 프로젝트는 404 Not Found가 아니라
성공 응답을 반환하므로, 액세스할 수 없는 프로젝트와 구분할 수 있습니다.
이 엔드포인트는 개인 액세스 토큰, 프로젝트 액세스 토큰, 그룹 액세스 토큰, OAuth 토큰 또는 CI/CD job 토큰을 허용합니다. 배포 토큰은 지원되지 않습니다. 공개 프로젝트를 포함해 인증되지 않은 요청은 거부됩니다.
CI/CD job 토큰에는 특정 세분화된 권한이 필요하지 않습니다. 제약은 job이 실행되는 프로젝트에서 나옵니다.
job 토큰은 해당 프로젝트만 확인할 수 있습니다. 다른 프로젝트에 대한 요청은, 대상 프로젝트의
인바운드 job 토큰 허용 목록에 job의 프로젝트가 있더라도,
그리고 해당 허용 목록 항목에 어떤 세분화된 권한이 부여되어 있든 상관없이 403 Forbidden으로 거부됩니다.
한 프로젝트의 방화벽 상태는 다른 프로젝트의 파이프라인이 알아야 할 정보가 아닙니다.
사전 요구 사항:
- 프로젝트를 읽을 수 있는 권한이 있어야 합니다.
GET /projects/:id/dependency_firewall/enablement
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | 예 | 프로젝트의 ID 또는 URL 인코딩된 경로입니다. |
성공하면 200 OK와 다음 응답 속성을 반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
enabled |
boolean | 프로젝트에서 의존성 방화벽이 활성화되어 있는지 여부입니다. 하나로 합쳐진 답이므로, 라이선스와 네임스페이스 설정 중 무엇이 이 값을 만들었는지는 응답에 나타나지 않습니다. |
가능한 응답 코드:
| 상태 코드 | 설명 |
|---|---|
401 |
인증되지 않았습니다. 요청에 유효한 인증이 포함되어 있지 않았습니다. |
403 |
금지되었습니다. 이 엔드포인트를 사용할 수 없는 자격 증명입니다. job이 실행되는 프로젝트가 아닌 다른 프로젝트에 대한 CI/CD job 토큰이거나, 프로젝트를 읽을 권한이 없는 세분화된 토큰입니다. 프로젝트를 읽을 수 없는 사용자는 대신 404를 받습니다. |
404 |
찾을 수 없습니다. 의미는 응답 본문이 enabled, message, error 중 어느 키를 사용하는지에 따라 달라집니다. 이 표 뒤의 안내를 참고합니다. |
429 |
요청이 너무 많습니다. 이 엔드포인트의 속도 제한을 초과했습니다. 이 제한은 호출하는 사용자 단위이며, 다른 프로젝트 엔드포인트의 제한과는 별개입니다. |
기능 플래그가 꺼져 있는 동안에는 엔드포인트가 아직 일반 공급되지 않았으므로 200이 아니라 404를 반환합니다.
따라서 404 응답은 세 가지 중 하나를 뜻하며, 클라이언트는 문구가 아니라 응답 본문이 사용하는
키로 이를 구분합니다.
{"enabled": false}처럼enabled키가 있는 본문은 이 프로젝트에서 기능 플래그가 꺼져 있다는 뜻입니다. 방화벽이 활성 상태가 아니므로 클라이언트는 이번 실행에서 방화벽을 건너뛸 수 있습니다.{"error":"404 Not Found"}처럼error키가 있는 본문은 이 엔드포인트가 인스턴스에 없다는 뜻입니다. 예를 들어 인스턴스가 GitLab Community Edition이거나 이 엔드포인트가 추가되기 전에 릴리스된 버전일 수 있습니다. 클라이언트는 구성 문제를 보고하지 말고 이전 동작으로 되돌아가야 합니다.message키가 있는 본문은 엔드포인트가 존재하며 요청을 거부했다는 뜻입니다. 프로젝트가 없거나 읽을 수 없는 경우입니다. 클라이언트는 구성 문제를 보고해야 하며 해당 프로젝트를 보호되지 않는 것으로 취급해서는 안 됩니다.
이 판단을 메시지 문구에 의존하지 않습니다. 프로젝트를 읽을 수 없는 호출자는
{"message":"404 Project Not Found"}를 받지만, 프로젝트에 액세스할 수 없는 세분화된 토큰은
{"message":"404 Not Found"}를 받으며, 문구만 비교하면 이는 엔드포인트가 없는 경우와 똑같이 읽힙니다.
요청 예시:
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/enablement"
응답 예시:
{
"enabled": true
}
파이프라인 job에서 인증하려면 JOB-TOKEN 헤더와 함께 CI/CD job 토큰을
사용합니다.
curl --request GET \
--header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
--url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/enablement"
프로젝트의 의존성 방화벽 정책에 대해 패키지 평가#
지정한 프로젝트의 의존성 방화벽 정책에 대해 단일 패키지를 평가합니다.
이 엔드포인트는 개인 액세스 토큰, 프로젝트 액세스 토큰, 그룹 액세스 토큰,
OAuth 토큰 또는 CI/CD job 토큰을 허용합니다. job 토큰은 job이 실행되는
프로젝트의 패키지만 평가할 수 있습니다. 다른 프로젝트의 job 토큰은, 대상 프로젝트의
인바운드 job 토큰 허용 목록에 job의 프로젝트가 있더라도
403 Forbidden 상태 코드로 거부됩니다. 배포 토큰은 지원되지 않습니다.
사전 요구 사항:
- 프로젝트에 대해 Reporter 권한 이상이 있어야 합니다. 패키지 레지스트리가 켜져 있지 않아도 됩니다. 의존성 방화벽은 업스트림 레지스트리에서 가져오는 의존성을 평가하므로, 평가 권한은 프로젝트의 패키지 레지스트리 설정과 별개입니다.
POST /projects/:id/dependency_firewall/evaluate
지원되는 속성:
| 속성 | 유형 | 필수 | 설명 |
|---|---|---|---|
id |
integer or string | 예 | 프로젝트의 ID 또는 URL 인코딩된 경로입니다. |
ecosystem |
string | 예 | 패키지 에코시스템입니다. cargo, composer, conan, gem, golang, maven, npm, nuget, pub, pypi, swift 중 하나입니다. |
name |
string | 예 | 패키지 이름이며 최대 255자입니다. maven에서는 groupId:artifactId 형식을 사용합니다(예: com.example:trivial-lib). pypi에서는 평가 전에 이름이 PEP 503에 따라 정규화되므로 Flask_Login과 flask-login은 동일합니다. |
version |
string | 예 | 패키지 버전이며 최대 255자입니다. |
operation |
string | 아니요 | 평가할 패키지 작업입니다. download 또는 upload 중 하나입니다. 기본값은 download입니다. |
요청 헤더:
X-Gitlab-Dependency-Firewall-Session-Id: 선택 사항입니다. 패키지 관리자를 한 번 호출할 때 발생하는 모든 평가를 묶으므로, 패키지마다 평가 하나를 트리거하는 단일 설치 명령을 이 값으로 연관 지을 수 있습니다. GitLab은 이 값을 해당 평가의 감사 이벤트와 분석 이벤트에 기록하며, 검증하지 않고 불투명한 값으로 취급합니다.
값은 1~255자여야 하며 문자, 숫자, 밑줄, 하이픈만 포함할 수 있습니다. 값이 이 제약 조건을 충족하지 않으면 GitLab은 이를 무시하고 헤더를 보내지 않은 것처럼 평가를 진행합니다. 요청은 실패하지 않습니다.
성공하면 200 OK와 다음 응답
속성을 반환합니다.
| 속성 | 유형 | 설명 |
|---|---|---|
outcome |
string | 평가 결과입니다. allowed, warned, blocked 중 하나입니다. |
reason |
string | 패키지가 경고되거나 차단된 이유를 설명하는 메시지입니다. 일치한 정책의 이름을 나타냅니다. outcome이 allowed이면 null입니다. |
outcome 속성은 다음 값 중 하나입니다.
allowed: 패키지와 일치하는 정책 규칙이 없습니다. 의존성 방화벽이 활성화되어 있지만 연결된 정책이 없는 프로젝트는 항상allowed를 반환합니다.allowed결과는 GitLab이 해당 패키지의 취약점 또는 라이선스 데이터를 보유하고 있다는 보증이 아닙니다. 패키지 메타데이터 데이터베이스에 없는 패키지도 허용됩니다.warned: 정책 규칙이 패키지와 일치했고, 일치한 정책이 경고 모드입니다.blocked: 정책 규칙이 패키지와 일치했고, 일치한 정책이 적용(enforce) 모드입니다.
이 엔드포인트는 다음 상태 코드도 반환할 수 있습니다.
| 상태 코드 | 코드 | 설명 |
|---|---|---|
400 |
None | name 또는 version이 비어 있거나, ecosystem 또는 operation이 허용되는 값 중 하나가 아닙니다. |
401 |
None | 요청이 인증되지 않았습니다. |
403 |
None | 인증된 사용자에게 프로젝트에 대한 Reporter 권한 이상이 없거나, 요청이 job이 실행되는 프로젝트가 아닌 다른 프로젝트의 CI/CD job 토큰을 사용했습니다. |
404 |
None | 프로젝트가 없거나, 인증된 사용자가 프로젝트에 액세스할 수 없거나, dependency_firewall_access 기능 플래그가 비활성화되어 있습니다. |
422 |
dependency_firewall_not_enforced |
프로젝트에서 의존성 방화벽이 활성화되어 있지 않습니다. |
429 |
None | 이 엔드포인트의 속도 제한을 초과했습니다. 제한은 프로젝트와 사용자의 조합 단위입니다. |
503 |
dependency_firewall_evaluation_failed |
패키지 메타데이터 조회가 완료되지 않았습니다. 가져오기를 차단합니다. |
요청 예시:
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/evaluate" \
--data '{"ecosystem": "npm", "name": "lodash", "version": "4.17.15"}'
응답 예시:
{
"outcome": "blocked",
"reason": "Package 'lodash' violates 'deny-mit' policy"
}
의존성 방화벽이 활성화되어 있지만 연결된 정책이 없는 프로젝트의 응답 예시:
{
"outcome": "allowed",
"reason": null
}
파이프라인 job에서는 CI/CD job 토큰으로 인증합니다.
curl --request POST \
--header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
--header "Content-Type: application/json" \
--url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/evaluate" \
--data '{"ecosystem": "npm", "name": "lodash", "version": "4.17.15"}'