内容
# 安全操作
一个MCP（模型上下文协议）服务器，为AI助手提供安全的访问权限和身份验证的HTTP请求方式，而无需暴露凭证给LLM。
## 为什么？
当AI助手需要调用需要身份验证的API时，简单的方法是直接在聊天中粘贴令牌。这样一来，您的秘密信息就会出现在：
- LLM的上下文窗口中
- 聊天记录和转录中
- 模型训练数据中（可能）
**安全操作**通过在静止时保持秘密信息的加密，只有在使用时才解密 - 在MCP服务器进程内部，而不会在LLM上下文中。
## 工作原理
```
用户 ──► Claude 代码 ──► MCP 协议 ──► 安全操作 ──► MongoDB
│
├─ 使用 AES-256-GCM 加密
├─ 主密钥位于 ~/.secure-actions/master.key
└─ 仅在 HTTP 请求执行期间解密
```
1. **存储秘密信息** — MCP服务器向客户端（Claude Code）发送一个提示请求。用户在表单中输入该值。该值仅通过本地MCP连接传输，而不会通过LLM。
2. **使用秘密信息** — 在进行HTTP请求时，秘密信息通过占位符（`<<secret:identifier>>`）引用。服务器在请求时解密并注入它们。LLM只看到占位符，而不会看到实际值。
3. **删除秘密信息** — 需要通过提示确认后才能删除。
## 安全
- **AES-256-GCM加密** — 所有秘密信息在存储前都会加密
- **每个安装的主密钥** — 一个唯一的256位随机密钥在首次运行时自动生成，位于 `~/.secure-actions/master.key`（文件权限 `0600`）。每个用户都不同。
- **秘密信息从不进入LLM上下文** — 集合使用MCP提示（客户端表单），而不是聊天消息
- **不记录秘密信息值** — 只有标识符被记录，而不记录纯文本值
- **确认提示** — 破坏性操作（删除，覆盖）需要明确的用户批准
- **唯一索引强制** — MongoDB中`identifier`的唯一索引防止数据库级别的重复
> **注意：** 所有内容 - MongoDB，主密钥和加密的秘密信息 - 都完全位于您的本地机器上。只要您不共享或暴露`~/.secure-actions/master.key`给他人或LLM，您的秘密信息就保持安全。除非您明确使用`http_request`发出HTTP请求，否则不会有数据离开您的系统。
## 安装
### 先决条件
- Docker（用于MongoDB）
### macOS / Linux
```bash
curl -sSL https://raw.githubusercontent.com/Kota-Karthik/secure-actions/main/scripts/install.sh | sh
```
或固定特定版本：
```bash
VERSION=v0.1.0 curl -sSL https://raw.githubusercontent.com/Kota-Karthik/secure-actions/main/scripts/install.sh | sh
```
### Windows
从 [GitHub Releases](https://github.com/Kota-Karthik/secure-actions/releases) 下载最新的 `.zip` 文件，解压 `secure-actions.exe`，并将其添加到您的 PATH 中。
### 从源代码（任何操作系统）
```bash
go install github.com/kotakarthik/secure-actions/cmd/secure-actions@latest
```
### 验证安装
```bash
secure-actions --version
```
## 设置
### 1. 启动 MongoDB
```bash
docker compose -f deployments/docker-compose.yml up -d
```
这会在端口 `27018` 上启动 MongoDB，并在 `~/.secure-actions/mongo` 处持久化数据。
### 2. 注册 MCP 服务器
将以下内容添加到您的 Claude Code 配置（`.claude.json` 或通过 UI）：
```json
{
"secure-actions": {
"type": "stdio",
"command": "secure-actions",
"env": {
"MONGO_URI": "mongodb://localhost:27018"
}
}
}
```
### 3. 首次运行
在首次运行时，服务器将：
- 在 `~/.secure-actions/master.key` 处生成主加密密钥
- 创建具有 `identifier` 唯一索引的 `secrets` 集合
无需手动设置。
## 工具
### `ping`
健康检查。返回 `pong` 以验证服务器正在运行。
### `request_secret`
安全地收集和存储用户的秘密信息。
**输入：**
| 字段 | 必需 | 描述 |
|-------|----------|-------------|
| `name` | 是 | 秘密信息的标识符（规范化为小写，空格变为连字符） |
| `prompt` | 否 | 显示给用户的自定义提示消息 |
| `description` | 否 | 显示在输入表单上方的描述 |
**行为：**
- 如果标识符已经存在，则在更新前提示用户确认
- 标识符验证：仅允许小写字母、数字和连字符
- 示例：`"My API Key"` 变成 `"my-api-key"`
### `list_secrets`
返回所有存储的秘密信息标识符和计数。不会暴露秘密信息值。
**输出：**
```json
{
"secrets": ["github-pat", "aws-key", "slack-token"],
"count": 3
}
```
### `delete_secret`
永久删除存储的秘密信息。
**输入：**
| 字段 | 必需 | 描述 |
|-------|----------|-------------|
| `name` | 是 | 要删除的秘密信息标识符 |
**行为：**
- 如果标识符不存在，则返回“未找到”
- 在删除前提示用户确认
### `http_request`
执行具有自动秘密信息注入的HTTP请求。
**输入：**
| 字段 | 必需 | 描述 |
|-------|----------|-------------|
| `method` | 是 | `GET`，`POST`，`PUT`，`PATCH` 或 `DELETE` |
| `url` | 是 | 目标 URL |
| `headers` | 否 | 请求头（键值映射） |
| `body` | 否 | 请求体 |
**秘密信息注入：** 在 URL、头或正文中任何地方使用 `<<secret:identifier>>`。占位符在请求时替换为解密的秘密信息值。
**示例：**
```json
{
"method": "GET",
"url": "https://api.github.com/user",
"headers": {
"Authorization": "Bearer <<secret:github-pat>>",
"Accept": "application/vnd.github+json"
}
}
```
LLM 看到的是 `<<secret:github-pat>>` — 实际令牌值从未出现在对话中。
## 使用示例
### 存储和使用 GitHub 令牌
```
您： “存储我的 GitHub 个人访问令牌”
→ 调用 request_secret，您在安全表单中输入令牌
您： “列出我的仓库”
→ 调用 http_request，内容为：
GET https://api.github.com/user/repos
Authorization: Bearer <<secret:github-pat>>
```
### 管理秘密信息
```
您： “我存储了哪些秘密信息？”
→ list_secrets 返回：["github-pat", "slack-webhook"]
您： “删除 Slack 网络钩子”
→ delete_secret 提示： “您确定吗？” → 是 → 已删除
```
## 配置
| 环境变量 | 默认值 | 描述 |
|---------------------|---------|-------------|
| `MONGO_URI` | `mongodb://localhost:27018` | MongoDB 连接字符串 |
| `SECURE_ACTIONS_KEY_PATH` | `~/.secure-actions/master.key` | 主加密密钥路径 |
## 项目结构
```
cmd/secure-actions/ 入口点
internal/
actions/
ping/ 健康检查工具
request_secret/ 秘密信息收集和存储
list_secrets/ 列出存储的标识符
delete_secret/ 删除并确认
http_request/ 具有秘密信息注入的 HTTP 客户端
app/ 应用程序连接
config/ 配置加载
mcp/ MCP 服务器和工具注册
secrets/ 加密，密钥管理，管理器接口
storage/mongo/ MongoDB 客户端和存储库
deployments/
docker-compose.yml 本地 MongoDB 设置
Dockerfile 容器构建（计划中）
scripts/
install.sh macOS/Linux 安装程序
```
## 开发
```bash
# 在本地运行
docker compose -f deployments/docker-compose.yml up -d
go run ./cmd/secure-actions
# 构建
go build -o secure-actions ./cmd/secure-actions
# 测试二进制文件
./secure-actions --version
```
## 发布
发布版本通过 GitHub Actions 和 GoReleaser 自动进行：
```bash
git tag v0.1.0
git push origin v0.1.0
```
这会为所有平台（linux/darwin/windows × amd64/arm64）构建二进制文件，创建具有校验和的 GitHub Release，并发布工件。
## 许可证
请参阅 [LICENSE](LICENSE) 了解详情。
