Hostveil / 문서 / 기여하기

기여하기

Hostveil은 Go로 작성되었으며, 의존성 트리가 작고 아키텍처 규칙이 엄격합니다. 이 페이지는 빠른 안내이며, 정식 개발자 가이드는 docs/DEVELOPMENT.md, 데모 VM은 demo/README.md에 정리되어 있습니다.

시작하기

git clone https://github.com/seolcu/hostveil.git
cd hostveil
go build ./cmd/hostveil     # produces ./hostveil
go test ./...

PR를 열기 전에 CI가 실행하는 전체 점검을 돌리세요 — go build ./..., go vet, gofmt -l ., go mod tidy, 그리고 go test -race ./...입니다. 정확한 명령과 고정된 Go 버전은 DEVELOPMENT.md에 있습니다.

리눅스 도구, 이식 가능한 테스트

Hostveil은 어떤 OS에서도 빌드되고 테스트가 통과하지만, 바이너리를 의미 있게 실행하려면 관련 도구가 설치된 리눅스가 필요합니다 — 본인의 머신 대신 데모 VM을 사용하세요.

구조

엔진은 internal/core에 있고, CLI·TUI·웹 UI는 그 위의 얇은 계층입니다. import-lint 테스트가 ui/*가 fix, history, check, compose를 절대 import하지 않도록 강제하며, 이것이 세 인터페이스를 동일하게 동작하게 만듭니다. 전체 저장소 구조와 아키텍처 설명은 DEVELOPMENT.md에 있습니다.

확장하기

플러그인 시스템도, 룰 파일도, 설정 파일도 없습니다. 이건 빠진 기능이 아니라 결정입니다. 점수가 의미를 가지려면 축 가중치의 합이 100이어야 하고, 모든 발견 항목은 누군가 따져 본 조치를 달고 있어야 하며 — 일부러 수정을 붙이지 않은 항목들의 명부는 테스트가 파싱하는 주석 속 산문입니다 — 배포의 전부는 서명된 정적 바이너리 하나입니다. 룰 형식은 이 세 가지를 아무도 서명하지 않는 파일 뒤로 밀어 넣게 됩니다.

그래서 Hostveil을 확장한다는 것은 Go를 쓰고 다시 빌드한다는 뜻이고, 추가하고 싶을 만한 세 가지는 규모가 자릿수만큼 다릅니다.

무엇을 더하는가무엇이 필요한가
기존 도메인의 규칙 하나발견 항목을 돌려주는 함수 하나, 그 도메인 규칙 표의 행 하나, internal/check/checktest로 만든 테스트, 그리고 양 언어 점검 항목 표의 행 하나. 작습니다.
기존 발견 항목의 수정빌더 하나, 등록 하나, 그리고 판단 하나: 등록하지 않는다면 fix.Default() 주석의 명부에 이유와 함께 이름을 올리고, 사용자가 보게 될 한 문장짜리 거부 사유를 달아야 합니다. 테스트가 이 셋을 함께 묶어 둡니다. 작습니다.
탐지 도메인 전체진짜 변경입니다. 아래를 보세요.

새 도메인은 Checker를 구현하는 패키지 하나이고, 그다음에는:

  • sourceDefs의 행 하나. 도메인의 이름·라벨·축, 그리고 가중치를 담습니다.
  • 재조정. 가중치의 합은 정확히 100이고 테스트가 이를 강제하므로, 새 도메인은 늘 기존 도메인에서 점수를 떼어 와 마련해야 하고 그 이동 하나하나에 근거가 필요합니다.
  • cmd/hostveil/app.go에 등록. 도메인 표가 선언한 순서대로입니다.
  • 양 언어 점검 항목 표의 행들. 발견 항목마다 심각도와 수정 종류, 그리고 가중치 열까지.
  • 점수 산정 페이지 표의 가중치. 양 언어 모두.
  • 수정을 등록하지 않는 모든 발견 항목에 대한 거부 사유.
  • 그리고 그 도메인이 리눅스가 아닌 호스트에서 건너뛰는 대신 틀린 답을 내놓을 종류라면, 이유와 함께 OS 게이트 목록에 등록.

각 단계를 마칠 때까지 테스트 열한 개쯤이 실패하며, 그중 대부분은 코드가 아니라 문서 가드입니다. 그게 의도된 경험입니다. 테스트가 곧 체크리스트이고, 문서가 실제로 존재하는 도구를 설명하는 이유가 바로 그것입니다.

실제로 실행해 보기: 데모 VM

demo/는 코드로 정의된, 의도적으로 취약하게 만든 Ubuntu 서버입니다. Hostveil은 VM 내부에서 여러분의 작업 트리로부터 빌드되므로 항상 현재 코드를 반영합니다. ./run.sh up으로 띄우고 ./run.sh scan으로 스캔하세요. 플랫폼별 프로바이더 설정, 5분 데모 스크립트, 초기화 절차, 문제 해결은 모두 demo/README.md에 있습니다.

← 문제 해결 GitHub 저장소 →