API Discovery는 애플리케이션을 분석하여 노출하는 웹 API를 설명하는 OpenAPI 문서를 생성합니다. 이 스키마 문서는 API 보안 테스팅 분석기 또는 API 퍼징이 웹 API의 보안 스캔을 수행하는 데 사용할 수 있습니다.

지원되는 프레임워크#

• Java Spring-Boot

API Discovery는 언제 실행되나요?#

API Discovery는 파이프라인에서 독립적인 job으로 실행됩니다. 결과 OpenAPI 문서는 이후 단계의 다른 job에서 사용할 수 있도록 job 아티팩트로 캡처됩니다.

API Discovery는 기본적으로 test 단계에서 실행됩니다. test 단계는 API 보안 테스팅 및 API 퍼징과 같은 다른 보안 기능에서 사용하는 단계보다 일반적으로 먼저 실행되기 때문에 선택되었습니다.

API Discovery 구성 예시#

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

• Java Spring Boot v2 Pet Store 예시

Java Spring-Boot#

Spring Boot는 독립형 프로덕션 급 Spring 기반 애플리케이션을 만들기 위한 인기 있는 프레임워크입니다.

지원되는 애플리케이션#

• 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 실행 가능한 JAR으로 빌드된 애플리케이션만 지원됩니다.

파이프라인 job으로 구성#

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

1. 이미지 요구 사항을 충족하는 컨테이너 이미지가 컨테이너 레지스트리에 업로드됩니다. 컨테이너 레지스트리에 인증이 필요한 경우 이 도움말 섹션을 참조하세요.

2. build 단계의 job에서 애플리케이션을 빌드하고 결과 Spring Boot 실행 가능 JAR을 job 아티팩트로 구성합니다.

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. .api_discovery_java_spring_boot에서 확장하는 새 job을 만듭니다. 기본 단계는 test이며 선택적으로 다른 값으로 변경할 수 있습니다.

   api_discovery:
       extends: .api_discovery_java_spring_boot
   

5. job의 image를 구성합니다.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
   

6. 애플리케이션에 필요한 Java 클래스 경로를 제공합니다. 여기에는 2단계의 호환 가능한 빌드 아티팩트와 추가 종속성이 포함됩니다. 이 예시에서 빌드 아티팩트는 build/libs/spring-boot-app-0.0.0.jar이며 필요한 모든 종속성이 포함되어 있습니다. API_DISCOVERY_JAVA_CLASSPATH 변수를 사용하여 클래스 경로를 제공합니다.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
   

7. 선택 사항. 제공된 이미지에 API Discovery에 필요한 종속성이 없는 경우 before_script를 사용하여 추가할 수 있습니다. 이 예시에서 eclipse-temurin:17-jre-alpine 컨테이너에는 API Discovery에 필요한 curl이 포함되어 있지 않습니다. Debian 패키지 관리자 apt를 사용하여 종속성을 설치할 수 있습니다:

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       variables:
           API_DISCOVERY_JAVA_CLASSPATH: build/libs/spring-boot-app-0.0.0.jar
       before_script:
           - apk add --no-cache curl
   

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

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-jre-alpine
       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 및 레지스트리에 대한 읽기 접근 권한이 있는 토큰을 제공합니다. gitlab.com을 사용하고 API_DISCOVERY_PACKAGES 변수를 사용자 정의하지 않은 경우에는 필요하지 않습니다. 다음 예시에서는 토큰을 저장하기 위해 GITLAB_READ_TOKEN이라는 사용자 정의 CI/CD 변수를 사용합니다.

   api_discovery:
       extends: .api_discovery_java_spring_boot
       image: eclipse-temurin:17-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 job이 성공적으로 실행된 후 OpenAPI 문서는 gl-api-discovery-openapi.json이라는 job 아티팩트로 제공됩니다.

이미지 요구 사항#

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

사용 가능한 CI/CD 변수#

지원 받기 또는 개선 요청#

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

GitLab.com의 GitLab 이슈 트래커는 API Discovery에 대한 버그 및 기능 제안을 위한 적절한 장소입니다. API Discovery에 관한 새 이슈를 열 때 올바른 사람들이 신속하게 검토할 수 있도록 ~"Category:API Security" 레이블을 사용하세요.

본인의 이슈를 제출하기 전에 이슈 트래커를 검색하여 유사한 항목을 확인하세요. 다른 사람이 동일한 이슈나 기능 제안을 한 가능성이 높습니다. 이모지 반응으로 지지를 표시하거나 토론에 참여하세요.

예상대로 작동하지 않는 동작을 경험할 때 문맥 정보를 제공하는 것을 고려하세요:

• GitLab Self-Managed 인스턴스를 사용하는 경우 GitLab 버전.
• .gitlab-ci.yml job 정의.
• 전체 job 콘솔 출력.
• 버전과 함께 사용 중인 프레임워크 (예: "Spring Boot v2.3.2").
• 버전과 함께 언어 런타임 (예: "Eclipse Temurin v17.0.1").