内容
# Tenable.sc MCP 服务器
[](https://github.com/ABMJ/tenable-sc-mcp-server/releases)
[](https://github.com/ABMJ/tenable-sc-mcp-server/actions/workflows/ci.yml)
[](https://choosealicense.com/licenses/gpl-3.0/)
[](https://www.python.org/)
**本工具不是Tenable官方支持的项目。**
适用于Tenable Security Center Plus的生产就绪型模型上下文协议（MCP）服务器。具备智能缓存功能，可节省 **90% 的令牌**，并提供 **1000 倍更快的响应**。
**最新版本**：[v1.2.2](https://github.com/ABMJ/tenable-sc-mcp-server/releases/tag/v1.2.2) (2026-06-19) | **状态**：✅ 生产就绪
---
## 快速开始
```bash
# 1. 创建 .env 文件
cd tenable-sc-mcp-server
cp .env.example .env
nano .env # 添加您的 Tenable.sc 凭证
# 2. 构建并启动
docker build -t tenable-sc-mcp:latest .
docker-compose up -d
# 服务器运行在：http://localhost:8000/mcp
```
**必需的 `.env` 配置：**
```bash
TSC_URL=https://your-sc-server.com
TSC_ACCESS_KEY=your-access-key
TSC_SECRET_KEY=your-secret-key
TSC_VERIFY_SSL=true
```
---
## 功能
- **节省 90% 的令牌** - 智能 Redis 缓存
- **速度提升 1000 倍** - <1ms 缓存响应 vs 200-500ms API 调用
- **100+ 资源** - 完整的 Tenable.sc REST API 覆盖
- **零存储** - 无状态代理，可选缓存
- **基于 RBAC 的强制执行** - 尊重所有 Tenable.sc 权限
- **生产就绪** - 带有健康检查的 Docker Compose
---
## 可用工具
### 高级工具（针对大型语言模型优化）
**参见 [USER_GUIDE.md](USER_GUIDE.md) 以获取完整文档和示例。**
| 工具 | 目的 | 令牌节省 | 缓存 TTL |
|------|---------|---------------|-----------|
| `tsc_profile_ip_efficient` | 完整的 IP 安全评估 | 83% (2.5K vs 15K) | 180-300s |
| `tsc_list_vulns_by_ip_summary` | 快速漏洞计数 | 88% (700 vs 6K) | 180s |
| `tsc_list_vulns_by_ip_full` | 详细的漏洞记录 | 58% (5K vs 12K) | 180s |
| `tsc_list_ips` | 具有 55+ 个筛选器的 IP 发现 | 400-3.7K 令牌 | 120s |
| `tsc_list_vulns_by_cve` | CVE 爆发响应 | 85% (1-2K vs 10K) | 240s |
### 核心 API 工具
- `tsc_resource_action` - 统一的 CRUD 操作，适用于所有资源（`list`、`get`、`create`、`update`、`delete`）
- `tsc_catalog` - 浏览 100+ 可用资源
- `tsc_current_user` - 验证 API 身份和权限
- `tsc_analyze` - 运行分析查询（缓存）
- `tsc_cache_stats` / `tsc_cache_clear` - 缓存管理
**参见 [docs/TOOLS.md](docs/TOOLS.md) 以获取完整的工具参考。**
---
## 配置
### OpenCode
添加到 `opencode.json`：
```json
{
"mcp": {
"tenable-sc": {
"type": "remote",
"url": "http://localhost:8000/mcp",
"enabled": true
}
}
}
```
### Claude Desktop
添加到 MCP 设置：
```json
{
"mcpServers": {
"tenable-sc": {
"command": "docker",
"args": ["run", "--rm", "-i",
"-e", "TSC_URL=https://your-sc-server.com",
"-e", "TSC_ACCESS_KEY=your-key",
"-e", "TSC_SECRET_KEY=your-secret",
"tenable-sc-mcp:latest"]
}
}
}
```
---
## 架构
```
MCP 客户端（OpenCode/Claude）
↓
tenable-sc-mcp 服务器
↓
Redis 缓存（90%命中率）
↓
Tenable.sc REST API
```
**关键原则** （参见 [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md)）：
- 统一的 `filters` 字典参数（55+ 个筛选器）
- 具有数据类型特定 TTL 的智能缓存
- 令牌优化（目标减少 80%+）
- 全面的错误处理
---
## 过滤系统
**v1.2.0 新增**：所有工具都使用统一的 `filters` 字典参数。
```python
# 示例：查找具有 CVE 的关键资产
tsc_list_vulns_by_cve("CVE-2021-44228", filters={
"asset_criticality": "7-10", # 需要范围格式
"severity": "critical",
"exploit_available": "Yes"
})
```
**重要规则：**
- 评分筛选器使用 **范围格式**：`"7-10"` 而不是 `">7"`
- 适用于：`asset_criticality`、`vpr_score`、`aes_score`、`cvss_v3_base_score`、`epss_score`
- 常见筛选器：`severity`、`exploit_available`、`cve`、`plugin_id`、`port`、`protocol`
**文档：**
- 完整参考： [FILTER_FORMAT_REFERENCE.md](FILTER_FORMAT_REFERENCE.md)
- MCP 资源：`tenable-sc://filters/format-reference`
- 示例： [USER_GUIDE.md](USER_GUIDE.md)
---
## 部署选项
### Docker Compose（推荐）
```bash
docker build -t tenable-sc-mcp:latest .
docker-compose up -d
```
### 独立 Docker
```bash
docker run -d --name tenable-sc-mcp \
-p 8000:8000 \
-v ~/.tenable-sc-mcp.env:/config/tsc.env:ro \
tenable-sc-mcp:latest \
--transport streamable-http \
--host 0.0.0.0 --port 8000 \
--env-file /config/tsc.env
```
### 本地 Python
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install .
export TSC_URL="https://sc.example.com"
export TSC_ACCESS_KEY="key"
export TSC_SECRET_KEY="secret"
tenable-sc-mcp --transport stdio
```
---
## 故障排除
**容器无法启动：**
```bash
docker compose logs tenable-sc-mcp
# 检查：缺少 .env、无效的 TSC_URL、防火墙
```
**无法访问 Tenable.sc：**
```bash
curl -k https://your-sc-server.com/rest/currentUser
# 预期： "invalid token" （端点可达）
```
**缓存不工作：**
```bash
docker ps --filter "name=redis" # 应该显示（健康）
# 问 MCP： "show me cache statistics"
```
**远程客户端无法连接：**
```bash
docker ps --filter "name=tenable-sc-mcp" # 应该显示 0.0.0.0:8000
curl http://your-server-ip:8000/mcp
```
参见 [SUPPORT.md](SUPPORT.md) 获取更多帮助。
---
## 安全
- **基于 RBAC 的强制执行** - 使用您的 Tenable.sc API 密钥，所有权限均适用
- **无凭证存储** - 仅环境变量
- **SSL/TLS 支持** - 在生产环境中设置 `TSC_VERIFY_SSL=true`
- **无内置身份验证** - 仅绑定到受信任的网络（本地 127.0.0.1）
**最佳实践：**
- ❌ 永远不要将 API 密钥提交到 git
- ✅ 使用模式为 `0600` 的 env 文件
- ✅ 在 Tenable.sc 中创建专用的最小权限 API 用户
- ✅ 使用防火墙规则或 SSH 隧道进行远程访问
参见 [SECURITY.md](SECURITY.md) 以报告漏洞。
---
## 文档
### 用户文档
- [USER_GUIDE.md](USER_GUIDE.md) - 完整的工具使用指南
- [FILTER_FORMAT_REFERENCE.md](FILTER_FORMAT_REFERENCE.md) - 过滤系统参考
- [CACHING_DEEP_DIVE.md](CACHING_DEEP_DIVE.md) - 缓存行为和性能
- [TEST_PROMPTS.md](TEST_PROMPTS.md) - 可用的测试查询
### 开发者文档
- [ARCHITECTURE.md](ARCHITECTURE.md) - 系统设计
- [DESIGN_PRINCIPLES.md](DESIGN_PRINCIPLES.md) - 工具开发模式
- [TOOLS_ROADMAP.md](TOOLS_ROADMAP.md) - 功能路线图（v1.3.0、v1.4.0）
- [HANDOFF.md](HANDOFF.md) - 面向 LLM 的开发移交
### 项目
- [CONTRIBUTING.md](CONTRIBUTING.md) - 贡献指南
- [SECURITY.md](SECURITY.md) - 安全策略
- [SUPPORT.md](SUPPORT.md) - 支持资源
---
## 兼容性
| 组件 | 版本 |
|-----------|---------|
| Python | 3.11+ |
| Tenable.sc | 当前 API 版本 |
| Docker | 20.10+ (Compose v2) |
| Redis | 7+ |
---
## 贡献
欢迎贡献！参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
**快速链接：**
- [报告错误](https://github.com/ABMJ/tenable-sc-mcp-server/issues/new?template=bug_report.yml)
- [请求功能](https://github.com/ABMJ/tenable-sc-mcp-server/issues/new?template=feature_request.yml)
- [查看问题](https://github.com/ABMJ/tenable-sc-mcp-server/issues)
---
## 许可证
GNU GPL v3.0 - 参见 [LICENSE](LICENSE)
---
**需要帮助？** 查看 [SUPPORT.md](SUPPORT.md) 或 [打开问题](https://github.com/ABMJ/tenable-sc-mcp-server/issues)。
