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

Ashley Innocent

Ashley Innocent

21 May 2026

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

API 문서 보안은(는) 거의 아무도 감사하지 않는 API 프로그램의 일부입니다. 여러분은 인증, 속도 제한, 보안 테스트를 통해 API 자체를 강화합니다. 하지만 해당 API를 설명하는 문서, 즉 OpenAPI 스펙, Swagger UI 페이지, 인증 흐름을 설명하는 마크다운 등은 종종 Git 저장소나 정적 호스트에 저장되며, 설정된 날부터 아무도 검토하지 않습니다. 2026년 5월 20일, GitHub는 공격자들이 약 3,800개의 내부 코드 저장소에서 데이터를 훔쳐 갔음을 확인했습니다. 진입점은 GitHub 직원 노트북에 설치된 악성 VS Code 확장 프로그램이었습니다. 이 침해 사고는 여러분의 설정에 대해 불편한 질문을 던져볼 좋은 이유가 됩니다. 만약 누군가 여러분이 게시한 API 문서를 몰래 변경할 수 있다면, 여러분은 알아차릴 수 있을까요? 그리고 여러분의 API 소비자들은 알아차릴 수 있을까요?

요약

안전한 API 문서는 문서가 접근 제어, 버전 기록, 검증 가능한 무결성 및 감사 추적을 갖추고 있음을 의미합니다. 따라서 침해된 저장소나 호스트가 잘못된 엔드포인트, 토큰 또는 인증 지침을 프로덕션에 복사하는 개발자에게 은밀하게 제공할 수 없습니다. Git에서 코드로 문서화(Docs-as-code)하는 방식은 많은 팀에 적합하며, 무료로 검토 및 기록 기능을 제공합니다. 이 방식은 저장소가 접근 제어 없이 공개되거나, 오래된 사양이 실제 API와 동기화되지 않거나, 변조된 예시가 소비자에게 감지되지 않은 채 도달할 때 문제가 됩니다. Apidog와 같은 관리형 문서화 레이어는 비밀번호 보호, IP 및 이메일 허용 목록, 사용자 지정 도메인, 버전 관리, 그리고 API 설계와 동기화되어 진실의 원천 역할을 하는 사양을 추가합니다.

GitHub 침해 사고가 API 문서를 살펴보게 해야 하는 이유

GitHub 사고는 패닉에 빠지기 전에 이해할 가치가 있습니다. 위협 그룹 TeamPCP는 GitHub 내부 저장소를 유출했으며, 현재 이 데이터를 지하 포럼에서 5만 달러 이상에 판매하고 있습니다. BleepingComputer의 보도에 따르면 악성 VS Code 확장 프로그램은 공식 마켓플레이스에서 직접 제공되었으며 직원 기기에서 실행되었습니다. GitHub는 내부 저장소 외부에 저장된 고객 데이터가 영향을 받았다는 증거는 찾지 못했으며 조사가 진행 중이라고 밝혔습니다.

이번 침해 사고는 여러분에게 경고를 던집니다. 이는 API 문서가 어디에 어떻게 존재하며, 변조될 수 있는지 살펴보라는 경고입니다. 대부분의 팀은 이러한 질문을 해본 적이 없습니다. 그들은 3년 전에 Swagger UI를 GitHub Pages에 게시하고, CNAME을 연결한 후 다른 작업으로 넘어갔습니다. 저장소는 공개되어 있고, 사양은 마지막으로 병합된 내용 그대로입니다. 누구도 애플리케이션 코드에 적용하는 것과 동일한 주의를 기울여 문서 사이트 변경 사항을 검토하지 않습니다.

그 간극이 중요한 이유는 API 문서가 곧 지침이기 때문입니다. 개발자가 여러분의 API와 통합할 때, 그들은 엔드포인트 경로, 요청 형태, 인증 헤더, 그리고 종종 예시 값들을 문서에서 직접 코드에 복사합니다. 만약 공격자가 이 지침들을 변경할 수 있다면, 그들은 마케팅 페이지를 훼손하는 것이 아닙니다. 그들은 다른 사람들이 실행할 코드를 편집하는 것입니다. 동일한 논리가 다른 2026년 침해 사고의 사후 검토에서도 나타납니다. Vercel 침해 사고로부터 얻은 API 보안 교훈에 대한 저희 글은 신뢰할 수 있는 표면에서의 작은 변화가 어떻게 외부로 파급되는지 다룹니다.

