API 디스커버리

Tier: Ultimate Offering: GitLab.com, 자체 관리, GitLab Dedicated

GitLab 15.9에서 도입되었습니다. API 디스커버리 기능은 베타 상태입니다.

API 디스커버리는 응용 프로그램을 분석하고 노출하는 웹 API를 설명하는 OpenAPI 문서를 작성합니다. 이 스키마 문서는 나중에 DAST API 또는 API Fuzzing에서 웹 API의 보안 스캔을 수행하는 데 사용할 수 있습니다.

지원되는 프레임워크

Java Spring-Boot

API 디스커버리 실행 시점

API 디스커버리는 파이프라인에서 독립적으로 실행되는 작업으로 실행됩니다. 결과 OpenAPI 문서는 작업 아티팩트로 캡처되어 나중 단계의 다른 작업에서 사용할 수 있습니다.

API 디스커버리는 기본적으로 test 단계에서 실행됩니다. 다른 API 보안 기능인 DAST API 및 API Fuzzing에서 사용하는 스테이지보다 일반적으로 먼저 실행되기 때문에 test 단계가 선택되었습니다.

API 디스커버리 구성 예시

다음 프로젝트는 API 디스커버리를 보여줍니다:

예시 Java Spring Boot v2 Pet Store

Java Spring-Boot

Spring Boot은 독립적이고 프로덕션 등급의 Spring 기반 응용 프로그램을 만드는 데 사용되는 인기 있는 프레임워크입니다.

지원되는 응용 프로그램

Spring Boot: v2.X (>= 2.1)
Java: 11, 17 (LTS 버전)
실행 가능 JAR

API 디스커버리는 Spring Boot 주 버전 2, 부 버전 1 이상을 지원합니다. 버전 2.0.X는 API 디스커버리에 영향을 미치는 알려진 버그로 인해 지원되지 않습니다.

주 버전 3은 향후 지원될 예정입니다. 주 버전 1의 지원은 계획되어 있지 않습니다.

API 디스커버리는 Java 런타임의 LTS 버전을 테스트하고 공식적으로 지원합니다. 다른 버전도 작동할 수 있으며, LTS 버전 이외의 버그 보고를 환영합니다.

Spring Boot 실행 가능 JARs로 빌드된 응용 프로그램만 지원됩니다.

파이프라인 작업으로 구성

API 디스커버리를 실행하는 가장 쉬운 방법은 CI 템플릿을 기반으로 한 파이프라인 작업을 통해 실행하는 것입니다. 이 방법으로 실행할 때, 필요한 종속성이 설치된 컨테이너 이미지(예: 적절한 Java 런타임)를 제공합니다. 자세한 내용은 이미지 요구 사항을 참조하세요.

이미지 요구 사항을 충족하는 컨테이너 이미지가 컨테이너 레지스트리에 업로드됩니다. 컨테이너 레지스트리가 인증을 필요로 하는 경우 이 도움말 섹션을 참조하세요.
build 단계의 작업에서 응용 프로그램을 빌드하고 결과 Spring Boot 실행 가능 JAR를 작업 아티팩트로 구성합니다.
.gitlab-ci.yml 파일에서 API 디스커버리 템플릿을 포함합니다.
```
 include:
    - template: Security/API-Discovery.gitlab-ci.yml
```
.gitlab-ci.yml 파일 당 하나의 include 문만 허용됩니다. 다른 파일을 포함하는 경우 하나의 include 문으로 병합합니다.
```
 include:
    - template: Security/API-Discovery.gitlab-ci.yml
    - template: Security/DAST-API.gitlab-ci.yml
```
.api_discovery_java_spring_boot에서 확장하는 새로운 작업을 만듭니다. 기본으로 test 스테이지가 선택되어 있으며, 선택적으로 다른 값으로 변경할 수 있습니다.
```
api_discovery:
    extends: .api_discovery_java_spring_boot
```

작업에 대한 image를 구성합니다.

api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim

응용 프로그램에서 필요한 Java 클래스 경로를 제공합니다. 이는 2단계에서 호환되는 빌드 아티팩트뿐만 아니라 추가 종속성을 포함합니다. 이 예에서 빌드 아티팩트는 build/libs/spring-boot-app-0.0.0.jar이며 모든 필요한 종속성을 포함합니다. 변수 API_DISCOVERY_JAVA_CLASSPATH을 사용하여 클래스 경로를 제공합니다.
```
api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
```
선택 사항. 제공된 이미지에 API 디스커버리에서 필요로 하는 종속성이 누락된 경우 before_script를 사용하여 추가할 수 있습니다. 이 예에서 openjdk:11-jre-slim 컨테이너에는 API 디스커버리에서 필요로 하는 curl이 포함되어 있지 않습니다. Debian 패키지 관리자 apt를 사용하여 종속성을 설치할 수 있습니다.
```
api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
    before_script:
        - apt-get update && apt-get install -y curl
```

