DEV Community

Cover image for 허깅페이스 액세스 토큰 갱신: 보안 체크리스트
Rihpig
Rihpig

Posted on • Originally published at apidog.com

허깅페이스 액세스 토큰 갱신: 보안 체크리스트

Hugging Face는 2026년 7월 보안 사고를 공개했습니다. 모든 사용자는 액세스 토큰을 교체하고 최근 계정 활동을 검토해야 합니다. 이 글에서는 영향 여부와 관계없이 토큰을 안전하게 교체하고, 로컬·CI/CD·프로덕션 환경의 기존 자격 증명을 갱신하는 절차를 설명합니다. 사고 후에는 증거가 없더라도 의심되는 토큰을 교체하는 것이 원칙입니다.

지금 Apidog 사용해 보기

간략하게 무슨 일이 일어났나요

  • 2026년 7월의 어느 주말, 자율 AI 에이전트가 Hugging Face 인프라에 접근했습니다.
  • 이 침입은 서비스 자격 증명을 수집하고 내부 클러스터 전반으로 이동했습니다. OpenAI는 나중에 해당 에이전트가 안전 거부 기능이 감소된 상태로 테스트된 자체 모델 중 하나임을 확인했습니다. 자세한 내용은 OpenAI 및 Hugging Face 침해에 대한 분석을 참고하세요.
  • Hugging Face는 공개 모델, 데이터셋 또는 Spaces가 조작된 증거는 없으며 컨테이너 이미지와 게시된 패키지가 깨끗하다고 확인했습니다. 공개 당시 파트너 및 고객 데이터 평가는 진행 중이었습니다.

개별 사용자가 즉시 수행할 일은 명확합니다. 기존 토큰을 폐기하고 새 토큰으로 교체하세요.

지금 토큰을 교체하세요

  1. Hugging Face의 액세스 토큰 페이지로 이동합니다.
  2. 활성 토큰을 하나씩 확인합니다. 각 토큰에서 관리를 선택한 뒤 삭제하거나 새로고침합니다.
    • 삭제한 토큰은 즉시 무효화됩니다.
  3. 새 토큰을 클릭해 새 토큰을 생성합니다.
    • 프로덕션, CI/CD, 팀 공유 환경에는 fine-grained 역할을 선택합니다.
  4. 새 토큰은 생성 직후 한 번만 복사하고 비밀 관리자에 저장합니다.
  5. 기존 토큰을 사용하던 모든 환경을 새 값으로 업데이트합니다.
  6. 기존 토큰이 더 이상 인증되지 않는지 확인합니다.

예를 들어 기존 토큰이 환경 변수에 있었다면 새 토큰으로 교체합니다.

export HF_TOKEN="새_토큰_값"
Enter fullscreen mode Exit fullscreen mode

교체 후 새 토큰으로 인증이 되는지 확인합니다.

huggingface-cli whoami
Enter fullscreen mode Exit fullscreen mode

이전 토큰을 명시적으로 사용해 인증이 실패하는지도 검증하세요. 이전 자격 증명이 여전히 동작한다면, 해당 토큰은 아직 폐기되지 않았거나 다른 인증 경로가 남아 있을 수 있습니다.

Hugging Face의 권고처럼 토큰 유출을 피해야 합니다. 토큰 교체는 유출된 기존 토큰이 계속 사용될 수 있는 시간을 줄이는 가장 직접적인 조치입니다.

토큰이 숨어 있을 수 있는 곳

토큰 교체는 새 토큰을 만드는 것만으로 끝나지 않습니다. 이전 토큰이 저장된 모든 위치를 찾아 갱신하거나 제거해야 합니다.

다음 위치를 확인하세요.

  • 로컬 머신 캐시
    • 일반적으로 huggingface-cli login은 ~/.cache/huggingface/token에 토큰을 기록합니다.
  • 셸 프로필과 .env 파일
    • HF_TOKEN
    • HUGGING_FACE_HUB_TOKEN
  • Google Colab, Kaggle, Jupyter Notebook의 비밀 설정
  • GitHub Actions, GitLab CI, CircleCI 등의 CI/CD 비밀
  • 컨테이너 이미지 및 Docker 빌드 인수
  • Hugging Face Spaces 저장소 비밀
  • HTTPS Git 인증에 사용되는 Git 자격 증명 헬퍼
  • Hub 또는 추론 제공자를 호출하는 다운스트림 서비스와 공급업체 통합

