설치

한 줄 명령이면 바이너리 하나가 설치됩니다. 작성해야 할 설정 파일도, 만들어야 할 계정도 없습니다 — 설치 후 바로 스캔할 수 있습니다.

빠른 설치

설치 스크립트는 OS와 아키텍처를 감지하고, 릴리스 바이너리를 내려받아 체크섬을 검증한 뒤 /usr/bin/hostveil에 설치합니다:

curl -fsSL https://hostveil.seolcu.com/install.sh | bash

같은 명령을 언제든 다시 실행하면 최신 릴리스로 업데이트됩니다. 그런 다음 확인하세요:

hostveil version

지원 플랫폼

Hostveil은 리눅스 호스트를 감사합니다. 사전 빌드 바이너리는 Linux와 macOS의 amd64·arm64용으로 제공되고 macOS 빌드도 실제로 실행됩니다 — 다만 그 안의 탐지 규칙은 전부 리눅스에 관한 것이라, Mac에서는 대부분의 도메인이 N/A로 나오고 점수는 그렇지 않은 두 개에서 나옵니다. 거기서 나온 숫자를 읽기 전에 macOS에서 실행하기를 보세요.

설치 스크립트가 하는 일

OS(linux/darwin)와 아키텍처(amd64/arm64)를 감지합니다.
릴리스 tarball과 hostveil-checksums.txt를 내려받은 뒤 SHA-256 체크섬을 검증합니다. 일치하지 않으면 중단합니다.
sudo로 바이너리를 /usr/bin/hostveil에 설치(권한 0755)하고, hostveil --version을 실행해 정상 동작을 확인합니다.
선택적 이미지 CVE 스캔을 위한 Trivy 설치를 제안합니다. 거절해도 Hostveil 설치를 막지 않습니다.

설치 스크립트 옵션

옵션	효과
`--version vX.Y.Z`	최신 대신 특정 릴리스를 설치합니다.
`--no-trivy`	선택적 Trivy 안내를 아예 건너뜁니다.
`--yes` / `-y`	비대화형으로 실행합니다(모든 확인을 수락).

파이프를 통해 옵션을 전달하려면 bash -s --를 사용하세요. 예:

curl -fsSL https://hostveil.seolcu.com/install.sh | bash -s -- --no-trivy

권한 상승은 자동입니다

참고

SSH와 방화벽 점검은 sshd_config 같은 root 소유 파일을 읽어야 하고, 수정을 적용하려면 보호된 경로에 써야 합니다. 그래서 hostveil은 sudo 아래에서 자동으로 자신을 다시 실행합니다 — sudo hostveil과 동일한 sudo 비밀번호 프롬프트가 표시되며, 인증 후 같은 터미널에서 계속 진행됩니다. version과 help는 절대 프롬프트를 띄우지 않습니다. 권한 없이(스크립트·CI에서) 실행하려면 HOSTVEIL_NO_SUDO=1을 설정하세요. 그러면 root 소유 영역은 명확한 메시지와 함께 건너뛰어지고, 점수는 오해를 부르는 완벽한 결과를 주지 않도록 재정규화됩니다.

선택 도구

해당 도구가 없으면 각 영역은 깔끔하게 건너뛰어집니다. 추가 범위를 원한다면 다음을 추가하세요:

도구	열어 주는 기능	참고
Docker	Docker / Compose 점검	Hostveil은 Compose 파일을 읽어 서비스를 점검합니다.
Trivy	이미지 CVE 스캔	있으면 사용되며, 설치 스크립트가 대신 설정해 줄 수 있습니다.
Ollama	AI 설명(`explain --ai`)	기본적으로 로컬에서 동작하며 호스트 밖으로 아무것도 나가지 않습니다. 필수는 아닙니다 — 로컬 모델을 감당하기엔 약한 호스트라면 `HOSTVEIL_AI_PROVIDER=anthropic` 또는 `openai`로 외부 API를 대신 쓸 수 있습니다. AI 설명을 참고하세요.

Debian·RPM 패키지

모든 릴리스에는 .deb와 .rpm 패키지도 함께 올라갑니다. 스크립트를 셸에 파이프하고 싶지 않은 분들을 위한 것이고, 보안 도구라면 특히 타당한 선호입니다. 최신 릴리스에서 아키텍처에 맞는 파일을 받아 패키지 관리자로 설치하세요.

