Claude File API로 GWS 감사 로그를 대화형으로 분석하기

Claude의 Files API(베타 기능, 2025년 4월 공개)는 파일을 한 번 업로드하면 동일 워크스페이스 내의 여러 API 요청에서 재사용할 수 있는 구조입니다. 이 기사에서는 GWS(Google Workspace) 감사 로그 CSV를 File API로 대화형으로 분석하는 설계 패턴과 Batch API와의 선택 기준을 정리합니다.

• GWS 관리 콘솔의 감사 로그를 매달 수동으로 확인하고 Excel로 정리하는 정보 시스템(情シス) 담당자
• Claude API를 사용한 감사 로그 분석에 관심이 있지만, Batch API의 잡(Job) 설계는 진입 장벽이 높다고 느끼는 분
• 이번 달 로그를 간편하게 심층 분석한 뒤, 자동화 설계는 나중에 고민하고 싶은 분

GWS 감사 로그를 Claude로 분석할 경우, 크게 두 가지 접근 방식이 있습니다.

먼저 Batch API부터 정리하겠습니다. 전월분 로그를 월초에 일괄 투입하여 다음 날 아침에 결과를 받는 비동기 처리 방식입니다. Anthropic 공식 문서에 따르면 표준 API 비용의 50%로 이용할 수 있어, 정형화된 월간 보고서 자동화에 적합합니다. DRASENAS에서는 'Claude Batch API로 GWS 감사 로그를 월간 분석하기'에서 설계 절차를 해설하고 있습니다.

반면, File API가 적합한 경우는 "이번 달 5월분 로그에 권한 변경이 많다. 대상은 누구인가? 시간대는? 업무 시간 외의 기록도 포함되어 있는가?"와 같이 연속적인 질문으로 심층 탐구하는 탐색 단계입니다. 잡(Job) 관리는 필요 없으며, 그 자리에서 CSV를 업로드하고 질문을 거듭하는 것만으로 시작할 수 있습니다.

두 가지 접근 방식은 서로 경쟁하는 관계가 아니라, 탐색과 자동화를 보완하는 관계로 사용하는 것이 실무적입니다. 예를 들어, Batch API의 정기 보고서에서 "권한 변경이 전월 대비 2배"라는 수치가 나온 달에, File API를 사용하여 "내역은? 누가 무엇을 변경했는가? 업무 시간 외의 조작이 있었는가?"라고 파고드는 조합을 생각할 수 있습니다. 심층 분석 결과 "이 확인 작업은 매달 패턴화할 수 있다"라고 깨달은 것부터 Batch API의 잡(Job)으로 이식해 나가는 것이 무리 없는 자동화 진행 방식입니다.

관점	File API	Batch API
처리 타이밍	실시간 (동기)	비동기 (최대 24시간)
...
탐색 결과 "이 확인은 패턴화할 수 있다"라고 판단되면, Batch API로 자동화에 이행하는 것이 실무적인 흐름입니다.

File API로 분석하려면 먼저 관리 콘솔에서 감사 로그를 CSV로 내보내기(Export) 합니다. 관리 콘솔의 「보고서」 섹션에서 대상 로그 유형(로그인·관리·Drive·그룹 등)을 선택하고, 기간을 지정하여 내보내기를 실행합니다.

로그 유형별로 별도 파일로 내보내기 됩니다. 분석 대상이 「로그인 이상 + 권한 변경」과 같이 여러 유형에 걸쳐 있는 경우, 분석 초기에 Claude에게 "이 CSV의 컬럼 구성을 알려줘"라고 물으면, 열 이름과 앞부분 몇 줄을 파악한 후 다음 질문에 답해줍니다. 사전에 구조를 확인한 뒤 프롬프트(Prompt)를 구성하면 열 이름 지정이 어긋나는 실수를 방지할 수 있습니다.

대량의 이벤트가 발생한 달은 파일 하나당 20,000행을 넘을 수 있습니다. 내보내기 시 기간을 2주 단위로 분할하거나, 이벤트 유형별로 필터링하여 다운로드해 두면, 후술할 컨텍스트 윈도우(Context Window) 상한 문제를 사전에 회피할 수 있습니다.

File API의 핵심은 "파일을 한 번 업로드하여 file_id로 참조할 수 있다"는 점입니다. 동일한 CSV에 대해 5개의 질문을 던져도, CSV 자체의 업로드는 1회로 충분합니다.

CSV는 네이티브 「document」 블록 형식을 지원하지 않으므로, 텍스트(text/plain)로 변환하여 업로드합니다. 취득한 file_id를 각 메시지에서 참조하면 파일 내용이 입력 토큰(Input Token)으로 처리됩니다.

파일 작업별 비용은 Anthropic의 공식 문서에 명시되어 있습니다.