선택 사항. 제공된 이미지가 자동으로 JAVA_HOME 환경 변수를 설정하지 않거나 경로에 java를 포함하지 않는 경우, API_DISCOVERY_JAVA_HOME 변수를 사용할 수 있습니다.

api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:11-jre-slim
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
        API_DISCOVERY_JAVA_HOME: /opt/java

선택 사항. API_DISCOVERY_PACKAGES의 패키지 레지스트리가 공개되지 않은 경우, API_DISCOVERY_PACKAGE_TOKEN 변수를 사용하여 GitLab API 및 레지스트리에 대한 읽기 액세스를 제공하는 토큰을 제공합니다. gitlab.com을 사용하고 API_DISCOVERY_PACKAGES 변수를 사용자 정의하지 않은 경우에는 이를 요구하지 않습니다. 다음 예에서는 토큰을 저장하기 위해 사용자 정의 CI/CD 변수인 GITLAB_READ_TOKEN을 사용합니다.
```
api_discovery:
    extends: .api_discovery_java_spring_boot
    image: openjdk:8-jre-alpine
    variables:
        API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
        API_DISCOVERY_PACKAGE_TOKEN: $GITLAB_READ_TOKEN
```

API 디스커버리 작업이 성공적으로 실행된 후, OpenAPI 문서는 gl-api-discovery-openapi.json이라는 작업 아티팩트로 사용할 수 있습니다.

이미지 요구 사항

Linux 컨테이너 이미지.
Java 버전 11 또는 17은 공식적으로 지원되지만, 다른 버전도 호환될 가능성이 높습니다.
curl 명령어.
/bin/sh에 셸이 있어야 합니다 (busybox, sh, 또는 bash와 같은).

사용 가능한 CI/CD 변수

CI/CD 변수	설명
`API_DISCOVERY_DISABLED`	템플릿 작업 규칙을 사용할 때 API Discovery 작업을 비활성화합니다.
`API_DISCOVERY_DISABLED_FOR_DEFAULT_BRANCH`	템플릿 작업 규칙을 사용하여 기본 브랜치 파이프라인에서 API Discovery 작업을 비활성화합니다.
`API_DISCOVERY_JAVA_CLASSPATH`	Spring Boot 애플리케이션을 포함하는 Java 클래스 경로입니다. (`build/libs/sample-0.0.0.jar`)
`API_DISCOVERY_JAVA_HOME`	제공된 경우 `JAVA_HOME`을 설정하는 데 사용됩니다.
`API_DISCOVERY_PACKAGES`	GitLab 프로젝트 패키지 API 접두어(기본값은 `$CI_API_V4_URL/projects/42503323/packages`).
`API_DISCOVERY_PACKAGE_TOKEN`	GitLab 패키지 API를 호출하는 데 필요한 GitLab 토큰입니다. `API_DISCOVERY_PACKAGES`가 비공개 프로젝트로 설정된 경우에만 필요합니다.
`API_DISCOVERY_VERSION`	사용할 API Discovery 버전(기본값은 `1`)입니다. `1.1.0`과 같은 전체 버전 번호를 제공하여 특정 버전을 설정하는 데 사용할 수 있습니다.

지원 받거나 개선 사항 요청하기

특정 문제에 대한 지원을 받으려면 도움 채널을 이용하십시오.

GitLab.com의 GitLab 이슈 트래커는 API Discovery에 대한 버그 및 기능 제안을 위한 적절한 장소입니다. API Discovery에 관한 새로운 이슈를 열 때는 ~"Category:API Security" 라벨을 사용하여 해당하는 사람들에 의해 신속하게 검토되도록 해야 합니다. 응답을 받아야 하는 시점을 이해하려면 리뷰 응답 SLO를 참조하십시오.

나의 문제 또는 기능 제안을 제출하기 전에 이슈 트래커를 검색하여 다른 유사한 항목을 찾아보세요. 다른 사람도 같은 문제나 기능 제안을 가질 수 있습니다. 이를 지원하는 이모지 반응이나 토론에 참여하세요.

예상치 못한 동작을 경험할 때, 컨텍스트 정보를 제공하는 것이 좋습니다:

자체 관리형 인스턴스를 사용하는 경우 GitLab 버전.
.gitlab-ci.yml 작업 정의.
전체 작업 콘솔 출력.
사용 중인 프레임워크와 버전 (예: Spring Boot v2.3.2).
언어 런타임과 버전 (예: OpenJDK v17.0.1).

경고: 지원이슈에 첨부된 데이터를 소독하세요. 자격 증명, 비밀번호, 토큰, 키 및 비밀 정보와 같은 민감한 정보를 제거하세요.

API 디스커버리

지원되는 프레임워크

API 디스커버리 실행 시점

API 디스커버리 구성 예시

Java Spring-Boot

지원되는 응용 프로그램

파이프라인 작업으로 구성

이미지 요구 사항

사용 가능한 CI/CD 변수

지원 받거나 개선 사항 요청하기

도움말

기능 사용 가능성과 제품 평가판

도움받기