[프로젝트] PathSentinel — LLM 시대의 시크릿 스캐너

PathSentinel 깃허브 보기

문제 정의

LLM 코딩 에이전트(Claude Code, Cursor, Continue 등)는 답을 만들기 전에 파일 시스템을 먼저 읽는다. 한 번의 부주의한 read_file ~/.aws/credentials 또는 cat .env로 인해 비밀이 다음 위치에 남는다:

• 모델 컨텍스트 윈도우
• 프로바이더의 요청 로그
• 이후 공유되는 모든 대화 트랜스크립트

기존 시크릿 스캐너(gitleaks, trufflehog)는 커밋과 CI 중심이다. 코드가 이미 버전 관리에 들어간 뒤에 동작한다. PathSentinel은 그 반대편 — 모델이 말을 꺼내기 전, 디렉터리 워크 단계에서 동작한다.

위협 모델(threat model): 홈 디렉터리에 읽기 권한을 가진 호기심 많거나 손상된 AI 에이전트. PathSentinel은 _에이전트 자체를 신뢰 경계의 적_으로 가정한다 (네트워크가 아니라).

핵심 설계

1. Privacy-first traversal

~/.ssh/, ~/.aws/, ~/.gnupg/, 셸 히스토리, TLS 키 같은 경로는 디렉터리 워크 레이어에서 제외된다. 내용물은 메모리에 절대 읽히지 않으며, 요약에서 카운트만 된다.

2. Sensitive config — 보고하되 열지 않음

.env, credentials.json, service-account.json 같은 파일은 발견(finding) 으로 표시되지만 그 바이트는 첨부되지 않는다.

3. Redacted excerpts

시크릿 패턴이 매치되더라도 앞 4글자만 보이고, 나머지는 …[REDACTED]로 치환된다. 전체 시크릿은 스캐너 밖으로 절대 나가지 않는다.

4. 다섯 진입점, 하나의 엔진

다섯 모두 동일한 ProjectGuardian 스캐너를 공유한다.

사용한 기술

관련 개념과 레퍼런스

• MCP (Model Context Protocol): Anthropic이 공개한 LLM-도구 표준. PathSentinel은 stdio MCP 서버로 동작하므로 MCP를 지원하는 어떤 클라이언트에서도 같은 방식으로 붙는다.
• SARIF (Static Analysis Results Interchange Format): OASIS 표준. PathSentinel이 SARIF 2.1.0을 출력하기 때문에 GitHub Code Scanning 탭 / GitLab SAST 대시보드에 그대로 업로드된다.
• Baseline / diff mode: 레거시 레포에 도입할 때 기존 finding 전부를 막지 않고도 게이트를 그린(green)으로 만들 수 있게 해 주는 패턴. adopt-without-fix-everything 전략.
• Adversarial AI agent threat model: “에이전트는 잠재적 적이다” — 프롬프트 인젝션과 confused deputy 공격에 대한 최근 보안 연구의 흐름과 같은 가정에 서 있다.

어디에 어울리는가

• Claude Code / Cursor / Continue 같은 파일 시스템 접근권을 가진 에이전트를 일상적으로 사용하는 개발자
• 회사 노트북에서 OSS 기여를 하면서도 사적 키가 모델로 흘러가는 것을 막고 싶을 때
• CI에서 시크릿 누출을 PR 머지 전에 차단하고 싶을 때
• SARIF로 보안 대시보드에 통합하고 싶을 때

한 줄 요약

시크릿이 git에 들어가는 것을 막는 도구는 많다. PathSentinel은 시크릿이 프롬프트에 들어가는 것을 막는다.