이 글은 Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine에 제출하는 내용입니다.
제가 만든 것
사이버 보안 명령어는 처음 접할 때는 마법 주문처럼 보일 수 있습니다:
nmap -sV -p 22,80,443 localhost
플래그(flags) 자체는 짧습니다. 하지만 그 뒤에 숨겨진 가정들은 그렇지 않습니다. -p가 포트를 여는 것일까요? 열린 포트라는 것이 누군가가 침입했다는 것을 의미할까요? -sn은 조용히 스캔하는 것일까요, 아니면 완전히 다른 질문을 하는 걸까요?
GhostPort는 초보자를 위한 유령이 깃든 Nmap 학습 교실입니다. 사용자는 네 가지 작은 레슨을 따라가고, 명령어를 구절별로 읽으며, 질문에 답하고, 여전히 이해가 안 되는 부분이 있을 때 유령 같은 Gemma 튜터에게 물어볼 수 있습니다.
테마는 문자 그대로의 것입니다. 브라우저 안에 유령이 존재하지만, 그 목적은 기계(machine)를 설명하기 위함입니다. 희미한 달빛, 떠다니는 안개, 그리고 양초 오렌지색 액센트가 교실에 할로윈 분위기를 더합니다. 설명 내용은 읽기 쉬움을 유지하며, 움직임 최소화 설정(reduced-motion preferences)도 존중합니다.
범위는 의도적으로 작습니다. GhostPort는 명령어를 해석할 뿐이며, 절대 실행하거나 대상과 통신하지 않습니다. 모든 레슨 예제는 localhost를 사용합니다.
데모
실시간 앱: https://ghostport.onrender.com/
GhostPort running on Render, showing the Nmap classroom and a local Gemma response
레슨을 열고, 원한다면 명령어를 변경한 다음 **의미 공개(Reveal meaning)**를 선택합니다. 토큰별 노트가 즉시 작동합니다. **유령 깨우기(Wake the ghost)**를 선택하여 로컬 Gemma 튜터를 불러온 후 질문을 해보세요.
첫 모델 다운로드는 약 1.5 GB로 용량이 크며, 호환 가능한 WebGPU 브라우저와 약 2 GB의 GPU 메모리가 필요합니다. 이 모델은 나중에 다시 방문할 때 캐시됩니다. 최신 버전의 Chrome 또는 Edge 브라우저를 사용하는 것이 권장됩니다. 만약 하드웨어에서 모델을 실행할 수 없다면, 작성된 레슨과 퀴즈는 계속 이용 가능합니다.
앱을 빠르게 둘러보기:
nmap localhost를 읽고 명령이 발견(finding)이 아니라 요청(request)을 설명한다는 것을 배웁니다.- 포트를 선택하려면
-p 22,80,443를 추가합니다. 이것은 포트를 여는 것이 아닙니다.
- 서비스 및 버전 식별을 시도하려면
-sV를 추가합니다.
- 포트 스캔 없이 응답하는 호스트를 검색하려면
-sn을 사용해 봅니다.
퀴즈 완료는 브라우저에 저장되며, **필드 노트 초기화(Reset field notes)**를 통해 다시 연습할 수 있습니다.
코드
공용 저장소: https://github.com/Mochi-coder-star/ghostport
이 저장소에는 애플리케이션, 원본 코드를 위한 MIT 라이선스, 로컬 미리보기 서버, 테스트 및 Render Blueprint가 포함되어 있습니다. Gemma와 기타 타사 구성 요소는 자체 라이선스와 약관을 유지합니다.
구축 방법
이 애플리케이션은 정적 HTML, CSS 및 JavaScript로 구성되어 있습니다. Render가 프론트엔드를 서비스합니다. WebLLM 0.2.87은 방문자의 GPU에서 Google의 오픈 웨이트 모델인 Gemma 2 2B를 MLC 양자화 빌드(gemma-2-2b-it-q4f16_1-MLC)를 사용하여 실행합니다.
두 가지 보완적인 설명 방식이 있습니다:
- 참조 노트(Reference notes): 결정론적 파서(deterministic parser)가 지원되는 명령 옵션을 인식하고 그 설명을 Nmap 공식 문서와 연결합니다.
- 유령(The ghost): Gemma는 학습자의 질문과 함께 해당 노트를 받아 짧은 설명과 비유를 생성합니다.
지원되지 않는 플래그는 추측된 설명 대신 명시적인 메시지를 생성합니다. 이것은 완전한 Nmap 명령 검증기가 아니라 초보자 가이드입니다.
Command → parser → referenced field notes
↓
Question + field notes → local Gemma → targeted reference check → reply
...
Gemma 2는 사용자 차례(user turn)에서 지침을 기대하므로, 런타임은 튜터 지침, 참조 사실 및 질문을 포함하는 단일 사용자 역할 메시지를 받습니다. 모델은 명령을 실행할 수 있는 도구(tools)를 얻지 못합니다.
유령이 무언가를 잘못 알았어요
가장 유용했던 테스트 중 하나는 실패 사례였습니다. -sn에 대해 질문했을 때, Gemma는 포트를 스캔하지 않는다고 정확하게 말했지만, 운영체제와 네트워크 유형을 확인한다고 잘못 주장했습니다.
이는 학습하러 온 사람에게는 좋지 않은 교훈이 될 수 있습니다.
저는 이 관찰된 오류를 위해 작고 목표 지향적인 참조 검사를 추가했습니다. 만약 호스트 발견 응답(host-discovery reply)에서 운영체제 또는 서비스 버전 주장이 들어오면, 표시되는 답변은 대신 정확한 학습 정의를 사용합니다. 두 번째 검사는 '잠긴 문 비유'를 대체합니다: 리스닝 서비스라 할지라도 인증이 필요할 수 있기 때문입니다.
모델의 스트리밍 출력은 이 검사가 완료될 때까지 버퍼링됩니다. 이러한 검사들은 특정 실수를 잡아내지만, 가능한 모든 답변을 검증하는 것은 아닙니다. 원래 참조된 노트는 계속해서 보이도록 유지됩니다.
지원되는 학습 내용, 인자 구문 분석(argument parsing), 유효하지 않은 입력, 플래그 충돌, Gemma 프롬프트 구성, 관찰된 응답 오류 및 로컬 서버의 파일 경계를 포괄하는 아홉 개의 통과 자동화 테스트가 있습니다. 브라우저 체크에는 실제 Gemma 추론(inference), 캐시 로딩, 퀴즈, 그리고 와이드/나로우 레이아웃이 포함되었습니다.
또한 빌드 초기에 더 작은 Qwen 모델들도 시도해 보았습니다. 가장 작은 응답은 학습 자료로 사용하기에 너무 모호했습니다. Gemma로 전환하면서 프로젝트는 관련성 있는 파트너 통합을 얻었지만, 그 답변들을 테스트해야 할 필요성을 없애지는 못했습니다.
Open Innovation이 중요한 이유?
사이버 보안 학습 도구로서, 저는 학습자가 해당 명령어를 호스팅된 모델에 전송하지 않고도 질문할 수 있기를 바랍니다.
Gemma의 오픈 웨이트(open weights)와 WebLLM 덕분에 이러한 아키텍처가 가능해졌습니다. 즉, 모델이 브라우저로 오고, 명령어와 질문은 학습자의 장치에서 처리됩니다. 프론트엔드에 붙여 넣을 추론 API 키도 없고, 채팅 프롬프트를 처리하는 애플리케이션 서버도 없습니다.
이 페이지가 네트워크 요청을 전혀 하지 않는다는 주장은 아닙니다. 앱, 런타임(runtime), 모델 및 글꼴을 로드하는 과정에는 다운로드가 필요합니다. 오프라인 작동 여부는 검증되지 않았습니다. 차이점은 이러한 에셋 다운로드에 학습자의 명령어(commands)나 채팅 질문(chat questions)이 포함되어 있지 않다는 것입니다.
소스 코드 역시 검사하기에 충분히 작습니다. 파서(parser), 프롬프트(prompt), 모델 식별자(model identifier), 참조 확인(reference checks) 등은 모두 일반적인 JavaScript로 구성되어 있습니다. 따라서 누구나 독점 백엔드(proprietary backend)를 재구축할 필요 없이 학습 내용의 문구를 변경하거나, 다른 오픈 웨이트(open-weight) 모델을 테스트하거나, 검사를 개선할 수 있습니다.
수상 부문 (Prize Categories)
- Gemma 활용 최우수: Gemma가 현재 명령어의 참조 노트에 기반한 인터랙티브 로컬 튜터(interactive local tutor)를 구동합니다.
- Render 활용 최우수: Render는 상단의 라이브 데모 URL에서 배포된 클래스룸 프론트엔드(classroom frontend)를 호스팅합니다.
참고 자료 및 크레딧 (References and Credits)
AI 기여도 명시: 저는 Nmap 교육 초점과 시각적 피드백을 포함한 프로젝트 개념 및 방향성을 제공했습니다. Codex가 대부분의 구현을 생성하고, 검사를 실행했으며, 저를 대신하여 이 글을 작성했습니다. 본 내용은 AI가 작성한 것으로 공개되며, 인간이 달성한 교육 결과나 사용자 후기는 주장되지 않습니다.
