`pki health-check` — PKI 마운트 건강 상태 확인하기

vault pki health-check 명령어는 주어진 PKI 시크릿 엔진 마운트의 건강 상태를 선택적 구성에 대해 검증하는 명령어예요.

이것은 주어진 토큰의 권한으로 실행되며, 주어진 Vault 서버에 대해 마운트와 /sys의 다양한 API를 읽어요.

마운트는 경로에 네임스페이스 접두사를 포함해 지정해야 해요. 예: ns1/pki.

출처: 문서

본문

예시 (Examples)

pki-root 마운트에 대해 기본 헬스 체크를 수행해요:

$ vault pki health-check pki-root/

구성은 -health-config 플래그로 지정할 수 있어요:

$ vault pki health-check -health-config=mycorp-root.json pki-root/

-list 플래그를 사용하면 이 마운트에 대해 실행될 헬스 체크 목록과 알려진 구성 값(기본값 포함)을 보여줘요:

$ vault pki health-check -list pki-root/

사용법 (Usage)

이 명령어에 고유한 플래그는 다음과 같아요:

-default-disabled — 지정하면 구성 파일이 명시적으로 활성화하지 않는 한 모든 헬스 체크가 기본적으로 비활성화돼요. 기본값은 false로, 모든 기본 활성화 헬스 체크가 실행된다는 뜻이에요.
-health-config (string: "") — 헬스 체크 실행과 매개변수를 수정하는 JSON 구성 파일 경로.
-list — 지정하면 헬스 체크를 실행하지 않고 알려진 모든 헬스 체크를 출력해요. 여전히 위치 인자로 마운트가 필요해요. 기본값은 false로, 목록이 출력되지 않고 헬스 체크가 실행된다는 뜻이에요.
-return-indicator (string: "default") — 이 명령어의 반환 값(종료 코드) 동작:
- permission — 도구에 권한이 없거나 서버와 버전이 일치하지 않을 때 0이 아닌 코드로 종료;
- critical — 위에 추가로 검사가 critical 상태를 반환할 때 0이 아닌 코드로 종료;
- warning — 위에 추가로 검사가 warning 상태를 반환할 때 0이 아닌 상태로 종료;
- informational — 위에 추가로 검사가 informational 상태를 반환할 때 0이 아닌 상태로 종료;
- default — 메시지 심각도에 기반한 기본 동작으로, 모든 검사가 통과하고 실행 오류가 없을 때만 0 종료 상태를 반환.

이 명령어는 stdout으로 보내는 출력의 표시를 제어하기 위해 -format 매개변수를 존중해요. 헬스 체크 실행을 막는 치명적 오류는 이 형식을 따르지 않을 수 있어요.

반환 상태와 출력 (Return status and output)

이 명령어는 다음 종료 코드를 반환해요:

0 — 모든 것이 정상.
1 — 사용법 오류(CLI 파라미터 확인).
2 — 헬스 체크의 informational 메시지.
3 — 헬스 체크의 warning 메시지.
4 — 헬스 체크의 critical 메시지.
5 — 헬스 체크와 Vault 서버 사이의 버전 불일치로, 하나 이상의 헬스 체크가 완전히 실행되지 못함.
6 — 하나 이상의 헬스 체크에 대해 Vault 서버가 권한 거부(permission denied) 메시지를 반환함.

종료 코드 5(버전 불일치로 인한)가 헬스 체크에 반드시 치명적인 것은 아니라는 점을 참고하세요. 예를 들어 crl_validity_period 헬스 체크는 Vault 1.11에 Delta CRL이 없어 해당 버전에서 실행하면 invalid version 경고를 반환하지만, 전체 CRL을 검사하는 능력에는 영향을 주지 않아요.

각 헬스 체크는 하나 이상의 결과를 목록으로 출력해요. 이 목록은 키(status, status_code, endpoint, message)를 헬스 체크가 반환한 값에 매핑한 것이에요. 엔드포인트는 둘 이상의 헬스 체크에 나타날 수 있으며 서버에 존재한다는 보장은 없어요(예: 와일드카드로 모든 일치 경로가 같은 결과임을 나타내는 경우). 표(table) 형식은 프로그램적으로 소비되기 위한 것이므로 상태 코드를 생략해요.

이들은 다음 헬스 체크 상태 값에 대응해요:

not_applicable 상태 / 상태 코드 0: 종료 코드 0.
ok 상태 / 상태 코드 1: 종료 코드 0.
informational 상태 / 상태 코드 2: 종료 코드 2.
warning 상태 / 상태 코드 3: 종료 코드 3.
critical 상태 / 상태 코드 4: 종료 코드 4.
invalid_version 상태 / 상태 코드 5: 종료 코드 5.
insufficient_permissions 상태 / 상태 코드 6: 종료 코드 6.