sudo apt install ./hostveil_<version>_linux_amd64.deb
# 또는
sudo dnf install ./hostveil-<version>.x86_64.rpm

패키지는 설치 스크립트와 같은 경로 /usr/bin/hostveil에 같은 바이너리 하나를 설치하므로 둘은 서로 바꿔 쓸 수 있습니다 — PATH에 사본이 두 개 남는 일 없이 옮겨 갈 수 있습니다. Docker와 iproute2는 권장일 뿐 필수가 아닙니다. 없으면 컨테이너·CVE·노출된 서비스 영역이 N/A로 표시될 뿐, Hostveil이 실행되지 않는 것은 아닙니다.

활성화할 서비스도, 편집할 설정 파일도 없습니다. 패키지를 제거해도 /var/lib/hostveil은 남습니다 — --uninstall과 같은 이유로, 그 체크포인트가 Hostveil이 편집한 모든 파일의 백업이기 때문입니다.

패키지는 리눅스 전용입니다.

내려받은 것이 진짜인지 확인하기

스크립트를 셸에 파이프로 넘기고, 그 도구를 root로 실행하라는 요구를 받고 계신 겁니다. 그 전에 확인할 수 있는 것들을 적어 둡니다.

설치 스크립트는 이미 받아온 아카이브의 체크섬을 릴리스의 hostveil-checksums.txt와 대조하고, 맞지 않으면 버립니다. 그것으로 증명되는 것은 바이트가 온전히 도착했다는 사실입니다. 누가 만들었는지는 증명되지 않습니다 — 변조된 아카이브 옆에 함께 게시된 체크섬 파일은 그 아카이브와 완벽하게 일치할 테니까요.

모든 릴리스 아카이브에는 서명된 빌드 프로버넌스 증명이 함께 담깁니다. 이것은 증명해 줍니다. 그 아카이브가 이 저장소의 릴리스 워크플로에서, 명시된 커밋과 태그로부터 빌드됐다는 사실을요. 관리자의 노트북에서 돌아가는 그 무엇도 이 증명을 만들어 낼 수 없습니다.

gh attestation verify hostveil-linux-amd64.tar.gz --repo seolcu/hostveil

GitHub CLI가 있으면 hostveil update가 이 확인을 대신 해 줍니다. 프로버넌스 확인이 실패하면 업데이트를 중단하고, gh가 없어서 확인 자체를 못 하면 오류가 아니라 안내로 남깁니다. 체크섬은 여전히 바이트의 무결성을 증명하고, 그 이상인 척하는 것은 정직하지 않기 때문입니다.

각 아카이브에는 바이너리에 들어간 것을 모두 나열한 SBOM(.sbom.json)도 함께 담깁니다. 오늘 나온 보안 권고에 실린 라이브러리가 여기 들어 있는지를 직접 빌드해 보지 않고도 답할 수 있습니다.

macOS에서 실행하기

macOS 빌드는 진짜 빌드입니다 — 설치 스크립트가 받아 가고, 실행되고, 보고서를 냅니다. 공개하는 이유는 Hostveil이 흔히 노트북에서 조작되기 때문이고, 공개하지 않는 빌드는 깨져도 아무도 모르기 때문입니다. 다만 이것은 macOS 감사 도구가 아닙니다. 도구 어디에도 Darwin 전용 규칙은 없습니다.

Docker가 없는 Mac에서는 열두 도메인 중 열 개가 N/A로 나옵니다. 일곱 개는 스스로 볼 것을 찾지 못하고 — /proc/sys도, systemd도, apt나 dnf도, ss도 없습니다 — 나머지 셋은 일부러 제외됩니다. macOS에서는 묻지 않은 질문에 답을 해 버리기 때문입니다.

