• 지원되는 프레임워크
• API Discovery 실행 시기
• API Discovery 구성 예시
• Java Spring-Boot
  • 지원되는 애플리케이션
  • 파이프라인 작업으로 구성
    • 이미지 요구 사항
• 지원 받거나 개선을 요청하세요

API Discovery

• GitLab 15.9에서 도입되었습니다. API Discovery 기능은 Beta 단계에 있습니다.

API Discovery는 애플리케이션을 분석하고 노출한 웹 API를 설명하는 OpenAPI 문서를 생성합니다. 이 스키마 문서는 나중에 DAST API 또는 API Fuzzing에서 사용하여 웹 API의 보안 스캔을 수행할 수 있습니다.

지원되는 프레임워크

• Java Spring-Boot

API Discovery 실행 시기

API Discovery는 파이프라인에서 독립적으로 실행됩니다. 생성된 OpenAPI 문서는 작업 artifact로 캡처되어 이후 단계에서 다른 작업에서 사용할 수 있습니다.

API Discovery는 기본적으로 test 단계에서 실행됩니다. test 단계는 일반적으로 DAST API 및 API Fuzzing과 같은 다른 API 보안 기능에서 사용하는 단계보다 먼저 실행되도록 선택되었습니다.

API Discovery 구성 예시

다음 프로젝트는 API Discovery를 보여줍니다:

• 예시 Java Spring Boot v2 Pet Store

Java Spring-Boot

Spring Boot은 스프링 기반의 독립적이고 프로덕션에 적합한 애플리케이션을 생성하기 위한 인기 있는 프레임워크입니다.

지원되는 애플리케이션

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

API Discovery는 Spring Boot 주 버전 2와 부 버전 1 이상을 지원합니다. 버전 2.0.X는 API Discovery에 영향을 미치는 알려진 버그로 인해 지원되지 않습니다. 이러한 버그는 2.1에서 수정되었습니다.

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

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

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

파이프라인 작업으로 구성

API Discovery를 실행하는 가장 쉬운 방법은 우리의 CI 템플릿을 기반으로 한 파이프라인 작업을 통해 실행하는 것입니다. 이 방법으로 실행할 때는 필요한 의존성이 설치된 컨테이너 이미지를 제공합니다(예: 적절한 Java 런타임). 더 많은 정보는 이미지 요구 사항을 참조하세요.

1. 이미지 요구 사항을 충족하는 컨테이너 이미지를 컨테이너 레지스트리에 업로드합니다. 컨테이너 레지스트리가 인증을 필요로 하는 경우 이 도움말 섹션을 확인하세요.
2. build 단계의 작업에서 애플리케이션을 빌드하고 결과로 나온 Spring Boot 실행 가능 JAR를 작업 artifact로 구성합니다.

3. .gitlab-ci.yml 파일에서 API Discovery 템플릿을 포함시킵니다.

    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
   

4. 기본 단계를 test에서 실행되도록 선택한 .api_discovery_java_spring_boot에서 확장하는 새 작업을 생성합니다. 이 단계는 선택적으로 다른 값으로 변경될 수 있습니다.

   api_discovery:
       extends: .api_discovery_java_spring_boot
   

5. 작업을 위해 image를 구성합니다.

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

6. 애플리케이션에서 필요한 Java 클래스 경로를 제공합니다. 이는 해당 예시에서 사용되는 호환성 빌드 artifact와 추가적인 의존성을 포함합니다. 이 예시에서 빌드 artifact는 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
   

7. 선택 사항. 제공된 이미지에 API Discovery에 필요한 누락된 의존성이 있는 경우, 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
   

8. 선택 사항. 제공된 이미지가 자동으로 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
   

9. 선택 사항. API_DISCOVERY_PACKAGES의 패키지 레지스트리가 공개되지 않은 경우, API_DISCOVERY_PACKAGE_TOKEN 변수를 사용하여 GitLab API 및 레지스트리에 대한 읽기 액세스를 제공하는 토큰을 제공합니다. 이는 API_DISCOVERY_PACKAGES를 사용자 정의하고 gitlab.com을 사용하고 있지 않은 경우에 필요하지 않습니다. 다음 예제는 토큰을 저장하기 위해 사용자 정의 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 Discovery 작업이 성공적으로 실행된 후, OpenAPI 문서는 gl-api-discovery-openapi.json이라는 작업 artifact로 사용할 수 있습니다.

이미지 요구 사항

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

지원 받거나 개선을 요청하세요

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

GitLab.com의 GitLab 이슈 트래커는 API Discovery에 관한 버그 및 기능 제안을 위한 적절한 장소입니다. API Discovery에 관한 새 이슈를 오픈할 때 ~"Category:API Security" 레이블을 사용하여 적절한 사람들에 의해 신속하게 검토되도록 해주세요. 응답이 올바른 시기에 이루어지는지 확인하려면 리뷰 응답 SLO를 참조하세요.

본인의 것이 아닌 이슈 또는 기능 제안을 제출하기 전에 이슈 트래커에서 유사한 항목을 검색하여 다른 사람이 동일한 문제나 기능 제안을 한 경우가 있는지 확인하세요. 이슈에 대한 지지 표시 또는 토론에 참여하여 지지를 표현하세요.

예상과 다르게 작동하는 동작을 경험할 때는 관련 정보를 제공하는 것이 좋습니다:

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