API 디스커버리

Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

API 디스커버리는 애플리케이션을 분석하고 노출하는 웹 API를 설명하는 OpenAPI 문서를 생성합니다. 그런 다음, 해당 스키마 문서는 API 보안 테스트 분석기 또는 API 퍼징에서 웹 API의 보안 스캔을 수행하는 데 사용할 수 있습니다.

지원되는 프레임워크

Java Spring-Boot

API 디스커버리 실행 시점

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

API 디스커버리는 기본적으로 test 단계에서 실행됩니다. 다른 API 보안 기능(예: DAST API 및 API 퍼징)에서 사용하는 단계보다 일반적으로 먼저 실행되는 test 단계가 선택되었습니다.

API 디스커버리 구성 예

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

예시 Java Spring Boot v2 Pet Store

Java Spring-Boot

Spring Boot은 스프링을 기반으로 하는 독립적인, 제품 수준의 애플리케이션을 만드는 데 사용되는 인기 있는 프레임워크입니다.

지원되는 애플리케이션

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

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

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

API 디스커버리는 Java 런타임의 LTS 버전과 공식적으로 호환됩니다. 다른 버전도 작동할 수 있으며, LTS 버전이 아닌 버전에서의 버그 보고는 환영합니다.

Spring Boot 실행 가능한 JAR 파일로 빌드된 애플리케이션만 지원됩니다.

파이프라인 작업으로 구성

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

이미지 요구 사항을 충족하는 컨테이너 이미지를 컨테이너 레지스트리에 업로드합니다. 컨테이너 레지스트리가 인증을 필요로 하는 경우에는 이 도움말 섹션을 참조하세요.
build 단계의 작업에서 애플리케이션을 빌드하고, 그 결과로 나온 Spring Boot 실행 가능 JAR 파일을 작업 artifact로 구성합니다.
.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
```
기본 단계를 test에서 다른 값으로 변경할 수 있는 선택 사항으로 .api_discovery_java_spring_boot를 확장한 새로운 작업을 만듭니다.
```
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 컨테이너에는 필요한 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이라는 작업 artifact로 이용할 수 있습니다.

이미지 요구 사항

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

사용 가능한 CI/CD 변수

CI/CD 변수	설명
`API_DISCOVERY_DISABLED`	템플릿 작업 규칙을 사용할 때 API 디스커버리 작업을 비활성화합니다.
`API_DISCOVERY_DISABLED_FOR_DEFAULT_BRANCH`	템플릿 작업 규칙을 사용할 때 기본 브랜치 파이프라인의 API 디스커버리 작업을 비활성화합니다.
`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를 호출하기 위한 토큰입니다. `API_DISCOVERY_PACKAGES`가 비공개 프로젝트로 설정된 경우에만 필요합니다.
`API_DISCOVERY_VERSION`	사용할 API 디스커버리 버전(기본값은 `1`)입니다. 전체 버전 번호 `1.1.0`를 제공하여 버전을 고정하는 데 사용할 수 있습니다.

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

특정 문제에 대한 지원을 받으려면 도움을 받을 수 있는 채널을 사용하세요.

GitLab.com의 GitLab 이슈 트래커는 API 디스커버리에 대한 버그 및 기능 제안에 대한 올바른 위치입니다. 새로운 API 디스커버리에 관한 이슈를 여는 경우 ~"Category:API Security" label를 사용하여 올바른 담당자가 빠르게 검토하도록 해야 합니다. 답변 SLO(SLO)를 확인하여 언제 답변을 받아야 하는지 이해하십시오.

자신의 제안 또는 문제를 제출하기 전에 유사한 항목을 찾아보세요. 다른 사람도 같은 문제 또는 기능 제안을 한 경우가 많을 것입니다. 이에 대한 지원을 표현하거나 토론에 참여하세요.

예상대로 작동하지 않는 동작을 경험하는 경우, 맥락적인 정보를 제공하는 것이 좋습니다:

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

경고: 지원 이슈에 첨부된 데이터를 살펴보세요. 자격 증명, 비밀번호, 토큰, 키 및 비밀 정보 등을 제거하세요.

API 디스커버리

지원되는 프레임워크

API 디스커버리 실행 시점

API 디스커버리 구성 예

Java Spring-Boot

지원되는 애플리케이션

파이프라인 작업으로 구성

이미지 요구 사항

사용 가능한 CI/CD 변수

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

도움말

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

도움받기