🛡️ vibecode-checker

AI로 빠르게 만든 코드, 한국 정부 보안 기준으로 점검하세요.

바이브 코딩(AI 코딩 도구로 빠르게 개발)한 결과물에 숨은 개인정보 노출·API 키·SQL 삽입·위험한 명령 실행·취약 패키지를, 공무원이 이해할 수 있는 한국어 리포트로 알려주는 보안 점검 도구입니다.

🎬 데모

💡 gvskb scan ./내프로젝트 한 줄이면, 무엇이 위험하고 어떻게 고치는지 한국어로 알려줍니다.

$ gvskb scan ./my-project

## 결론
> 차단 권고 — 치명 등급 포함 총 6건 발견, 이 중 차단(block) 4건.
  커밋·배포 전 수정 또는 보안담당자 승인 필요.

#### [CRITICAL] 치명 · block — 주민등록번호 평문 저장 (app.py line 12)
  왜 위험한가: 주민번호는 일방향 해시·토큰화·마스킹 후 저장해야 합니다 …
  공공 업무 영향: 개인정보 유출, 정보주체 통지·과징금 …
  안전한 수정 방향: ↓
      # 수집 자체를 재검토하거나, KMS로 암호화 후 별도 PII 테이블에 …
  출처: KISA Python 가이드 제3절, 개인정보보호법 §29

Related MCP server: DevSecOps MCP Server

📑 목차

• 60초 시작 가이드

• 누구에게 필요한가

• 무엇을 잡아주나요

• 사용 가이드 (초보 → 고급)

• 무엇을 탐지하나 — 룰과 출처

• 성능 (정직하게)

• 공공기관 · 망분리 환경

• 기여하기

• 연락 · 문의

• 면책 · 라이선스

🚀 60초 시작 가이드

전제 조건 (Prerequisites)

• Python 3.11 이상 (python --version으로 확인)

• 운영체제 무관 (Windows·macOS·Linux). Windows 한글 깨짐은 한 번만 설정

설치 (Installation)

pip install vibecode-checker        # PyPI 배포본
# 또는 소스에서:
git clone https://github.com/<your-org>/vibecode-checker.git
cd vibecode-checker && pip install .

사용 (Usage)

# 1. 내 환경 점검 (룰 개수·인코딩·MCP 상태)
gvskb doctor

# 2. 내 프로젝트 검사 → 화면에 한국어 리포트
gvskb scan ./my-project

# 3. 보안 담당자에게 보낼 보고서를 파일로 저장 (.md + 보기 좋은 .html 함께 생성)
gvskb scan ./my-project -o 보안점검.md

끝입니다. AI가 짜준 코드 폴더를 가리키기만 하면 됩니다. -o로 저장하면 텍스트 보안점검.md와 색깔 카드형 보안점검.html(인쇄→PDF 결재 문서)이 함께 만들어집니다.

📖 비전공자용 한 장 요약: 30초 시작 가이드

👋 누구에게 필요한가

• "AI가 짜준 코드가 안전한지 모르겠어요" — Claude Code·Cursor·Copilot으로 업무 코드를 만드는 분

• 민원·통계·DB·파일 업로드·챗봇을 빠르게 만들어 보는 공공기관 실무자

• 위탁 개발 소스를 배포 전에 한 번 더 점검하고 싶은 담당자

• 보안 용어는 어렵지만 "이게 위험한지, 어떻게 고치는지" 알고 싶은 분

🔍 무엇을 잡아주나요

📖 사용 가이드

🌱 처음이신가요 — 검사하고 리포트 읽기

gvskb scan ./my-project                              # 화면 출력
gvskb scan ./my-project --format markdown -o 보고서.md # 파일 저장

리포트의 결과 색깔만 알면 됩니다:

⚠️ 검사된 파일이 0개라고 나오면 "안전"이 아니라 경로·확장자를 확인하라는 뜻입니다.

🌿 더 써보기 — MCP·의존성·오프라인

claude_desktop_config.json 등에 추가하면, AI에게 자연어로 "이 코드 안전한지 검사해줘"라고 물을 수 있습니다.

{
  "mcpServers": {
    "vibecode-checker": {
      "command": "python",
      "args": ["-m", "gvskb.server"],
      "env": { "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8" }
    }
  }
}

연결 후: "server_status로 룰이 몇 개 로드됐는지 확인해줘"

이렇게 말하면 됩니다 (도구 이름을 몰라도, 아래 단어가 들어가면 점검→보고서까지 진행됩니다):

• 🟢 *"이 폴더 보안 점검해줘 → ./my-project"*

• 🟢 *"방금 만든 이 코드 안전한지 체크해줘"*

• 🟢 *"이 파일 검토하고 위험한 부분을 한국어 보고서로 만들어줘"*

• 🟢 *"고쳤어, 다시 검사해줘"*

트리거 단어: 보안 · 점검 · 체크 · 검토 · 검사 · 스캔 · "안전한지". Claude·Cursor에서는 /보안점검 명령으로도 한 번에 실행됩니다. 잘 안 불러오면 "vibecode-checker로 점검해줘" 라고 덧붙이세요.

⚠️ 신뢰하는 클라이언트에만 연결하세요. MCP scan_path 도구는 지정한 경로의 로컬 파일을 읽습니다(검사 목적). 연결한 AI 클라이언트가 임의 경로를 스캔하도록 요청할 수 있으므로, 신뢰할 수 있는 클라이언트·환경에서만 사용하고 민감 디렉터리는 가리키지 마세요. 자세한 내용은 SECURITY.md 참고.