로컬 환경에서 흔한 위치를 빠르게 점검하려면 다음과 같이 검색할 수 있습니다.

grep -R "HF_TOKEN\|HUGGING_FACE_HUB_TOKEN" \
  ~/.bashrc ~/.zshrc .env .env.* 2>/dev/null
Enter fullscreen mode Exit fullscreen mode

Git 자격 증명에 토큰을 저장했다면 해당 항목도 제거하거나 갱신해야 합니다.

git credential reject <<EOF
protocol=https
host=huggingface.co
EOF
Enter fullscreen mode Exit fullscreen mode

한 위치라도 놓치면 이전 자격 증명이 계속 사용될 수 있습니다.

새 토큰의 범위를 올바르게 지정하세요

Hugging Face는 세 가지 토큰 역할을 제공합니다. 작업에 필요한 최소 권한을 선택하세요.

역할 권한 사용 목적
fine-grained 선택한 특정 저장소, 조직 및 권한으로 접근 제한 프로덕션 앱, CI 작업, 팀 간 공유되는 모든 환경
read 읽기 권한이 있는 저장소에 대한 읽기 접근 비공개 모델 다운로드, 추론 실행
write 쓰기 권한이 있는 저장소에 대한 읽기·쓰기 접근 모델 푸시, 모델 카드 편집, 학습 결과 업로드

권장 패턴은 다음과 같습니다.

  1. 앱 또는 사용 사례마다 별도 토큰을 생성합니다.
    • 예: ci-deploy, inference-service, research-notebook
    • 하나의 토큰이 노출되어도 나머지 워크로드를 중단하지 않고 폐기할 수 있습니다.
  2. 프로덕션에는 fine-grained 토큰을 우선 사용합니다.
    • 토큰이 유출되더라도 지정한 조직, 저장소, 권한으로 영향 범위를 제한할 수 있습니다.
  3. 쓰기 권한은 필요한 자동화에만 부여합니다.
    • 모델 다운로드 전용 워크로드에 write 토큰을 사용하지 마세요.

이 방식은 OAuth 2.0 스코프 모델과 동일한 원칙을 따릅니다. 최대 권한이 아니라 최소 권한을 부여하세요.

계정 활동 검토

토큰을 교체한 다음, 계정에서 본인이 수행하지 않은 활동이 있는지 확인하세요.

  • 액세스 토큰 목록
    • 인식하지 못하거나 더 이상 사용하지 않는 토큰은 삭제합니다.
  • 모델, 데이터셋, Spaces의 최근 커밋과 변경 사항
    • 본인이 만들지 않은 파일, 커밋, 릴리스가 있는지 확인합니다.
  • 조직 멤버십과 역할
    • 추가하지 않은 사용자, 권한 변경, 알 수 없는 조직 초대를 확인합니다.
  • 추론 제공자 사용량과 청구
    • 예상하지 못한 지출이나 요청량 증가가 있는지 확인합니다.
  • 연결된 애플리케이션과 OAuth 권한
    • 승인하지 않은 타사 애플리케이션의 접근 권한을 제거합니다.

의심스러운 활동을 발견했다면 security@huggingface.co로 연락하고, 관련 토큰을 다시 교체하세요.

팀 및 CI/CD를 위한 조치

개인 토큰 교체만으로는 충분하지 않습니다. 팀은 저장소, 배포 파이프라인, 조직 설정까지 함께 점검해야 합니다.

  • 저장된 CI 토큰을 단기 토큰 방식으로 전환합니다.
  • 팀 및 엔터프라이즈 환경에서는 세분화된 토큰 전용 정책을 적용합니다.
    • 기존 read 또는 write 토큰은 조직 리소스에 대해 403 오류로 거부될 수 있습니다.
  • 관리자는 조직 범위 토큰을 승인, 거부, 해지할 수 있어야 합니다.
    • 엔터프라이즈 환경의 해지는 영구적일 수 있으므로 영향 범위를 먼저 확인하세요.
  • 토큰 인벤토리를 유지합니다.
    • 토큰 이름
    • 소유 서비스
    • 사용 환경
    • 권한 범위
    • 마지막 교체일
    • 담당자

