SOCPilot——人工智能安全运营副驾驶

用于私有子网部署的AI驱动的SOC代理。通过MCP（模型上下文协议）连接到20多个安全工具，并通过单个命令、浏览器聊天或HTTP API调用协调端到端调查。

所有MCP工具调用都保留在您的网络内。只有AI推理请求越过边界。

______________________________________________________________________

建筑

┌────────────────────────────────────────────────────────────┐
│              Analyst Interface                              │
│   Browser UI  │  CLI  │  HTTP (SSE)  │  WebSocket  │  SIEM │
└───────────────┴───────┴──────────────┴─────────────┴───────┘
                              │
                         server.py
                         FastAPI app
                              │
                         agent.py
                    run_investigation()
                    (async generator)
                              │
               ┌──────────────┴──────────────┐
               │                             │
          AI_PROVIDER=demo            AI_PROVIDER=anthropic
          (pre-recorded)              or openai (Ollama etc.)
                                             │
                                    MCP_MODE=mock     MCP_MODE=live
                                    (sample data)     mcp_client.py
                                                      MCPClientPool
                                                      asyncio.gather()
                                                           │
              ┌──────┬─────────┬──────────┬──────────┬──────┐
              │      │         │          │          │      │
           npx/uvx subprocess per MCP server (stdio JSON-RPC)
              │      │         │          │          │      │
          Sentinel  GHAS  GreyNoise   OpenCTI    Vault   Jira
          Splunk    Snyk  VirusTotal  Prowler    Okta    Slack
          …         …    …           …          …       …

数据流——单次调查轮次：

分析员发送查询（浏览器/CLI/HTTP/WebSocket）
run_investigation() 使用查询+工具定义调用AI
AI以一个或多个响应 tool_use 块
同一回合中的所有工具调用都会执行并行通过 asyncio.gather()
结果得到反馈；人工智能对它们进行推理，并可能调用更多工具
最终分析逐令牌流式传输

______________________________________________________________________

先决条件

要求	版本	注释
Python	3.12+	`python3 --version`
Node.js	20+	`node --version` --需要 `npx`-基于MCP的服务器（仅限实时模式）
uv	最新	`uv --version` --需要 `uvx`-基于MCP的服务器（仅限实时模式）
AI API密钥	-	仅用于 `AI_PROVIDER=anthropic` 或 `openai`。演示模式不需要。

安装Node.js：https://nodejs.org/en/download 安装紫外线： curl -LsSf https://astral.sh/uv/install.sh | sh

______________________________________________________________________

项目布局

mcp-security-ops-suite/
├── agent.py            ← Core agent: run_investigation() + CLI + demo scenarios
├── server.py           ← FastAPI app: REST + WebSocket + UI serving + session store
├── mcp_client.py       ← Async MCP subprocess client (JSON-RPC over stdio)
├── config.py           ← Centralised configuration (reads .env)
├── onboard.py          ← CLI onboarding wizard (also powers the web wizard)
├── mcp_config.json     ← MCP server spawn commands + env var references
├── .env.example        ← Template for credentials (copy → .env)
├── requirements.txt    ← Python dependencies
├── Dockerfile          ← Python 3.12 + Node 20 + uv, non-root user
├── docker-compose.yml  ← Private-subnet deployment
├── ui/
│   └── index.html      ← Single-file SPA (served at GET /)
├── sessions/           ← Persisted WebSocket session history (auto-created)
├── reports/            ← Generated investigation reports (auto-created)
├── playbooks/          ← SOC workflow documentation
├── architecture/       ← Reference architecture diagrams
├── mcp-configs/        ← Example MCP server configuration snippets
└── scripts/            ← Helper scripts

______________________________________________________________________

快速开始

选项A——演示模式（无凭据）

尝试使用真实的流媒体调查的完整UI。无需API密钥，无需工具凭据，无需配置。

git clone  && cd mcp-security-ops-suite

# Create a virtual environment and install dependencies
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Start the server in demo mode
AI_PROVIDER=demo MCP_MODE=mock uvicorn server:app --host 0.0.0.0 --port 8000

# Open http://localhost:8000 in your browser

演示模式通过逼真的工具调用、完整的Markdown输出和可折叠的工具卡流式传输预先录制的调查，因此您可以在连接任何实际服务之前探索每个UI功能。

