nexus/openclaw/xingyao/vaultwarden/vaultwarden-research.md

# vaultwarden凭证查找研究

## 📅 研究日期
2026-03-13

## 🎯 用户需求
用户希望：通过item名称从vaultwarden中查找对应的用户名和密码。

**具体场景**：
- 用户说："从vaultwarden里找出n8n的credential"
- 我需要：
  1. 登录vaultwarden
  2. 搜索item名称为"n8n"的项目
  3. 提取对应的用户名和密码

## 🔍 技术方案研究

### 方案一：Bitwarden CLI (bw)

#### 安装和配置
```bash
# 安装Bitwarden CLI
brew install bitwarden-cli

# 配置连接到vaultwarden实例
bw config server http://localhost:8080

# 登录（需要API密钥）
export BW_CLIENTID="your-client-id"
export BW_CLIENTSECRET="your-client-secret"
bw login --apikey
```

#### 搜索命令示例
```bash
# 列出所有项目
bw list items

# 搜索特定名称的项目
bw list items --search "n8n"

# 获取特定项目的详细信息
bw get item "item-id-here"

# 获取用户名和密码
bw get username "item-id-here"
bw get password "item-id-here"
```

#### 自动化脚本示例
```bash
#!/bin/bash
# vaultwarden-search.sh

ITEM_NAME="$1"

# 搜索项目
ITEM_ID=$(bw list items --search "$ITEM_NAME" | jq -r '.[0].id')

if [ -z "$ITEM_ID" ] || [ "$ITEM_ID" = "null" ]; then
    echo "❌ 未找到项目: $ITEM_NAME"
    exit 1
fi

# 获取详细信息
USERNAME=$(bw get username "$ITEM_ID")
PASSWORD=$(bw get password "$ITEM_ID")

echo "✅ 找到项目: $ITEM_NAME"
echo "👤 用户名: $USERNAME"
echo "🔑 密码: $PASSWORD"
```

### 方案二：直接REST API调用

#### API端点
```
POST /identity/connect/token          # 获取访问令牌
GET  /api/collections                 # 获取集合列表
GET  /api/list/object/items           # 获取项目列表
GET  /api/items/{id}                  # 获取特定项目
```

#### Python示例
```python
import requests
import json

class VaultwardenClient:
    def __init__(self, server_url, client_id, client_secret):
        self.server_url = server_url
        self.client_id = client_id
        self.client_secret = client_secret
        self.access_token = None
    
    def login(self):
        """获取访问令牌"""
        auth_data = {
            "grant_type": "client_credentials",
            "client_id": self.client_id,
            "client_secret": self.client_secret,
            "scope": "api"
        }
        
        response = requests.post(
            f"{self.server_url}/identity/connect/token",
            data=auth_data
        )
        
        if response.status_code == 200:
            self.access_token = response.json()["access_token"]
            return True
        return False
    
    def search_item(self, item_name):
        """搜索项目"""
        headers = {"Authorization": f"Bearer {self.access_token}"}
        
        # 获取所有项目
        response = requests.get(
            f"{self.server_url}/api/list/object/items",
            headers=headers
        )
        
        if response.status_code == 200:
            items = response.json()
            # 搜索匹配的项目
            for item in items:
                if item_name.lower() in item["name"].lower():
                    return item
        return None
    
    def get_credentials(self, item_name):
        """获取项目的凭证"""
        item = self.search_item(item_name)
        if item:
            return {
                "username": item.get("login", {}).get("username"),
                "password": item.get("login", {}).get("password")
            }
        return None
```

### 方案三：集成到OpenClaw技能系统

#### 技能结构
```
vaultwarden-skill/
├── SKILL.md                    # 技能文档
├── vaultwarden-client.sh       # CLI客户端脚本
├── vaultwarden-api.py          # Python API客户端
└── examples/
    └── get-credentials.sh      # 使用示例
```

#### 技能功能
1. **配置管理**：存储vaultwarden连接配置
2. **认证处理**：处理API密钥和会话管理
3. **搜索功能**：按名称搜索项目
4. **凭证提取**：安全获取用户名和密码
5. **安全清理**：使用后清理内存中的凭证

## 🔐 安全考虑

### 凭证存储
- **不存储明文密码**：只在内存中临时使用
- **加密配置**：API密钥加密存储
- **会话管理**：短期访问令牌，定期刷新

### 访问控制
- **最小权限**：只读取需要的项目
- **审计日志**：记录所有访问请求
- **手动确认**：重要操作需要用户确认