헬스 체크 (Health checks)

현재 구현된 헬스 체크는 다음과 같아요. 향후 릴리스에서 더 많은 헬스 체크가 추가될 수 있으며 기본적으로 활성화될 수 있어요.

CA 유효 기간 (CA validity period)

이름: ca_validity_period

접근하는 API:

LIST /issuers (unauthenticated)
READ /issuer/:issuer_ref/json (unauthenticated)

구성 파라미터:

root_expiry_critical (duration: 182d) — 루트의 수명이 critical로 간주되는 기간.
intermediate_expiry_critical (duration: 30d) — 중간(intermediate)의 수명이 critical로 간주되는 기간.
root_expiry_warning (duration: 365d) — 루트의 수명이 warning으로 간주되는 기간.
intermediate_expiry_warning (duration: 60d) — 중간의 수명이 warning으로 간주되는 기간.
root_expiry_informational (duration: 730d) — 루트의 수명이 informational로 간주되는 기간.
intermediate_expiry_informational (duration: 180d) — 중간의 수명이 informational로 간주되는 기간.

이 헬스 체크는 마운트의 각 발급자(issuer)의 유효 상태를 확인해 목록을 반환해요. CA가 다음 30일 안에 만료되면 결과는 critical이에요. 루트 CA가 다음 12개월 안에 또는 중간 CA가 다음 2개월 안에 만료되면 결과는 warning이에요. 루트 CA가 24개월 안에 또는 중간 CA가 6개월 안에 만료되면 결과는 informational이에요.

교정 단계:

곧 만료될 CA를 확인하려면 CA 회전 작업을 수행해요.
만료 예정 CA에서 새 CA로 마이그레이션해요.
다음 옵션 중 하나로 만료된 CA를 삭제해요:
- vault write <mount>/tidy tidy_expired_issuers=true로 tidy를 수동 실행.
- Vault API로 delete issuer를 호출.

CRL 유효 기간 (CRL validity period)

이름: crl_validity_period

접근하는 API:

LIST /issuers (unauthenticated)
READ /config/crl (선택)
READ /issuer/:issuer_ref/crl (unauthenticated)
READ /issuer/:issuer_ref/crl/delta (unauthenticated)

구성 파라미터:

crl_expiry_pct_critical (int: 95) — CRL이 만료에 임박한 것으로 간주되는 유효 기간의 백분율.
delta_crl_expiry_pct_critical (int: 95) — Delta CRL이 만료에 임박한 것으로 간주되는 유효 기간의 백분율.

이 헬스 체크는 각 발급자의 CRL 유효 상태를 확인해 목록을 반환해요. 성공적인 회전에 필요한 노력 때문에 날짜 기반 기간이 합리적인 CA와 달리, CRL 회전은 훨씬 쉬우므로 백분율 기반 접근 방식이 합리적이에요. 선택한 백분율이 CRL 구성의 grace_period를 초과하면 OK가 아니라 informational 메시지가 발행돼요.

정보 제공을 위해 CRL 구성을 읽고, 활성화되지 않았다면 CRL 자동 재구축(auto-rebuild) 활성화를 제안해요.

교정 단계:

vault write로 CRL 자동 재구축을 활성화해요:

$ vault write <mount>/config/crl auto_rebuild=true

하드웨어 기반 루트 인증서 (Hardware-Backed root certificate)

이름: hardware_backed_root

API:

LIST /issuers (unauthenticated)
READ /issuer/:issuer_ref
READ /key/:key_ref

구성 파라미터:

enabled (boolean: false) — 기본적으로 실행되지 않음.

이 헬스 체크는 소프트웨어 키로 뒷받침되는 루트 CA가 있는 발급자를 확인해요. Vault는 안전하지만, 프로덕션 루트 인증서에는 KMS 기반 키의 추가 무결성을 권장해요. 이것은 정보 제공용 검사일 뿐이에요. 모든 루트가 KMS 기반이면 OK를 반환하고, 어떤 발급자도 루트가 아니면 not applicable을 반환해요.

Vault Enterprise Managed Keys에서 하드웨어 기반 키에 대해 더 알아보세요.

루트 인증서가 발급한 Non-CA 리프 (Root certificate issued Non-CA leaves)

이름: root_issued_leaves

API:

LIST /issuers (unauthenticated)
READ /issuer/:issuer_ref/pem (unauthenticated)
LIST /certs
READ /certs/:serial (unauthenticated)

