• 지원하는 프레임워크
• API 발견은 언제 실행되나요?
• API 발견 구성 예제
• Java Spring-Boot
  • 지원되는 애플리케이션
  • 파이프라인 작업으로 구성
    • 이미지 요구 사항
  • 사용 가능한 CI/CD 변수
• 지원 요청 또는 개선 요청

API 발견

• GitLab 15.9에서 도입됨. API 발견 기능은 베타 상태입니다.

API 발견은 귀하의 애플리케이션을 분석하고 노출하는 웹 API를 설명하는 OpenAPI 문서를 생성합니다. 이 스키마 문서는 API 보안 테스트 분석기 또는 API 퍼징에 의해 웹 API의 보안 스캔을 수행하는 데 사용될 수 있습니다.

지원하는 프레임워크

• Java Spring-Boot

API 발견은 언제 실행되나요?

API 발견은 파이프라인에서 독립 실행형 작업으로 실행됩니다. 생성된 OpenAPI 문서는 작업 아티팩트로 캡처되어 나중 단계의 다른 작업에서 사용할 수 있습니다.

API 발견은 기본적으로 test 단계에서 실행됩니다. test 단계는 일반적으로 DAST API 및 API 퍼징과 같은 다른 API 보안 기능에서 사용하는 단계 이전에 실행되기 때문에 선택되었습니다.

API 발견 구성 예제

다음 프로젝트는 API 발견을 보여줍니다:

• 예제 Java Spring Boot v2 애완동물 가게

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 발견에 영향을 미치는 알려진 버그가 있어 지원되지 않으며 이는 2.1에서 수정되었습니다.

주요 버전 3은 향후 지원할 계획입니다. 주요 버전 1에 대한 지원은 계획되어 있지 않습니다.

API 발견은 Java 런타임의 LTS 버전에서 테스트되고 공식적으로 지원됩니다. 다른 버전도 작동할 수 있으며 비 LTS 버전에서의 버그 보고는 환영합니다.

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

파이프라인 작업으로 구성

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

1. 이미지 요구 사항에 부합하는 컨테이너 이미지가 컨테이너 레지스트리에 업로드됩니다. 컨테이너 레지스트리가 인증을 요구하는 경우 이 도움말 섹션을 참조하세요.
2. build 단계의 작업에서 애플리케이션을 빌드하고 생성된 Spring Boot 실행 가능한 JAR를 작업 아티팩트로 구성합니다.

3. .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  
   

4. .api_discovery_java_spring_boot에서 확장되는 새 작업을 생성합니다. 기본 단계는 test이며 필요에 따라 다른 값으로 변경할 수 있습니다.

   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 클래스 경로를 제공합니다. 여기에는 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  
   

7. 선택 사항. 제공된 이미지에 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  
   

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에서 패키지 레지스트리가 공용이 아닌 경우 GitLab API 및 레지스트리에 대한 읽기 권한이 있는 토큰을 API_DISCOVERY_PACKAGE_TOKEN 변수를 사용하여 제공합니다. 이는 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이라는 작업 아티팩트로 사용 가능합니다.

이미지 요구 사항

• 리눅스 컨테이너 이미지.
• 자바 버전 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 애플리케이션을 포함한 자바 클래스 경로입니다. (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을 제공하여 버전을 고정할 수 있습니다.

지원 요청 또는 개선 요청

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

API Discovery에 대한 버그 및 기능 제안은 GitLab.com의 GitLab 이슈 트래커가 적합한 장소입니다. 새로운 API Discovery 관련 이슈를 열 때는 ~"Category:API Security" 라벨을 사용하여 적절한 사람들이 빠르게 검토할 수 있도록 하세요. 검토 응답 SLO를 참조하여 응답을 받을 시기를 이해하세요.

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

예상대로 작동하지 않는 행동을 경험할 때는 다음과 같은 맥락 정보를 제공하는 것을 고려하세요:

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

경고: 지원 이슈에 첨부된 데이터는 정화하십시오. 자격 증명, 비밀번호, 토큰, 키 및 비밀 정보를 포함한 민감한 정보를 삭제하세요.