• 업로드·삭제·목록 취득: 무료
• 메시지 내에서 파일 내용을 참조한 부분: 입력 토큰으로 과금

file_id는 업로드 시 API로부터 반환되는 랜덤 식별자입니다. 동일한 세션 내라면 변수에 보관하는 것만으로 몇 번이고 재사용할 수 있습니다. 세션을 넘어 재사용하고 싶다면 별도로 파일이나 데이터베이스에 file_id를 저장해 두어야 합니다. 매달 동일한 CSV를 여러 분석 세션에서 참조한다면, 세션 시작 시 client.beta.files.list()를 사용합니다.

기존 파일을 확인한 후 재업로드할지 여부를 결정하는 구현 방식도 하나의 선택지가 될 수 있습니다.

파일은 워크스페이스 내에 삭제하기 전까지 무기한 남습니다. 테스트용 파일이나 지난달의 로그가 축적되지 않도록, 분석 세션 마지막에 삭제하는 처리를 스크립트에 포함해 두는 운영 방식을 권장합니다.

다음은 "CSV를 업로드하고, 여러 질문을 연속해서 던지는" 최소 구성입니다. anthropic 라이브러리(pip install anthropic)와 환경 변수 ANTHROPIC_API_KEY가 전제 조건입니다.

CSV 본문을 io.BytesIO로 바이트 열(byte sequence)로 변환하여 업로드하는 점과, 메시지의 content에 document 블록을 추가하여 file_id를 참조하는 점이 일반적인 messages API와 다른 부분입니다.

import io
import anthropic
client = anthropic.Anthropic()
...

betas=["files-api-2025-04-14"]는 Files API가 베타 기능이기 때문에 필수적인 파라미터입니다. 이 파라미터가 없으면 API 호출 시 에러가 발생합니다. CSV를 그대로 application/csv로 전달하려고 해도 문서 블록(document block)으로 받아들여지지 않으므로, text/plain으로 변환하여 업로드해야 한다는 점에 주의하십시오.

위의 샘플에서는 질문마다 독립적인 API 요청을 보내고 있습니다. 이전 답변을 바탕으로 더 깊이 있게 탐색하고 싶다면, messages 리스트에 어시스턴트의 답변을 추가하며 대화를 쌓아가는 멀티턴 (multi-turn) 형식으로 변경합니다. 다만, 멀티턴 방식을 사용하면 과거의 대화 내용이 축적되어 토큰(token) 수가 증가합니다. 탐색의 첫 단계는 위와 같은 독립 요청 형식으로 시작하고, 관심 있는 부분만 멀티턴으로 심층 분석하는 것이 효율적인 진행 방식입니다.

GWS 감사 로그의 월간 확인 시 자주 사용하는 프롬프트 3가지를 제시합니다. 도메인 이름이나 판정 기준은 조직의 정책에 맞춰 수정하여 사용하십시오.

관리자 권한 변경은 부정 액세스나 내부자 리스크(insider risk)를 조기에 발견하는 것과 직결되는 이벤트입니다. 동일 사용자에게 반복적인 권한 변경이 일어나는 것은 설정 실수(misconfiguration)의 반복이나 의도적인 조작 은폐를 나타낼 수 있습니다. "반복 있음" 플래그를 세우면 후속 조치가 필요한 케이스를 한눈에 추려낼 수 있습니다.

이 CSV에서 관리자 권한(슈퍼 관리자, 대리 관리자, 그룹 관리자)의
추가 또는 삭제가 수행된 이벤트를 모두 추출해 주세요.
날짜, 작업자, 대상 사용자를 Markdown 표 형식으로 출력하고,
...

업무 시간 외의 로그인은 계정 탈취나 의심스러운 내부 조작의 신호가 됩니다. 산발적인 심야 로그인은 정규 야근이나 해외 출장 때문일 수도 있지만, 동일 사용자가 3일 이상 연속해서 심야에 접속하는 경우에는 해당 사용자에 대한 인터뷰와 해당 기간의 액티비티(activity) 확인을 우선적으로 수행하는 것이 효율적입니다.

이 CSV의 로그인 이벤트 중, 22시~익일 06시(일본 표준시 JST)에
발생한 것을 추출해 주세요.
사용자 이메일 주소, 일시, IP 주소 목록을 작성하고,
...

외부 도메인으로의 파일 공유가 집중되는 패턴은 정보 유출 리스크의 지표가 됩니다. 퇴직 직전의 조작이나 특정 외부 위탁 업체로의 집중 공유 등도 이 패턴을 통해 발견할 수 있습니다. "5건 이상"이라는 임계값(threshold)은 조직의 규모나 업태에 맞춰 조정하십시오.

이 CSV에서 자사 도메인(@company.com) 이외의 파일 공유 및
권한 부여 이벤트를 모두 추출해 주세요.
공유자, 대상 파일, 외부 도메인, 일시를 표로 나타내고,
...

