maskara 딥다이브
— 코딩 에이전트 로그에 새어든 비밀키를 찾아 가려주는 오프라인 CLI

mrgoonie/maskara. Claude Code·Codex·Cursor·Gemini CLI 같은 코딩 에이전트가 디스크에 남긴 대화 로그를 훑어, 거기 섞여 들어간 OpenAI·Anthropic·GitHub·AWS 토큰, JWT, 개인키, DB 접속 주소 같은 비밀값을 찾아내는 작은 Go 명령줄 도구다. 찾은 비밀은 전체를 보여주지 않고 가린 미리보기 + SHA-256 지문만 리포트(마크다운·JSON)로 남기고, 원하면 로컬 사본을 *.maskara.bak 백업과 함께 가림 처리(redact)한다. 핵심은 철저히 오프라인 — 발견한 내용을 어디로도 보내지 않는다. 이름은 mascara(마스카라) + mask(가리다)의 합성어. (저장소: mrgoonie/maskara · 언어 Go · ★낮음(초기 v0.1단계) · 라이선스 MIT · TrendShift 라이브 멘션 등재)

1프로젝트 한줄 요약

"AI한테 시킨 작업 기록에 비밀번호가 적혀 있진 않은지, 내 컴퓨터 안에서만 조용히 점검한다."

구체적으로 maskara는 Go로 짜인 단일 바이너리 CLI다. 아직 초기 단계(v0.1 수준)의 작은 프로젝트지만 구조가 깔끔하다. 인자 없이 그냥 maskara라고 치면 "스캔 → (백업 후) 가림 → 리포트 작성"의 전체 워크플로가 한 번에 돌고, scan/report/guardrails 하위 명령으로 단계를 나눠 쓸 수도 있다. 이름 그대로 마스카라(mascara) + 마스크(mask) — "비밀을 흘려 울지 않으려면 가려라"는 농담 섞인 작명이다.

이 문서가 주목하는 건 도구의 사용법만이 아니라 그 안의 설계다. "정규식으로 비밀을 어떻게 잡아내는가", "전체 값을 안 보여주면서 어떻게 같은 비밀임을 증명하는가(지문)", "남의 파일을 고치는 위험한 작업을 어떻게 안전하게 하는가" — 보안 도구를 처음 만들어 보려는 개발자에게 좋은 교본이다.

2왜 주목받는가

"비밀은 git 저장소만 새는 게 아니다 — AI와의 대화 기록이 새로운 구멍이다."

먼저, 왜 에이전트 로그에 비밀이 새는가

전통적으로 "비밀 유출"은 git 커밋에 .env를 실수로 넣는 것을 뜻했다. 그래서 git-secrets, ggshield 같은 도구가 커밋 전에 막아준다. 그런데 AI 코딩 에이전트 시대에는 완전히 새로운 누출 경로가 생겼다. 사용자가 에이전트에게 "이 토큰으로 API 호출해줘", "왜 인증이 안 되는지 봐줘" 하며 비밀값을 채팅에 그대로 붙여넣고, 에이전트도 디버깅하다 키를 출력한다. 이 모든 대화는 ~/.claude/projects, ~/.codex/sessions 같은 곳에 JSON·JSONL 로그로 영구 저장된다. git에는 안 올라가니 기존 도구는 못 잡지만, 백업·동기화·실수 공유로 새어 나갈 수 있는 진짜 위험이다.

maskara가 사람들 눈에 띈 이유는 이 틈새를 정확히 겨냥했기 때문이다. 같은 "시크릿 스캐너"라도 대상이 다르다.

경쟁 구도 한눈에

요약하면 주목 포인트는 셋이다. ① 새로운 위협 모델(에이전트 로그 누출)을 정조준했고, ② 탐지에서 그치지 않고 가림·백업·예방(가드레일)까지 한 바퀴를 돌며, ③ Go 단일 바이너리라 설치가 가볍고 오프라인이다. 다만 아직 작고 어린 프로젝트라, 탐지 규칙 수나 성숙도는 상용 도구에 못 미친다는 점은 솔직히 감안해야 한다.

3기술 스택 전체 지도

"Go 표준 라이브러리만으로 — 외부 의존성이 거의 없는, 의도된 미니멀 설계."

maskara의 go.mod를 열면 놀랍도록 비어 있다. 모듈 선언과 Go 1.25 한 줄뿐, 외부 라이브러리 의존성이 사실상 0개다. CLI 파싱도 cobra 같은 인기 프레임워크 대신 표준 라이브러리 flag 패키지로 직접 짰다. 보안 도구일수록 의존성을 줄여 공급망 위험(남의 코드에 숨은 악성)을 없애려는 의도된 선택이다.

