DEV Community

Cover image for API 문서 보안: Git에서 안전한가?
Rihpig
Rihpig

Posted on • Originally published at apidog.com

API 문서 보안: Git에서 안전한가?

#api #git #github #security

API 문서 보안은 API 보안 점검에서 자주 빠지는 영역입니다. 인증, 속도 제한, 보안 테스트로 API 자체는 강화하지만, OpenAPI 스펙, Swagger UI 페이지, 인증 흐름을 설명하는 Markdown 문서 등은 Git 저장소나 정적 호스트에 올려둔 뒤 오래 방치되는 경우가 많습니다. 2026년 5월 20일, GitHub는 공격자들이 약 3,800개의 내부 코드 저장소에서 데이터를 훔쳐 갔음을 확인했습니다. 진입점은 GitHub 직원 노트북에 설치된 악성 VS Code 확장 프로그램이었습니다. 이 사건은 한 가지 질문을 던집니다. 누군가 여러분의 API 문서를 몰래 바꾼다면, 여러분과 API 소비자는 이를 알아차릴 수 있을까요?

오늘 Apidog를 사용해 보세요

요약

안전한 API 문서는 다음을 갖춰야 합니다.

  • 접근 제어
  • 버전 관리
  • 검증 가능한 무결성
  • 감사 추적

Git 기반 Docs-as-code는 리뷰와 변경 기록을 제공하므로 많은 팀에 적합합니다. 하지만 저장소가 공개되어 있거나, 정적 호스트에 접근 제어가 없거나, 오래된 스펙이 실제 API와 동기화되지 않거나, 변조된 예제가 소비자에게 그대로 전달되면 문제가 됩니다.

Apidog 같은 관리형 문서화 레이어는 비밀번호 보호, IP 및 이메일 허용 목록, 사용자 지정 도메인, 버전 관리, API 설계와 동기화되는 문서 생성을 제공해 이러한 간극을 줄일 수 있습니다.

GitHub 침해 사고가 API 문서 점검으로 이어져야 하는 이유

GitHub 사고의 핵심은 저장소 자체보다 “신뢰된 개발자 환경이 침해될 수 있다”는 점입니다. 위협 그룹 TeamPCP는 GitHub 내부 저장소를 유출했으며, 현재 이 데이터를 지하 포럼에서 5만 달러 이상에 판매하고 있습니다. BleepingComputer의 보도에 따르면 악성 VS Code 확장 프로그램은 공식 마켓플레이스에서 제공되었고 직원 기기에서 실행되었습니다. GitHub는 내부 저장소 외부에 저장된 고객 데이터가 영향을 받았다는 증거는 찾지 못했으며 조사가 진행 중이라고 밝혔습니다.

이 사건을 계기로 다음을 확인해야 합니다.

  1. API 문서가 어디에 저장되어 있는가?
  2. 누가 문서를 수정할 수 있는가?
  3. 게시된 문서가 검토된 소스와 일치하는가?
  4. 문서가 변조되면 누가 어떻게 감지하는가?
  5. 소비자가 문서에서 복사한 코드가 안전한가?

많은 팀은 몇 년 전 Swagger UI를 GitHub Pages에 배포하고 CNAME을 연결한 뒤 더 이상 검토하지 않습니다. 저장소는 공개되어 있고, OpenAPI 스펙은 마지막으로 병합된 상태 그대로이며, 문서 변경 사항은 애플리케이션 코드만큼 엄격하게 리뷰되지 않습니다.

하지만 API 문서는 단순한 설명이 아닙니다. 개발자는 문서에서 엔드포인트 경로, 요청 바디, 인증 헤더, 토큰 교환 URL, 예제 코드를 그대로 복사합니다. 공격자가 이 지침을 바꾸면, 마케팅 페이지를 훼손하는 것이 아니라 다른 개발자가 실행할 코드를 바꾸는 것입니다.