도메인	macOS에서
호스트 방화벽	제외됩니다. Hostveil은 ufw, firewalld, nftables, iptables를 봅니다. macOS에는 넷 다 없고 대신 `pf`를 쓰므로, “내가 보는 것 중에 아무것도 없다”가 `firewall.inactive`로 보고됐을 겁니다 — 찾아본 적도 없는 방화벽에 대한 최상위 심각도 발견 항목으로요.
계정 위생	제외됩니다. macOS에도 `/etc/passwd`가 있지만 계정 데이터베이스는 Open Directory이고 그 파일은 호스트를 설명하지 않습니다. `/etc/shadow` 쪽은 아예 실행될 수 없으며, 그때 나올 조언인 “`sudo`로 다시 실행하세요”는 결코 도움이 될 수 없습니다. 파일이 읽히지 않는 게 아니라 없기 때문입니다.
AI 에이전트 런타임	제외됩니다. 같은 `/etc/passwd`에서 리눅스 UID 범위로 홈 디렉터리를 찾습니다. macOS 계정은 501부터라 `/var/root`만 찾았을 것이고, `/Users`는 열어보지도 않은 채 “에이전트 런타임 없음”이라고 보고했을 겁니다.

두 도메인은 실행됩니다. SSH는 /etc/ssh/sshd_config를 읽는데, 이 파일은 원격 로그인이 켜져 있든 아니든 macOS가 싣고 있습니다. 그리고 그 발견 항목들은 리눅스가 아니라 OpenSSH에 관한 것입니다 — PasswordAuthentication은 Darwin에서도 같은 뜻입니다. 파일 권한은 아는 파일만 확인하고 나머지는 건너뜁니다. 기본 상태의 macOS에서는 대개 둘 다 깨끗합니다.

macOS에서의 수정은 실제 파일을 씁니다

SSH 도메인은 읽기 전용 시늉이 아닙니다. Mac에서 hostveil fix ssh.passwordauth를 실행하면 서버에서와 똑같이 /etc/ssh/sshd_config를 백업하고 다시 씁니다. hostveil history에서 되돌리는 것도 똑같습니다. 이건 올바른 동작이고, 노트북에서 실행하기 전에 알아 둘 값어치가 있습니다.

그리고 점수는 N/A가 아니라 숫자로 나옵니다. 도메인 두 개가 실행됐으니 평균 낼 것이 있으니까요. 다만 그것은 100점 중 19점어치의 가중치에 대한 평균이고, 실행되지 않은 열 개 도메인에 대해서는 아무 말도 하지 않습니다. 헤드라인 말고 축별 분해를 읽으세요. pf, 응용 방화벽, Homebrew의 업데이트 상태, launchd 서비스, System Integrity Protection — 그 어느 것도 Hostveil의 어떤 부분도 살펴보지 않습니다.

업그레이드와 제거

둘 다 Hostveil이 직접 합니다. 설치 스크립트를 다시 실행하라고 안내하지 않는 이유는, 이 바이너리가 어떻게 여기 왔는지를 Hostveil이 알고 있기 때문입니다.

hostveil update      # --check을 붙이면 아무것도 바꾸지 않고 확인만 합니다
hostveil uninstall

update는 설치 경로 — 설치 스크립트, .deb, .rpm, go install — 를 알아내 같은 방식으로 갱신합니다. 패키지로 설치한 곳에 설치 스크립트를 다시 돌리면 dpkg나 rpm이 여전히 자기 것으로 아는 파일을 덮어쓰게 되는데, 이 명령은 바로 그 상태를 막으려고 있습니다. 내려받은 파일은 릴리스의 체크섬과, GitHub CLI가 있으면 서명된 빌드 프로버넌스와도 대조합니다. 설치 경로를 알 수 없으면 아무것도 하지 않고 그렇게 말합니다. 전체 표는 CLI 레퍼런스에 있습니다.

제거는 /usr/bin/hostveil을 삭제하고 상태 디렉터리의 위치를 알려주되, 그 디렉터리는 지우지 않습니다. 그 안의 체크포인트는 Hostveil이 이 호스트에서 수정한 모든 파일의 백업이며, 도구를 지운다는 것이 그 수정들을 되돌릴 능력을 포기하겠다는 뜻은 아니기 때문입니다. 지우고 싶다면 필요한 명령도 함께 출력됩니다. trivy도 건드리지 않습니다. 범용 스캐너라서 Hostveil보다 먼저 설치되었거나 다른 용도로 쓰이고 있을 수 있습니다.

소스에서 빌드하기

최신 Go 툴체인이 설치되어 있다면:

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

재현 가능한 데모 VM을 포함한 전체 개발 환경 설정은 기여하기를 참고하세요.