토큰 분류 및 강화

• OAuth 본문 키(access_token, refresh_token, id_token) 및 쿠키 이름 휴리스틱이 토큰 유형을 결정합니다.
• Microsoft 세션 쿠키(ESTSAUTH, ESTSAUTHPERSISTENT, ESTSAUTHLIGHT, SignInStateCookie)는 리프레시와 동등한 토큰으로 명시적으로 인식됩니다(그렇지 않으면 일반 "auth" 쿠키 힌트로 잘못 분류됨).
• JWT 클레임(헤더 + 페이로드)이 디코딩되어 그대로 저장됩니다 — 절대 잘리지 않습니다.
• Microsoft FOCI(클라이언트 ID 계열)는 토큰 엔드포인트 응답의 foci 필드를 통해 감지됩니다.
• Microsoft BroCI / 중첩 앱 인증은 요청 본문의 brk_client_id, brk_redirect_uri 및 brk-<guid>:// 리디렉션 체계를 통해 감지됩니다.
• 선택적 --enrich 플래그는 https://entrascopes.com/에서 firstpartyscopes.json 및 resources.json을 가져와 appid / azp / aud GUID를 클릭 가능한 링크가 있는 친숙한 이름으로 확인합니다.

대시보드 카드

• 요약 타일 — 토큰 수, 호스트, 교환(FOCI / BroCI 콜아웃 포함) 및 강화 상태 표시기.
• 사용자 — upn / preferred_username / unique_name / email / name별 토큰 버킷팅, sub@iss 또는 oid로 폴백하며 앱 전용 및 알 수 없는 ID 버킷을 별도로 표시합니다. 각 ID 행은 사용자가 ≥2개의 source_tag에 나타날 때 캡처 배지를 표시하고(교차 캡처 생존, 핵심 --append 연구 신호) first_seen → last_seen 범위와 해당 사용자의 모든 토큰을 시퀀스 다이어그램 탭에서 강조하는 타임라인 버튼을 표시합니다.
• 토큰 유효성 — 현재 유효한 액세스 토큰과 만료된 액세스 토큰 수, 리프레시 토큰 만료 상태(불투명 토큰의 경우 "만료 알 수 없음") 및 30초 자동 새로고침이 있는 상위 3개 "다음 만료" 목록.
• 클라이언트 — 교환에 나타난 모든 고유 앱(appid / azp / 폼 본문 client_id / brk_client_id / brk_nested_id)에 FOCI / 브로커 가능 / 브로커 / 중첩 배지 표시.
• 대상(audience) — 관찰된 모든 aud 클레임을 가능한 경우 entrascopes 리소스 이름으로 확인.
• 테넌트 — 토큰 / 사용자 / 앱 수가 있는 고유 tid 값.
• 호스트 — 호스트별 이벤트, 고유 베어러 수신자, 고유 발급자 및 교환 수.
• 권한 있는 범위 및 역할 — 각 토큰의 scp / scope / roles를 선별된 고영향 Microsoft Graph 권한 및 Azure 리소스 범위 목록과 대조.
• 대상 / 호스트 불일치 — 토큰이 aud 클레임과 일치하지 않는 호스트에서 사용된 모든 (토큰, 호스트) 쌍을 플래그(자격 증명 유출 또는 오용 시사).
• 인증 방법(amr) — pwd / mfa / pop / smartcard 분포.
• 보안 기능 — 지속적 액세스 평가(xms_cc=CP1), 소유 증명 바인딩 (cnf 클레임, 대상 간 공유 kid 감지 포함), 단계 상승 인증 요구 사항 (acrs) 및 acr 인증 컨텍스트 수준을 플래그합니다. 각 행은 클릭 가능하며 해당 마커를 가진 토큰만 표시하도록 토큰 탭을 필터링합니다.
• 리프레시 토큰 체인 — 교환 엣지를 탐색하여 회전 계보, 가장 긴 체인 길이 및 유휴 리프레시 토큰을 식별합니다. 각 체인은 Δ 범위 열(홉 간 추가 / 제거된 범위, 호버 시 전체 홉별 차이 표시)을 표시하고 추가된 범위가 권한 있는 범위 워치리스트와 일치하는 체인에 ⚠ priv 배지를 플래그합니다 — FOCI / BroCI 스타일 권한 확장 연구 신호.
• 소스 — 각 수집 패스에서 온 행 수를 확인할 수 있는 source_tag별 토큰 수.