이 글은 네 가지 사항을 다룹니다. 손상된 API 문서가 소비자에게 피해를 주는 구체적인 방법, Git에서의 코드형 문서가 정말 괜찮은 경우와 문제가 되는 경우, "안전한 API 문서화"가 체크리스트로서 실제로 의미하는 것, 그리고 관리형 문서화 레이어가 어떻게 이러한 간극을 메우는지입니다. 두 개의 관련 글에서는 더 깊이 있는 내용을 다룹니다. GitHub 침해 사고가 자체 호스팅 API 도구에 미치는 영향VS Code 확장 프로그램 API 키 보안입니다.

API 문서 저장소 또는 호스트가 침해될 경우 발생하는 문제

위협 모델부터 시작해 보겠습니다. 여러분의 API 문서는 Git 저장소, 이를 빌드하는 CI 파이프라인, 그리고 이를 제공하는 호스트와 같은 특정 표면에 존재합니다. 이 중 어느 하나라도 침해되면 몇 가지 구체적인 나쁜 결과가 뒤따릅니다. 이들은 이론적인 것이 아닙니다.

문서 변조가 프로덕션 코드에 도달함

이는 최악의 시나리오이자 가장 명확하지 않은 경우입니다. 문서 저장소 또는 빌드된 사이트를 제공하는 호스트에 대한 쓰기 권한이 있는 공격자가 작은 수정을 가합니다. 그들은 https://api.payments.acme.com/v2/charge를 자신들이 제어하는 도메인으로 변경합니다. 그들은 "시작하기" 페이지의 예시 베어러 토큰을 자신들의 프록시를 통해 라우팅되는 토큰으로 바꿉니다. 그들은 OAuth 섹션의 한 문장을 다시 작성하여 토큰 교환이 잘못된 URL로 게시되도록 합니다.

이 중 어느 것도 여러분의 사이트를 손상시키지 않습니다. 페이지는 여전히 렌더링되고, CI는 사양이 여전히 유효한 YAML이기 때문에 통과됩니다. 하지만 여러분의 API와 통합하는 다음 개발자는 해당 엔드포인트나 흐름을 자신의 서비스에 복사합니다. 이 변경 사항은 이제 그들의 프로덕션 환경에서 실행되며, 그들은 공식 문서에서 왔기 때문에 이를 신뢰했습니다.

실제 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

침해된 계정을 통해 병합되거나 탈취된 호스트로 푸시된 해당 servers URL에 대한 한 번의 수정만으로도, 스펙에서 클라이언트를 다시 생성하는 모든 소비자는 이제 공격자의 도메인으로 카드 데이터를 전송하게 됩니다. 변경 사항은 두 단어에 불과합니다. 문서 커밋에서 두 단어를 문제 삼는 사람은 없습니다.

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

문서 저장소에는 많은 것이 쌓입니다. 공개 API로 시작된 사양에는 종종 게시될 의도가 없었던 내부 전용 경로, 관리자 엔드포인트, 디버그 경로 또는 파트너 전용 작업이 추가됩니다. 저장소가 공개되어 있거나 잘못된 구성으로 인해 공개되면, 이러한 엔드포인트는 공격 표면을 스캔하는 누구에게나 지도가 됩니다.

심지어 비공개 저장소도 문제입니다. GitHub와 같은 침해 사고는 비공개 저장소를 유출시킵니다. 내부 API 사양이 도난당한 저장소에 있는 순간, 공격자는 여러분의 엔드포인트, 매개변수, 예상 페이로드에 대한 정확한 목록을 갖게 됩니다. 그들은 추측할 필요가 없습니다. 여러분이 스키마를 그들에게 넘겨준 셈입니다. 다른 사람이 먼저 발견하기 전에 이러한 간극을 찾기 위한 프레임워크를 원한다면, 저희 2026년 API 보안 테스트 체크리스트는 바로 이러한 종류의 표면 검토를 중심으로 구축되었습니다.

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

GitHub Pages는 정적 호스트입니다. 파일을 제공하며, 누가 읽는지에 대한 개념이 없습니다. 진정한 공개 API의 경우 이는 정확하고 괜찮습니다. 유료 고객, 지정된 파트너 또는 여러분의 팀에게만 보여야 하는 문서의 경우, 이는 잘못된 도구입니다. 왜냐하면 접근을 막는 어떤 장치도 없기 때문입니다.

팀들은 "추측하기 어려운 URL을 통한 보안"으로 이 문제를 해결합니다. 문서는 아무도 연결하지 않는 경로에 있습니다. 이것은 접근 제어가 아닙니다. URL은 브라우저 기록, 리퍼러 헤더, 프록시 로그, 공유 북마크를 통해 유출될 수 있습니다. 링크를 찾은 사람은 모든 것을 영원히 볼 수 있으며, 여러분은 그들이 그렇게 했다는 것을 알 방법이 없습니다.

