Hostveil / 문서 / 인터페이스

인터페이스

Hostveil에는 세 가지 얼굴이 있습니다. 터미널 UI, localhost 웹 대시보드, 스크립트로 다루는 CLI이고, 셋 모두 하나의 공유 엔진 위의 얇은 계층입니다. 어느 하나에서 스캔하거나, 고치거나, 되돌리든 다른 곳에도 반영됩니다.

TUI: 기본값

인수 없이 대화형 터미널에서 hostveil을 실행하면 키보드 기반 TUI가 열립니다. 명시적으로 실행할 수도 있습니다.

hostveil        # or: hostveil tui

점수와 발견 항목을 심각도·영역 필터, 일괄 수정을 위한 다중 선택, 쉬운 말 상세 설명, 그리고 적용 전 수정 미리보기와 함께 보여 줍니다. 스캔이 도는 동안에는 아직 작업 중인 영역의 이름을 보여 주므로, 이미지가 많은 호스트에서 CVE 스캔이 오래 걸려도 멈춘 것이 아니라 진행 중임을 알 수 있습니다.

키 목록

화면 맨 아래 두 줄에는 지금 보고 있는 화면의 키가 항상 표시됩니다. 전체 목록은 다음과 같습니다.

호스트를 바꾸는 동작, 곧 수정 적용과 롤백은 모두 diff를 보여 주고 먼저 물어봅니다. 미리보기 없이 디스크에 쓰는 키는 없습니다.

한 줄이 말하는 것

각 행은 심각도, 수정 종류, 발견 항목 id, 제목, 그리고 대상 서비스를 담습니다. 눈으로 훑을 열은 수정 종류입니다. 초록색 AUTO는 Hostveil이 알아서 적용할 수 있다는 뜻, 강조색 REVIEW는 선택을 물어본다는 뜻, 회색 MANUAL과 N/A는 누를 버튼이 없다는 뜻입니다.

다섯 번째 값은 무언가를 적용한 뒤에만 나타납니다. 강조색 PEND입니다. 수정은 기록됐지만 호스트가 아직 읽지 않았다는 뜻입니다 — 다시 만들기를 기다리는 Compose 파일, 다시 읽기를 기다리는 systemd 드롭인처럼요. 점수가 여전히 감점하고 있기 때문에 행은 목록에 남고, 더 적용할 것이 없으므로 표시 대상에서는 빠집니다. 무엇을 실행해야 반영되는지는 항목 아래 문장이 알려 줍니다.

웹: localhost 대시보드

브라우저로 검토하는 편이 나을 때 동일한 스캔을 HTTP로 제공합니다.

hostveil serve

일회용 접근 토큰이 담긴 URL이 출력됩니다. 그 URL을 그대로 여세요. loopback 바인딩은 대시보드를 네트워크에서 차단하지만 같은 머신의 다른 계정으로부터는 지켜주지 못하며, 이곳의 모든 경로는 root 권한으로 수정을 적용하거나 /etc/shadow 스캔 결과를 읽습니다. 토큰이 그 틈을 막습니다. 첫 페이지 로드에서 세션 쿠키로 교환되므로 이후 링크에는 다시 나타나지 않습니다.

127.0.0.1:8787에 바인딩됩니다. 대시보드는 localhost로 향하지 않은 요청을 모두 거부하므로 --addr로는 네트워크에 노출할 수 없습니다. non-loopback 주소를 지정하면 바인딩은 되지만, 이 머신을 IP나 호스트 이름으로 찾아온 요청은 거부합니다. 포트를 포워딩해 접근하면 그대로 동작합니다. 다른 머신에서 접근하려면 포트를 포워딩하세요: ssh -L 8787:127.0.0.1:8787 you@server. (hostveil web은 serve의 별칭입니다.)

아무것도 고르기 전에도 오른쪽 패널이 스캔 결과를 읽어 줍니다. 점수를 말로 풀어 주고, 심각도별 분포, 사용자의 판단 없이 고칠 수 있는 항목 수, 그리고 가장 심각한 몇 건을 바로 가기 목록으로 보여 줍니다. 발견 항목을 선택하면 그 자리에 상세 내용과 Preview fix 버튼이 들어오고, History를 누르면 적용된 수정들이 각각 되돌릴 diff와 Roll back 버튼과 함께 표시됩니다.

