zstar-mcp-server
MCP server for the zstar archive utility
Make your private environment keys go supernova with the self-destructing encrypted archives
概述
一 MCP(模型上下文协议) 公开所有功能的服务器 参考设计 归档实用程序。它允许AI助手通过标准化的工具界面创建、提取、验证、加密和签署压缩档案。
服务器使用 stdio传输,兼容 开爪, 克劳德桌面版以及任何其他MCP客户端。
🛡️ 为什么选择zstar MCP服务器?
> 你的数据。你的钥匙。你的规则。 人工智能代理是强大的,但没有护栏的权力是一种负担。zstar MCP服务器为您提供 密码控制 代理接触的每一个字节。
问题: 人工智能代理需要访问敏感数据——API密钥、证书、财务记录、医疗文件——但交出原始外壳访问权限是一场安全噩梦。密码最终会出现在shell历史中,文件未加密地保存在磁盘上,并且没有关于谁访问了什么的审计跟踪。
解决方案: zstar MCP服务器将久经考验的GPG加密、zstd压缩和SHA-512完整性验证打包成 结构化、可审核的工具库API代理人从不粗鲁无礼 gpg 命令或文件系统内部——它调用类型化的、经过验证的工具,默认情况下强制加密。
| 🔑 能力 | 这对你意味着什么 |
|---|---|
| GPG公钥加密 | 只有 你 可以解密您的数据——代理无法读取您未授权的内容 |
| 签名档案 | 每个存档都有一个可验证的签名——你确切地知道是谁创建的 |
| 自毁档案 | 读取后焚烧模式提取后粉碎档案——无残留,无重新访问 |
| SHA-512完整性 | 对每个存档进行自动校验和,可以立即检测到损坏和篡改 |
| 零壳注射 | 带参数验证的结构化API-否 ; rm -rf / 惊喜 |
| 代理引导密钥设置 | GPG密钥生成、导出和导入——全部通过工具调用完成,无需手动命令 |
底线是: 您的私有环境密钥、凭据和敏感数据在静止状态下保持加密,经过签名以确保真实性,并且只能由您明确授权的各方访问。当你完成共享后,读取后刻录可确保数据自毁。 那是 你如何让你的秘密变成超新星。 💥
🎬 数据保护演示
工具
服务器提供 20工具 涵盖zstar实用程序的所有功能——归档创建、网络流、代理到代理加密通信和GPG密钥管理:
| 工具 | 说明 |
|---|---|
create_archive |
创建压缩文件 .tar.zst 使用SHA-512校验和和自解压脚本进行归档 |
encrypt_archive |
创建密码加密存档(通过GPG对称的AES-256) |
sign_archive |
创建GPG签名的存档以进行真实性验证 |
sign_and_encrypt_archive |
创建签名和收件人加密的存档(公钥加密) |
create_burn_after_reading_archive |
创建一个存档,在提取后安全地将其粉碎 |
extract_archive |
使用生成的解压缩脚本提取存档 |
list_archive |
列出存档内容而不提取 |
verify_checksum |
验证存档的SHA-512完整性校验和 |
check_dependencies |
检查是否安装了所有必需的系统依赖项 |
net_stream_archive |
通过netcat将压缩存档直接流式传输到远程主机(无磁盘I/O) |
net_stream_encrypted_archive |
通过netcat将密码加密的存档直接流式传输到远程主机 |
net_stream_signed_encrypted_archive |
通过netcat将GPG签名和收件人加密的存档直接流式传输到远程主机 |
listen_for_stream |
使用解压缩脚本的监听模式监听传入的流数据 |
gpg_init_agent_communication |
初始化加密代理间通信的GPG身份 |
encrypted_agent_stream |
通过网络将GPG签名和加密的数据直接从一个代理流式传输到另一个代理 |
request_secure_channel |
请求远程代理配置自己以进行安全的GPG加密实时通信 |
gpg_list_keys |
列出密钥环中的GPG密钥(公共或秘密) |
gpg_generate_key |
为用户或代理生成新的GPG密钥对 |
gpg_export_public_key |
以铠装格式导出GPG公钥以供共享 |
gpg_import_key |
将GPG公钥从文件导入密钥环 |
快速开始
Docker(推荐)
从GitHub容器注册表中提取预构建映像:```bash
docker pull ghcr.io/8r4n/zstar-mcp-server:latest
或者在本地构建:```bash
git clone --recurse-submodules https://github.com/8r4n/zstar-mcp-server.git
cd zstar-mcp-server
docker build -t zstar-mcp-server .
Docker镜像构建在 红帽UBI 9最小 --具有最小攻击面的强化SELinux本机基础映像。所有依赖关系(bash, tar, zstd, gpg, pv, ncat, jq)以及 tarzst.sh 捆绑在一起——不需要额外的设置。
npm```bash
npm install zstar-mcp-server
或者克隆并从源代码构建:```bash
git clone --recurse-submodules https://github.com/8r4n/zstar-mcp-server.git
cd zstar-mcp-server
npm install
npm run build
配置
服务器定位 tarzst.sh 按以下顺序编写脚本:
ZSTAR_PATH环境变量 --设置为绝对路径tarzst.sh- 系统路径 --寻找
tarzst或tarzst.sh在你的 `PATH````bash
export ZSTAR_PATH=/usr/local/bin/tarzst.sh
> **注:** Docker镜像集 `ZSTAR_PATH` 自动-无需配置。
## 客户端配置
服务器通过以下方式进行通信 **标准**,OpenClaw、Claude Desktop和任何其他MCP客户端支持的标准传输。
### 码头工人
#### OpenClaw(`openclaw.json`)```json
{
"mcpServers": {
"zstar": {
"command": "docker",
"args": ["run", "--rm", "-i", "ghcr.io/8r4n/zstar-mcp-server:latest"]
}
}
}
克劳德桌面(claude_desktop_config.json)```json
{
"mcpServers": {
"zstar": {
"command": "docker",
"args": ["run", "--rm", "-i", "ghcr.io/8r4n/zstar-mcp-server:latest"]
}
}
}
要装载用于存档操作的本地目录,请添加卷装载:```json
{
"mcpServers": {
"zstar": {
"command": "docker",
"args": ["run", "--rm", "-i", "-v", "/path/to/data:/data", "ghcr.io/8r4n/zstar-mcp-server:latest"]
}
}
}
npm
OpenClaw(openclaw.json)```json
{
"mcpServers": {
"zstar": {
"command": "npx",
"args": ["-y", "zstar-mcp-server"],
"env": {
"ZSTAR_PATH": "/path/to/tarzst.sh"
}
}
}
}
或者,如果从源代码安装:```json
{
"mcpServers": {
"zstar": {
"command": "node",
"args": ["/path/to/zstar-mcp-server/dist/index.js"],
"env": {
"ZSTAR_PATH": "/path/to/tarzst.sh"
}
}
}
}
克劳德桌面(claude_desktop_config.json)```json
{
"mcpServers": {
"zstar": {
"command": "npx",
"args": ["-y", "zstar-mcp-server"],
"env": {
"ZSTAR_PATH": "/path/to/tarzst.sh"
}
}
}
}
## 用法
### 码头工人```bash
docker run --rm -i ghcr.io/8r4n/zstar-mcp-server:latest
Node.js```bash
node dist/index.js
## 工具参考
#### `create_archive`
从文件或目录创建压缩的tar.zst存档。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档的文件或目录|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)。默认值:3|
| `outputName` | `string` |否|输出文件的自定义基名|
| `excludePatterns` | `string[]` |否| tar的文件排除模式|
| `cwd` | `string` |否|工作目录|
**输出文件:** `.tar.zst`, `.tar.zst.sha512`, `_decompress.sh`
______________________________________________________________________
#### `encrypt_archive`
使用AES-256对称加密创建密码加密的存档。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档的文件或目录|
| `password` | `string` |是|对称加密密码|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)|
| `outputName` | `string` |否|自定义基名称|
| `excludePatterns` | `string[]` |否|排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `sign_archive`
创建GPG签名的存档以进行真实性验证。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档的文件或目录|
| `signingKeyId` | `string` |是| GPG密钥ID(例如,电子邮件或指纹)|
| `passphrase` | `string` |是|签名密钥的密码|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)|
| `outputName` | `string` |否|自定义基名称|
| `excludePatterns` | `string[]` |否|排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `sign_and_encrypt_archive`
使用GPG公钥加密创建签名和收件人加密的存档。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档的文件或目录|
| `signingKeyId` | `string` |是|用于签名的GPG密钥ID|
| `passphrase` | `string` |是|签名密钥的密码|
| `recipientKeyId` | `string` |是|收件人的GPG密钥ID|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)|
| `outputName` | `string` |否|自定义基名称|
| `excludePatterns` | `string[]` |否|排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `create_burn_after_reading_archive`
使用自擦除程序创建存档。提取后,存档文件会被安全地切碎。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档的文件或目录|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)|
| `outputName` | `string` |否|自定义基名称|
| `excludePatterns` | `string[]` |否|排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `extract_archive`
使用生成的自解压脚本提取zstar存档。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `scriptPath` | `string` |是|通往 `*_decompress.sh` 脚本|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `list_archive`
列出zstar存档的内容,不进行解压缩。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `scriptPath` | `string` |是|通往 `*_decompress.sh` 脚本|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `verify_checksum`
验证zstar存档的SHA-512校验和。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `checksumFile` | `string` |是|通往 `.sha512` 校验和文件|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `check_dependencies`
检查是否安装了所有必需的系统依赖项。
**参数:** 无
**退货:** 每个依赖项的状态(bash、tar、zstd、sha512sum、numfmt、gpg、pv、nc)。
______________________________________________________________________
#### `net_stream_archive`
通过netcat将压缩的存档直接流式传输到远程主机,绕过所有磁盘I/O。没有存档文件、校验和或解压缩脚本写入磁盘。需要 `nc` (netcat)在发送方和接收方上。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档和流式传输的文件或目录|
| `target` | `string` |是|网络目标在 `host:port` 格式(例如。, `remote_host:9000`) |
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)。默认值:3|
| `outputName` | `string` |否|自定义基名称(用于流标识)|
| `excludePatterns` | `string[]` |否| tar的文件排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `net_stream_encrypted_archive`
通过netcat将密码加密(AES-256对称)压缩档案直接流式传输到远程主机。没有文件写入磁盘。接收方需要相同的密码才能解密。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档和流式传输的文件或目录|
| `target` | `string` |是|网络目标在 `host:port` 格式|
| `password` | `string` |是|对称加密密码|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)。默认值:3|
| `outputName` | `string` |否|自定义基名称(用于流标识)|
| `excludePatterns` | `string[]` |否| tar的文件排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `net_stream_signed_encrypted_archive`
通过netcat将GPG签名和收件人加密的压缩档案直接流式传输到远程主机。使用非对称加密——发送方使用其私钥进行签名,并为接收方的公钥进行加密。没有文件写入磁盘。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档和流式传输的文件或目录|
| `target` | `string` |是|网络目标在 `host:port` 格式|
| `signingKeyId` | `string` |是|用于签名的GPG密钥ID(例如,电子邮件或指纹)|
| `passphrase` | `string` |是|签名密钥的密码|
| `recipientKeyId` | `string` |是|收件人用于加密的GPG密钥ID|
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)。默认值:3|
| `outputName` | `string` |否|自定义基名称(用于流标识)|
| `excludePatterns` | `string[]` |否| tar的文件排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `listen_for_stream`
使用解压缩脚本的监听模式监听传入的流数据。解压缩脚本实时接收、解密(如果适用)、解压缩和提取流数据。需要 `nc` (netcat)。开始这个 **之前** 发送方流式传输数据。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `scriptPath` | `string` |是|生成的路径 `*_decompress.sh` 脚本|
| `port` | `number` |是|要监听的端口号(1-65535)|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `gpg_init_agent_communication`
初始化加密代理到代理通信的GPG标识。为本地代理生成GPG密钥对(如果尚未存在)并导出公钥。这是在两个代理之间建立安全通道的第一步。请参阅 代理到代理加密流媒体 完整工作流的部分。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `agentName` | `string` |Yes |代理的显示名称(例如。, `"Agent Alpha"` 或 `"Build Server"`) |
| `agentEmail` | `string` |是|代理的电子邮件标识符(例如。, `"agent-alpha@mcp-server.local"`) |
| `passphrase` | `string` |是|保护代理私钥的密码|
| `keyType` | `string` |否|密钥类型: `"RSA"`, `"DSA"`,或 `"EDDSA"`默认值: `"EDDSA"` |
| `keyLength` | `number` |否|密钥长度(位)(1024-4096,用于RSA/DSA)。默认值:4096|
| `expireDate` | `string` |否|密钥到期(例如。, `"1y"`, `"0"` 无过期)。违约: `"0"` |
| `outputFile` | `string` |否|保存导出公钥的文件路径。如果省略,则直接返回装甲钥匙|
**退货:** 成功状态、铠装公钥、GPG指纹和完成密钥交换的设置说明。
______________________________________________________________________
#### `encrypted_agent_stream`
通过网络将GPG签名和加密的数据直接从一个代理流式传输到另一个代理。验证两个代理是否都有彼此的密钥,然后通过netcat流式传输签名和收件人加密的压缩存档。需要事先通过以下方式进行密钥交换 `gpg_init_agent_communication`。请参阅 代理到代理加密流媒体 完整工作流的部分。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `inputPaths` | `string[]` |是|要存档并流式传输到远程代理的文件或目录|
| `target` | `string` |是|远程代理的网络地址在 `host:port` 格式(例如。, `agent-b-host:9000`) |
| `signingKeyId` | `string` |是|本地代理用于签名的GPG密钥ID(例如。, `"agent-alpha@mcp-server.local"`) |
| `passphrase` | `string` |是|本地代理签名密钥的密码|
| `recipientKeyId` | `string` |是|远程代理用于加密的GPG密钥ID(例如。, `"agent-beta@mcp-server.local"`) |
| `compressionLevel` | `number` |无|zstd压缩级别(1-19)。默认值:3|
| `outputName` | `string` |否|流标识的自定义基名称|
| `excludePatterns` | `string[]` |否| tar的文件排除模式|
| `cwd` | `string` |否|工作目录|
______________________________________________________________________
#### `request_secure_channel`
请求远程代理配置自己以进行安全的实时GPG加密通信。初始化本地代理的GPG标识,并生成包含公钥和设置指令的结构化请求。远程代理使用此请求完成通道设置。请参阅 代理到代理加密流媒体 完整工作流的部分。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `agentName` | `string` |Yes |请求代理的显示名称(例如。, `"Build Agent"`) |
| `agentEmail` | `string` |是|请求代理的电子邮件标识符(例如。, `"agent-alpha@mcp-server.local"`) |
| `passphrase` | `string` |是|保护请求代理私钥的密码|
| `keyType` | `string` |否|密钥类型: `"RSA"`, `"DSA"`,或 `"EDDSA"`默认值: `"EDDSA"` |
| `keyLength` | `number` |否|密钥长度(位)(1024-4096,用于RSA/DSA)。默认值:4096|
| `expireDate` | `string` |否|密钥到期(例如。, `"1y"`, `"0"` 无过期)。违约: `"0"` |
| `listeningAddress` | `string` |否|网络 `host:port` 该代理将在那里监听(例如。, `"agent-alpha-host:9000"`) |
______________________________________________________________________
#### `gpg_list_keys`
列出密钥环中的GPG密钥。GPG设置演练的第一步——检查哪些密钥已经可用。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `secretOnly` | `boolean` |否|如果为真,则仅列出密钥(私钥)。默认值:false|
______________________________________________________________________
#### `gpg_generate_key`
生成新的GPG密钥对。创建公钥(供他人为您加密数据)和私钥(用于解密和签名)。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `name` | `string` |是|密钥的真实名称(例如,“Alice Smith”或“MCP Agent”)|
| `email` | `string` |是|密钥的电子邮件地址(例如,“user@example.com") |
| `passphrase` | `string` |是|保护私钥的密码|
| `keyType` | `string` |否|密钥类型:“RSA”、“DSA”或“EDDSA”。默认值:“RSA”|
| `keyLength` | `number` |否|密钥长度(位)(1024-4096,用于RSA/DSA)。默认值:4096|
| `expireDate` | `string` |否|密钥过期(例如,“1y”,“0”表示无过期)。默认值:“0”|
______________________________________________________________________
#### `gpg_export_public_key`
导出铠装(ASCII)格式的GPG公钥,以便与另一方共享。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `keyId` | `string` |是|要导出的密钥ID、电子邮件或指纹|
| `outputFile` | `string` |否|保存密钥的文件路径。如果省略,则直接返回密钥|
______________________________________________________________________
#### `gpg_import_key`
将GPG公钥从文件导入密钥环。使用此功能导入另一方的公钥。
**参数:**
|名称|类型|必填|描述|
|------|------|----------|-------------|
| `keyFile` | `string` |是|要导入的铠装密钥文件的路径|
## GPG密钥设置详解
MCP服务器包括4个GPG密钥管理工具,使代理能够引导用户完成完整的GPG密钥设置过程——无需手动 `gpg` 需要的命令。```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#e94560', 'primaryColor': '#1a1a2e', 'primaryTextColor': '#eee', 'edgeLabelBackground': '#1a1a2e', 'clusterBkg': '#0d1b2a'}}}%%
flowchart TD
A["🔭 1. gpg_list_keys Check existing keys"] --> B{Keys exist?}
B -->|No| C["🌟 2. gpg_generate_key Generate key pair for user"]
B -->|Yes| D["☄️ 3. gpg_export_public_key Export user's public key"]
C --> D
D --> E["🚀 Share public key with other party"]
E --> F["🪐 4. gpg_import_key Import other party's public key"]
F --> G["💫 Ready for encrypted communication Use sign_and_encrypt_archive"]
style A fill:#1a1a2e,stroke:#e94560,color:#eee
style B fill:#16213e,stroke:#0f3460,color:#eee
style C fill:#0f3460,stroke:#53d8fb,color:#eee
style D fill:#533483,stroke:#e94560,color:#eee
style E fill:#e94560,stroke:#f5a623,color:#fff
style F fill:#0f3460,stroke:#53d8fb,color:#eee
style G fill:#2d6a4f,stroke:#52b788,color:#eee
步骤1--检查现有密钥```
gpg_list_keys({})
gpg_list_keys({ secretOnly: true })
代理检查密钥环中已经有哪些密钥。如果用户或代理已经有密钥对,则此步骤将进行确认。
### 步骤2——生成密钥(如果需要)```
gpg_generate_key({
name: "Alice Smith",
email: "user@example.com",
passphrase: "secure-passphrase",
keyType: "RSA",
keyLength: 4096
})
对于代理的环境:```
gpg_generate_key({
name: "MCP Agent",
email: "agent@mcp-server.local",
passphrase: "agent-passphrase"
})
### 步骤3——导出公钥以供共享```
gpg_export_public_key({
keyId: "user@example.com",
outputFile: "./user_public.asc"
})
gpg_export_public_key({
keyId: "agent@mcp-server.local",
outputFile: "./agent_public.asc"
})
步骤4——导入对方的公钥```
gpg_import_key({ keyFile: "./agent_public.asc" })
gpg_import_key({ keyFile: "./user_public.asc" })
完成此演练后,双方都可以使用 `sign_and_encrypt_archive` 用于安全的双向加密通信。
______________________________________________________________________
## GPG加密场景
以下场景演示了zstar MCP服务器如何在AI代理和用户之间实现安全、加密的通信。这些工作流显示了服务器的实际效用: **代理从不处理明文秘密**,并且用户保留对谁可以访问他们的数据的完全控制权。
### GPG场景的先决条件
用户和代理环境都需要GPG密钥。使用 GPG密钥设置详解 通过MCP服务器交互式设置密钥的工具,或运行以下手动命令:```bash
# User generates their key pair (if they don't already have one)
gpg --full-generate-key # follow prompts; e.g., user@example.com
# Agent environment generates its own key pair
gpg --full-generate-key # e.g., agent@mcp-server.local
# Exchange public keys so each side can encrypt for the other
gpg --export --armor user@example.com > user_public.asc
gpg --export --armor agent@mcp-server.local > agent_public.asc
# Import the other party's public key
gpg --import agent_public.asc # user imports agent's public key
gpg --import user_public.asc # agent imports user's public key
在此一次性设置之后,双方都可以加密数据 只有预期的收件人可以解密.
场景1——双向加密数据交换
此场景演示了一个完整的往返过程:用户将加密数据发送到代理,代理对其进行处理并返回加密结果——所有这些都不会以不受保护的形式在磁盘上公开明文。
运作原理```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'actorBkg': '#1a1a2e', 'actorTextColor': '#53d8fb', 'actorBorder': '#e94560', 'signalColor': '#e94560', 'signalTextColor': '#c0392b', 'noteBkgColor': '#533483', 'noteTextColor': '#fff', 'noteBorderColor': '#f5a623', 'sequenceNumberColor': '#f5a623', 'actorLineColor': '#533483'}}}%%
sequenceDiagram
participant User as 🧑🚀 User
participant Agent as 🤖 Agent (MCP)
User->>Agent: 1. sign_and_encrypt_archive
signed with: user@example.com
encrypted for: agent@mcp-server.local
Note right of Agent: 2. Decrypts with its private key
Verifies user's signature
Processes the data
Agent->>User: 3. sign_and_encrypt_archive
signed with: agent@mcp-server.local
encrypted for: user@example.com
Note left of User: 4. Decrypts with their private key
Verifies agent's signature
#### 步骤1——用户向代理发送加密数据
用户创建了一个用他们的密钥签名并为代理加密的存档:```
User → Agent (via MCP tool call):
sign_and_encrypt_archive({
inputPaths: ["./financial-report.csv", "./projections/"],
signingKeyId: "user@example.com",
passphrase: "users-gpg-passphrase",
recipientKeyId: "agent@mcp-server.local",
outputName: "data-for-agent"
})
输出文件:
data-for-agent.tar.zst.gpg--加密;只有代理的私钥可以解密data-for-agent.tar.zst.sha512--完整性校验和data-for-agent_decompress.sh--自解压脚本(处理解密+验证)
步骤2——代理解密和处理
代理使用其自己的GPG私钥提取存档。解压脚本会自动验证用户的签名:```
Agent (MCP tool call):
extract_archive({
scriptPath: "./data-for-agent_decompress.sh"
})
代理现在拥有明文文件,可以处理它们(分析数据、生成报告等)。
#### 步骤3——代理将加密结果返回给用户
代理将其结果打包并为用户加密:```
Agent → User (via MCP tool call):
sign_and_encrypt_archive({
inputPaths: ["./analysis-results/"],
signingKeyId: "agent@mcp-server.local",
passphrase: "agents-gpg-passphrase",
recipientKeyId: "user@example.com",
outputName: "results-for-user"
})
步骤4——用户解密结果
用户运行解压缩脚本,该脚本使用他们的私钥解密并验证代理的签名:```bash
bash results-for-user_decompress.sh
→ Decrypts, verifies agent signature, extracts analysis-results/
#### 为什么这很重要
|财产|担保|
|----------|-----------|
| **保密性** |数据是静态加密的,只有预期收件人的私钥可以解密|
| **真实性** |GPG签名证明发件人的身份;检测到篡改|
| **正直** |SHA-512校验和捕获传输或磁盘上的任何损坏|
| **不可否认性** |发件人不能否认创建了存档(签名与密钥绑定)|
______________________________________________________________________
### 场景2——具有授权访问权限的用户控制的私有数据
此场景演示了用户如何加密敏感数据,并有选择地授权代理使用GPG公钥加密访问它。用户保留完全控制权: **只有为代理的公钥明确加密的存档才能访问**.
#### 原则```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#e94560', 'primaryColor': '#1a1a2e', 'primaryTextColor': '#eee', 'edgeLabelBackground': '#1a1a2e', 'clusterBkg': '#0d1b2a', 'clusterBorder': '#e94560'}}}%%
graph LR
subgraph vault["🌌 USER'S DATA VAULT"]
A["personal-taxes.tar.zst.gpg
🔒 encrypted for user only"]
B["medical-records.tar.zst.gpg
🔒 encrypted for user only"]
C["project-data.tar.zst.gpg
🔓 encrypted for user + agent ✓"]
D["credentials.tar.zst.gpg
🔒 encrypted for user only"]
end
Agent["🤖 Agent
agent@mcp-server.local"]
A -.-x Agent
B -.-x Agent
C -->|"✓ can decrypt"| Agent
D -.-x Agent
style vault fill:#0d1b2a,stroke:#e94560,color:#eee
style A fill:#1a1a2e,stroke:#e94560,color:#e94560
style B fill:#1a1a2e,stroke:#e94560,color:#e94560
style C fill:#0f3460,stroke:#52b788,color:#52b788
style D fill:#1a1a2e,stroke:#e94560,color:#e94560
style Agent fill:#533483,stroke:#53d8fb,color:#53d8fb
步骤1--用户加密私人数据(代理无权访问)
用户创建加密档案供自己使用。这些是用用户自己的密钥加密的——代理 不能 解密它们:```
encrypt_archive({
inputPaths: ["./tax-returns/"],
password: "users-secret-password",
outputName: "personal-taxes"
})
或者仅对用户使用GPG公钥加密:```
sign_and_encrypt_archive({
inputPaths: ["./medical-records/"],
signingKeyId: "user@example.com",
passphrase: "users-gpg-passphrase",
recipientKeyId: "user@example.com", ← encrypted for self
outputName: "medical-records"
})
代理无法解密这两个存档。私钥仅属于用户。
步骤2——用户授予代理访问特定数据的权限
当用户决定与代理共享特定数据时,他们会为代理的公钥对其进行加密:```
sign_and_encrypt_archive({
inputPaths: ["./project-data/"],
signingKeyId: "user@example.com",
passphrase: "users-gpg-passphrase",
recipientKeyId: "agent@mcp-server.local", ← authorized for agent
outputName: "project-data"
})
这是显式授权步骤。用户正在做出有意识的决定: *“我希望代理能够读取这些特定数据。”*
#### 步骤3——代理仅访问授权的数据```
# ✓ This succeeds — the agent's private key can decrypt it
extract_archive({ scriptPath: "./project-data_decompress.sh" })
# ✗ This fails — the agent does not have the decryption key
extract_archive({ scriptPath: "./personal-taxes_decompress.sh" })
# → GPG error: no secret key available for decryption
步骤4——用户撤销访问权限
访问撤销很简单:用户只需停止为代理的密钥加密新数据。以前共享的档案仍然是加密的,但没有新的数据流向代理。为了获得更强的撤销,用户可以旋转自己的密钥。
阅读后燃烧选项
为了获得最大的安全性,请使用 create_burn_after_reading_archive 用于一次性数据共享。代理提取数据后,存档会自动分解:```
create_burn_after_reading_archive({
inputPaths: ["./one-time-credentials/"],
outputName: "temp-access"
})
提取后 `.tar.zst`, `.sha512`,以及 `_decompress.sh` 文件被安全地覆盖和删除。数据仅以提取的形式存在,没有可重新提取或转发的存档。
______________________________________________________________________
### 为什么MCP服务器对数据保护很重要
zstar MCP服务器弥合了 **强大的加密工具** 和 **AI代理工作流程**没有它,代理将需要原始的shell访问、凭据处理以及对GPG和tar命令的深入了解。MCP服务器提供:
|功能|无MCP服务器|有zstar MCP服务器|
|-----------|-------------------|----------------------|
| **加密** |代理运行为原始状态 `gpg` 命令,处理shell历史|结构化API中的密码短语,并进行参数验证;无外壳注射风险|
| **密钥管理** |Agent必须了解GPG内部| Agent调用 `sign_and_encrypt_archive` 带有密钥ID|
| **正直** |代理必须手动运行 `sha512sum` |在每个存档上自动进行SHA-512校验和|
| **访问控制** |“代理数据”和“用户数据”之间没有边界|GPG公钥加密强制执行加密访问边界|
| **审计跟踪** |无|每个存档都经过签名——来源可验证|
| **安全处置** |代理人必须知道 `shred` 语义学| `create_burn_after_reading_archive` 处理安全删除|
| **错误处理** |原始shell错误|带退出代码的结构化成功/失败响应|
服务器将基于GPG的加密从手动、易出错的过程转变为 **安全、可审核、工具库API** AI代理可以使用它,而无需直接访问私钥、shell命令或文件系统内部。
______________________________________________________________________
### SELinux代理限制强制访问控制
当代理框架部署在具有以下功能的主机上时 **安全增强型Linux** 启用并配置为所有文件访问都通过MCP服务器路由,内核强制强制访问控制(MAC)提供了一个额外的安全边界,限制 **代理可以在主机上读取哪些数据** --无论代理的应用程序级代码尝试什么。
#### 运作原理
zstar项目包括一个即用型SELinux策略模块(`zstar/selinux/`)它定义了三种安全类型:
|SELinux类型|用途|
|-------------|---------|
| `zstar_mcp_t` | **进程域** --MCP服务器运行的安全上下文|
| `zstar_archive_t` | **文件类型** --应用于存档、校验和、解压缩脚本和拆分部分的标签|
| `zstar_exec_t` | **入口点类型** --MCP服务器可执行文件上的标签,触发自动域转换到 `zstar_mcp_t` |
当MCP服务器启动时,SELinux将其转换为 `zstar_mcp_t` 域。那么政策 **明确允许** 只有服务器需要的操作 **默认情况下拒绝其他所有内容**:```
# The MCP server (zstar_mcp_t) can ONLY access files labeled zstar_archive_t
allow zstar_mcp_t zstar_archive_t:file { create read write open ... };
allow zstar_mcp_t zstar_archive_t:dir { search read write ... };
# System utilities required by tarzst.sh (tar, zstd, gpg, etc.)
corecmd_exec_bin(zstar_mcp_t)
corecmd_exec_shell(zstar_mcp_t)
# GPG keyring access
gpg_entry_type(zstar_mcp_t)
# Stdio transport (inherited file descriptors from the MCP client)
allow zstar_mcp_t self:fifo_file { read write getattr };
# Everything else → DENIED (implicit SELinux default)
代理人不能做什么
因为SELinux策略是强制执行的 在内核中,即使代理妥协或操纵MCP服务器进程 不能:
阻止行动 · 为什么
阅读 /etc/shadow、SSH密钥或任何未标记的用户文件 zstar_archive_t · 没有 allow 规则为 zstar_mcp_t 访问 user_home_t, etc_t, ssh_home_t等等。
写入任意目录 · 仅 zstar_archive_t-标记的目录是可写的
仅执行任意二进制文件 corecmd_exec_bin (系统 /usr/bin)是允许的--不是用户脚本
访问其他进程的内存或文件 · 否 allow 规则为 zstar_mcp_t 到 ptrace 或读取其他域
升级特权 · 否 allow 超出定义策略的角色或域转换规则
禁用或修改SELinux策略 · 策略管理需要 semanage/setsebool 在 unconfined_t 域名
文件上下文标签
文件上下文配置(zstar.fc)自动为zstar输出工件添加标签 zstar_archive_t:```
/home/[^/]+/..tar.zst → zstar_archive_t
/home/[^/]+/..tar.zst.gpg → zstar_archive_t
/home/[^/]+/..tar.zst.sha512 → zstar_archive_t
/home/[^/]+/._decompress.sh → zstar_archive_t
/home/[^/]+/.*.tar.zst.[0-9]+.part → zstar_archive_t
这意味着,当用户创建存档时,生成的文件会自动标记为MCP服务器访问。主机上的所有其他文件——文档、凭据、配置文件、SSH密钥——都保留在默认的SELinux上下文中 **MCP服务器进程不可见**.
#### 部署架构```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#e94560', 'primaryColor': '#1a1a2e', 'primaryTextColor': '#eee', 'edgeLabelBackground': '#1a1a2e', 'clusterBkg': '#0d1b2a', 'clusterBorder': '#e94560'}}}%%
flowchart TB
subgraph host["🖥️ Host — SELinux Enforcing"]
subgraph agent_domain["🤖 Agentic Framework"]
A["AI Agent\n(MCP Client)"]
end
subgraph mcp_domain["🔒 zstar_mcp_t Domain"]
M["zstar MCP Server\n(mcp-server.sh)"]
end
subgraph files["📁 Filesystem"]
F1["🔓 zstar_archive_t\n.tar.zst, .sha512,\n_decompress.sh"]
F2["🚫 user_home_t\nDocuments, configs,\nSSH keys, secrets"]
F3["🚫 etc_t\n/etc/shadow,\n/etc/passwd"]
end
end
A -->|"stdio\n(JSON-RPC)"| M
M -->|"✅ allowed"| F1
M -.->|"❌ denied\n(AVC)"| F2
M -.->|"❌ denied\n(AVC)"| F3
style host fill:#0d1b2a,stroke:#e94560,color:#eee
style agent_domain fill:#1a1a2e,stroke:#53d8fb,color:#eee
style mcp_domain fill:#1a1a2e,stroke:#e94560,color:#eee
style files fill:#1a1a2e,stroke:#53d8fb,color:#eee
style A fill:#0f3460,stroke:#53d8fb,color:#eee
style M fill:#533483,stroke:#e94560,color:#eee
style F1 fill:#2d6a4f,stroke:#52b788,color:#eee
style F2 fill:#3d0000,stroke:#e94560,color:#eee
style F3 fill:#3d0000,stroke:#e94560,color:#eee
集成策略接口
这 zstar.if 接口文件提供可重用的策略宏,用于与其他SELinux受限应用程序集成:
| 接口 | 说明 |
|---|---|
zstar_read_archive |
授予域名 只读 访问 zstar_archive_t 文件 |
zstar_manage_archive |
授予域名 满的 (创建/读取/写入/删除)访问 zstar_archive_t 文件 |
例如,如果单独的部署代理需要读取MCP服务器生成的存档,但不应创建新的存档:```
In the deployment agent's .te policy:
zstar_read_archive(deploy_agent_t)
#### 安装SELinux策略```bash
# Build and install the policy module
cd zstar/selinux
make -f /usr/share/selinux/devel/Makefile zstar.pp
sudo semodule -i zstar.pp
# Apply file contexts to existing files
sudo restorecon -Rv /home/*/
> 注: SELinux策略适用于基于Docker的bash服务器和Node.js/npm服务器。Docker镜像基于Red Hat UBI 9 Minimal构建,这是一个经过强化的SELinux原生基础镜像。对于Docker部署,当Docker守护进程配置为 --selinux-enabled.
快速入门:仅限Docker主机访问限制的OpenClaw
本指南将OpenClaw配置为使用基于Docker的zstar MCP服务器作为 唯一文件访问机制,防止代理读取或写入主机上的任意文件。
1.拉动硬化图像```bash
docker pull ghcr.io/8r4n/zstar-mcp-server:latest
#### 2.创建专用数据目录
创建一个允许代理访问的单个目录。不会装载其他主机路径:```bash
mkdir -p ~/zstar-data
在启用SELinux的主机上,标记它,以便受限的MCP服务器进程可以访问它:```bash
sudo semanage fcontext -a -t zstar_archive_t "$HOME/zstar-data(/.*)?"
sudo restorecon -Rv ~/zstar-data
#### 3.配置OpenClaw
创建或编辑 `openclaw.json` 使用zstar服务器作为 **仅** MCP服务器——没有文件系统、shell或其他工具:```json
{
"mcpServers": {
"zstar": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--read-only",
"--tmpfs", "/tmp",
"--cap-drop=ALL",
"--security-opt=no-new-privileges",
"-v", "/home/you/zstar-data:/data",
"ghcr.io/8r4n/zstar-mcp-server:latest"
]
}
}
}
替换 /home/you/zstar-data 带有数据目录的绝对路径。
> 关键标志:
>
> - --read-only --容器文件系统是不可变的(防止篡改服务器二进制文件)
> - --tmpfs /tmp --用于GPG操作和临时文件的可写暂存空间(短暂的,从不接触主机)
> - --cap-drop=ALL --删除所有Linux功能(无权限升级)
> - --security-opt=no-new-privileges --防止 setuid/setgid 集装箱内的升级
> - 仅 /data 已装载--代理无法访问任何其他主机路径
4.代理人能做什么和不能做什么
| 行动 | 允许 | 为什么 |
|---|---|---|
在中创建档案 /data |
✅ | 安装体积 |
提取档案 /data |
✅ | 安装体积 |
验证校验和 /data |
✅ | 安装体积 |
在中加密/签名存档 /data |
✅ | 安装体积 |
| 通过网络流式传输档案 | ✅ | 网络流媒体工具 |
阅读 /etc/shadow、SSH密钥、用户文件 |
❌ | 未安装到容器中 |
在外面写 /data |
❌ | 只读文件系统+无其他挂载 |
| 执行主机二进制文件 | ❌ | 容器隔离 |
| 升级特权 | ❌ | --cap-drop=ALL + no-new-privileges |
5.验证隔离
启动OpenClaw并要求代理创建存档:```
Create a zstar archive of /data/myfiles
然后验证代理 **不能** 访问外面的任何东西 `/data`:```
List files in /etc
代理将失败——它没有列出文件的工具,MCP服务器也无法访问 /etc.
6.添加SELinux强制(RHEL/Fedora)
在SELinux强制主机上,添加 --security-opt label=type:zstar_mcp_t 对于内核级MAC强制的Docker args:```json
{
"mcpServers": {
"zstar": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--read-only",
"--tmpfs", "/tmp",
"--cap-drop=ALL",
"--security-opt=no-new-privileges",
"--security-opt", "label=type:zstar_mcp_t",
"-v", "/home/you/zstar-data:/data:Z",
"ghcr.io/8r4n/zstar-mcp-server:latest"
]
}
}
}
这 `:Z` 卷后缀告诉Docker用正确的SELinux上下文重新标记装载。结合the `zstar_mcp_t` 在进程域中,内核强制即使容器受到损害,也只能 `zstar_archive_t`-标记的文件是可访问的。
______________________________________________________________________
## 用例:两个AI代理实时流式传输压缩、GPG加密的数据
一种常见的部署模式涉及两个AI代理,每个代理都运行自己的MCP客户端,需要通过网络实时安全地交换数据。例如:
- **阿尔法特工** (构建代理)生成必须交付给的构建工件、日志或模型权重 **贝塔特工** (部署代理)在远程主机上。
- 任何代理都不应将敏感数据作为未加密的中间文件写入磁盘。
- 两个代理都必须能够验证对方的身份(真实性),并确保数据未被篡改(完整性)。
- 数据应进行压缩,以便通过电线进行高效传输。
zstar MCP服务器通过组合 **zstd压缩**, **GPG公钥加密**, **GPG签署**,以及 **netcat流媒体** 集成到单个工具调用管道中。整个流程——压缩→ sign → 加密→ 流——发生在发送方没有磁盘I/O的内存中。```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#e94560', 'primaryColor': '#1a1a2e', 'primaryTextColor': '#eee', 'edgeLabelBackground': '#1a1a2e', 'clusterBkg': '#0d1b2a', 'clusterBorder': '#e94560'}}}%%
flowchart LR
subgraph alpha["🤖 Agent Alpha — Build Agent"]
A1["1. gpg_init_agent_comm.\n→ generates EDDSA key\n→ exports public key"]
A2["2. gpg_import_key\n(imports Beta's key)"]
A3["3. encrypted_agent_stream\n→ compresses with zstd\n→ signs with Alpha key\n→ encrypts for Beta\n→ streams via netcat"]
end
subgraph beta["🤖 Agent Beta — Deployment Agent"]
B1["1. gpg_init_agent_comm.\n→ generates EDDSA key\n→ exports public key"]
B2["2. gpg_import_key\n(imports Alpha's key)"]
B3["3. listen_for_stream\n→ listens on port 9000\n→ decrypts with Beta key\n→ verifies Alpha's sig\n→ decompresses & extract"]
end
A1 -.->|"🔑 public key"| B2
B1 -.->|"🔑 public key"| A2
A3 ==>|"🔒 encrypted data"| B3
style alpha fill:#0d1b2a,stroke:#e94560,color:#eee
style beta fill:#0d1b2a,stroke:#e94560,color:#eee
style A1 fill:#1a1a2e,stroke:#53d8fb,color:#eee
style A2 fill:#0f3460,stroke:#53d8fb,color:#eee
style A3 fill:#533483,stroke:#e94560,color:#eee
…(正文过长,页面只展示前面部分,完整内容见仓库)