오래되고 검증 불가능한 문서

더 조용한 실패 모드는 공격자가 전혀 필요 없습니다. Git 저장소의 문서는 시간이 지남에 따라 달라집니다. 누군가 API 변경 사항을 배포하고 사양을 업데이트하는 것을 잊으면, 마크다운은 이제 프로덕션에서 다르게 작동하는 엔드포인트를 설명하게 됩니다. 소비자는 문서화된 동작에 따라 통합하지만 실제 동작과 맞닥뜨려 하루 종일 디버깅에 시간을 허비합니다.

문서가 침해되면, 변조와 달라짐을 구분할 능력을 잃게 되므로 이 문제는 더욱 악화됩니다. 해당 엔드포인트는 항상 잘못되었던 것일까요, 아니면 누군가가 변경한 것일까요? 실제 API 설계와 연결된 검증 가능한 기록 없이는 그 질문에 답할 수 없습니다. 문서는 검증 불가능하게 되며, 검증 불가능한 문서는 문서가 없는 것과 크게 다르지 않습니다.

Git에서의 코드형 문서가 괜찮은 경우와 문제가 되는 경우

코드형 문서(Docs-as-code)는 합법적이고 인기 있는 관행이며, 이 섹션은 이에 대한 반론이 아닙니다. OpenAPI 사양과 마크다운을 Git 저장소에 넣고, CI로 Swagger UI 또는 Redoc을 빌드하며, 정적 호스트에 배포하는 것은 실제적인 이점을 제공합니다. 문서 변경 사항에 대한 풀 리퀘스트 검토를 받을 수 있습니다. 누가 무엇을 언제 변경했는지에 대한 전체 기록을 얻을 수 있습니다. 코드와 함께 문서가 버전 관리됩니다. 이러한 속성들은 워크플로우를 따를 때 변조를 감지할 수 있게 합니다.

따라서 질문은 "Git이냐 아니냐"가 아닙니다. "이 특정 API에 대해 이 특정 설정이 안전한가"입니다. 다음은 두 가지 경우가 어떻게 나뉘는지입니다.

Git에서 코드형 문서화가 괜찮은 경우

이 관행은 특정 조건에서 잘 작동합니다.

이 모든 조건이 충족된다면, Git 호스팅 문서는 강력하고 투명한 시스템입니다. 기록은 여러분의 감사 추적이며, 검토는 여러분의 무결성 검사입니다.

Git에서의 코드형 문서화가 문제가 되는 경우

동일한 설정이 조건이 충족되지 않을 때 위험해집니다.

GitHub 침해 사고는 이러한 실패 모드에 정확히 해당합니다. 공격은 개발자 엔드포인트를 통해 내부 저장소에 도달했습니다. 만약 여러분의 비공개 API 사양이 이들 저장소 중 하나에 있었다면, 침해 사고는 여러분의 검토 프로세스가 얼마나 신중했는지와 상관없이 스키마를 노출했습니다. Git은 투명성을 제공하지만, 저장소 자체가 도난당하면 기밀성을 제공하지는 않습니다. 이러한 절충점(tradeoffs)에 대한 다양한 자체 호스팅 문서화 접근 방식의 전체적인 비교는 저희 자체 호스팅 API 문서 비교를 참조하십시오.

이 요점은 의도적으로 균형을 맞춘 것입니다. API가 공개되어 있고 파이프라인이 잘 관리된다면 코드형 문서화를 유지하십시오. 문서에 접근 제어가 필요하거나, 검토 프로세스에서 문서가 덜 중요하게 다루어지거나, "라이브 사이트가 검토된 소스와 일치하는가"라는 질문에 답할 수 없다면 재고해 보십시오.

"안전한 API 문서화"가 실제로 의미하는 것

"안전한 API 문서화"는 확인할 수 있는 속성으로 나누기 전까지는 모호합니다. 그 중 네 가지가 중요합니다.

접근 제어

문서는 이를 봐야 할 사람들에게만 보여야 합니다. 공개 API의 경우 공개, 고객 전용, 파트너 전용 또는 내부 문서의 경우 제한됨. 제한은 모호한 URL이 아닌 실제 게이트, 비밀번호, IP 허용 목록, 이메일 허용 목록 또는 SSO여야 합니다. 테스트: 지금 여러분의 문서를 읽을 수 있는 사람을 정확히 말할 수 있으며, 그 중 한 명의 접근 권한을 1분 안에 철회할 수 있습니까?