구성 파라미터:

certs_to_fetch (int: 100) — 루트가 직접 발급한 리프가 있는지 보기 위해 가져올 리프 인증서 수.

이 헬스 체크는 적절한 CA 계층이 사용 중인지 검증해요. certs_to_fetch개의 리프 인증서를 가져와(설정 가능) 그것들이 non-issuer 리프인지, 그리고 이 마운트의 루트 발급자가 서명했는지 확인해요. 발견되면 이에 대해 경고하고 중간 CA 설정을 권장해요.

교정 단계:

루트 발급자에 대한 sign, sign-verbatim, issue, ACME API 사용을 제한해요.
다른 마운트에 중간 발급자를 생성해요.
루트 발급자가 새 중간 발급자에 서명하게 해요.
중간 발급자를 사용해 새 리프 인증서를 발급해요.

역할이 암시적 localhost 발급을 허용함 (Role allows implicit localhost issuance)

이름: role_allows_localhost

API:

LIST /roles
READ /roles/:name

구성 파라미터: (없음)

비어 있지 않은 allowed_domains 값으로 암시적 localhost 기반 발급(allow_localhost=true)을 허용하는 역할이 있는지 확인해요.

교정 단계:

모든 역할에 대해 allow_localhost를 false로 설정해요.
allowed_domains 필드를 허용된 localhost 유사 도메인의 명시적 목록으로 업데이트해요.

역할이 Glob 기반 와일드카드 발급을 허용함 (Role allows Glob-Based wildcard issuance)

이름: role_allows_glob_wildcards

API:

LIST /roles
READ /roles/:name

구성 파라미터:

allowed_roles (list: nil) — 무시할 역할의 허용 목록.

각 역할이 와일드카드 발급과 glob 도메인을 허용하는지 확인해요. 와일드카드와 glob은 상호작용해 중첩 와일드카드 같은 (잠재적으로 위험한) 특이점을 만들 수 있어요.

교정 단계:

allow_glob_domains와 allow_wildcard_certificates가 모두 true여야 하는 역할은 두 역할로 나눠요.
glob 도메인과 와일드카드를 허용하는 역할을 allowed_roles에 추가해 Vault가 향후 검사에서 무시하게 해요.
모든 역할에 대해 다음 두 가지가 모두 참이 될 때까지 역할 분할을 계속해요:
- 역할이 allow_glob_domains 또는 allow_wildcard_certificates 중 하나만 가짐(둘 다가 아님).
- allow_glob_domains와 allow_wildcard_certificates가 있는 역할만 인증서의 모든 SAN에 필요.

역할이 no_store=false를 설정함 (Role sets no_store=false and performance)

이름: role_no_store_false

API:

LIST /roles
READ /roles/:name
LIST /certs
READ /config/crl

구성 파라미터:

allowed_roles (list: nil) — 무시할 역할의 허용 목록.

각 역할이 no_store를 false로 설정했는지 확인해요.

경고: 시간 CRL 자동 재구축 없이 인증서가 많고 no_store를 true로 설정하면 Vault가 경고를 주고 성능이 저하돼요.

교정 단계:

no_store=false인 비-ACME 역할을 업데이트해요. 참고: ACME 발급에 사용되는 역할은 no_store를 true로 설정해야 해요.
인증서 수명을 가능한 한 짧게 설정해요.
필요에 따라 BYOC 폐기를 사용해 인증서를 폐기해요.

감사 정보 접근성 (Accessibility of audit information)

이름: audit_visibility

API:

READ /sys/mounts/:mount/tune

구성 파라미터:

ignored_parameters (list: nil) — HMAC 상태를 무시할 파라미터 목록.

이 헬스 체크는 감사 정보가 로그 소비자에게 접근 가능한지 확인하며, 안전한 감사 파라미터와 안전하지 않은 감사 파라미터의 목록이 일반적으로 지켜지는지 검증해요. 존재한다면 이들은 informational 응답이에요.

교정 단계:

vault secrets tune으로 원하는 감사 파라미터를 설정해요:

$ vault secrets tune \
  -audit-non-hmac-response-keys=certificate \
  -audit-non-hmac-response-keys=issuing_ca \
  -audit-non-hmac-response-keys=serial_number \
  -audit-non-hmac-response-keys=error \
  -audit-non-hmac-response-keys=ca_chain \
  -audit-non-hmac-request-keys=certificate \
  -audit-non-hmac-request-keys=issuer_ref \
  -audit-non-hmac-request-keys=common_name \
  -audit-non-hmac-request-keys=alt_names \
  -audit-non-hmac-request-keys=other_sans \
  -audit-non-hmac-request-keys=ip_sans \
  -audit-non-hmac-request-keys=uri_sans \
  -audit-non-hmac-request-keys=ttl \
  -audit-non-hmac-request-keys=not_after \
  -audit-non-hmac-request-keys=serial_number \
  -audit-non-hmac-request-keys=key_type \
  -audit-non-hmac-request-keys=private_key_format \
  -audit-non-hmac-request-keys=managed_key_name \
  -audit-non-hmac-request-keys=managed_key_id \
  -audit-non-hmac-request-keys=ou \
  -audit-non-hmac-request-keys=organization \
  -audit-non-hmac-request-keys=country \
  -audit-non-hmac-request-keys=locality \
  -audit-non-hmac-request-keys=province \
  -audit-non-hmac-request-keys=street_address \
  -audit-non-hmac-request-keys=postal_code \
  -audit-non-hmac-request-keys=permitted_dns_domains \
  -audit-non-hmac-request-keys=permitted_email_addresses \
  -audit-non-hmac-request-keys=permitted_ip_ranges \
  -audit-non-hmac-request-keys=permitted_uri_domains \
  -audit-non-hmac-request-keys=excluded_dns_domains \
  -audit-non-hmac-request-keys=excluded_email_addresses \
  -audit-non-hmac-request-keys=excluded_ip_ranges \
  -audit-non-hmac-request-keys=excluded_uri_domains \
  -audit-non-hmac-request-keys=policy_identifiers \
  -audit-non-hmac-request-keys=ext_key_usage_oids \
  -audit-non-hmac-request-keys=csr \
   <mount>

ACL 정책이 문제 있는 엔드포인트를 허용함 (ACL policies allow problematic endpoints)

이름: policy_allow_endpoints

API:

LIST /sys/policy
READ /sys/policy/:name

구성 파라미터:

allowed_policies (list: nil) — 안전하지 않은 API 접근을 위해 허용 목록에 넣을 정책 목록.

이 헬스 체크는 API에 대한 안전하지 않은 접근(예: sign-intermediate, sign-verbatim, sign-self-issued)이 허용되는지 확인해요. 발견 사항은 critical 결과이며 관리자가 시정하거나 명시적으로 허용해야 해요.

If-Modified-Since 요청 허용 (Allow If-Modified-Since requests)

이름: allow_if_modified_since

API:

READ /sys/internal/ui/mounts

구성 파라미터: (없음)

이 헬스 체크는 If-Modified-Since 헤더가 passthrough_request_headers에 추가되었고 Last-Modified 헤더가 allowed_response_headers에 추가되었는지 확인해요. 둘 다 설정되지 않았으면 informational 메시지, 하나만 설정되었으면 warning이에요.

교정 단계:

vault secrets tune으로 모든 정책의 allowed_response_headers와 passthrough_request_headers를 업데이트해요:

$ vault secrets tune \
    -passthrough-request-headers="If-Modified-Since" \
    -allowed-response-headers="Last-Modified" \
    <mount>

ACME를 사용한다면 vault secrets tune으로 ACME 전용 헤더를 업데이트해요:

$ vault secrets tune \
    -passthrough-request-headers="If-Modified-Since" \
    -allowed-response-headers="Last-Modified" \
    -allowed-response-headers="Replay-Nonce" \
    -allowed-response-headers="Link" \
    -allowed-response-headers="Location" \
    <mount>

Auto-Tidy 비활성화 (Auto-Tidy disabled)

이름: enable_auto_tidy

API:

READ /config/auto-tidy

구성 파라미터:

interval_duration_critical (duration: 7d) — critical 임계값에 도달하기 위한 최대 허용 interval_duration.
interval_duration_warning (duration: 2d) — warning 임계값에 도달하기 위한 최대 허용 interval_duration.
pause_duration_critical (duration: 1s) — critical 임계값에 도달하기 위한 최대 허용 pause_duration.
pause_duration_warning (duration: 200ms) — warning 임계값에 도달하기 위한 최대 허용 pause_duration.

이 헬스 체크는 auto-tidy가 interval_duration과 pause_duration에 합리적인 기본값으로 활성화되었는지 확인해요. 비활성화된 발견 사항은 정보 제공용인데, 이것은 모범 사례일 뿐 엄격히 요구되진 않기 때문이에요. 하지만 interval_duration이나 pause_duration에 관한 다른 발견 사항은 critical/warning이에요.

교정 단계

vault write로 권장 기본값과 함께 auto-tidy를 활성화해요:

