_본 프로젝트는 Hacktoberfest 2026 — Week 3: Open-Source AI Challenge에 제출되었습니다. (#hf26challenge).
🧭 딜레마: 코드 보안이 오픈 소스 AI를 요구하는 이유
Hacktoberfest의 '느리고 꾸준한' 나무늘보 철학 정신으로 볼 때, 너무 빠르게 움직여서 무언가를 망가뜨리는 것이 API 키 유출이나 주입 결함(injection flaws)이 프로덕션 환경에 도달하게 만드는 방식입니다. SecureScope는 느리지만 꾸준하고 체계적이며 개인 정보 보호를 유지하는 AI 감사를 워크플로우에 가져옵니다. 왜냐하면 느리고 꾸준한 것이 보안 경쟁에서 승리하기 때문입니다. 🦥
모든 개발자는 프로덕션 환경에서 의도하지 않은 보안 취약점을 발견했을 때의 좌절감을 알고 있습니다. 어쩌면 이스케이프되지 않은 SQL 파라미터였을 수도 있고, 설정 파일에 유출된 API 키였을 수도 있으며, 코드 검토(code review)를 통과한 안전하지 않은 역직렬화 호출일 수도 있습니다.
당연하게도 업계는 코드 분석을 위해 AI로 눈을 돌렸습니다. 하지만 오늘날의 상용 AI 코드 스캐너들은 고통스러운 역설을 제시합니다:
사용자의 개인 코드를 찾으려면, 전체 독점(proprietary) 코드베이스를 제3자 폐쇄형 클라우드에 업로드해야 합니다.
개별 오픈 소스 개발자, 개인 정보 보호에 민감한 스타트업, 그리고 규제가 엄격한 산업(핀테크, 헬스케어, 국방 등)에게 이는 종종 용납할 수 없는 트레이드오프입니다. 귀하의 지적 재산은 와이어를 타고 전송되며, 제3자의 보존 정책, 공급업체의 사용량 제한(rate limits), 그리고 반복적인 구독 청구서의 대상이 됩니다.
저는 이러한 트레이드오프를 깨기 위해 **SecureScope**를 구축했습니다.
SecureScope는 핵심에 Google Gemma 2를 탑재한 오픈 소스, 로컬 우선(local-first) 코드 보안 인텔리전스 에이전트입니다. 이 에이전트는 6개 이상의 언어에 걸쳐 코드를 스캔하고, 마이크로초 단위의 정규 표현식 사전 필터(regex pre-filter)를 통해 취약점을 검사하며, 전문적인 오픈 웨이트 AI 페르소나를 사용하여 위협을 검증하고, 실시간 SerpApi CVE 데이터에 근거하여 발견 사항을 근거화하며, ElevenLabs를 이용해 임원용 음성 브리핑을 합성합니다. 이 모든 과정은 소스 코드를 엄격하게 사용자 통제 하에 유지하면서 이루어집니다.
🏆 목표 수상 부문
SecureScope는 오픈 웨이트(open-weight) AI 및 파트너 생태계를 강조하도록 의도적으로 설계되었습니다:
| 카테고리 | 파트너 / 기술 | SecureScope의 활용 방식 |
|---|
| 🌟 Gemma의 최적 활용 ($200) | Google Gemma 2 (gemma2-9b-it) | 취약점 탐지, 신뢰도 점수 산정 및 즉시 적용 가능한 코드 수정 생성을 주도하는 주요 오픈 웨이트 기반 모델. |
| ... | | |
💡 SecureScope에 있어 개방형 혁신이 중요한 이유
Week 3의 핵심 질문은 다음과 같습니다. 폐쇄형 방식보다 오픈 기반 접근 방식이 더 잘 작동하는 곳은 어디인가요? 여기에 직접적인 엔지니어링 현실을 알려드립니다:
1. 인터넷이 없는 노트북에서도 실행되나요?
예, 100% 가능합니다. Ollama를 사용하면 SecureScope가 Google Gemma 2를 한 번 다운로드하여 완전히 오프라인으로 실행할 수 있습니다:
python cli.py --path ./my-project --provider ollama --model gemma2 --output all
비행기 안이든, 에어갭(air-gapped) 연구실에 있든, Wi-Fi 없이 원격으로 작업하든 관계없이, 파일 탐색부터 AI 추론 및 HTML 보고서 생성까지 전체 감사 파이프라인은 사용자의 CPU/GPU에서 로컬로 실행됩니다.
2. 제어하지 않는 서버에 데이터를 남기지 않나요?
절대적으로 그렇습니다. 귀하의 코드는 절대 localhost를 벗어나지 않습니다. 독점적인 로직, 내부 데이터베이스 연결 문자열 또는 아키텍처 비밀이 폐쇄형 모델 API 제공업체로 전송되거나 외부 프롬프트 로그에 저장되지 않습니다.
3. 모델 교체 및 사용자 지정 에이전트 동작을 허용하나요?
예. 폐쇄 플랫폼은 사용자를 자신들이 선택한 모델에 가둡니다. SecureScope는 모듈식 어댑터 아키텍처를 사용합니다. Google Gemma 2에서 CodeGemma로 전환하거나, 사용자 지정 보안 파인튜닝(security fine-tune)을 테스트하고 싶습니까? 단순히 플래그를 전달하면 됩니다:
python cli.py --path . --provider ollama --model codegemma
특화된 보안 프롬프트(analyzer/prompts.py)는 완전히 오픈 소스이며 팀별 코딩 표준에 맞게 사용자 지정이 가능합니다.
4. 실행 비용이 전혀 들지 않나요?
한계 비용 제로(Zero marginal cost). 고빈도 CI/CD 파이프라인 전반에 걸쳐 상용 API 감사를 실행하는 것은 토큰 사용량으로 인해 매월 수백 달러의 비용이 발생할 수 있습니다. Gemma 2를 로컬에서 또는 관대한 무료 오픈 모델 엔드포인트를 통해 실행하면 유지 관리자나 학생들은 $0로 무제한 스캔을 실행할 수 있습니다.
📊 직접 비교: 폐쇄형 SaaS 대 SecureScope
| 기능 | 기존 폐쇄형 SaaS SAST | SecureScope (오픈 가중치 AI) |
|---|
| 코드 개인 정보 보호 | 공급업체 클라우드에 업로드되는 코드 | 코드가 기기를 벗어나지 않음 |
| ... | | |
🏗️ 아키텍처: SecureScope 작동 방식
SecureScope는 전체 저장소(repository)를 LLM 컨텍스트 창으로 무차별적으로 넣는 방식을 피합니다. 대신, 효율적인 5단계 파이프라인을 활용합니다:
┌───────────────────────────────┐
│ 대상 코드베이스 / 저장소 │
└──────────────┬────────────────┘
...
스테이지 1: Git 인식 파일 순회 (Git-Aware File Traversal)
파일 워커(scanner/file_walker.py)는 git ls-files를 쿼리하여 .gitignore 규칙을 자동으로 준수하고, 빌드 디렉터리(node_modules, dist, venv)를 건너뛰며, 활성 Git 브랜치에서 변경된 파일을 격리하는 --diff 모드를 포함합니다.
스테이지 2: 밀리초 이하 정규식 사전 필터링 (Sub-Millisecond Regex Pre-Filter)
LLM으로 수백 개의 깨끗한 파일을 스캔하는 것은 느리고 비효율적입니다. SecureScope는 Python, JavaScript, TypeScript, Go, Java, PHP를 포괄하는 언어별 정규식 규칙(scanner/languages.py)을 실행합니다. 깨끗한 파일은 즉시 건너뛰고, 주변 코드 컨텍스트와 함께 의심스러운 라인만 후보 스니펫으로 패키징합니다.
스테이지 3: Google Gemma 2를 활용한 다중 역할 추론 (Multi-Role Reasoning)
후보 스니펫은 Google Gemma 2(analyzer/ai_client.py)로 전송됩니다. 모호한 프롬프트 대신, 우리는 전문 보안 감사자 페르소나(persona)를 할당합니다:
- Injection Auditor: 신뢰할 수 없는 매개변수(untrusted parameters)가
sqlite3.execute(), child_process.exec(), 또는 eval()로 흐르는지 추적합니다.
- Credential & Secret Detector: 실제 고엔트로피(high-entropy) API 키와 무해한 변수 선언을 구별합니다.
- Access & Cryptographic Reviewer: 취약한 알고리즘(
MD5, SHA1, DES)과 불안전한 역직렬화(deserialization, pickle.loads, unsafe YAML)를 플래그 지정합니다.
Stage 4: SerpApi를 통한 실시간 위협 근거 확보 (Live Threat Grounding)
Gemma 2가 취약점을 확인하면, SecureScope는 SerpApi(analyzer/cve_search.py)를 호출하여 National Vulnerability Database (NVD)와 MITRE CWE에 질의합니다:
search_query = f"{vulnerability} {language} (site:cve.mitre.org OR site:nvd.nist.gov)"
이 과정은 발견된 각 취약점에 실제 CVE 식별자, CVSS 컨텍스트 및 직접적인 연구 링크를 추가합니다.
Stage 5: 멀티모달 보고서 및 ElevenLabs 음성 출력
결과는 세 가지 출력 스트림으로 컴파일됩니다:
- 리치 터미널 대시보드 (Rich Terminal Dashboard): 색상 코드가 지정된 심각도 미터와 OWASP 카테고리 분류.
- 대화형 독립형 HTML 보고서 (Interactive Standalone HTML Report): 확장 가능한 코드 diff가 포함된 제로-의존성 다크 모드 대시보드.
- ElevenLabs 오디오 보안 브리핑: 팀에 심각한 위험을 알리는 구두 요약(executive summary,
.mp3)을 합성합니다.
🔬 실제 사례: 주입 취약점 발견 및 수정
시스템을 테스트하기 위해, 저는 안전하지 않은 SQL 쿼리를 포함하는 의도적으로 취약한 더미 데이터(fixture)에 SecureScope를 실행했습니다:
취약한 입력 코드 (app.py):
def search_users(username):
conn = sqlite3.connect("users.db")
cursor = conn.cursor()
...
SecureScope 터미널 출력:
╭──────────────── #1 — SQL Injection via String Formatting ────────────────╮
│ Severity: 🔴 CRITICAL │
│ OWASP: A03:2021 — Injection │
...
생성된 ElevenLabs 음성 브리핑 스크립트:
"보안팀 여러분의 주의를 바랍니다. 이것은 SecureScope 자동 보안 감사 브리핑입니다. 저희는 0.1초 만에 2개의 파일을 스캔하여, app.py에서 문자열 포맷팅을 통한 SQL Injection이라는 심각한 취약점 1개를 식별했습니다. AI가 제안한 매개변수화된 쿼리 패치들이 HTML 보고서에 컴파일되었습니다."
⚡ 빠른 시작 및 실행 방법
1. 설치 (Installation)
git clone https://github.com/SuperSaiyan101/securescope.git
cd securescope
pip install -r requirements.txt
2. 즉시 스캔 (Instant Scan) (오프라인 / API 키 불필요)
python cli.py --path ./tests/fixtures/vulnerable_app --skip-ai --output all
3. Google Gemma 2를 활용한 전체 AI 스캔 (Full AI Scan with Google Gemma 2)
# 클라우드 Gemma 2용 무료 Groq API 키 설정
export GROQ_API_KEY="gsk_..." # Windows: $env:GROQ_API_KEY="gsk_..."
python cli.py --path ./my-project --output all
4. Ollama를 이용한 100% 오프라인 로컬 스캔 (Offline Local Scan with Ollama)
ollama pull gemma2
python cli.py --path ./my-project --provider ollama --model gemma2 --output all
5. ElevenLabs를 이용한 음성 브리핑 생성 (Generate Voice Briefing with ElevenLabs)
export ELEVENLABS_API_KEY="your_key"
python cli.py --path ./my-project --voice --output all
🐙 CI/CD 통합: GitHub Actions
SecureScope는 들어오는 Pull Request를 자동으로 감사하는 드롭인 워크플로우( exttt{.github/workflows/securescope.yml})를 포함하고 있습니다:
name: SecureScope Security Gate
on: [push, pull_request]
...
🛠️ 제작 과정 (작업 공개)
이 프로젝트는 오픈 웨이트(open-weight) LLM에 연결되는 오픈 소스 터미널 코딩 에이전트 하네스인 OpenCode를 사용하여 반복적으로 개발되었습니다.
OpenCode를 사용하여 저는 다음 작업을 수행했습니다:
- 여러 프로그래밍 언어에 걸쳐 정규 표현식(regex) 사전 필터링 엔진을 프로토타입으로 제작했습니다.
- 대규모 언어 모델(LLM)의 환각 현상(hallucinations)을 제거하고 구조화된 JSON 출력을 강제하기 위해 전문화된 시스템 프롬프트(system prompt)를 반복 개선했습니다.
- 의존성을 최소화하고 설치 속도를 매우 빠르게 유지하기 위해 표준 라이브러리 폴백(fallbacks)(예: 무거운 HTTP 클라이언트 대신
urllib)을 구현했습니다.
- 스캐너를 실제 환경 및 합성된(synthetic) OWASP Top 10 테스트 스위트와 비교하여 스트레스 테스트했습니다.
오픈 에이전트 하네스(agent harness)를 사용하여 오픈 보안 도구를 구축하는 것은 2026년에 오픈 소스 AI가 무엇을 가능하게 하는지에 대한 궁극적인 시연처럼 느껴졌습니다.
🔗 코드 및 저장소
현대 코드 보안 스캐너에서 가장 큰 문제점은 무엇인가요? 프로젝트에 SecureScope를 실행해보고, 아래에 여러분의 생각과 피드백을 공유해주세요!
