senhasegura

Senhasegura

技能类型： 库/API 参考（类型 1）+ 数据获取（类型 3）。

senhasegura（Segura）特权访问管理平台实用集成指南。涵盖 A2A OAuth 2.0 身份验证、PAM Core 凭据和 SSH 密钥 API、用于 CI/CD 的 DevOps Secret Manager（DSM）、Kubernetes External Secrets Operator、MySafe，以及可选的 MCP 服务。

语音通知（调用时）

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the Senhasegura skill"}' \
  > /dev/null 2>&1 &

工作流路由

触发条件	工作流
“设置 A2A”、“创建 senhasegura 应用程序”、首次创建 OAuth 客户端	Workflows/SetupA2A.md
“将密钥同步到 Kubernetes”、ESO + senhasegura DSM	Workflows/SyncKubernetesSecrets.md
“轮换密码”、计划轮换、Executions 模块	Workflows/RotatePasswords.md
“在流水线中获取密钥”、CI/CD 中的 DSM runb	Workflows/InjectCiCdSecrets.md
“注册 SSH 密钥”、管理 SSH 密钥轮换	Workflows/RegisterSshKey.md

参考资料路由

主题	文件
OAuth 2.0 流程、创建 A2A 应用程序、令牌缓存	Authentication.md
PAM Core 端点——凭据、托管、SSH 密钥	PamApi.md
DSM CLI、runb、mapping.json、External Secrets Operator	Dsm.md
MySafe、Python/TypeScript 客户端、CI/CD 流水线模板	Integrations.md
错误、调试模式、速率限制、常见故障模式	Troubleshooting.md
MCP 服务（可选的 Claude Code 集成）	References/McpIntegration.md + Tools/SenhaseguraMcpServer.ts
OAuth 1.0 旧版参考	References/OAuth1Legacy.md
Python SDK 参考（PAI 标准为 TypeScript+Bun）	References/PythonSdk.md

易踩坑点

这些是 senhasegura 中不易察觉、容易让用户遇到问题的行为。发现新问题时请添加条目。

#	易踩坑点
1	GET /iso/coe/senha?credentialId=N 会自动将凭据锁定并纳入托管。 之后必须执行 DELETE /iso/pam/credential/custody/N，否则凭据会一直被锁定，直到手动释放。并发作业在第二次获取时会发生死锁。
2	OAuth 2.0 访问令牌的 TTL 为 3600s。请缓存令牌，并在过期前 60s 的缓冲期刷新，而不是等收到 401 后重试。401 重试风暴会冲击 IDP 并触发速率限制。
3	/iso/coe/senha 是旧版 A2A v1 密码获取路径；/api/pam/credential/{id} 仅返回元数据。旧版路径仍在使用——不要将其重构掉。
4	A2A 授权 IP 限制会根据 senhasegura 所见的 HTTP 源 IP 进行匹配——对于 Kubernetes，该 IP 是出口 NAT 的 IP，而不是 Pod IP。请将集群出口 IP 加入允许列表。ESO 故障会显示为通用错误“could not get provider client”。
5	DSM runb 会将密钥写入当前工作目录下的 .runb.vars。如果当前工作目录是仓库根目录，该文件可能会被误提交。请始终从临时目录运行，或设置 SENHASEGURA_SECRETS_FILE=/tmp/runb.$$.vars。
6	External Secrets Operator 的 provider 键为 senhasegura（小写），模块为 DSM（大写）。大小写混用会导致 provider 无提示地找不到；ESO 只会因无法协调而失败，不会给出明确错误。
7	dsm runb --tool-name <X> 接受 github、azure-devops、gitlab、linux。在非 Linux 容器环境（例如 Windows runner，或未指定环境）中使用 linux，会导致 CI 日志不屏蔽密钥值——密钥会泄露到日志输出中。
8	References/ 中的 Python 和 TypeScript 客户端在直接调用 getPassword 时不会自动释放托管状态。请使用提供的 withPassword(...) / password_context(...) 帮助函数，它们使用 try/finally 包装调用。
9	令牌端点是 /iso/oauth2/token——注意是 /iso/，不是 /api/。Senhasegura 的路径方案混用了 /iso/（旧版/控制台）和 /api/（较新的 REST），且不一致。
10	大多数企业安装使用内部 CA。仅在本地调试时使用 ignoreSslCertificate: true / SENHASEGURA_INSECURE: true。正确做法是通过 ca 字段将 CA 证书包挂载到 ESO。

快速参考

# 1. Get token (1h TTL)
TOKEN=$(curl -s -X POST "$SENHASEGURA_URL/iso/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$SENHASEGURA_CLIENT_ID" \
  -d "client_secret=$SENHASEGURA_CLIENT_SECRET" | jq -r '.access_token')

# 2. List credentials
curl -H "Authorization: Bearer $TOKEN" "$SENHASEGURA_URL/api/pam/credential"

# 3. Get password (auto-locks custody — see Gotcha #1)
curl -H "Authorization: Bearer $TOKEN" \
  "$SENHASEGURA_URL/iso/coe/senha?credentialId=123"

# 4. Release custody (REQUIRED after step 3)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$SENHASEGURA_URL/iso/pam/credential/custody/123"

# 5. DSM secret fetch via CLI
dsm runb --tool-name github \
  --application my-app --system production --environment prod
source .runb.vars && rm -f .runb.vars

环境变量

SENHASEGURA_URL="https://senhasegura.example.com"
SENHASEGURA_CLIENT_ID="oauth2-client-id"
SENHASEGURA_CLIENT_SECRET="oauth2-client-secret"

# DSM CLI optionals
SENHASEGURA_CONFIG_FILE="/path/to/config.yaml"
SENHASEGURA_MAPPING_FILE="/path/to/mapping.json"
SENHASEGURA_SECRETS_FILE="/tmp/runb.$$.vars"   # don't write into repo root
SENHASEGURA_TIMEOUT="30"
# SENHASEGURA_INSECURE — local debug only; mount the CA bundle in prod

文档链接

• 官方文档
• A2A 模块
• DSM 模块
• PAM Core API 参考
• GitHub 上的 DSM CLI
• External Secrets Operator — senhasegura 提供程序

执行日志

每次工作流运行后追加：

echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Senhasegura","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' \
  >> ~/.claude/PAI/MEMORY/SKILLS/execution.jsonl