버전 관리

문서의 모든 게시된 버전은 보존되고 식별 가능해야 합니다. v1 API를 사용하는 소비자는 v1 문서를 보고, v2 소비자는 v2 문서를 봅니다. 특정 날짜에 문서가 무엇을 말했는지 보여줄 수 있습니다. 테스트: 이전 API 버전을 통합하는 개발자가 v2로 자동 업데이트된 문서 대신 해당 버전에 대한 정확한 문서를 여전히 찾을 수 있습니까?

무결성

게시된 문서가 의도한 바와 일치하는지 확인할 수 있습니다. 문서는 통제된 진실의 원천에서 생성되거나, 승인되지 않은 변경 사항이 눈에 띄게 드러날 만큼 강력한 검토 및 기록 추적이 있어야 합니다. 테스트: 한 시간 전에 라이브 문서의 한 엔드포인트 URL을 누군가 변경했다면, 여러분에게 알려줄 수 있는 것이 있습니까?

감사 추적

누가 문서를 변경했는지, 무엇을 변경했는지, 그리고 언제 변경했는지 답할 수 있어야 합니다. Git 기록은 저장소에 대한 정보를 제공하지만, 배포 단계 자체가 공격 지점이기 때문에 게시된 표면에 대해서도 필요합니다. 테스트: 지난 90일 동안 게시된 문서에 대한 변경 로그를 생성할 수 있습니까?

이 네 가지를 모두 충족하는 설정이 안전한 문서화입니다. Git 호스팅 문서는 브랜치 보호 및 기록을 통해 버전 관리, 무결성, 감사 추적을 달성할 수 있습니다. 정적 호스트에서 주로 놓치는 것은 접근 제어이며, 이 간극을 관리형 문서화 레이어가 메울 수 있습니다.

Apidog가 안전한 API 문서화를 제공하는 방법

Apidog는 API 설계, 디버깅, 테스트, 모킹 및 문서화를 위한 올인원 API 플랫폼입니다. 문서화 측면은 위의 네 가지 속성이 추가로 부착하는 것이 아니라 기본적으로 제공되도록 구축되었습니다. 따라하려면 Apidog를 다운로드하고 API 정의가 포함된 프로젝트를 여십시오.

통제된 진실의 원천으로부터 생성된 게시 문서

Apidog에서 문서는 프로젝트 내 API 설계로부터 생성됩니다. 시각적 디자이너에서 엔드포인트, 스키마, 인증을 설계하면 Apidog가 해당 정의로부터 문서를 자동 생성합니다. "게시(Publish)"를 누르면 "Try it" 콘솔과 다국어 코드 샘플을 갖춘 대화형 문서 사이트를 얻을 수 있습니다.

무결성 이점은 구조적입니다. 게시된 문서는 자체적으로 달라지거나 변조될 수 있는 별도의 편집 가능한 마크다운이 아닙니다. 그들은 API 정의를 반영합니다. 정의를 변경하면 문서도 따라갑니다. 소비자가 보는 것을 변경하려면, 정적 호스트의 개별 파일을 편집하는 대신 자체 권한 및 변경 기록이 있는 프로젝트 내부의 설계를 변경해야 합니다.

문서 접근 제어

여기가 Apidog가 GitHub Pages의 간극을 메우는 지점입니다. 게시할 때 가시성을 선택하며, 옵션은 모호함이 아닌 실제 게이트입니다.

Apidog는 API 문서 접근 제어 가이드에서 이 다섯 가지 방법을 모두 설명합니다. 이는 접근 제어 테스트에 직접적으로 답합니다. 즉, 누가 문서를 읽을 수 있는지 명시할 수 있으며, 비밀번호를 철회하거나 허용 목록에서 이메일을 즉시 제거할 수 있습니다.

사용자 지정 도메인

게시된 문서를 자체 도메인에서 제공할 수 있으므로, 소비자는 일반적인 URL 대신 developer.yourcompany.com을 보게 됩니다. Apidog는 DNS CNAME(권장 경로) 또는 리버스 프록시를 통해 사용자 지정 도메인을 지원합니다. 사용자 지정 도메인만으로는 보안 제어가 아니지만, 아무도 소유하지 않는 호스트에 분산되는 대신 여러분이 관리하고 통제하는 인프라에 문서를 유지하게 합니다.

API 설계와 동기화된 OpenAPI 사양

