themiddleblue/vibegate호스트에 구애받지 않는 코딩 에이전트용 사전 작성 보안 훅: Semgrep을 통해 사용자 입력 패턴을 감지하고 결정론적이며 LLM이 없는 보안 지침을 출력합니다.
AI 코딩 도구를 위한 보안 검문소입니다. AI 어시스턴트가 작성하는 모든 파일을 검사하여, 위험한 파일이 디스크에 저장되기 전에 차단합니다.
AI 코딩 어시스턴트(Claude Code, Codex, …)는 빠르게 코드를 작성합니다. 여기에는 비밀번호, 이메일, API 키, 또는 원시 사용자 입력을 처리하는 코드도 포함됩니다. 어시스턴트가 그러한 데이터를 생각 없이 데이터베이스 쿼리, 셸 명령어 또는 HTTP 응답에 바로 연결하기 쉽습니다.
VibeGate는 어시스턴트와 파일 시스템 사이에 위치합니다. 어시스턴트가 파일을 쓰거나 편집하려고 할 때마다 VibeGate가 새 코드를 먼저 스캔합니다:
분석 자체에는 LLM이 전혀 관여하지 않습니다. 빠르고 결정론적인 정적 분석이므로, 허위 정보를 만들어내지 않으며 토큰 비용이 들지 않습니다.
다음은 VibeGate가 현재 검사하는 모든 항목입니다:
| 검사 항목 | 탐지 내용 | 결과 |
|---|
| 명령어 주입 | 정제되지 않은 입력이 셸 명령어에 도달함 | 차단 |
| SQL 주입 | 정제되지 않은 입력이 데이터베이스 쿼리에 도달함 | 차단 |
| NoSQL 주입 | 요청 본문이 데이터베이스 필터로 직접 사용됨 | 차단 |
| 템플릿 주입(SSTI) | 템플릿 소스 자체가 사용자 입력에서 비롯됨 (데이터만이 아님) | 차단 |
| 안전하지 않은 역직렬화 | 신뢰할 수 없는 데이터가 안전하지 않은 역직렬화(pickle, 안전하지 않은 YAML 등)에 도달함 | 차단 |
| 경로 탐색 | 정제되지 않은 입력이 파일 읽기/쓰기/삭제에 도달함 | 차단 |
| XXE | 신뢰할 수 없는 XML이 외부 엔터티가 활성화된 상태로 파싱됨 | 차단 |
| XSS | 정제되지 않은 입력이 원시 HTML로 렌더링됨 | 차단 |
| 제한 없는 파일 업로드 | 업로드된 파일의 이름 자체가 저장 경로를 구성하는 데 사용됨 | 차단 |
| SSRF | 서버가 하드코딩되지 않은 URL을 가져옴 | 경고 |
| 오픈 리다이렉트 | 하드코딩되지 않은 리다이렉트 대상 | 경고 |
| 대량 할당 | 전체 요청 본문이 모델 생성자 또는 업데이트에 전달됨 | 경고 |
| 요청 본문 내 민감 데이터 | 이메일, 비밀번호, 토큰 등이 요청 본문에서 읽힘 | 경고 |
| URL/쿼리 내 민감 데이터 | 이메일, 비밀번호, 토큰 등이 쿼리 문자열에서 읽힘 | 경고 |
| 헤더 내 민감 데이터 | 이메일, 비밀번호, 토큰 등이 요청 헤더에서 읽힘 | 경고 |
| 사용자 입력의 파일 경로 | 하드코딩된 문자열이 아닌 변수가 파일 경로로 사용됨 | 경고 |
| CLI 인수 | 데이터가 명령줄 인수에서 비롯됨 | 경고 |
| 표준 입력 | 데이터가 stdin에서 비롯됨 | 경고 |
| 환경 변수 | 데이터가 환경 변수에서 비롯됨 | 경고 |
| 고정되지 않은 GitHub Action | 워크플로가 커밋 SHA 대신 변경 가능한 태그(@v4)를 사용함 | 경고 |
안전하지 않은 pull_request_target | 워크플로가 pull_request_target 트리거를 사용함 | 경고 |
| 자격 증명 로깅 | 비밀번호, API 키 또는 토큰이 print/console.log/로거에 전달됨 | 경고 |
| 하드코딩된 비밀 | 비밀처럼 이름이 지정된 변수에 실제로 보이는 리터럴 값이 할당됨 | 경고 |
전체 최신 목록은 guidance.TECHNICAL_RISKS 및 formatter.BLOCKING_CATEGORIES에 있습니다. 아래 표가 변경될 경우를 대비한 것입니다.
┌───────────────────────────────┐
│ You ask Claude Code to │
│ write or edit a file │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────┐
│ Claude Code tries to save │
│ the file (Write/Edit tool) │
└───────────────┬───────────────┘
│
▼
┌───────────────────────────────┐
│ VibeGate hook │
│ (runs automatically, │
│ before the file is saved) │
└───────────────┬───────────────┘
│
scans the new code with Semgrep
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────────┐ ┌────────────────────┐ ┌──────────────────────┐
│ No risky input │ │ Risky input, │ │ Risky input reaches │
│ found │ │ but lower risk │ │ a critical sink │
│ │ │ (e.g. shown in │ │ (SQL/command/RCE, │
│ │ │ an HTTP reply) │ │ template injection) │
└─────────┬──────────┘ └─────────┬──────────┘ └───────────┬──────────┘
│ │ │
▼ ▼ ▼
File is saved, File is saved, File is NOT saved.
nothing shown. plus a warning in Claude Code sees
the terminal with the block reason
risk + how to fix it. and is told what
to fix.
요약하자면: 안전한 코드는 그냥 통과되고, 위험하지만 감당 가능한 코드는 경고와 함께 저장되며, SQL 주입, 명령어 주입, 원격 코드 실행 등에서 한 발짝 떨어진 코드는 디스크에 도달하기 전에 중단됩니다.
VibeGate 자체에서 예상치 못한 오류가 발생하면 항상 쓰기를 허용합니다. 후크의 버그가 작업을 차단하는 이유가 되어서는 안 됩니다.
모든 경고와 차단에는 Claude Code가 결과를 조용히 수정하는 대신 응답에서 해당 발견 사항을 사용자에게 언급하도록 명시적인 지시가 포함됩니다. 이것이 VibeGate의 활동을 터미널 로그뿐만 아니라 대화에서도 볼 수 있게 하는 이유입니다.
| VibeGate가 보는 것 | 어떤 일이 일어나는가 |
|---|---|
| 사용자 입력이 없거나 아직 지원하지 않는 언어 | 파일이 정상적으로 저장됨, 아무것도 표시되지 않음 |
| 사용자 입력이 발견되었지만 위험이 중간 정도(예: 오픈 리다이렉트, 대량 할당) | 파일이 저장됨, 터미널에 경고 + 안내 표시 |
| 사용자 입력이 정제되지 않은 채 중요한 싱크(SQL/NoSQL 쿼리, 셸 명령어, 템플릿 엔진, 역직렬화기, XML 파서, 파일 경로, 업로드된 파일 이름 또는 원시 HTML 출력)로 흐름 | 파일이 저장되지 않음 — Claude Code에게 이유가 설명됨 |
무엇이 차단되고 무엇이 경고만 하는지에 대한 전체 항목별 분석은 위의 "이 도구가 해결하는 문제는 무엇인가요?" 표를 참조하세요.
현재 VibeGate는 Python, JavaScript/TypeScript, Go, Java, PHP, Ruby를 이해하며, Claude Code 및 Codex에 연결됩니다. 핵심 로직을 건드리지 않고도 더 많은 언어와 도구를 추가할 수 있습니다.
또한 GitHub Actions 워크플로 파일에서 두 가지 일반적인 CI/CD 공급망 실수(커밋 SHA 대신 변경 가능한 태그(@v4)에 고정된 액션, 안전하지 않은 pull_request_target 트리거)를 검사합니다. 둘 다 차단보다는 경고로 처리됩니다. 활성 익스플로잇의 증명보다는 강화 검사이기 때문입니다.
다음은 VibeGate가 실행되는 동안 Claude Code가 RSS 피드 리더 앱을 처음부터 구축하는 실제 녹화입니다. Claude Code가 멈추고 VibeGate가 무엇을 표시했는지, 왜 그런지 명시적으로 말한 후 계속 진행하는 순간들을 주목하세요. 여기에는 피드 가져오기 코드의 실제 SSRF 위험을 포함하여 즉시 수정하는 장면이 있습니다.
다음은 정지 이미지로 된 두 번째 예시입니다. Claude Code가 사진을 업로드하고 세부 정보를 볼 수 있는 앱을 구축 중입니다. VibeGate는 파일 이름 및 기타 파일 세부 정보가 나중에 화면에 표시될 것임을 감지하고, 이것이 페이지에 유해한 코드를 주입하는 데 사용될 수 있다고 경고합니다(XSS라고 함). Claude Code는 정보가 안전하게 표시되도록 코드를 조정합니다.
두 경우 모두, 이유 없이 차단된 것은 없었으며, 문제를 찾기 위해 코드를 한 줄씩 읽을 필요도 없었습니다. VibeGate는 파일이 작성되는 순간 문제를 잡았고, AI가 즉시 수정했습니다.
AI 어시스턴트가 더 안전한 코드를 작성하도록 만드는 두 가지 방법이 있습니다. 하나는 시작하기 전에 대화에 보안 코딩에 대한 큰 지침 세트를 로드하는 것입니다(예: SQL 주입, XSS, 비밀번호 처리, 파일 업로드 등을 다루는 체크리스트). 다른 방법은 VibeGate가 하는 방식입니다. 파일이 작성될 때 자동으로 코드를 확인하고, 실제로 문제가 있을 때만 언급하는 것입니다.
첫 번째 접근 방식은 필요 여부와 관계없이 모든 메시지에 대해 토큰 비용이 발생합니다. 여러 위험 범주를 다루는 일반적인 보안 코딩 체크리스트는 쉽게 수천 개의 토큰을 추가할 수 있습니다. AI 어시스턴트가 한 세션에서 50개의 파일을 작성하고, 해당 체크리스트가 매번 다시 로드되거나 컨텍스트에 유지된다면, 대부분의 경우 현재 작성 중인 파일에 적용되지 않는 조언에 대해 10만 개 이상의 토큰을 지불할 수 있습니다. 로그인 페이지와 단순한 색상 상수 파일에는 동일한 경고가 필요하지 않지만, 로드된 체크리스트는 미리 그것을 구분할 수 없습니다.
VibeGate는 이를 뒤집습니다. 위험한 패턴이 없는 모든 파일에 대해 침묵을 유지하고 추가 비용이 들지 않습니다. 실제로 무언가(예: 사용자 입력이 데이터베이스 쿼리로 흐르는 것)를 찾았을 때만, 그 하나의 문제에 대한 짧고 구체적인 메모를 추가합니다. 일반적으로 전체 체크리스트 크기의 아주 작은 부분입니다. 따라서 모든 파일에 고정된 토큰 비용을 지불하는 대신, 실제로 주의가 필요한 파일에만 적은 비용을 지불하고, 그 비용은 발견된 문제에 정확히 맞춰집니다(일반적인 보안 강의가 아닌).
이것은 또한 안내를 더 신뢰할 수 있게 만듭니다. 백 줄의 코드를 작성하는 동안 "보안을 염두에 두라"고 요청받은 AI 어시스턴트는 많은 줄 중에서 위험한 한 줄을 단순히 놓칠 수 있습니다. 게이트는 피곤하거나 주의가 산만해지지 않습니다. 매번 동일한 고정 규칙을 사용하여 모든 쓰기를 확인합니다.
한 번 설치하면 VibeGate가 의존하는 Semgrep도 함께 설치됩니다:
pipx install git+https://github.com/theMiddleBlue/vibegate
그런 다음 보호하려는 프로젝트 내에서 활성화합니다:
cd your-project
vibegate on # 여기서 켜기 (이후 Claude Code 다시 로드)
vibegate status # 이 프로젝트에 대해 켜져 있는지 확인
vibegate off # 여기서 끄기
vibegate on은 Write|Edit|MultiEdit에 대한 PreToolUse 후크를 해당 프로젝트의 .claude/settings.local.json에 추가합니다. 프로젝트별로 범위가 지정되므로 한 저장소에서 켜도 다른 저장소에 영향을 미치지 않습니다.
Claude Code는 후크를 vibegate run --host claude_code로 실행합니다. 절대 경로가 필요 없으므로 다시 설치하거나 이동해도 계속 작동합니다.
vibegate status는 또한 이 프로젝트에서 VibeGate가 실제로 포착한 활동 로그(모든 경고 및 차단, 파일, 줄, 범주 포함)를 보여주므로, 단순히 켜져 있는지 여부뿐만 아니라 시간 경과에 따른 활동을 볼 수 있습니다:
$ vibegate status
█ █ █████ ████ █████ ████ ███ █████ █████
...
● VibeGate는 .claude/settings.local.json에서 활성화됨
최근 활동 (기록된 2개 중 최근 2개, 최신순):
2026-07-02T17:35:48+00:00 ⛔ 차단됨 server.py:3 EXEC_INPUT (FREE_TEXT)
2026-07-02T17:35:46+00:00 ⚠ 경고 app.py:2 HTTP_BODY (EMAIL)
이 로그는 프로젝트 루트의 .vibegate/activity.jsonl에 있습니다. .gitignore에 추가하세요. 커밋할 대상이 아닌 로컬 개발자 상태입니다.
VibeGate는 다음 순서로 통신 중인 호스트를 파악합니다: 명시적 --host <name> 플래그, VIBEGATE_HOST 환경 변수, 들어오는 페이로드에서 자동 감지, 마지막으로 claude_code로 fallback.
VibeGate가 의도적으로 안전하다고 판단한 것을 플래그하는 경우, 같은 줄에 vibegate-ignore 주석을 추가하세요. 모든 주석 구문(#, //, …)에서 작동합니다. VibeGate는 단순히 텍스트를 찾기 때문입니다:
query = f"SELECT * FROM users WHERE id = {user_id}" # vibegate-ignore
해당 줄의 모든 것을 억제하는 대신 특정 범주만 억제하려면 콜론 뒤에 나열하세요(기술 범주 또는 의미 유형과 일치, 쉼표로 구분, 대소문자 무시):
query = f"SELECT * FROM users WHERE id = {user_id}" # vibegate-ignore: DB_QUERY
src/vibegate/
├── hook.py # 진입점
├── cli.py # on/off/status 명령어 + ASCII 배너
├── activity_log.py # 경고/차단을 .vibegate/activity.jsonl에 저장
├── colors.py # 공유 ANSI 색상 코드 (리포트 + CLI 배너)
├── core.py # 호스트에 독립적인 파이프라인
├── models.py # InputEvent / ClassifiedFinding / AnalysisResult
├── semgrep_runner.py # Semgrep을 하위 프로세스로 실행 (fail-safe)
├── classifier.py # Semgrep 규칙 → 범주, 변수 이름 → 데이터 유형 매핑
├── guidance.py # 정적 위험/수정 설명
├── formatter.py # 결과를 터미널 리포트 + 호스트 컨텍스트로 변환
├── adapters/ # base, claude_code, codex + 작은 레지스트리
└── rules/ # Semgrep 규칙 — 언어별 파일 하나 (Python, JS/TS,
# Go, Java, PHP, Ruby) + 일반 플레이스홀더
파이프라인 자체(core.py)는 특정 호스트와 직접 통신하지 않습니다. 모든 호스트별 입력/출력은 adapters/에 있으므로, 분석 로직을 건드리지 않고 새 호스트를 추가할 수 있습니다.
semgrep --validate --config src/vibegate/rules/ # 규칙이 유효한지 확인
pytest tests/ # 단위 + 통합 테스트
Claude Code 없이 종단 간 작동을 확인하려면:
python3 -c 'import json; print(json.dumps({"tool_name":"Write","tool_input":{"file_path":"/tmp/t.py","new_content":"email = request.json.get(\"email\")"}}))' \
| python3 src/vibegate/hook.py --host claude_code
rules/<lang>-user-input.yaml 추가, 새 규칙 ID를 classifier.RULE_TO_TECHNICAL에 등록, 파일 확장자를 core.EXT_TO_LANGUAGE에 매핑.classifier.VARNAME_TO_SEMANTIC에 키워드 추가, guidance.SEMANTIC_GUIDANCE에 설명 추가.RULE_TO_TECHNICAL에 항목 추가, guidance.TECHNICAL_RISKS에 카드 추가.adapters/ 아래에 어댑터 추가, adapters/__init__.py에 등록.codex 어댑터는 초기, 최선의 매핑입니다. 차단에 의존하기 전에 Codex 버전과 이벤트 계약을 다시 확인하세요."requires login"을 반환하므로, 분류기가 파일 내용과 줄 번호를 사용하여 스니펫을 직접 재구성합니다.Edit/MultiEdit의 경우 claude_code 어댑터는 디스크에서 편집 후 전체 파일을 재구성하여, 오염된 소스와 별도의 편집으로 도입된 싱크가 여전히 연결되도록 합니다. 그러나 편집이 실제로 건드린 줄의 발견 사항만 보고됩니다. 싱크가 이미 존재하고 이후 편집에서 싱크에 도달하는 오염된 소스만 추가하는 경우, 해당 상황은 포착되지 않습니다(싱크의 줄이 새 편집의 일부가 아니었기 때문). 이 재구성은 Claude Code에 특화되어 있습니다. codex 어댑터는 아직 이 작업을 수행하지 않습니다.