gvskb check-package requests --ecosystem pypi    # 알려진 취약점 조회
gvskb check-package reqeusts --ecosystem pypi    # 오타 패키지(typosquat) 경고

# (외부망 PC) 보안 피드 캐시를 미리 받아둡니다
gvskb update-intel --all

# (망분리 PC) 캐시를 옮긴 뒤, 외부 호출 없이 로컬 룰·캐시로만 검사
$env:GVSKB_MODE = "offline"      # PowerShell
gvskb doctor --offline
gvskb scan ./my-project

정적 분석 룰 95개는 외부 통신 없이 그대로 동작합니다.

🌳 CI에 넣고 싶다면 — 자동 게이트

gvskb scan은 결과에 따라 **종료 코드(exit code)**를 반환해 커밋·배포를 자동 차단할 수 있습니다.

gvskb scan ./src --fail-on block   # block만 실패시킴(2), warn은 통과 — CI 게이트 권장
gvskb scan ./src --fail-on warn    # warn 이상 실패 (기본값)
gvskb scan ./src --fail-on never   # 항상 0 (리포트만)

name: security scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pip install vibecode-checker
      - run: gvskb scan . --format markdown -o report.md --fail-on block
      - if: always()
        uses: actions/upload-artifact@v4
        with: { name: security-report, path: report.md }

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: gvskb-scan
        name: vibecode-checker 보안 스캔
        entry: gvskb scan
        args: ["--format", "json", "--fail-on", "block"]
        language: system
        types: [text]

🛡️ 무엇을 탐지하나 — 룰과 출처

탐지는 한국 정부·국제 보안 가이드를 직접 인용합니다. 단순 패턴 매칭이 아니라, 왜 위험한지 → 행정 업무에 어떤 사고로 이어지는지 → 어떻게 고치는지를 출처와 함께 제시합니다.

총 215개 룰 (자동 탐지 95 + 지식·참조 120). 모든 룰은 Markdown 한 장으로 정의돼 누구나 읽고 검토·확장할 수 있습니다.

📊 성능 (정직하게)

독립 코퍼스(외부 ground truth 30개 시드)로 측정한 카테고리별 탐지율:

개인정보(PII)   ████████████████████  100%   (5/5)
시크릿·키       ████████████████████  100%   (4/4)
코드 실행       ████████████████████  100%   (3/3)
암호화·TLS      ████████████████████  100%   (3/3)
Python 전체     █████████████████░░░   85%
SQL·명령 주입   ████████████████░░░░   80%
JavaScript      ███████████████░░░░░   75%
─────────────────────────────────────────────
종합 recall     ███████████████████░   96.7%  · 오탐 0

재현: GVSKB_MODE=offline PYTHONPATH=src python scripts/run_benchmark.py

정직성 원칙: "자체검증 100%"는 룰이 자기 예제를 맞히는 측정이라 외부 코드 성능을 뜻하지 않습니다. 그래서 독립 코퍼스로 따로 측정해 **96.7%**를 함께 공개합니다. 보안 전문 검토를 대체하지 않는 1차 보안 린터로 설계되었습니다.

🏛️ 공공기관 · 망분리 환경

• 소스코드는 외부로 전송되지 않습니다. 모든 정적 분석은 로컬에서 수행됩니다.

• 외부 통신은 패키지 취약점 조회에 한정(OSV·CISA·NVD·EPSS 5개 공개 API). 보내는 것은 패키지명·CVE ID 같은 공개 식별자뿐입니다.

• GVSKB_MODE=offline 한 줄로 외부 통신을 완전 차단하고, 사전에 받아둔 캐시·로컬 룰만으로 동작합니다.

🤝 기여하기

룰은 코드가 아니라 Markdown 파일 한 장입니다. rules/ 아래에 frontmatter로 탐지 패턴·설명·예제를 적으면 끝입니다.

gvskb validate-rules     # 새 룰 형식·정규식 검증
gvskb evaluate           # 룰 예제 기반 정밀도 측정
pytest -q                # 전체 테스트

새 룰에는 examples.positive/negative를 넣어주세요 — 회귀 테스트로 자동 보증됩니다. 자세한 방법은 CONTRIBUTING.md를 참고하세요.

기여를 환영합니다:

• 🐛 버그·오탐 제보 → Issues

• 💡 새 룰·기능 제안 → Discussions

• 🔧 직접 고치기 → Pull Request (작은 PR 환영)

📮 연락 · 문의

• 버그·기능 요청: GitHub Issues

• 사용 질문·아이디어: GitHub Discussions

• 보안 취약점 비공개 제보: SECURITY.md의 절차를 따라주세요

• 그 외 문의: 메인테이너에게 이슈로 멘션해 주세요

⚖️ 면책 · 라이선스

이 도구의 자동 점검은 공식 보안적합성 검토를 대체하지 않습니다. 비전공자가 명백한 실수를 1차로 걸러내고 학습하도록 돕는 보조 도구입니다. critical·high 항목은 보안 담당자 검토를 권장하며, 기관별 보안 정책·개인정보 처리 기준을 함께 확인하세요.

정부·공공기관 지침(KISA·행안부·국정원), OWASP·NIST·CISA 등 외부 자료는 원문을 복제하지 않고 요약·인용·구조화하여 사용하며 각 출처의 이용 조건을 존중합니다.

MIT License — 자유롭게 사용·수정·배포할 수 있습니다. LICENSE 참고.