### 清理机制
```bash
# 使用后清理环境变量
unset BW_SESSION
unset VAULTWARDEN_CREDENTIALS

# 清理命令行历史
history -c
```

## 🚀 实施建议

### 阶段一：基础测试
1. **安装Bitwarden CLI**
   ```bash
   brew install bitwarden-cli jq
   ```

2. **测试连接**
   ```bash
   # 配置服务器
   bw config server http://localhost:8080
   
   # 测试API连接
   bw status
   ```

3. **创建测试脚本**
   ```bash
   # 简单的搜索脚本
   ./vaultwarden-search.sh n8n
   ```

### 阶段二：集成开发
1. **创建vaultwarden技能**
   - 基于1password技能模式
   - 添加vaultwarden特定功能

2. **安全封装**
   - 凭证安全处理
   - 错误处理和日志
   - 清理机制

3. **测试验证**
   - 单元测试
   - 集成测试
   - 安全测试

### 阶段三：生产部署
1. **配置管理**
   - 环境变量配置
   - 加密存储
   - 备份机制

2. **监控审计**
   - 访问日志
   - 异常监控
   - 定期审计

3. **文档培训**
   - 使用文档
   - 安全指南
   - 故障排除

## 📋 使用流程设计

### 用户指令
```
"从vaultwarden里找出n8n的credential"
```

### 系统响应
1. **解析指令**：识别"vaultwarden"和"n8n"
2. **认证登录**：使用API密钥登录vaultwarden
3. **搜索项目**：查找名称为"n8n"的项目
4. **提取凭证**：获取用户名和密码
5. **返回结果**：安全地返回凭证信息
6. **清理内存**：清除临时凭证数据

### 输出格式
```
✅ 找到vaultwarden项目: n8n
📋 项目ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
👤 用户名: admin@example.com
🔑 密码: ********
📝 备注: n8n工作流平台管理员账户
```

## ⚠️ 风险与缓解

### 风险1：凭证泄露
- **缓解**：不在日志中记录密码，使用后立即清理内存

### 风险2：API密钥泄露
- **缓解**：加密存储，定期轮换，最小权限原则

### 风险3：未授权访问
- **缓解**：IP白名单，访问频率限制，审计日志

### 风险4：会话劫持
- **缓解**：短期令牌，HTTPS加密，定期刷新

## 🔮 未来扩展

### 功能扩展
1. **批量操作**：一次获取多个项目的凭证
2. **自动填充**：在Web表单中自动填充凭证
3. **密码生成**：生成安全密码并保存
4. **过期提醒**：密码过期前提醒更新

### 集成扩展
1. **Docker集成**：在容器启动时注入凭证
2. **CI/CD集成**：在流水线中安全使用凭证
3. **监控集成**：监控vaultwarden服务状态
4. **备份集成**：自动备份vaultwarden数据

## 📝 待决策事项

### 技术决策
1. **使用Bitwarden CLI还是直接API？**
   - CLI更成熟，API更灵活
   - 建议：从CLI开始，需要时扩展API

2. **认证方式？**
   - API密钥 vs 用户名密码
   - 建议：API密钥，更安全可控

3. **凭证存储方式？**
   - 环境变量 vs 配置文件 vs 密钥管理服务
   - 建议：加密配置文件+环境变量覆盖

### 安全决策
1. **访问控制粒度？**
   - 只读访问 vs 读写访问
   - 建议：只读访问，最小权限

2. **审计日志级别？**
   - 基本日志 vs 详细日志
   - 建议：详细日志但脱敏敏感信息

3. **会话超时时间？**
   - 短期（分钟） vs 长期（小时）
   - 建议：短期会话，自动刷新

## ✅ 下一步行动

### 立即行动
1. **安装测试工具**
   ```bash
   brew install bitwarden-cli jq
   ```

2. **获取API密钥**
   - 从vaultwarden Web界面生成API密钥

3. **创建测试脚本**
   - 实现基本的搜索功能

### 短期计划（1周内）
1. **创建vaultwarden技能原型**
2. **安全测试和验证**
3. **文档编写**

### 中期计划（1个月内）
1. **集成到OpenClaw系统**
2. **实现完整的凭证管理流程**
3. **用户培训和部署**

---

**研究完成时间**: 2026-03-13 22:30 GMT+8  
**研究人员**: 星曜 (OpenClaw助手)  
**状态**: 研究完成，等待用户决策