같은 논리는 다른 침해 사고에서도 반복됩니다. Vercel 침해 사고로부터 얻은 API 보안 교훈에서는 신뢰된 표면에서의 작은 변경이 외부 소비자에게 어떻게 전파되는지 다룹니다.

이 글에서는 다음을 구현 관점에서 정리합니다.

  • 손상된 API 문서가 소비자에게 피해를 주는 방식
  • Git 기반 Docs-as-code가 적합한 경우와 위험한 경우
  • “안전한 API 문서화” 체크리스트
  • Apidog 같은 관리형 문서화 레이어로 간극을 줄이는 방법

관련해서 더 깊게 보려면 GitHub 침해 사고가 자체 호스팅 API 도구에 미치는 영향과 VS Code 확장 프로그램 API 키 보안을 참고하십시오.

API 문서 저장소 또는 호스트가 침해되면 생기는 문제

API 문서는 보통 세 곳에 걸쳐 존재합니다.

  • Git 저장소
  • 문서를 빌드하는 CI 파이프라인
  • 문서를 제공하는 정적 호스트 또는 문서 플랫폼

이 중 하나라도 침해되면 API 소비자에게 직접적인 영향을 줄 수 있습니다.

1. 문서 변조가 프로덕션 코드에 들어감

가장 위험한 시나리오는 작은 문서 변경이 소비자의 프로덕션 코드로 복사되는 경우입니다.

예를 들어 공격자가 문서 저장소 또는 배포된 사이트에 쓰기 권한을 얻었다고 가정해 보겠습니다. 공격자는 다음과 같은 변경을 할 수 있습니다.

  • https://api.payments.acme.com/v2/charge를 공격자 도메인으로 변경
  • “시작하기” 페이지의 예제 Bearer 토큰을 공격자 프록시로 라우팅되는 값으로 변경
  • OAuth 토큰 교환 URL을 잘못된 도메인으로 변경
  • SDK 예제의 baseUrl만 교체

이 변경은 눈에 잘 띄지 않습니다. YAML은 여전히 유효하고, Swagger UI도 정상 렌더링되며, CI도 통과할 수 있습니다.

예를 들어 다음 OpenAPI 스펙이 있다고 가정합니다.

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created
Enter fullscreen mode Exit fullscreen mode

여기서 공격자가 servers.url만 바꾸면 어떻게 될까요?

servers:
  - url: https://api-acme-pay.example-attacker.com
Enter fullscreen mode Exit fullscreen mode

스펙에서 클라이언트를 자동 생성하는 소비자는 이제 카드 데이터나 결제 요청을 공격자 도메인으로 보낼 수 있습니다. 변경은 한 줄뿐이지만 영향은 큽니다.

실무에서는 OpenAPI 변경 리뷰에서 다음 항목을 반드시 확인해야 합니다.

 servers:
-  - url: https://api.acme-pay.com
+  - url: https://api-acme-pay.example-attacker.com
Enter fullscreen mode Exit fullscreen mode

문서 PR에서도 코드 PR과 동일하게 “보안상 민감한 필드”를 리뷰 대상으로 지정해야 합니다.

체크할 필드 예시는 다음과 같습니다.

  • servers.url
  • securitySchemes
  • OAuth authorizationUrl
  • OAuth tokenUrl
  • Webhook URL
  • Callback URL
  • 예제 API 키 또는 토큰
  • SDK 초기화 코드의 baseURL

2. 내부 및 문서화되지 않은 엔드포인트가 유출됨

문서 저장소에는 공개용 API만 있는 경우가 드뭅니다. 시간이 지나면서 다음 항목이 섞입니다.

  • 내부 관리자 API
  • 디버그 엔드포인트
  • 파트너 전용 API
  • 베타 기능
  • 삭제 예정 경로
  • 실제 운영 파라미터 예제

저장소가 공개되어 있거나 실수로 공개되면, 공격자는 스캔 없이도 정확한 공격 지도를 얻습니다.