차이(Drift)는 문서를 검증 불가능하게 만들기 때문에 문서 보안 문제입니다. Apidog는 API 설계를 진실의 단일 원천으로 간주하고, 설계가 변경됨에 따라 문서를 동기화합니다. Apidog는 OpenAPI 3.0, 3.1, Swagger 2.0을 가져오며, 외부 사양이 자동으로 최신 상태를 유지하도록 예약된 가져오기를 지원합니다.

현재 Git 저장소에서 사양을 수동으로 유지 관리한다면, 이는 가장 큰 차이를 보이고 검증하기 가장 어려운 설정입니다. 사양을 Apidog로 옮겨 진실의 원천으로 삼는다는 것은 게시된 문서가 항상 여러분이 제어하는 정의와 일치함을 의미합니다. SwaggerHub에서 온 팀은 SwaggerHub API 문서를 Apidog로 마이그레이션하는 가이드를 따를 수 있습니다.

문서 버전 관리

Apidog는 문서 버전 관리를 지원하여 여러 버전을 나란히 게시하고 유지할 수 있습니다. v1 API를 통합하는 소비자는 v2가 출시된 후에도 정확한 v1 문서를 읽을 수 있습니다. 버전 관리는 브랜치 및 변경 기록과 연결되어 API와 문서의 진화가 추적됩니다. 이는 버전 관리 및 감사 추적 테스트를 모두 다룹니다.

이 중 어느 것도 TeamPCP가 개발자 노트북을 침해하는 것을 막지는 못했을 것입니다. 하지만 이것은 다른 것을 의미합니다. 즉, 누가 여러분의 문서를 읽을 수 있는지, 게시된 버전이 여러분의 설계와 일치하는지, 그리고 시간이 지남에 따라 무엇이 변경되었는지에 대한 명확한 답변을 제공합니다. 이것이 GitHub 침해 사고가 여러분에게 실행하도록 유도해야 할 감사입니다.

문서 호스팅 옵션 비교

네 가지 보안 속성에 대한 일반적인 접근 방식들을 빠르게 비교합니다.

속성 공개 GitHub Pages (Swagger UI / Redoc) 자체 서버에서 호스팅되는 문서 관리형 문서 (Apidog)
접근 제어 없음; URL 모호성만 직접 구축하고 유지 관리하는 방식 내장: 비밀번호, IP, 이메일, 사용자 지정 로그인
버전 관리 수동; 별도 빌드 또는 브랜치 수동 내장; 버전별 동시 게시
무결성 Git 검토 + 기록 (강제하는 경우) 파이프라인에 따라 다름 통제된 API 설계로부터 문서 생성
감사 추적 저장소에 대한 Git 기록, 배포에 대한 기록 아님 로깅 방식에 따라 다름 설계 및 게시 문서에 대한 변경 기록
유지 보수 비용 설정 비용은 낮으나 지속적인 파이프라인 유지 보수 높음; 전체 스택을 직접 소유 낮음; 플랫폼이 호스팅 및 게이트 관리
가장 적합한 경우 완전 공개 API, 잘 관리되는 파이프라인 엄격한 자체 호스팅 요구 사항이 있는 팀 운영 오버헤드 없이 접근 제어가 필요한 팀

보편적으로 올바른 선택은 없습니다. 공개 GitHub Pages는 잘 관리되는 파이프라인을 가진 공개 API에 좋은 선택입니다. 자체 호스팅은 엄격한 상주 또는 격리 요구 사항이 있는 팀에 적합합니다. 저희 자체 호스팅 API 문서 비교Scalar vs SwaggerHub vs Apidog 비교는 이러한 절충점(tradeoffs)을 자세히 설명합니다. 핵심은 3년 전 설정을 그대로 물려받아 다시는 보지 않는 것이 아니라, 네 가지 속성을 고려하여 신중하게 선택하는 것입니다.

결론

GitHub 침해 사고는 코드형 문서를 포기하거나 GitHub를 불신할 이유가 아닙니다. 이는 대부분의 팀이 무시해왔던 표면, 즉 API 문서가 어디에 존재하며 변조될 수 있는지 감사하도록 유도하는 경고입니다.

다음 단계: API 문서가 게시된 모든 위치를 나열하고, 각 위치를 네 가지 속성에 대해 확인한 다음, 가장 큰 간극을 메우십시오. 만약 접근 제어가 간극이라면, Apidog를 다운로드하여 한 프로젝트의 문서를 비밀번호나 이메일 허용 목록과 함께 게시하여 관리형 레이어가 이를 어떻게 처리하는지 확인하십시오.

button

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요