모두 "추출 → 플래그 지정 → 우선순위 표시"라는 구성입니다. 첫 번째 질문으로 전체상을 파악하고, 다음 질문으로 플래그가 표시된 대상을 심층 분석하는 방식이 실무에 적합합니다. Claude의 출력은 Markdown 표 형식으로 반환되는 경우가 많으므로, 그대로 월간 보고서에 붙여넣는 자료로 사용할 수 있습니다.

GWS 관리 콘솔에서 내보낸 감사 로그 CSV의 토큰 수는 열(column) 수와 값의 길이에 따라 달라집니다. 1행당 약 100~150자 정도를 기준으로 할 때, 규모별 대략적인 수치는 다음과 같습니다.

테이블

로그 규모	예상 입력 토큰	claude-haiku-4-5 (200K 윈도우)
5,000행	약 12만~19만 토큰	컨텍스트 내에 수용 가능
20,000행	약 48만~75만 토큰	초과할 가능성 있음

5,000행 규모는 claude-haiku-4-5의 컨텍스트 윈도우(200K 토큰)에 수용됩니다. 20,000행은 초과하는 경우가 있으므로, 이벤트 유형별(로그인/권한 변경/공유 작업) 또는 기간별로 분할하여 분석하는 설계가 필요합니다.

비용을 더욱 절감하는 관점에서는 Files API × Prompt Caching의 조합이 효과적입니다. 동일 파일을 여러 번 참조하는 세션에서는, Prompt Caching이 유효할 경우 캐시 히트분 입력 토큰 비용을 대폭 줄일 수 있습니다. Files API와 Prompt Caching을 결합한 설계의 자세한 내용은 GWS 감사 로그의 Prompt Caching 설계에서 비용 절감 측면으로 설명하고 있습니다.

모델 선택 또한 비용에 영향을 미칩니다. 탐색 단계의 첫 번째 순회는 claude-haiku-4-5(저비용/고속)로 전체적인 그림을 파악하고, 심층 분석이 필요한 부분만 claude-3-5-sonnet으로 전환하는 것이 정확도와 비용 사이에서 균형을 잡기 쉬운 운영 방식입니다. 구체적인 API 요금은 채택하는 모델과 토큰 수에 따라 달라지므로, Anthropic 공식 가격 페이지에서 최신 요금을 확인해 주십시오.

실제 사용을 시작하기 전에 다음 4가지를 확인하십시오.

지원 플랫폼: Files API는 Amazon Bedrock과 Google Cloud(Vertex AI)에서는 사용할 수 없습니다. Anthropic 직접의 API 엔드포인트, Claude Platform on AWS, 또는 Microsoft Foundry가 대상입니다 (Anthropic 공식 문서 참조). 현재 개발 환경이 Bedrock 경유인 경우, 사용하기 전에 엔드포인트 전환이 필요합니다.

파일 영속성 및 관리: 업로드한 파일은 명시적으로 삭제할 때까지 워크스페이스에 남아 있습니다. 월간 분석 후 삭제를 스크립트의 최종 단계로 포함시켜 주십시오. 여러 담당자나 스크립트가 API를 사용하는 환경에서는 어떤 파일을 누가 업로드했는지 구분하기 어려워지기 쉬우므로, 파일명에 업로드일이나 목적을 포함하는 명명 규칙을 정해두면 관리가 용이합니다.

개인정보 처리: 감사 로그에는 이메일 주소 및 IP 주소가 포함됩니다. Anthropic의 데이터 보존 정책과 사내 보안 정책을 대조한 후 사용을 시작하십시오. 특히, 외부 클라우드 API로 전송하는 데이터 범위에 대해서는 정보보안 담당자와 사전에 합의를 보는 것이 추후 반려되는 상황을 막을 수 있습니다.

베타 기능의 특성: 현재 시점에서는 베타 버전이므로 인터페이스나 사양이 변경될 가능성이 있습니다. 운영 흐름에 통합하기 전에 공식 문서를 통해 최신 사양을 확인해 주십시오. betas

파라미터 문자열(예: `

월간 감사 로그 확인을 "무슨 일이 생긴 뒤에 거슬러 올라가는 방식"에서 "매달 능동적으로 확인하는 방식"으로 바꾸는 것 자체가 보안 운영의 큰 진전입니다.

이 기사에서 다룬 것과 같은 업무 개선 및 자동화의 설계부터 구현까지, DRASENAS는 기업 IT (Corporate IT) 현장에 밀착하여 지원을 제공하고 있습니다.

"우선 상담만" 하는 것도 대환영입니다. DRASENAS 공식 사이트를 통해 편하게 문의해 주세요.

※ 이 기사는 DRASENAS Blog의 전재물입니다. 오리지널 게시물에서는 코드와 설정 절차가 수시로 업데이트되고 있습니다.