Vault 學習筆記

Vault 學習筆記

什麼是 Vault

Vault 是 HashiCorp 這家公司推出的一項中心化的機密管理系統，用來儲存與管理敏感資訊，例如：

  1. 密碼
  2. 憑證
  3. token
  4. API 金鑰
  5. 其他敏感資訊等

它要解決什麼問題

在傳統的開發與維運流程中，機密資訊常常散落在各處，造成安全風險與管理困難。Vault 主要想解決以下問題：

  1. 機密散落（Secret Sprawl）

    • 密碼、API 金鑰、憑證常被寫死在程式碼、設定檔或環境變數中
    • 難以追蹤到底有哪些機密、存放在哪裡

  2. 權限控管困難

    • 缺乏統一機制決定「誰」可以存取「哪些」機密
    • Vault 透過 policy 集中管理存取權限

  3. 缺乏稽核紀錄

    • 無法得知機密何時、被誰存取
    • Vault 提供完整的稽核日誌 audit log

  4. 機密沒有輪替 Rotation

    • 靜態機密長期不變，一旦外洩影響範圍大
    • Vault 支援動態機密與自動輪替，需要時才產生、到期自動撤銷

  5. 加密門檻高

    • 應用程式自行實作加密容易出錯
    • Vault 提供「加密即服務」，讓應用程式無需自行管理加密金鑰

Vault 不只是存密碼

Client 經過 authentication 和 validation 後會取得一個和 policy 綁定的 Vault token。之後 client 帶著這個 token 呼叫 Vault API 時，Vault 會透過 policy 上的路徑和操作來判斷要不要放行。

這邊容易搞錯，Vault token 主要是用來呼叫 Vault API 的憑證，不是應用程式真正要使用的機密。當 request 通過授權後，Vault 可以回傳已保存的 static secret，也可以透過 secrets engine 產生一組短效的 dynamic secret。

Dynamic secret 通常會有 TTL 和 lease。TTL 決定它能用多久，lease 則是 Vault 用來追蹤這組機密生命週期的紀錄。時間到了，或是 lease 被 revoke，這組臨時憑證就會失效。

這也是 Vault 很強大的地方，可以讓我們不需要把長期有效的密碼寫死在 application 中。

運作方式

Core Vault Workflow

Source: HashiCorp Vault documentation

1. Authenticate 認證

Client 向 Vault 出示身分證明方法（例如帳密、AppRole 的 role ID/secret ID、GitHub token 等）。

2. Validation 驗證

Vault 會依據前一步 client 提供的方法來驗證身分（GitHub、LDAP、AppRole 等）。

3. Authorize 授權

身分確認後，Vault 用你 token 綁的 policy 比對：你這次想存取的 path + 操作，允不允許？

policy 就是「哪些 API 路徑 / 操作可以碰」的規則集合。和 IAM 的機制很類似

這邊可能會覺得很奇怪：Authorize 還沒開始，為什麼 token 身上已經有 policy？

原因是 Vault token 是在 authentication / validation 成功後建立的，而 token 建立時就會附上對應的 token policies。之後每次 request 進入 Authorize 階段時，Vault 只是拿 token 上的 policy 來比對這次的 path 與操作。

4. Access 存取

通過授權後，Vault 才真正發出機密、金鑰或加密能力。之後就能拿這張 token 繼續做後續操作。

怎麼用

我們用一個簡單的 demo 來看看，並驗證上面的流程。

想驗證的重點：Vault 在處理 request 時，會先確認憑證有效，再依照 policy 授權，通過後才允許 access；任一關沒過就會被擋下。而且被擋下的 request 會進 audit log。

環境用 dev mode 的 Vault container，搭配 Python 的 hvac client。

Step 0. 起一個 dev mode Vault

dev mode 會自動幫你 init + unseal，root token 直接指定成 root，最適合拿來玩：

1
2
3
4
docker run -d --name vault-flow-demo --cap-add=IPC_LOCK \
  -e VAULT_DEV_ROOT_TOKEN_ID=root \
  -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \
  -p 8200:8200 hashicorp/vault

連上去，順便開 audit log 並輸出到 stdout，這樣我們就可以用 docker logs 查看：

1
2
3
4
5
6
import hvac
root = hvac.Client(url="http://127.0.0.1:8200", token="root")
root.sys.enable_audit_device(
    device_type="file", path="file",
    options={"file_path": "stdout", "log_raw": "true"},  # Production 環境不建議開 log_raw
)