4아키텍처 심화 분석 — 비밀키가 가려지기까지

"내가 maskara 한 줄을 치면, Claude 로그 속 sk-... 토큰 하나가 발견되어 가려지기까지 안에서 무슨 일이 벌어지나."

maskara는 작지만 내부 패키지(internal/)가 책임별로 깔끔히 갈려 있다. 각 패키지가 컨베이어 벨트의 한 공정처럼 결과를 다음으로 넘긴다. 먼저 기본 워크플로(인자 없는 maskara) 전체 그림을 보자.

핵심 설계 1 — 탐지 규칙 카탈로그: 한 곳에 모은 시크릿의 '몽타주'

maskara의 심장은 internal/detect의 규칙 카탈로그다. 비밀의 종류마다 "이런 모양이다"라는 정규식 + 심각도(critical/high/medium)를 한 줄씩 적어 둔 표다. 실제 규칙 몇 개를 보자(요점만).

// internal/detect/detect.go — DefaultRules() (발췌, 단순화)
{ID: "openai-api-key",  Sev: critical, Expr: `\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b`},
{ID: "anthropic-api-key",Sev: critical, Expr: `\bsk-ant-[A-Za-z0-9_-]{20,}\b`},
{ID: "github-token",    Sev: critical, Expr: `\bgh[pousr]_[A-Za-z0-9_]{36,}\b ...`},
{ID: "aws-access-key",  Sev: high,     Expr: `\b(?:AKIA|ASIA)[0-9A-Z]{16}\b`},
{ID: "jwt",             Sev: high,     Expr: `\beyJ...\....\....\b`},
{ID: "private-key",     Sev: critical, Expr: `-----BEGIN ... PRIVATE KEY----- ...`},
{ID: "database-url",    Sev: critical, Expr: `postgres|mysql|mongodb|redis ://...`},
{ID: "env-secret", Sev: medium, Expr: `(api_key|secret|token|password)=...`, ValueGroup: 1}

읽는 법은 간단하다. 각 규칙은 고유 ID + 심각도 + 정규식 세 가지가 핵심이다. 대부분은 매칭된 전체를 비밀로 보지만, 마지막 env-secret처럼 API_KEY=실제값 형태는 등호 뒤의 값만 비밀이므로 ValueGroup으로 "정규식 안 1번 괄호 그룹만 잡으라"고 지정한다. 매칭 뒤에는 겹치는 결과를 정리하고(dedupeOverlaps), 이미 가려진 표식(MASKARA_REDACTED)은 다시 잡지 않도록 거른다.

핵심 설계 2 — 마스킹 + 지문: 비밀을 안 보여주고 증명하기

비밀을 찾았다고 리포트에 통째로 적으면, 리포트 자체가 또 하나의 유출이 된다. maskara는 이를 두 가지로 푼다.

// Mask: 앞 4 + ... + 뒤 4 만 남긴다 (8자 이하면 그냥 ***)
Mask("sk-proj-abcdEFGH1234wxyz")  →  "sk-p...wxyz"

// 지문: 전체 값을 SHA-256 해시 → 앞 12자만 표시
sha256("sk-proj-abcdEFGH1234wxyz") → "9f86d081884c"...

덕분에 리포트는 "어느 파일·몇 번째 줄에, 어떤 종류의 비밀이, 가려진 미리보기와 지문은 무엇"까지만 담는다. 사람은 그것만으로 "아, 그 Stripe 키구나"를 알아채 폐기할 수 있고, 리포트가 새어도 진짜 비밀은 안 새는 것이다.

핵심 설계 3 — 안전한 파일 가림(redact): 망치기 전에 백업

남의 파일을 프로그램이 직접 수정하는 건 위험하다. internal/redact는 여러 안전장치를 겹쳐 둔다. ① 스캔 대상(targets) 바깥 경로는 거부, ② 심볼릭 링크는 거부, ③ 무엇보다 수정 전에 원본을 *.maskara.bak으로 백업한 뒤에야 덮어쓴다. 비밀 위치(start~end)를 뒤에서부터 잘라내 표식으로 바꾸는데(앞에서 바꾸면 뒤 위치가 어긋나므로), JSON처럼 구조가 깨지면 안 되는 파일은 구조 보존 방식으로 다시 시도한다.