______________________________________________________________________

选项B——真正的人工智能，模拟工具

使用具有模拟工具响应的真实AI模型（Anthropic或当地Ollama/LM Studio）。适用于在连接实时安全工具之前测试AI配置。

# Anthropic (cloud)
export AI_PROVIDER=anthropic
export AI_API_KEY=sk-ant-api03-...

# OR local Ollama (fully air-gapped)
export AI_PROVIDER=openai
export AI_BASE_URL=http://localhost:11434/v1
export AI_MODEL=qwen2.5:7b
export AI_API_KEY=ollama   # any non-empty string

export MCP_MODE=mock

uvicorn server:app --host 0.0.0.0 --port 8000
# Open http://localhost:8000

______________________________________________________________________

选项C——使用真实工具的实时模式

# 1. Run the onboarding wizard to pick tools and collect credentials
python onboard.py
# OR use the web wizard: start the server and click "🔌 MCP Tools" in the UI header

# 2. The wizard writes .env with your selections. MCP_MODE=live is set automatically.

# 3. Load the .env and start
source .env
uvicorn server:app --host 0.0.0.0 --port 8000

# 4. Or use the CLI directly
python agent.py --playbook incident-response "suspicious login 185.220.101.34"

______________________________________________________________________

选项D——Docker

# 1. Generate .env (via wizard or copy from .env.example)
python onboard.py   # or: cp .env.example .env && edit .env

# 2. Build and start
docker compose up -d

# 3. Check health
curl http://localhost:8000/health

# 4. Tail logs
docker compose logs -f

______________________________________________________________________

浏览器用户界面

服务器在以下位置提供单页应用程序 http://localhost:8000.

特性

功能	如何使用
流媒体聊天	在输入框中键入查询，按Send
工具调用卡	可扩展卡显示每个被调用的MCP工具、其输入和结果
Playbook启动器	单击侧栏中的剧本→ 输入目标→ 观看流媒体
报告生成	侧边栏→ 生成报告 → 选择剧本+目标→ 下载 `.md`
AI引擎设置头球→ ⚙ AI引擎 → 配置提供程序、API密钥和模型
MCP工具设置头球→ 🔌 MCP工具 → 层级选择、工具选择器、凭证表单
会话历史记录	在页面刷新过程中保持不变；清除历史记录擦拭它； +新聊天重新开始

演示模式徽章

跑步时 AI_PROVIDER=demo，紫色演示徽章出现在模式指示器旁边。所有功能都是功能性的——响应是预先录制的现实调查，而不是实时的人工智能调用。

______________________________________________________________________

入职向导

两个独立的向导分别处理AI配置和MCP工具设置。

Web向导（推荐）

启动服务器并使用标题按钮：

⚙ AI引擎 --在Anthropic云、本地Ollama/LM Studio/vLLM或演示模式之间进行选择。生成并可选地应用与AI相关的 .env 变量。
🔌 MCP工具 --层级选择（个人/团队/企业/自定义）、工具选择器、带有文档链接的每个工具凭证表格。生成并可选地应用MCP凭据变量。

两个向导都可以下载 .env 代码片段或将更改直接应用于正在运行的服务器。

CLI向导

python onboard.py

步骤：

选择一个层级 --选择与堆栈匹配的工具集：

层级	工具	成本
独立分析师	GHAS、Semgrep、GreyNoise、安全检测	免费
SOC团队	独奏+哨兵/Splunk、Snyk、Trivy、徘徊者、保险库、Jira、Slack	各不相同
企业	所有20+工具	企业许可
自定义	单独选择	--

输入凭据 --每个工具都会使用掩码输入和文档链接进行提示。

写 .env --现有 .env 在覆盖之前进行备份。

子命令：

python onboard.py --check              # Show which credentials are set / missing
python onboard.py --add splunk         # Add or reconfigure a single tool
python onboard.py --list               # List all available tools with tiers
python onboard.py --env-file /etc/socpilot/.env   # Use a different .env file

可用工具

