왜 만들었나​

오랫동안 보안 업무를 하면서 쌓인 지식이 여기저기 흩어져 있었다. 한곳에 정리하고, 필요하면 바로 공유할 수 있는 공간이 필요했다. 여러 도구를 고민하다 마크다운으로 쓰고 GitHub에 올리면 사이트가 되는 Docusaurus를 선택했다.

내 배경​

나는 네트워크와 보안을 기반으로 일해 왔다. 방화벽, IDS/IPS, 보안관제, 침해대응은 익숙하지만, 개발 도구를 직접 다뤄 본 경험은 많지 않았다.

Git도 마찬가지였다. IT에서 오래 일했기 때문에 Git이 무엇인지, 어떻게 동작하는지는 알고 있었다. 하지만 개발자가 아니다 보니 어디까지나 이론으로 아는 것이었다.

오늘 한 일​

Node.js · Git · GitHub Desktop · VS Code 설치
  → Docusaurus 프로젝트 생성
  → GitHub 저장소 연결
  → GitHub Actions로 자동 배포
  → 메뉴 구성, About 작성
  → 도메인 연결 (wiki.securenomad.kr)
  → 네이버 · 구글 검색 등록

과정마다 막힌 부분과 해결 방법은 Docusaurus Setup 에 따로 정리했다.

인상 깊었던 점​

도구들이 유기적으로 맞물려 돌아간다​

처음에는 VS Code, Git, GitHub Desktop, GitHub, GitHub Actions가 각각 따로 노는 도구라고 생각했다. 직접 써 보니 하나의 흐름으로 이어져 있었다.

VS Code에서 문서 작성
  → Git이 변경 내용 추적
  → GitHub Desktop으로 Commit · Push
  → GitHub Actions가 자동으로 빌드
  → GitHub Pages로 사이트 공개

내가 하는 일은 문서를 쓰고 Push 버튼을 누르는 것뿐이었다. 나머지는 정해진 흐름대로 자동으로 흘러갔다. 네트워크로 치면 구성만 잘 해 두면 트래픽이 알아서 흘러가는 것과 비슷한 느낌이었다.

변경 이력이 남고, Push만으로 배포된다​

가장 기억에 남는 것은 변경된 내용을 관리하고 퍼블리싱하는 방식이었다.

• 무엇을 바꿨는지 파일 단위, 줄 단위로 보인다
• 커밋마다 메시지가 남아 언제 무엇을 왜 바꿨는지 추적된다
• Push 하나로 빌드부터 배포까지 끝난다
• 문제가 생기면 이전 상태로 되돌릴 수 있다

보안 업무에서 늘 강조하는 변경 관리와 이력 추적이 도구 안에 자연스럽게 들어 있었다. 개발자들이 왜 Git 없이는 일을 못 한다고 하는지 비로소 이해가 됐다.

이론과 실습은 다르다​

Git이 분산 버전 관리 시스템이라는 것, commit과 push가 무엇인지는 알고 있었다. 하지만 실제로 써 보니 이론으로는 보이지 않던 것들이 보였다.

• GitHub Desktop의 Git과 터미널에서 쓰는 Git이 따로라는 것
• .git 폴더 하나가 저장소의 정체라는 것 (폴더가 중첩되어 생겼을 때 .git을 옮겨서 해결했다)
• .gitignore가 수만 개의 node_modules 파일을 걸러 준다는 것

머리로 아는 것과 손으로 해 본 것의 차이를 다시 한번 느꼈다.

보안 담당자 시선으로 본 포인트​

구축 과정에서 보안 담당자로서 짚고 넘어갈 장면이 꽤 있었다.

Public 저장소에는 생각보다 많은 것이 남는다​

GitHub Pages를 무료로 쓰려면 저장소가 Public이어야 한다. 그런데 커밋 기록에 작성자 이메일이 그대로 공개된다는 것을 확인했다. GitHub의 noreply 이메일 설정을 쓰면 실제 이메일 대신 GitHub가 제공하는 주소로 커밋을 남길 수 있다. 한 번 Push한 내용은 파일을 지워도 이력에 남는다는 점도 기억해 둘 만하다.

정책을 완화하기보다 우회 경로를 택했다​

VS Code 터미널에서 npm 실행이 PowerShell 실행 정책 때문에 막혔다. 실행 정책을 RemoteSigned로 바꾸는 방법도 있었지만, 시스템 정책을 건드리지 않고 터미널을 명령 프롬프트로 바꾸는 쪽을 선택했다. 작은 선택이지만 불필요하게 보안 설정을 완화하지 않는다는 원칙을 지키고 싶었다.

도메인 인증은 귀찮은 절차가 아니었다​

도메인을 연결할 때 GitHub에서 TXT 레코드로 소유 인증을 하는 단계가 있었다. 처음엔 번거로운 절차라고 생각했는데, 이것이 Subdomain Takeover를 막는 장치였다. 연결을 해제한 뒤 DNS 레코드가 남아 있으면 다른 사람이 내 서브도메인으로 사이트를 띄울 수 있다. 실무에서도 자주 지적되는 취약점이라 더 와닿았다.

공개 전에는 반드시 걸러낸다​

About 페이지를 이력서 기반으로 작성하면서 공개하면 안 되는 정보를 먼저 걸러냈다.

• 주소, 휴대폰 번호
• 자격증 번호, 학점
• 고객사명 (업종으로만 표기)

구축 기록 문서에서도 인증 값, 계정 정보 같은 민감 정보는 모두 제외했다. 공개되는 순간 회수할 수 없다는 것은 보안 담당자라면 누구나 아는 사실이지만, 직접 글을 쓰는 입장이 되니 더 신경 쓰였다.

AI와 함께 작업해 보니​

이번 구축은 처음부터 끝까지 AI(Claude)와 대화하면서 진행했다.

좋았던 점​

• 에러 메시지를 그대로 붙여 넣으면 원인과 해결 방법을 바로 알려 줬다
• 화면 캡처만 보여 줘도 어디를 눌러야 하는지 짚어 줬다
• 진행한 과정을 그대로 문서로 정리해 줘서 구축 기록을 따로 쓸 필요가 없었다
• 개발 경험이 부족해도 막히지 않고 끝까지 갈 수 있었다

아쉬웠던 점​

AI의 안내가 항상 맞지는 않았다.

• Node.js 설치 중 추가 도구 옵션을 체크하라는 안내를 따랐다가 설치 창이 멈췄다
• GitHub Desktop에서 저장소를 만드는 방법을 따랐는데 폴더가 중첩되어 생겼다
• 설정 예시에 넣은 옵션 하나 때문에 Git이 없는 환경에서 빌드가 실패했다

결국 문제를 발견한 것은 내가 직접 결과를 확인했기 때문이었다.

정리​

AI(Claude)는 막힌 곳을 뚫어 주는 데는 확실히 강력했다. 하지만 AI의 답을 그대로 믿기보다 결과를 확인하면서 진행해야 한다. 무엇을 공개할지, 어떤 설정을 선택할지 같은 판단은 결국 사람의 몫이었다.