배포하는 게임에는 텔레메트리를 보낼 권한이 필요합니다. 빌드 비교 작업에는 그 데이터를 읽을 권한이 필요합니다. 두 작업에 같은 자격 증명을 쓰면 게임 배포 패키지에서 분석 데이터 접근 권한까지 추출될 수 있습니다.

Framedash에서는 게임에 Ingest 키를, 일반적인 분석에는 별도의 Read-only 키를 사용합니다. 두 키의 접두사는 모두 fd_입니다. 서버는 키에 저장된 scope, 즉 허용된 작업의 집합으로 권한을 확인합니다. 키 이름이나 접두사가 권한을 결정하지는 않습니다.

작업에 맞는 프리셋 선택하기

프로젝트 대시보드의 API 키 페이지에서 다음 프리셋을 선택할 수 있습니다. 아래 scope 조합은 API 개요에 명시되어 있습니다.

프리셋	저장되는 scope	용도
Ingest	`events:write`	SDK 텔레메트리 전송
Read-only	`analytics:read`	집계, 프로젝트 상태, 설정 읽기 및 빌드 비교
Read & Write	`analytics:read`, `resources:write`	읽기에 더해 맵, 콘텐츠, 알림 변경
Full	`analytics:read`, `resources:write`, `data:admin`	추가로 원시 SQL 실행, 데이터 내보내기, 플레이어 텔레메트리 삭제

Full에는 events:write가 포함되지 않습니다. 게임의 Ingest 키를 대신할 수 없습니다. 프리셋은 서로 다른 작업의 권한 조합이며, 상위 프리셋이 하위 작업을 모두 포함하는 계층 구조가 아닙니다.

원시 SQL을 사용할 때는 부여하는 권한을 주의해서 살펴봐야 합니다. SELECT로도 플레이어 단위의 행을 반환할 수 있으므로 /api/v1/query에는 data:admin이 필요합니다. 같은 scope로 내보내기와 플레이어 데이터 삭제도 할 수 있습니다. 쿼리를 실행하려고 Full을 선택하면 이 권한들까지 함께 부여합니다. 집계 API로 답을 구할 수 있으면 먼저 사용하고, 더 넓은 권한은 필요한 관리 환경의 프로세스에만 부여하세요.

키는 프로젝트에 연결됩니다. 다른 프로젝트 ID를 지정해도 그 프로젝트의 권한을 얻을 수 없습니다. scope가 있어도 계정 제한과 요청 속도 제한은 적용됩니다.

분석용 자격 증명을 배포 빌드에서 제외하기

분리된 두 경로. 배포 게임은 events:write 키만 갖고 Ingest API로 전송하며, 관리되는 분석 환경은 analytics:read 키를 보관하고 Web API에서 읽는다. 두 환경 사이에 키를 복사하지 않는다.

위쪽 경로는 SDK 이벤트를 https://ingest.framedash.dev/v1/events로 보냅니다. 아래쪽 읽기 경로는 https://app.framedash.dev/api/v1을 사용합니다. 분석용 자격 증명은 관리되는 개발 머신, 백엔드, 신뢰할 수 있는 CI 러너에 둡니다. 게임 에셋, 웹 게임의 JavaScript, 다운로드 가능한 설정, 공개 빌드 산출물에 넣지 마세요.

배포 클라이언트에 포함된 키는 추출될 수 있다고 가정해야 합니다. 값을 소스 코드에서 빌드 시점의 환경 변수로 옮겨도, 빌드가 최종 패키지에 복사한다면 비밀로 유지되지 않습니다. 난독화를 이유로 더 강한 권한의 키를 배포하지 마세요. 앱 패키지에 포함된 비밀 정보의 추출 위험은 OWASP의 설명에서도 다룹니다.

성능 검사에서는 게임 프로세스에 Ingest 키를, 비교용 CLI에는 Read-only 키를 전달합니다. 필요한 프로세스에만 자격 증명을 제공하세요. CLI의 --api-key-file로 비공개 파일을 지정하면 키 값을 명령줄 인수에 넣지 않아도 됩니다. 하지만 같은 머신이나 작업 공간의 파일을 읽을 수 있는 코드로부터 키를 보호하는 기능은 아닙니다.

노출된 Ingest 키로도 가능한 작업

Ingest 키로 분석 데이터를 읽거나 맵을 수정하거나 기존 플레이어 텔레메트리를 삭제할 수는 없습니다. 그러나 해당 프로젝트에 이벤트를 보낼 수는 있습니다. 키를 추출한 사람은 수집 서비스가 허용하는 형식과 제한 안에서 허위 텔레메트리를 전송할 수 있습니다.