Step 1. 用 root 建好測試環境

建一個 secret，加一條 policy，再開一個綁上這條 policy 的使用者：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 建立 secret
root.secrets.kv.v2.create_or_update_secret(
    path="myapp", secret={"password": "s3cr3t", "api_key": "abc123"})

# 只允許讀 secret/data/myapp 的 policy
root.sys.create_or_update_policy(name="readonly", policy='''
path "secret/data/myapp" {
  capabilities = ["read"]
}
''')

# userpass 使用者，綁上這條 policy
root.sys.enable_auth_method(method_type="userpass", path="userpass")
root.auth.userpass.create_or_update_user(
    username="kevin", password="pass", policies=["readonly"])

Step 2. Authenticate - 帳密換 token

對應流程第 1 步：出示帳密證明我是誰，Vault 發一個 token 給我，並把 policy 綁上去。

1
2
3
4
user = hvac.Client(url="http://127.0.0.1:8200")
login = user.auth.userpass.login(username="kevin", password="pass")
ktok = login["auth"]["client_token"]
print(ktok[:12], login["auth"]["token_policies"])
1
hvs.CAESIAFf... ['default', 'readonly']

拿到 token 了，而且身上就綁著剛剛的 readonly policy。這張 token 就是後面每個 request 的憑證。

Step 3. 驗證 token - 把 token 竄改後再打，會在授權前就被擋

這裡用後續 request 示範：Vault 在授權前會先確認 token 本身是否有效。把 token 末 4 碼改掉看看。

1
2
3
forged = ktok[:-4] + "0000"          # 改掉末 4 碼
bad = hvac.Client(url="http://127.0.0.1:8200", token=forged)
bad.secrets.kv.v2.read_secret_version(path="myapp")
1
hvac.exceptions.Forbidden: 403

token 驗證沒過回 403，不會進到比對 policy 那一步。

Step 4. Authorize - 合法 token，但做沒授權的事 → 403

對應流程第 3 步。這次用正常的 token，但去做 policy 沒給的操作：寫入、或讀別的路徑。Vault 拿 token 綁的 policy 一比對，發現不允許，就擋下。

1
2
3
4
kv = hvac.Client(url="http://127.0.0.1:8200", token=ktok)

kv.secrets.kv.v2.create_or_update_secret(path="myapp", secret={"x": "1"})  # 寫入
kv.secrets.kv.v2.read_secret_version(path="other")                        # 讀別的路徑
1
2
寫入 secret/myapp  -> 403 permission denied  (policy 只能 read)
讀取 secret/other  -> 403 permission denied  (policy 沒包含這個路徑)

token 是好的，但 path + 操作不在 policy 允許範圍，一樣過不了。

Step 5. Access - 合法 token + policy 測試取得資料

對應流程第 4 步。這次做的事在 policy 範圍內，通過全部關卡，Vault 才真正把 secret 吐出來：

1
2
ok = kv.secrets.kv.v2.read_secret_version(path="myapp")
print(ok["data"]["data"])
1
{'api_key': 'abc123', 'password': 's3cr3t'}

Step 6. 驗證流程順序 - 撈 audit log 來看

撈出所有 request 紀錄：

1
docker logs vault-flow-demo | grep '"type":"request"'

整理成 operation / path / 結果，對照前面每個 step：

1
2
3
4
5
6
7
operation  path                       result
create     secret/data/myapp          allowed        <- Step 1 root 建 secret
update     auth/userpass/login/kevin  allowed        <- Step 2 登入
read       secret/data/myapp          DENIED         <- Step 3 竄改 token
update     secret/data/myapp          DENIED         <- Step 4 沒授權寫入
read       secret/data/other          DENIED         <- Step 4 沒授權讀取
read       secret/data/myapp          allowed        <- Step 5 授權通過

關鍵就在這張表：那 3 筆 DENIED 和最後成功那筆並列出現在 audit log。這代表 request 即使被拒絕也沒有被丟掉，而是留在 audit log 中，方便後續觀察。

收尾

關掉 Docker container 收工

1
docker rm -f vault-flow-demo

Reference

技術筆記
#Vault #HashiCorp #Secret Management #Security
Vault 學習筆記
https://weiblog.me/2026-08-19/2026-vault-learning-notes/
Author
wei
Posted on
August 19, 2026
Licensed under