토큰 / 교환 탭

• 열 헤더를 클릭하여 정렬.
• 다중 선택 체크박스가 도구 모음을 구동:
  • 그래프에서 강조 — 선택한 노드에 노란색 강조.
  • 그래프에서 격리 — 선택한 토큰과 교환하는 토큰만 표시하도록 다이어그램 다시 그리기.
  • 시퀀스에서 표시 — 선택한 토큰에 대한 집중 시퀀스 다이어그램.
• 행을 클릭하면 전체 JWT 헤더 + 페이로드(원시 JSON), 모든 이벤트, 관련 교환, 재생 준비 완료 내보내기 버튼(원시 / Bearer / curl / JSON / roadtx 토큰 캐시) 및 roadtx describe, roadtx auth, curl, Python requests, PowerShell Invoke-RestMethod용 복사-붙여넣기 스니펫이 있는 명령 미리보기 블록이 포함된 인라인 패널이 확장됩니다.
• 필터: 유형 칩(액세스 / 리프레시 / ID / 알 수 없음), 형식 칩 (jwt / 불투명), 사용됨 / 사용 안 됨 드롭다운, 유효성 드롭다운 (모두 / 유효 / 만료 / 만료 알 수 없음), FOCI 전용, BroCI 전용, 앱 일치 있음, 리소스 일치 있음, 그리고 fp / 샘플 / 클레임 / 호스트 / 앱 / 리소스 / source_tag / 사용자에 대한 자유 텍스트 검색.
• 현재 필터링 + 정렬된 행의 CSV / JSON 내보내기.
• URL 해시 영속성 — 활성 탭과 모든 필터 상태가 URL 해시에 직렬화되어 특정 필터링된 보기에 대한 링크를 공유할 수 있습니다.

WebSocket 지원

• mitmproxy 및 CDP 캡처는 모든 WebSocket 텍스트 / 바이너리 프레임 페이로드를 보존합니다. 프레임 내용은 HTTP 본문을 처리하는 것과 동일한 JSON / 폼 / 원시 JWT 워커로 토큰을 검색합니다.
• 프레임에서 발견된 토큰은 역할 ws-frame-sent / ws-frame-received, 소스 ws[body_json[<key>]] 및 하나의 WebSocket 연결 내의 모든 프레임을 그룹화하는 ws_session_id로 이벤트를 생성합니다.
• 핸드셰이크는 일반 HTTP 이벤트로 캡처되어 업그레이드에 전달된 쿠키 / 베어러 토큰도 추적됩니다.

개인정보 보호

• 데이터베이스는 SHA-256 지문(처음 12자리 16진수)과 관찰된 모든 토큰의 12자리 접두사를 저장합니다. 전체 토큰 문자열은 입력 파일을 벗어나지 않습니다.

• 디코딩된 JWT 클레임 내용(헤더 + 페이로드, oid, sub, upn, email, tid, 범위 목록 등 포함)은 분석의 핵심이므로 기본적으로 그대로 저장됩니다. JWT가 있을 때마다 데이터베이스와 공유된 대시보드 URL을 민감한 것으로 취급하세요.

• --redact-claims(ingest, mitm, cdp에서 사용 가능)는 나열된 클레임 값을 데이터베이스에 저장되기 전에 안정적인 해시 자리 표시자로 대체합니다. 기본 필드 목록은 sub, oid, upn, email, name, unique_name, preferred_username, emails, mail, ipaddr, given_name, family_name을 포함합니다. 기본값을 재정의하려면 명시적인 쉼표로 구분된 목록(예: --redact-claims sub,upn,oid)을 전달하세요. 동일한 입력은 항상 동일한 자리 표시자로 매핑되므로 사용자를 공개하지 않고도 대시보드의 사용자 / 테넌트 그룹화가 계속 작동합니다.