허위 이벤트는 측정 결과를 오염시키고 수집 처리 용량이나 이벤트 할당량을 소모할 수 있습니다. API 키는 전송 자격 증명의 권한을 확인할 뿐입니다. 프레임 시간 샘플이 수정되지 않은 게임의 실측값인지, 주장하는 플레이어 ID나 빌드 ID가 진짜인지는 증명하지 않습니다. 수집 전용 권한만 부여해도 허위 이벤트 전송을 막을 수는 없습니다.

출시 판단에 사용하는 통제된 테스트 결과는 가능하면 공개 클라이언트의 텔레메트리와 분리하세요. 격리가 필요하면 프로젝트를 나누는 방법이 있습니다. 클라이언트가 제출하는 빌드 ID만 바꾸는 것은 출처를 검증하는 방법이 아닙니다. 예상 밖의 급증은 자체 러너 기록과 대조하세요. 더 강한 출처 검증이 필요한 위협 모델이라면 관리하는 백엔드에 검증 절차를 설계해야 합니다. 키 분리만으로는 이 검증이 제공되지 않습니다.

CI와 에이전트가 접근할 범위 제한하기

CI 시크릿을 전달받은 코드는 그 값을 사용할 수 있습니다. 분석용이나 관리용 키를 읽을 수 있는 작업에서 신뢰하지 않는 풀 리퀘스트 코드를 실행하지 마세요. GitHub의 보안 사용 지침은 신뢰하지 않는 코드의 체크아웃, 스크립트 인젝션, 로그 마스킹의 한계를 다룹니다. 워크플로 변경을 검토하고 권한이 있는 분석 작업과 신뢰하지 않는 빌드를 분리하세요.

분석 에이전트에는 먼저 analytics:read와 조사에 필요한 도구만 제공합니다. 텔레메트리 문자열, 저장소 파일, 도구 결과는 신뢰하지 않는 입력으로 취급하세요. 그 안에 적힌 지시를 근거로 비밀 정보에 접근하거나, 자격 증명을 다른 곳으로 보내거나, scope를 확대해서는 안 됩니다. 키를 프롬프트나 도구 출력에 붙여 넣지 마세요.

최소 권한은 잘못된 도구 호출로 수행할 수 있는 작업을 제한합니다. 그래도 Read-only 키로 프로젝트 정보를 읽을 수 있으므로 에이전트가 결과를 보낼 수 있는 목적지도 관리해야 합니다. “데이터를 수정하지 마세요”라는 프롬프트는 서버가 적용하는 scope 제한을 대신하지 못합니다.

테스트 이벤트 없이 키 확인하기

GET https://app.framedash.dev/api/v1/whoami는 X-API-Key로 전달한 API 키를 검증합니다. Ingest 키도 사용할 수 있으므로 확인을 위해 텔레메트리를 업로드할 필요가 없습니다. 이 엔드포인트는 API 키만 받고 OAuth Bearer 토큰은 받지 않습니다.

다음 Python 스크립트는 시크릿 관리 도구가 해당 프로세스에 전달한 환경 변수에서 키를 읽습니다. 키 값을 명령줄 인수에 넣거나 출력하지 않는 예입니다. 실행 전후에 환경 변수 덤프나 디버그 로깅을 켜지 마세요.

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://app.framedash.dev/api/v1/whoami",
)
request.add_unredirected_header("X-API-Key", os.environ["FRAMEDASH_API_KEY"])
with urllib.request.urlopen(request, timeout=15) as response:
    data = json.load(response)["data"]
print(json.dumps({"projectId": data["projectId"], "scopes": data["scopes"]}))

반환된 프로젝트 ID와 scope가 작업의 목적에 맞는지 확인하세요. Ingest 전용 키의 응답에는 projectId와 scopes만 포함되며, 분석이나 관리 scope가 있는 키에는 추가 메타데이터가 반환됩니다. 유효하지 않거나 폐기된 키는 401을 반환합니다. 계정 제한이나 요청 속도 제한으로 거부될 수도 있습니다. 검증 성공은 현재 키의 연결 프로젝트와 권한을 확인한 것이며, 수집된 데이터의 완전성이나 진위를 확인한 것은 아닙니다.

다음 출시 전에 게임 패키지와 CI 자격 증명 설정을 점검하세요. 분석용 키가 공개 산출물에 들어갔다면 폐기하고, 관리되는 사용처에서 새 키로 교체한 뒤 노출된 사본도 제거합니다. 이미 배포한 Ingest 키는 클라이언트 업데이트와 함께 교체를 계획해야 합니다. 이전 키를 폐기하면 그 키를 사용하는 클라이언트의 텔레메트리도 중단되기 때문입니다. 어떤 빌드나 작업이 어떤 키를 사용하는지 기록해 두면 사고가 나기 전에 이 영향을 파악할 수 있습니다.