$ vault write <mount>/config/auto-tidy \
    enabled=true \
    tidy_cert_store=true \
    tidy_revoked_certs=true \
    tidy_acme=true \
    tidy_revocation_queue=true \
    tidy_cross_cluster_revoked_certs=true \
    tidy_revoked_cert_issuer_associations=true

Tidy가 실행되지 않음 (Tidy hasn't run)

이름: tidy_last_run

API:

READ /tidy-status

구성 파라미터:

last_run_critical (duration: 7d) — tidy가 마지막으로 실행되었어야 할 critical 지연 임계값.
last_run_warning (duration: 2d) — tidy가 마지막으로 실행되었어야 할 warning 지연 임계값.

이 헬스 체크는 tidy가 마지막 실행 창 안에 실행되었는지 확인해요. 이것은 Vault 성능에 심각한 영향을 미치기 시작할 수 있으므로 critical/warning 경고가 될 수 있어요.

교정 단계:

vault write로 tidy 수동 실행을 예약해요:

$ vault write <mount>/tidy \
    tidy_cert_store=true \
    tidy_revoked_certs=true \
    tidy_acme=true \
    tidy_revocation_queue=true \
    tidy_cross_cluster_revoked_certs=true \
    tidy_revoked_cert_issuer_associations=true

추가 정보는 vault read <mount>/tidy-status로 tidy 상태 엔드포인트를 검토해요.
로그 정보와 수동 실행 결과를 기반으로 auto-tidy를 재구성해요.

인증서가 너무 많음 (Too many certificates)

이름: too_many_certs

API:

READ /tidy-status
LIST /certs

구성 파라미터:

count_critical (int: 250000) — 인증서가 너무 많은 것으로 간주되는 critical 임계값.
count_warning (int: 50000) — 인증서가 너무 많은 것으로 간주되는 warning 임계값.

이 헬스 체크는 이 클러스터에 합리적인 수의 인증서가 있는지 확인해요. 이상적으로는 tidy의 상태나 새 메트릭 보고 형식에서 가져오지만, tidy가 실행되지 않았을 때의 폴백으로 목록 연산을 대신 수행해요.

교정 단계:

vault read로 tidy가 최근에 실행되었는지 확인해요:

$ vault read <mount>/tidy-status

vault write로 tidy 수동 실행을 예약해요:

$ vault write <mount>/tidy \
  tidy_cert_store=true \
  tidy_revoked_certs=true \
  tidy_acme=true \
  tidy_revocation_queue=true \
  tidy_cross_cluster_revoked_certs=true \
  tidy_revoked_cert_issuer_associations=true

auto-tidy를 활성화해요.
인증서를 너무 일찍 갱신하지 않도록 해요. 인증서 수명은 인증서의 예상 사용량을 반영해야 해요. TTL이 적절히 설정되면 대부분의 인증서는 수명의 약 2/3 지점에서 갱신돼요.
모든 역할의 no_store 필드를 true로 설정하고 BYOC 폐기를 사용해 저장을 피하는 것을 고려해요.

ACME 발급 활성화 (Enable ACME issuance)

이름: enable_acme_issuance

API:

READ /config/acme
READ /config/cluster
LIST /issuers (unauthenticated)
READ /issuer/:issuer_ref/json (unauthenticated)

구성 파라미터: (없음)

이 헬스 체크는 중간 발급자를 포함하는 마운트 안에 ACME가 활성화되었는지 확인해요. 자가 회전(self-rotating) PKI 인프라를 지원하는 모범 사례로 간주되기 때문이에요.

Vault에서 ACME 지원을 활성화하는 방법은 ACME Certificate Issuance API 문서를 검토하세요.

ACME 응답 헤더 (ACME response headers)

이름: allow_acme_headers

API:

READ /sys/internal/ui/mounts

구성 파라미터: (없음)

이 헬스 체크는 ACME 기능이 활성화되었을 때 Replay-Nonce, Link, Location 헤더가 allowed_response_headers에 추가되었는지 확인해요. 이 헤더들이 마운트에 추가되지 않으면 ACME 프로토콜은 동작하지 않아요.

교정 단계:

vault secrets tune으로 누락된 헤더를 allowed_response_headers에 추가해요:

$ vault secrets tune \
  -allowed-response-headers="Last-Modified" \
  -allowed-response-headers="Replay-Nonce" \
  -allowed-response-headers="Link" \
  -allowed-response-headers="Location" \
  <mount>

더 알아보기 (Learn more)

vault pki issue — 중간 CA 인증서 발급
vault pki — PKI 하위 명령어 모음
PKI 시크릿 엔진 문서

`pki health-check` — PKI 마운트 건강 상태 확인하기