비공개 저장소도 안전하다고 단정할 수 없습니다. GitHub 침해 사고처럼 저장소 자체가 유출되면 내부 API 스펙도 함께 노출됩니다. 공격자는 엔드포인트, 파라미터, 요청 바디, 인증 방식을 추측할 필요가 없습니다.

점검 방법은 단순합니다.

grep -R "internal" ./docs ./openapi
grep -R "admin" ./docs ./openapi
grep -R "debug" ./docs ./openapi
grep -R "localhost" ./docs ./openapi
grep -R "staging" ./docs ./openapi
Enter fullscreen mode Exit fullscreen mode

OpenAPI 파일에서는 다음도 확인하십시오.

grep -R "x-internal" ./openapi
grep -R "deprecated" ./openapi
grep -R "TODO" ./openapi
Enter fullscreen mode Exit fullscreen mode

이런 표면을 먼저 발견하려면 2026년 API 보안 테스트 체크리스트를 기반으로 문서와 실제 API를 함께 검토하는 것이 좋습니다.

3. 공개 GitHub Pages에는 접근 제어가 없음

GitHub Pages는 정적 파일 호스트입니다. 파일을 잘 제공하지만, 누가 읽는지 제어하지 않습니다.

완전 공개 API라면 괜찮습니다. 하지만 다음 문서는 GitHub Pages에 그대로 올리면 안 됩니다.

  • 유료 고객 전용 API 문서
  • 파트너 전용 API 문서
  • 내부 API 문서
  • 관리자 API 문서
  • 베타 API 문서
  • 보안상 민감한 인증 흐름 문서

“아무도 링크하지 않은 URL”은 접근 제어가 아닙니다. URL은 다음 경로로 쉽게 유출될 수 있습니다.

  • 브라우저 기록
  • 리퍼러 헤더
  • 프록시 로그
  • 채팅 메시지
  • 공유 북마크
  • 검색 엔진 인덱싱 실수
  • CI/CD 로그

최소한 다음 질문에 답할 수 있어야 합니다.

  • 지금 누가 문서를 읽을 수 있는가?
  • 특정 고객 또는 파트너의 접근을 즉시 철회할 수 있는가?
  • 접근 로그를 확인할 수 있는가?
  • 내부 문서와 공개 문서가 분리되어 있는가?

4. 오래되고 검증 불가능한 문서가 쌓임

공격자가 없어도 문서는 쉽게 위험해집니다. API는 변경되지만 OpenAPI 스펙은 업데이트되지 않는 경우가 많습니다.

예를 들어 실제 API는 다음 필드를 요구하도록 변경되었습니다.

{
  "amount": 1000,
  "currency": "USD",
  "customerId": "cus_123"
}
Enter fullscreen mode Exit fullscreen mode

하지만 문서는 여전히 다음처럼 되어 있습니다.

{
  "amount": 1000,
  "currency": "USD"
}
Enter fullscreen mode Exit fullscreen mode

소비자는 문서를 믿고 통합하다가 운영 환경에서 실패합니다.

보안 관점에서도 문제가 됩니다. 문서가 실제 API와 다르면, 나중에 이상한 변경을 발견해도 이것이 오래된 문서인지, 누군가 변조한 것인지 구분하기 어렵습니다.

따라서 문서에는 다음 검증 루프가 필요합니다.

  • OpenAPI 스펙을 실제 API에 대해 테스트
  • CI에서 스펙 lint 실행
  • 스펙 변경 시 API 테스트 실행
  • 배포된 문서와 검토된 소스의 일치 여부 확인
  • 오래된 버전 문서 분리

예시로 spectral을 사용할 수 있습니다.

npx @stoplight/spectral-cli lint openapi.yaml
Enter fullscreen mode Exit fullscreen mode

CI에서는 다음처럼 최소 검사를 넣을 수 있습니다.