흐름 한 줄기 — sk- 토큰 하나의 일생

// "Claude 로그에 들어간 OpenAI 키 하나"가 가려지기까지 (개념 단순화)
① $ maskara            → cli가 "기본 워크플로"로 진입
② agents.Resolve("auto") → ~/.claude/projects 가 존재 → 스캔 타깃 확정
③ scanner가 walk → conversation.jsonl (텍스트·25MB 이하) 통과, .png는 skip
④ detect.Find: 줄 안에서 sk-proj-abcd... 가 openai 규칙에 매칭
⑤ Finding 생성: preview "sk-p...wxyz", sha256 "9f86...", line=42
⑥ report.WriteOutput: 마크다운 표에 가린 미리보기+지문 기록 (값 없음)
⑦ redact.Apply: conversation.jsonl 을 .maskara.bak 로 백업
⑧ 원본의 그 자리를 [MASKARA_REDACTED:openai-api-key] 로 덮어씀
⑨ 종료 코드 1 반환 (findings 있음) — CI 등에서 "샜다"를 감지 가능

여기서 배울 핵심은 "읽기(스캔)·보고(리포트)·고치기(가림)가 깔끔히 분리"돼 있다는 점이다. 그래서 scan은 안전하게 들여다보기만 하고, report는 기록만 남기며, 위험한 파일 수정(가림)은 전체 워크플로일 때만 일어난다. 사용자가 "얼마나 위험한 일까지 허용할지"를 명령으로 고르게 한 설계다.

5디렉토리 구조 해부

"엔트리포인트 한 줄(cmd) + 책임별 internal 패키지 한 줌 — 작아서 하루면 다 읽는다."

maskara는 Go의 관례적 구조를 따른다. 실행 진입점은 cmd/에, 실제 로직은 외부에서 import 못 하는 internal/에 두어 "공개 API가 아니라 도구 내부 부품"임을 분명히 한다.

6학습 포인트 (기술별)

"작은 레포 하나에 'Go CLI · 정규식 보안 · 안전한 파일 IO · 릴리스 자동화'가 압축돼 있다."

maskara는 코드량이 적어 처음부터 끝까지 읽어볼 수 있는 드문 실전 예제다. 분야별로 무엇을 배울지 + 작게 실습할 거리를 정리했다.

7시스템 요구사항

"순수 소프트웨어 — 설치 바이너리는 의존성 0, 빌드만 Go가 필요하다."

maskara는 단일 정적 바이너리라 설치해서 쓰는 데는 아무 런타임도 필요 없다. 소스에서 빌드하거나 개발하려는 경우에만 Go가 필요하다.

스캔 대상 에이전트 로그 경로(일부)

maskara는 17종 에이전트의 기본 로그 위치를 카탈로그로 알고 있다. auto는 실제로 존재하는 디렉토리만 골라 스캔하고, --root로 임의 경로를 지정할 수도 있다.

# 설치 — Go만 있으면 한 줄
go install github.com/mrgoonie/maskara/cmd/maskara@latest

# 기본 워크플로: 스캔 + (백업 후) 가림 + 리포트
maskara

# 안전하게 들여다보기만 (가림 안 함)
maskara scan                 # 전체 자동 감지
maskara scan -a codex        # Codex 로그만

# 리포트 파일로 — JSON 출력
maskara report --json -o ./maskara-report.json

# 예방책(가드레일) — 무엇을 깔지 미리보기만
maskara guardrails --dry-run

핵심은 인자 없는 maskara가 "가림까지" 하는 강한 명령이라는 점 — 처음엔 maskara scan으로 읽기만 해보고, 결과를 확인한 뒤 가림을 결정하는 것이 안전하다. 모든 동작은 네트워크 없이 로컬에서만 일어난다.

8직접 해볼 수 있는 실습 과제

"읽기만 하면 안 남는다 — 난이도별로 손을 움직여 보자. (가림은 꼭 백업/사본에서!)"

9관련 기술 심화 학습 로드맵

"Go 기초에서 '나만의 시크릿 스캐너'까지 — 5주 코스 예시."

아래는 "Go를 조금 아는 사람이 maskara 코드를 읽고 비슷한 보안 CLI를 만들 수 있는 수준"까지의 한 가지 길이다. 작은 레포라 속도를 붙이기 좋다.

10핵심 키워드 사전

"이 문서와 maskara 코드에서 거듭 나오는 용어들 — 한 곳에 모아 풀었다."

11참고 링크

공식 저장소와 비슷한 결의 도구들(README References).