목록 위의 칩은 심각도와 영역으로 필터링하며 개수를 실시간으로 보여 주고, 체크박스는 한 번에 일괄 수정할 항목을 고릅니다. 모두 CLI와 같은 엔진을 거치므로, 브라우저에서 한 작업이 터미널의 hostveil history에 그대로 나열됩니다.

지난 스캔 이후 달라진 것

Hostveil은 스캔을 저장해 두기 때문에 다음 스캔이 무엇이 달라졌는지 말해 줄 수 있습니다. 변화가 있으면 두 UI 모두 발견 목록 위에 한 줄 요약을 보여 줍니다. ✓ 12 resolved, + 2 new, ~ 1 changed. "방금 한 수정이 실제로 도움이 됐나?"에 가장 빠르게 답하는 방법입니다. 첫 스캔에서는 비교할 대상이 없으므로 아무것도 표시되지 않습니다.

그 바로 아래에는 온전히 점검하지 못한 영역의 이름이 나옵니다. 부분적인 스캔으로 만든 점수는 그 사실을 한 번 알리고 사라지는 대신 계속 말해 줍니다. 영역을 온전히 점검하지 못했을 때를 참고하세요.

CLI: 스크립트 가능

scan, fix, rollback, history 하위 명령은 비대화형으로 동작합니다. scan --json은 기계가 읽을 수 있는 출력을 내보내며, scan은 수정되지 않은 발견 항목 중 HIGH가 하나라도 있으면 0이 아닌 값으로 종료합니다. 그래서 CI나 cron 작업에 그대로 들어갑니다.

hostveil scan --json > report.json
hostveil fix --all --yes

모든 명령과 플래그는 CLI 레퍼런스를 참고하세요.

테마

TUI와 대시보드는 다섯 가지 색상 테마를 제공합니다: onedark(기본값), gruvbox, nord, catppuccin, tokyonight. 하나의 팔레트 정의를 공유하므로 같은 테마가 터미널과 브라우저에서 동일하게 보입니다.

TUI에서는 t를 눌러 선택기를 엽니다. 방향키로 각 테마를 그 자리에서 미리 보고, Enter로 적용하며, Esc로 원래 테마를 되돌립니다. 선택은 다음 실행에도 기억됩니다. 대시보드는 같은 목록을 상태 표시줄에 두고 브라우저별로 기억합니다.

hostveil tui --theme nord
hostveil serve --theme gruvbox
HOSTVEIL_THEME=tokyonight hostveil

--theme와 HOSTVEIL_THEME은 기억된 선택보다 우선합니다. 색이 뜻하는 바는 모든 테마에서 같습니다. 세 단계의 심각도, 점수 구간, 안전이 그것이고, 그래서 테마를 바꿔도 발견 항목을 읽는 방식은 달라지지 않습니다.

기호

TUI와 hostveil scan은 상태 표시 기호, 곧 브랜드 마크와 체크와 경고와 영역이 온전히 점검되지 못하는 세 가지 경우를 기본적으로 일반 유니코드(plain)로 그리며, 이는 어떤 글꼴에서도 표시됩니다. 터미널에서 이미 Nerd Font를 쓰고 있다면 --glyphs nerd로 패치된 아이콘으로 바꿀 수 있습니다.

hostveil tui --glyphs nerd
hostveil scan --glyphs nerd
HOSTVEIL_GLYPHS=nerd hostveil

자동 감지가 아니라 사용자가 켜는 방식입니다. 터미널에 어떤 글꼴을 쓰는지 물어볼 방법이 없고, 글꼴에 없는 글리프도 있는 글리프와 똑같이 한 칸에 그려지기 때문에, 잘못 짐작하면 아무도 알아채지 못한 채 두부 글자만 늘어섭니다. Nerd Font라면 Mono든 아니든 모두 동작합니다. 기호는 Font Awesome 블록에서 가져오는데, 모든 패치 글꼴이 이 블록을 담고 있고 어떤 변형에서도 한 칸 너비를 유지합니다. --theme과 마찬가지로 선택은 다음 실행에도 기억되며, --glyphs와 HOSTVEIL_GLYPHS가 그보다 우선합니다.