name: Validate OpenAPI

on:
  pull_request:
    paths:
      - "openapi/**"
      - "docs/**"

jobs:
  lint-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI
        run: npx @stoplight/spectral-cli lint openapi/openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Git 기반 Docs-as-code가 괜찮은 경우와 위험한 경우

Docs-as-code는 좋은 방식입니다. OpenAPI 스펙과 Markdown을 Git에 넣고, PR 리뷰를 거쳐 Swagger UI 또는 Redoc을 빌드하고, 정적 호스트에 배포하면 다음 장점이 있습니다.

  • 변경 기록이 남음
  • 리뷰 프로세스를 적용할 수 있음
  • 코드와 문서를 함께 버전 관리할 수 있음
  • CI에서 lint와 테스트를 실행할 수 있음
  • 변경 사항을 추적하기 쉬움

문제는 “Git을 쓰느냐”가 아니라 “현재 설정이 해당 API에 충분히 안전한가”입니다.

Git 기반 문서화가 적합한 경우

다음 조건을 만족하면 Git 기반 문서화는 충분히 강력합니다.

  • API가 완전히 공개되어 접근 제어가 필요 없음
  • 저장소에 브랜치 보호가 설정되어 있음
  • 문서 변경에도 필수 리뷰가 적용됨
  • 쓰기 권한을 가진 사용자가 제한되어 있음
  • CI/CD 토큰 권한이 최소화되어 있음
  • 배포 파이프라인이 잠겨 있음
  • OpenAPI 스펙이 실제 API에서 생성되거나 실제 API에 대해 검증됨
  • 누군가 문서 최신성을 책임지고 있음

GitHub에서는 최소한 다음을 적용하십시오.

Settings → Branches → Branch protection rules
Enter fullscreen mode Exit fullscreen mode

권장 설정:

  • Require a pull request before merging
  • Require approvals
  • Dismiss stale pull request approvals
  • Require status checks to pass
  • Require conversation resolution
  • Restrict who can push to matching branches
  • Do not allow bypassing the above settings

문서 변경 리뷰어도 명시적으로 지정합니다.

.github/CODEOWNERS
Enter fullscreen mode Exit fullscreen mode

예시:

/openapi/ @api-platform-team @security-team
/docs/api/ @api-platform-team @security-team
Enter fullscreen mode Exit fullscreen mode

Git 기반 문서화가 위험한 경우

다음 중 하나라도 해당하면 재검토해야 합니다.

  • 문서는 파트너 전용인데 호스트에는 접근 제어가 없음
  • “비공개”가 사실상 “URL을 모르면 못 본다”는 의미임
  • 쓰기 권한이 광범위함
  • CI 토큰과 서비스 계정이 오래 방치됨
  • 문서 PR이 “그냥 문서”로 취급되어 형식적으로 승인됨
  • OpenAPI 스펙이 실제 API와 동기화되지 않음
  • 공개 문서 저장소에 내부 엔드포인트가 섞여 있음
  • 배포된 사이트가 검토된 소스와 일치하는지 확인할 방법이 없음

GitHub 침해 사고는 바로 이 지점을 보여줍니다. Git은 변경 기록과 투명성을 제공합니다. 하지만 저장소 자체가 유출되면 기밀성을 제공하지 않습니다.

자체 호스팅 문서화 접근 방식의 장단점은 자체 호스팅 API 문서 비교를 참고하십시오.

안전한 API 문서화 체크리스트

“안전한 API 문서화”는 추상적인 표현이 아닙니다. 다음 네 가지 속성으로 나눠 점검할 수 있습니다.

1. 접근 제어

문서는 필요한 사람에게만 보여야 합니다.

공개 API는 공개해도 됩니다. 하지만 고객 전용, 파트너 전용, 내부 문서는 실제 접근 제어가 필요합니다.