Category              Tool                           Tiers            Credentials
────────────────────────────────────────────────────────────────────────────────
SIEM                  Microsoft Sentinel             team, enterprise  7
SIEM                  Splunk                         team, enterprise  2
SIEM                  Elastic Security               enterprise        2
SIEM                  Datadog                        enterprise        2
Vuln Scanning         GHAS                           solo+             2  (free)
Vuln Scanning         Semgrep                        solo+             1  (free)
Vuln Scanning         Snyk                           team+             2
Vuln Scanning         Trivy                          team+             0  (free)
Vuln Scanning         StackHawk                      enterprise        1
Threat Intelligence   GreyNoise                      solo+             1  (free)
Threat Intelligence   OpenCTI                        team+             2
Threat Intelligence   VirusTotal                     enterprise        1
Cloud Security        Prowler                        team+             3  (free)
Cloud Security        Cloudflare                     enterprise        2
Secrets & Identity    HashiCorp Vault                team+             2
Secrets & Identity    Vault Radar                    team+             3
Secrets & Identity    Okta                           enterprise        2
Compliance            Drata                          enterprise        1
Compliance            Vanta                          enterprise        1
Detection Eng.        Security Detections            solo+             0  (free)
Ticketing             Jira                           team+             3
Ticketing             Slack                          team+             2

______________________________________________________________________

CLI参考

python agent.py [OPTIONS] [QUERY]

选项	简短	描述
`--playbook NAME`	`-p`	运行一个命名的SOC剧本
`--list-playbooks`	`-l`	打印所有剧本名称并退出
`--verbose`	`-v`	显示AI推理步骤
`--output FILE`	`-o`	将报告保存到Markdown文件

例子

# Free-form investigation
python agent.py "Is CVE-2024-50623 being actively exploited? Check payments-api."

# Run a structured playbook
python agent.py --playbook vuln-triage "CVE-2024-50623 in payments-api"
python agent.py --playbook incident-response "alert SEC-7721"
python agent.py --playbook threat-hunting "Cl0p ransomware TTPs"
python agent.py --playbook secret-leak-response "AWS key leaked in payments-service"
python agent.py --playbook cloud-posture-review "AWS prod account"
python agent.py --playbook compliance-audit "SOC 2 readiness"

# Save a report
python agent.py --playbook compliance-audit "AWS prod" --output reports/audit-$(date +%F).md

# Interactive multi-turn session
python agent.py
SOCPilot> --playbook vuln-triage CVE-2024-50623 in payments-api
SOCPilot> now check if auth-service is also affected
SOCPilot> create a P1 Jira ticket for both findings
SOCPilot> clear     ← resets session history
SOCPilot> exit

注： CLI需要AI API密钥(AI_PROVIDER=anthropic 或 openai).演示模式仅适用于浏览器。

______________________________________________________________________

HTTP API

启动服务器：

uvicorn server:app --host 0.0.0.0 --port 8000 --reload

Swagger用户界面： http://localhost:8000/docs

端点

`GET /`

提供浏览器UI(ui/index.html).

`GET /health`

生存性检查——返回提供者、模式、模型和时间戳。

{"status": "ok", "mode": "mock", "provider": "demo", "model": "claude-opus-4-6", "ts": "2026-02-24T10:30:00+00:00"}

`GET /health/llm`

以最小的请求探测配置的AI提供程序。返回延迟和状态。

{"provider": "anthropic", "model": "claude-opus-4-6", "status": "ok", "latency_ms": 420, "response": "pong"}

退货 {"status": "ok", "latency_ms": 0} 立即进入演示模式。

`GET /playbooks`

列出可用的SOC剧本。

{"playbooks": ["vuln-triage", "incident-response", "threat-hunting", "compliance-audit", "secret-leak-response", "cloud-posture-review"]}

`GET /playbooks/detail`

每个剧本的完整提示模板（含 {target} 占位符）。

`GET /tools`

所有带有输入模式的工具定义。

`POST /query` --SSE流媒体

进行自由形式的调查。返回服务器发送的事件。

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Check GreyNoise for IP 185.220.101.34", "verbose": false}' \
  --no-buffer

响应流——每行 data: \n\n:

data: {"type": "text",        "text": "Checking GreyNoise for..."}
data: {"type": "tool_call",   "name": "check_greynoise", "inputs": {"query": "185.220.101.34"}}
data: {"type": "tool_result", "name": "check_greynoise", "content": "Classification: MALICIOUS..."}
data: {"type": "text",        "text": "The IP is classified as malicious..."}
data: {"type": "done",        "turns": 2}