• --store-tokens(ingest, mitm, cdp에서 사용 가능, 기본적으로 꺼짐)은 전체 토큰 문자열을 데이터베이스에 기록하여 대시보드가 다음을 제공할 수 있게 합니다:

  • 원시 복사 / Bearer 복사 / curl 복사 작업.
  • 토큰 JSON 다운로드(원시 + 클레임 + 관찰된 이벤트).
  • roadtools 토큰 캐시로 복사 / 다운로드(파일을 .roadtools_auth에 넣으면 모든 roadtx 하위 명령이 이를 인식).
  • 토큰의 실제 tid, appid 및 aud 클레임을 사용하여 가장 일반적인 재생 호출 — roadtx describe, roadtx auth, curl, Python requests, PowerShell Invoke-RestMethod —을 미리 채우는 토큰별 블록.

설치

요구 사항

• Python 3.10+ (match 문 호환 유형 구문 및 최신 dataclasses 사용). 3.12에서 테스트됨.
• 빌드 단계 없음. 저장소를 클론하고 python -m tats를 직접 실행하세요.

선택적 종속성

빠른 설치

체크아웃에서 실행(설치 없음):```bash git clone tats cd tats python -m tats --help

설치 후에는 짧은 이름으로 도구를 호출할 수 있습니다:```bash tats ingest engagement.xml -o tokens.db --enrich tats serve tokens.db

하나의 DB에 Burp 캡처와 mitmproxy 플로우 파일을 결합하세요:```bash tats ingest engagement.xml -o tokens.db --enrich tats mitm chat-session.mitm -o tokens.db --enrich --append tats serve tokens.db

실행된 브라우저는 cdp 명령에서 Ctrl-C를 누르면 종료되고 임시 프로필이 삭제됩니다.

이미 실행 중인 브라우저에 연결하려면 --remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile로 시작한 다음 --launch-chrome 없이 cdp를 실행하세요.

공유 전 데이터베이스 정리(PII(개인 식별 정보) 삭제):```bash tats ingest engagement.xml -o tokens.db
--enrich --redact-claims

every sub / oid / upn / email / name / unique_name / preferred_username

(and a few related claims) is replaced with a stable hash placeholder

예시:```bash

fresh DB, with Microsoft enrichment

tats ingest burp.xml -o tokens.db --enrich

add another Burp export to an existing DB without losing the first one

tats ingest day2.xml -o tokens.db --append
--source-tag burp:day2

pip install mitmproxy가 필요합니다. 패키지가 없으면 도구가 명확한 오류를 출력합니다.

mitmproxy로 플로우 파일을 캡처하세요:```bash mitmdump -w session.mitm

... drive the browser ...

Ctrl-C to stop

tats mitm session.mitm -o tokens.db --enrich

도구가 브라우저를 실행하도록 하기 (--launch-chrome)```bash

auto-detect Chrome / Edge / Chromium / Brave

tats cdp -o tokens.db --launch-chrome

explicit path (useful for non-default installs / sandboxed builds)

tats cdp -o tokens.db
--launch-chrome /opt/google/chrome-canary/chrome

별도의 user-data-dir을 사용하면 개인 프로필에 붙지 않으며, 실행 중인 브라우저가 디버그 플래그를 거부하는 것을 방지합니다.

기본적으로 cdp는 브라우저 수준에서 연결되며, 시작 시 존재하는 모든 탭과 실행 중에 열린 모든 탭(window.open, Ctrl-클릭, 새 탭 버튼)을 추적합니다. 모든 탭은 CDP 플랫 프로토콜 세션 멀티플렉서를 통해 단일 WebSocket을 공유하므로, 캡처 실행 중 탭을 열거나 닫는 것이 완전히 지원됩니다. 각 탭의 연결 / 해제는 INFO 수준에서 stderr에 한 줄 메모로 출력됩니다.

단일 탭에 고정하고 해당 탭이 닫힐 때 연결이 종료되도록 하려면, 사용 가능한 대상을 나열하세요:```bash curl http://127.0.0.1:9222/json/list