사용 가능한 제어 방식:

  • 비밀번호 보호
  • IP 허용 목록
  • 이메일 허용 목록
  • SSO
  • 사용자 지정 로그인
  • 역할 기반 권한

점검 질문:

  • 지금 누가 문서를 읽을 수 있는지 정확히 말할 수 있는가?
  • 특정 사용자의 접근을 1분 안에 철회할 수 있는가?
  • 내부 문서 URL을 외부 사람이 열 수 없는가?

2. 버전 관리

게시된 문서는 API 버전과 함께 유지되어야 합니다.

예를 들어 v1 소비자는 v1 문서를 봐야 하고, v2 소비자는 v2 문서를 봐야 합니다. 최신 문서 하나만 있으면 오래된 통합이 깨집니다.

점검 질문:

  • v1 API 사용자가 여전히 v1 문서를 볼 수 있는가?
  • 특정 날짜의 문서 내용을 재현할 수 있는가?
  • 문서 버전과 API 배포 버전이 연결되어 있는가?

3. 무결성

게시된 문서가 승인된 소스와 일치해야 합니다.

가능한 방법:

  • API 설계에서 문서 자동 생성
  • OpenAPI 스펙을 단일 진실의 원천으로 사용
  • 문서 PR 필수 리뷰
  • CI에서 lint 및 테스트
  • 배포 후 해시 또는 아티팩트 검증
  • 변경 알림

점검 질문:

  • 한 시간 전에 라이브 문서의 엔드포인트 URL이 바뀌었다면 알 수 있는가?
  • 배포된 문서가 어떤 커밋에서 생성되었는지 확인할 수 있는가?

4. 감사 추적

누가, 무엇을, 언제 바꿨는지 확인할 수 있어야 합니다.

Git 기록은 저장소 수준의 감사 추적을 제공합니다. 하지만 배포된 사이트까지 포함하려면 다음도 필요합니다.

  • 배포 로그
  • 게시 이력
  • 문서 버전 변경 기록
  • 접근 제어 변경 기록
  • API 설계 변경 기록

점검 질문:

  • 지난 90일 동안 게시된 문서 변경 로그를 생성할 수 있는가?
  • 특정 엔드포인트 설명이 언제 바뀌었는지 확인할 수 있는가?
  • 문서 접근 권한 변경 이력을 볼 수 있는가?

Apidog로 안전한 API 문서화 구현하기

Apidog는 API 설계, 디버깅, 테스트, 모킹, 문서화를 제공하는 올인원 API 플랫폼입니다. 문서화 측면에서는 위 네 가지 속성을 별도 도구로 조합하지 않고 플랫폼 내에서 처리할 수 있습니다.

시작하려면 Apidog를 다운로드하고 API 정의가 포함된 프로젝트를 여십시오.

Apidog API documentation

1. API 설계에서 문서 생성하기

Apidog에서는 프로젝트 내 API 설계가 문서의 원천입니다. 엔드포인트, 스키마, 인증 방식을 설계하면 Apidog가 해당 정의에서 문서를 자동 생성합니다.

기본 흐름은 다음과 같습니다.

  1. Apidog 프로젝트 생성
  2. OpenAPI 또는 Swagger 스펙 가져오기
  3. 엔드포인트, 스키마, 인증 정보 검토
  4. 문서 미리보기
  5. 접근 제어 설정
  6. 게시

이 방식의 장점은 문서가 별도의 Markdown 파일로 흩어지지 않는다는 점입니다. 소비자가 보는 문서는 API 정의를 반영합니다. 문서를 바꾸려면 정적 호스트의 파일을 직접 수정하는 것이 아니라 권한과 변경 기록이 있는 API 설계를 수정해야 합니다.

2. 문서 접근 제어 설정하기

Apidog는 게시 시 문서 가시성을 선택할 수 있습니다.

지원되는 방식은 다음과 같습니다.