`POST /playbook` --SSE流媒体

对目标运行一个命名的剧本。

curl -X POST http://localhost:8000/playbook \
  -H "Content-Type: application/json" \
  -d '{"playbook": "vuln-triage", "target": "CVE-2024-50623 in payments-api"}' \
  --no-buffer

`POST /report`

运行一个剧本并将结果保存到Markdown文件中。等待完成。

curl -X POST http://localhost:8000/report \
  -H "Content-Type: application/json" \
  -d '{"playbook": "compliance-audit", "target": "AWS prod"}'

{"status": "ok", "file": "reports/compliance-audit-20260224-103000.md", "turns": 4, "bytes": 8423}

`GET /reports/{filename}`

下载生成的报告文件。路径遍历安全。

`GET /onboard/tools`

返回web入职向导使用的完整工具目录和层定义。

`POST /onboard/env`

写入或合并 .env 服务器上的值。由web向导的“应用到服务器”按钮使用。

{"values": {"AI_API_KEY": "sk-ant-...", "AI_PROVIDER": "anthropic"}}

`DELETE /sessions/{session_id}`

从内存和磁盘中清除会话的对话历史记录。由浏览器UI的“清除历史记录”按钮调用。

在Python中消费SSE流

import httpx, json

with httpx.Client(timeout=300) as client:
    with client.stream("POST", "http://localhost:8000/query",
                       json={"query": "Is CVE-2024-50623 exploited?"}) as r:
        for line in r.iter_lines():
            if line.startswith("data: "):
                event = json.loads(line[6:])
                if event["type"] == "text":
                    print(event["text"], end="", flush=True)

______________________________________________________________________

WebSocket会话

/ws/{session_id} 在多个查询之间保持有状态的对话。代理会记住会话中的所有先前发现。

历史坚持

会话历史记录存储在两个位置：

记忆 (_session_store)：在同一服务器运行中WebSocket重新连接后仍然有效
磁盘 (sessions/.json)：在服务器重新启动后幸存

当发生相同情况时，历史记录会自动恢复 session_id 重新连接。浏览器UI将会话ID存储在 localStorage，因此历史记录在页面刷新后仍然存在。“清除历史记录”会删除内存和磁盘上的状态。

# Using wscat
wscat -c ws://localhost:8000/ws/analyst-session-1
> {"query": "Check GreyNoise for 185.220.101.34"}
 {"query": "Now check if OpenCTI has any threat actor campaigns using this IP"}
`

### 端口8000已在使用中

SERVER_PORT=8001 uvicorn server:app --host 0.0.0.0 --port 8001

or update SERVER_PORT in .env


### Docker容器立即退出

docker compose logs socpilot

Most common cause: AI_API_KEY not set (use AI_PROVIDER=demo to avoid this)


### 检查哪些工具配置了凭据

python onboard.py --check

MCP Security Ops Suit

快速接入

详细介绍

SOCPilot——人工智能安全运营副驾驶

目录

建筑

先决条件

项目布局

快速开始

选项A——演示模式（无凭据）

选项B——真正的人工智能，模拟工具

选项C——使用真实工具的实时模式

选项D——Docker

浏览器用户界面

特性

演示模式徽章

入职向导

Web向导（推荐）

CLI向导

可用工具

CLI参考

例子

HTTP API

端点

GET /

GET /health

GET /health/llm

GET /playbooks

GET /playbooks/detail

GET /tools

POST /query --SSE流媒体

POST /playbook --SSE流媒体

POST /report

GET /reports/{filename}

GET /onboard/tools

POST /onboard/env

DELETE /sessions/{session_id}

在Python中消费SSE流

WebSocket会话

历史坚持

or update SERVER_PORT in .env

Most common cause: AI_API_KEY not set (use AI_PROVIDER=demo to avoid this)

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`GET /`

`GET /health`

`GET /health/llm`

`GET /playbooks`

`GET /playbooks/detail`

`GET /tools`

`POST /query` --SSE流媒体

`POST /playbook` --SSE流媒体

`POST /report`

`GET /reports/{filename}`

`GET /onboard/tools`

`POST /onboard/env`

`DELETE /sessions/{session_id}`