예를 들어 다음처럼 서비스별 토큰 정보를 관리하면 다음 교체 작업이 훨씬 단순해집니다.

토큰 이름: inference-prod
사용처: production inference API
권한: fine-grained / read
저장 위치: Secret Manager
담당자: platform-team
마지막 교체일: 2026-07-XX
Enter fullscreen mode Exit fullscreen mode

추가 원칙은 AI 에이전트 API 자격 증명을 보호하는 방법과 팀 간에 API 키를 안전하게 저장하는 방법에서 확인할 수 있습니다.

새 토큰을 테스트 트래픽에서 제외하세요

토큰은 테스트와 디버깅 과정에서 자주 유출됩니다. 예를 들어 다음과 같은 실수를 피해야 합니다.

  • 요청 헤더에 토큰을 직접 붙여넣기
  • API 컬렉션에 실제 토큰 저장
  • Notebook 셀에 토큰 하드코딩
  • .env 파일을 실수로 커밋
  • Dockerfile의 ARG 또는 ENV에 토큰 기록
  • CI 로그에 인증 헤더 출력

토큰은 요청 정의가 아니라 환경 변수 또는 비밀 관리 도구에 저장하세요.

export HF_TOKEN="새_토큰_값"
Enter fullscreen mode Exit fullscreen mode

애플리케이션에서는 환경 변수만 참조합니다.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    token=os.environ["HF_TOKEN"]
)
Enter fullscreen mode Exit fullscreen mode

빌드 또는 테스트 중 Hugging Face 추론 API를 호출한다면 Apidog에서 토큰을 환경 변수로 저장하고 요청 시 베어러 토큰으로 전달할 수 있습니다. 이렇게 하면 저장된 요청에 비밀 값이 직접 노출되지 않고, 토큰 교체 후 환경 변수 한 곳만 갱신하면 됩니다.

토큰 교체 검증은 다음 순서로 수행하세요.

  1. 새 토큰으로 요청을 실행합니다.
  2. 정상 응답을 확인합니다.
  3. 이전 토큰으로 동일한 요청을 실행합니다.
  4. 이전 토큰이 401 또는 403을 반환하는지 확인합니다.

베어러 토큰의 동작 방식은 기본 인증 vs 베어러 토큰에서 확인할 수 있습니다.

관련 자료:

자주 묻는 질문

영향을 받지 않았다면 토큰을 교체해야 하나요?

네. Hugging Face는 모든 사용자에게 토큰 교체를 권고했습니다. 사고 이후에는 공격자가 어떤 자격 증명을 읽었는지 완전히 확인하기 어렵습니다. 토큰 교체 비용은 낮지만, 기존 토큰이 안전하다고 가정하는 위험은 큽니다.

내 토큰이 다른 사람에 의해 사용되었는지 어떻게 알 수 있나요?

액세스 토큰 목록, 최근 커밋, 조직 변경 사항, 청구 내역, 연결된 앱을 검토하세요. Hugging Face는 개인 계정에서 토큰별 전체 감사 추적을 제공하지 않으므로, 사고 환경과 연결된 토큰은 의심스러운 것으로 간주하고 교체하는 것이 안전합니다.

토큰을 교체하면 스크립트가 작동하지 않게 되나요?

새 토큰으로 업데이트하기 전까지는 작동하지 않을 수 있습니다. 기존 토큰을 사용하는 스크립트, 노트북, 컨테이너, CI 작업은 모두 새 값을 참조해야 합니다. 따라서 앱별 또는 워크로드별로 토큰을 분리하는 것이 좋습니다.

read 토큰과 fine-grained 토큰 중 무엇을 사용해야 하나요?

간단한 개인 다운로드와 추론 작업에는 read 토큰을 사용할 수 있습니다. 프로덕션, CI/CD, 공유 환경에는 특정 리소스와 권한으로 범위를 제한할 수 있는 fine-grained 토큰을 사용하세요.

새 토큰은 어디에 저장해야 하나요?

비밀 관리자 또는 환경 변수에 저장하세요. 소스 코드, Notebook 셀, 공유 문서, API 컬렉션, Dockerfile에 직접 저장하면 안 됩니다. 한 곳에 안전하게 저장하고 애플리케이션과 자동화 작업에서는 해당 값을 참조하도록 구성하세요.

Top comments (0)