Tutorial: mascaramento e seu limite

Objetivo

Ao final você vai ver o mascaramento funcionar num valor que a API devolve, e ver exatamente onde ele deixa de funcionar.

Cada comando e cada saída abaixo vêm de uma execução real, gravada em demo/tutorials/masking/expected/ e conferida por run.sh --check. As saídas são do programa, em inglês.

Como rodar

bash demo/tutorials/masking/run.sh all
bash demo/tutorials/masking/run.sh --check

Script: demo/tutorials/masking/run.sh.

1. Um valor refletido é mascarado

A API coloca o cabeçalho recebido na resposta. O agente lê a referência, não o valor.

# The API reflects the header back: the agent sees the reference, not the value

$ BAO_WRAPPING_TOKEN=<wrapped token> khcall keyholder_run '{"command":"curl","args":["-sS","-H","Authorization: Bearer {{vault://my-project/dev/API_TOKEN}}","http://127.0.0.1:18080/"]}'
{
  "exit_code": 0,
  "refs_used": [
    "vault://my-project/dev/API_TOKEN"
  ],
  "stderr": "",
  "stdout": "api says: hello, caller with header Authorization: Bearer [hidden:vault://my-project/dev/API_TOKEN]\n"
}
--- stderr
<timestamp> audit cmd="curl" refs=[vault://my-project/dev/API_TOKEN] exit=0 dur=<duration> status=ok
exit_code=0

Did the API receive the stored token? yes

stderr is masked the same way (covered by internal/runner tests).

2. LIMITE: codificar escapa do mascaramento

python3 está liberado aqui só para mostrar o limite. O interpretador codifica o valor em base64 e o agente o lê, sem máscara. O mascaramento só casa o valor exato; por isso a lista de comandos nunca deve incluir interpretadores ou shells (sh, bash, python3, node, env).

# LIMIT: an allowed interpreter can encode the value and escape the mask

$ BAO_WRAPPING_TOKEN=<wrapped token> khcall keyholder_run '{"command":"python3","args":["-c","import base64,sys; print(base64.b64encode(sys.argv[1].encode()).decode())","{{vault://my-project/dev/API_TOKEN}}"]}'
{
  "exit_code": 0,
  "refs_used": [
    "vault://my-project/dev/API_TOKEN"
  ],
  "stderr": "",
  "stdout": "dG9rLWZha2Utbm90LWEtcmVhbC1zZWNyZXQ=\n"
}
--- stderr
<timestamp> audit cmd="python3" refs=[vault://my-project/dev/API_TOKEN] exit=0 dur=<duration> status=ok
exit_code=0

Decoded: tok-fake-not-a-real-secret (the fake token, unmasked)