예시:```bash

default — opens a browser tab automatically

tats serve tokens.db

bind to a different port without auto-launching the browser

tats serve tokens.db --port 9000 --no-browser

(do this only on a trusted network — no auth)

tats serve tokens.db --host 0.0.0.0

모든 소스 경로는 동일한 Tracker 객체를 생성합니다. ingest_to_db는 이를 데이터베이스의 행으로 변환합니다. Store는 HTTP 서버를 위해 데이터베이스를 읽으며, 서버는 /api/data, /api/meta, /api/token/<fp>, /api/export, /api/graph, /api/sequence를 통해 JSON을 노출합니다.

데이터베이스 스키마 (v4)

• tokens (기본 키 fp) — 지문, 샘플 접두사, 유형, 형식, 관찰된 수명, JWT 헤더/페이로드(JSON), 보강 필드, 파생 필드(user_identity, exp_unix, tenant_id, scopes_text), 쉼표로 구분된 source_tag, raw(전체 토큰 문자열, --store-tokens로 수집하지 않으면 NULL), 그리고 security_features(감지된 CAE / PoP / step-up 마커를 설명하는 압축 JSON — 보안 기능 카드 참조). 이전 v2 / v3 데이터베이스는 추가 모드로 다시 열면 자동 마이그레이션됩니다: v2 → v3은 nullable raw 열을 추가하고, v3 → v4는 nullable security_features 열을 추가하고 첫 열기 시 각 토큰의 저장된 jwt_payload_json에서 이를 역채웁니다. 기존 행은 두 열 모두 이전 값을 유지합니다.
• events — 관찰된 모든 토큰 상호작용: HTTP 요청/응답 또는 WebSocket 프레임. 역할: issued / returned / presented / used / exchanged-in / ws-frame-sent / ws-frame-received. 연결 내 프레임 그룹화를 위한 ws_session_id를 포함합니다.
• exchanges — 토큰 엔드포인트에 대한 토큰 포함 요청이 응답에서 새 토큰을 생성한 경우. FOCI / BroCI 메타데이터를 기록합니다.
• exchange_inputs, exchange_outputs — 각 교환의 양쪽에 있는 토큰 지문.
• hosts — 고유한 host:port 레이블.
• meta — 스키마 버전, 소스 목록, generated_at, last_modified(대시보드의 실시간 폴링에 사용), 카운트.

소스 태깅 및 추가 모드

DB에 기록되는 모든 행은 source_tag를 포함합니다 — 기본적으로 burp:<filename>, mitm:<filename>, 또는 cdp:<host>:<port>이며, --source-tag로 재정의할 수 있습니다. 동일한 지문이 둘 이상의 수집 패스에서 관찰되면 source_tag 필드는 쉼표로 구분된 목록으로 누적되므로, 대시보드의 소스 카드가 모든 토큰의 출처를 표시할 수 있습니다.

--append는 기존 DB를 유지하고 토큰에 대해 UPSERT(사용 횟수 + 관찰된 수명 누적, 알 수 없는 유형 업그레이드)로 병합하며, 이벤트/교환에 대해 INSERT(기존 최대값을 넘어 seq 번호를 오프셋하여 활동 타임라인이 단조롭게 유지됨)로 병합합니다. 스키마 버전 불일치는 자동 병합을 거부하여 조용한 데이터 손실을 방지합니다.

실시간 업데이트

웹 서버의 /api/meta 엔드포인트는 meta 테이블(약 200바이트)을 반환합니다. 대시보드는 5초마다 이를 폴링하고 last_modified가 변경된 경우에만 전체 /api/data를 다시 가져옵니다. cdp 수집 경로는 기본적으로 25개 이벤트마다 인메모리 트래커를 DB로 플러시하므로, 브라우저 요청에서 대시보드 업데이트까지의 실제 경과 시간은 일반적으로 10초 미만입니다.

제한 사항

• Burp .burp 프로젝트 파일은 지원되지 않습니다. 도구가 사용하는 XML을 생성하려면 Save items를 사용하세요.
• 프록시 CA 관리 없음. 이 도구는 TLS를 자체적으로 가로채지 않습니다. Burp / mitmproxy 하위에서 사용하거나, 브라우저 내부에서 TLS 복호화된 트래픽을 보는 CDP 경로를 사용하세요.
• CDP 연결은 최상위 페이지 대상을 다룹니다. OOPIF(Out-of-process iframe)와 전용 워커는 재귀적으로 자동 연결되지 않으므로, 해당 대상 유형을 통과하는 이벤트는 누락될 수 있습니다. 이 도구가 구축된 Microsoft / OAuth 흐름의 경우 최상위 페이지 연결이 중요한 모든 것을 포착합니다.
• JWT에 대한 서명 검증 없음. 도구는 표시를 위해 클레임을 디코딩합니다. 서명 확인, alg=none, 키 혼동 공격은 범위 밖입니다. 이러한 경우 전용 JWT 감사 도구를 사용하세요.
• 불투명 토큰 오탐. "이것이 토큰인가?" 휴리스틱은 OAuth 형태의 컨텍스트에서 20자 이상의 URL 안전 문자열을 토큰으로 취급합니다. 긴 임의 ID가 잘못 플래그될 수 있습니다. 유형을 추론할 수 없는 토큰은 unknown으로 끝나며, (Burp 전용) 이전 플래그에 --include-unknown이 설정되지 않는 한 기본적으로 숨겨집니다.
• --enrich는 아웃바운드 HTTP 요청을 수행합니다 https://entrascopes.com/로. 환경이 이를 허용하지 않으면 플래그를 건너뛰세요.
• 웹 UI에는 인증이 없습니다. 다른 인증 계층을 앞에 두지 않는 한 localhost에 바인딩하세요.

문제 해결

개발

스모크 테스트 픽스처

두 개의 픽스처 빌더가 examples/에 있습니다:```bash