방식 사용 사례
공개 완전 공개 API
비밀번호 보호 고객 또는 파트너에게 간단히 공유
IP 허용 목록 사무실, VPN, 내부망 문서
이메일 허용 목록 특정 사용자 또는 도메인 기반 접근
사용자 지정 로그인 자체 인증 시스템과 연결

예를 들어 파트너 문서라면 이메일 허용 목록을 사용할 수 있습니다.

partner-a@example.com
partner-b@example.com
*@trusted-partner.com
Enter fullscreen mode Exit fullscreen mode

내부 문서라면 IP 허용 목록을 사용할 수 있습니다.

203.0.113.10
203.0.113.0/24
Enter fullscreen mode Exit fullscreen mode

Apidog는 API 문서 접근 제어 가이드에서 이러한 방식을 설명합니다.

이 접근 방식은 GitHub Pages의 가장 큰 한계인 “읽기 접근 제어 부재”를 보완합니다.

3. 사용자 지정 도메인 연결하기

게시된 문서를 자체 도메인에서 제공할 수도 있습니다.

예:

developer.yourcompany.com
docs.yourcompany.com
api-docs.yourcompany.com
Enter fullscreen mode Exit fullscreen mode

Apidog는 DNS CNAME 또는 리버스 프록시를 통한 사용자 지정 도메인을 지원합니다.

사용자 지정 도메인 자체가 보안 제어는 아닙니다. 하지만 소비자가 신뢰할 수 있는 도메인에서 문서를 보게 하고, 문서 URL을 조직이 관리하는 인프라 안에 둘 수 있습니다.

4. OpenAPI 스펙 동기화하기

문서 drift를 줄이려면 API 설계와 OpenAPI 스펙이 계속 동기화되어야 합니다.

Apidog는 다음을 지원합니다.

  • OpenAPI 3.0 가져오기
  • OpenAPI 3.1 가져오기
  • Swagger 2.0 가져오기
  • 외부 스펙 예약 가져오기
  • API 설계 기반 문서 동기화

현재 Git 저장소에서 스펙을 수동으로 관리하고 있다면 drift가 생기기 쉽습니다. 이 경우 Apidog를 API 정의의 원천으로 삼거나, 외부 스펙을 주기적으로 가져오도록 구성해 게시 문서와 실제 설계의 차이를 줄일 수 있습니다.

SwaggerHub에서 이동하는 팀은 SwaggerHub API 문서를 Apidog로 마이그레이션하는 가이드를 참고할 수 있습니다.

5. 문서 버전 관리하기

API 버전이 여러 개라면 문서도 함께 버전 관리해야 합니다.

예:

/v1 문서 → v1 API 소비자
/v2 문서 → v2 API 소비자
/beta 문서 → 베타 파트너
Enter fullscreen mode Exit fullscreen mode

Apidog는 여러 문서 버전을 나란히 게시하고 유지할 수 있습니다. v2가 출시된 뒤에도 v1 소비자는 정확한 v1 문서를 계속 볼 수 있습니다.

버전 관리는 다음 문제를 줄입니다.

  • 오래된 통합이 최신 문서만 보고 잘못 구현하는 문제
  • API 변경 이력을 추적하기 어려운 문제
  • 특정 시점의 문서 내용을 재현할 수 없는 문제
  • 지원팀과 개발팀이 서로 다른 문서를 보는 문제

문서 호스팅 옵션 비교

아래 표는 일반적인 문서 호스팅 방식을 네 가지 보안 속성 기준으로 비교한 것입니다.