Burp XML fixture (HTTP-only, includes FOCI + BroCI exchanges)

python examples/make_fixture.py examples/fixture.xml tats ingest examples/fixture.xml -o tokens.db --enrich

mitmproxy flow fixture (HTTP + WebSocket frames carrying tokens)

python examples/make_mitm_fixture.py examples/fixture.mitm tats mitm examples/fixture.mitm -o tokens.db --enrich --append

이 스위트는 토큰 추출, JWT 파싱, Microsoft 세션 쿠키 분류, FOCI / BroCI 탐지, 클레임 요약, PII(개인 식별 정보) 마스킹, 추가 모드 UPSERT 의미론을 갖춘 Burp XML 수집 경로, 그리고 mitmproxy WebSocket 프레임 수집 경로(선택적 mitmproxy 의존성이 없을 때 자동으로 건너뜀)를 포함합니다.```text $ pytest tests/ ============================= test session starts ============================= … ======================== 62 passed in 1.4s =================================

…그리고 http://127.0.0.1:8765를 수동으로 엽니다. 서버는 모든 요청과 핸들러 오류를 stderr에 기록합니다.

파일 구조

단일 파일 구조는 의도적입니다. 이 도구는 Python이 설치된 누구나 읽고, 감사하고, 조사에 바로 투입할 수 있도록 설계되었습니다. 숨겨진 설정도, 평가할 의존성 트리도, 파일 자체 외의 다른 표면도 없습니다.

이 README 유지 관리

하위 명령, 스키마, 대시보드 카드 또는 공개 API 표면(CLI 플래그, /api/* 엔드포인트)을 변경하는 경우, 같은 변경에서 이 파일의 관련 섹션도 업데이트하세요. 가장 오래될 가능성이 높은 섹션:

• 기능 — 수집 소스 또는 대시보드 카드를 추가할 때
• 하위 명령 — 플래그를 변경할 때
• Microsoft 전용 지원 — 탐지 로직이 변경될 때
• 아키텍처 — 스키마 또는 실시간 업데이트 흐름이 변경될 때
• 문제 해결 — 새 오류 메시지가 추가될 때

라이선스

GNU General Public License v3.0 이상 — 전체 텍스트는 저장소 루트의 LICENSE 파일에 있습니다. 스크립트 소스에는 동일한 파일을 가리키는 표준 짧은 헤더가 포함되어 있습니다.

GPL v3(또는 선택에 따라 이후 버전)의 조건에 따라 이 도구를 재배포 및/또는 수정할 수 있습니다. 이 도구는 어떠한 보증도 없이 배포됩니다. 전체 조건은 LICENSE를 참조하세요.

이 기능을 활성화하면 데이터베이스가 일괄 자격 증명이 됩니다 — 캡처된 세션을 재생하는 데 필요한 모든 바이트가 포함됩니다. --redact-claims와 결합하여 디코딩된 JWT 보기를 정리할 수 있지만 원시 토큰에는 여전히 수정되지 않은 클레임이 인코딩되어 있다는 점을 인지하세요. 플래그가 꺼져 있을 때 대시보드의 명령 미리보기 블록은 여전히 렌더링되며 <TOKEN>을 자리 표시자로 사용하여 구문 참조로 작동합니다; 내보내기 버튼은 재수집을 위한 힌트를 렌더링합니다.