속성 공개 GitHub Pages (Swagger UI / Redoc) 자체 서버에서 호스팅되는 문서 관리형 문서 (Apidog)
접근 제어 없음. URL 모호성에 의존 직접 구축 및 유지 관리 내장: 비밀번호, IP, 이메일, 사용자 지정 로그인
버전 관리 수동. 브랜치 또는 별도 빌드 필요 수동 내장. 버전별 동시 게시
무결성 Git 리뷰와 기록에 의존 파이프라인 구성에 따라 다름 통제된 API 설계에서 문서 생성
감사 추적 저장소 Git 기록 중심 로깅 구현에 따라 다름 설계 및 게시 문서 변경 기록
유지 보수 비용 초기 비용 낮음, 파이프라인 유지 필요 높음. 전체 스택 직접 운영 낮음. 플랫폼이 호스팅과 게이트 관리
적합한 경우 완전 공개 API, 잘 관리되는 파이프라인 엄격한 자체 호스팅 요구 사항 접근 제어가 필요하고 운영 부담을 줄이고 싶은 팀

보편적으로 정답인 선택지는 없습니다.

  • 완전 공개 API이고 파이프라인이 잘 관리된다면 GitHub Pages도 충분히 좋은 선택입니다.
  • 데이터 상주, 네트워크 격리, 내부 정책 때문에 직접 운영해야 한다면 자체 호스팅이 맞을 수 있습니다.
  • 접근 제어와 버전 관리가 필요하지만 운영 부담을 줄이고 싶다면 관리형 문서화 레이어가 적합합니다.

더 자세한 비교는 자체 호스팅 API 문서 비교와 Scalar vs SwaggerHub vs Apidog 비교를 참고하십시오.

바로 적용할 수 있는 점검 목록

현재 팀의 API 문서에 대해 아래 항목을 확인하십시오.

[ ] API 문서가 게시된 모든 위치를 알고 있다.
[ ] 공개 문서와 내부 문서가 분리되어 있다.
[ ] 문서 저장소에 브랜치 보호가 설정되어 있다.
[ ] 문서 변경에도 필수 리뷰가 적용된다.
[ ] OpenAPI 스펙 변경 시 CI 검증이 실행된다.
[ ] servers.url, tokenUrl, authorizationUrl 변경을 리뷰한다.
[ ] 문서 호스트에 접근 제어가 있다.
[ ] 파트너 또는 고객 접근을 즉시 철회할 수 있다.
[ ] 문서 버전이 API 버전과 연결되어 있다.
[ ] 배포된 문서가 어떤 커밋 또는 설계 버전에서 생성되었는지 알 수 있다.
[ ] 지난 90일의 문서 변경 이력을 확인할 수 있다.
[ ] 내부 엔드포인트가 공개 문서에 섞여 있지 않다.
Enter fullscreen mode Exit fullscreen mode

가장 먼저 할 일은 문서 인벤토리입니다.

문서 이름:
URL:
저장소:
배포 파이프라인:
접근 제어:
소유 팀:
API 버전:
마지막 검토일:
Enter fullscreen mode Exit fullscreen mode

이 목록을 만들면 어떤 문서가 방치되어 있는지 바로 드러납니다.

결론

GitHub 침해 사고는 GitHub를 불신하거나 Docs-as-code를 포기하라는 신호가 아닙니다. 대신 API 문서라는 신뢰된 표면을 점검하라는 경고입니다.

API 문서는 소비자가 그대로 복사해 실행하는 지침입니다. 따라서 코드와 같은 수준으로 보호해야 합니다.

실행 순서는 다음과 같습니다.

  1. API 문서가 게시된 모든 위치를 나열합니다.
  2. 각 문서에 접근 제어, 버전 관리, 무결성, 감사 추적이 있는지 확인합니다.
  3. 공개 문서와 내부 문서를 분리합니다.
  4. OpenAPI 변경 리뷰와 CI 검증을 강화합니다.
  5. 접근 제어가 필요하다면 Apidog 같은 관리형 문서화 레이어로 한 프로젝트부터 게시해 봅니다.

가장 큰 간극이 접근 제어라면, Apidog에서 한 프로젝트의 문서를 비밀번호 또는 이메일 허용 목록으로 게시해 관리형 문서화가 팀의 운영 부담을 얼마나 줄일 수 있는지 확인해 보십시오.

Top comments (0)