Abnormal Security

abnormal-mcp

适用于 Abnormal Security 的 MCP 服务——基于 AI 的威胁检测、案例管理和邮件修复。

工具

此服务采用决策树架构。首先调用 abnormal_navigate 选择一个领域，然后使用该领域的专用工具。

导航

工具	描述
abnormal_navigate	导航至某个领域（威胁、消息、修复、滥用、案例）
abnormal_back	返回领域选择

威胁领域

工具	描述
abnormal_threats_list	列出检测到的威胁案例（分页）
abnormal_threats_get	按 ID 获取特定威胁的完整详情

消息领域

工具	描述
abnormal_messages_list	列出威胁案例中的消息
abnormal_messages_get	获取详细的消息分析（标头、URL、附件、AI 分析）

修复领域

工具	描述
abnormal_remediation_manage	触发或检查针对某条消息的修复操作

滥用领域

工具	描述
abnormal_abuse_list	列出通过 Abuse Mailbox 举报的钓鱼邮件

案例领域

工具	描述
abnormal_cases_list	列出活跃的安全调查案例
abnormal_cases_get	获取特定案例的详情

交互式威胁卡片（MCP Apps）

• 在 MCP Apps 主机（Claude Desktop/web）中，abnormal_threats_get 会呈现为交互式威胁卡片，显示主题、发件人、攻击分类、修复状态以及威胁中的消息。卡片为只读——修复仍是一项由模型介导、需要主动执行的操作。在其他主机中的纯 JSON 行为保持不变。默认采用中性样式，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）进行品牌定制——无需重新构建。

身份验证

Abnormal Security 使用 Bearer 令牌身份验证。复制 .env.example，并设置以下变量。

变量	必需	描述
ABNORMAL_API_TOKEN	stdio 和 AUTH_MODE=env 时必需	Abnormal Security API 令牌。在 Abnormal 门户的 Settings > Integrations > API 下生成。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	env（Docker 外的默认值）或 gateway。镜像和 Compose 服务设置为 gateway。网关模式要求每个 /mcp 请求都携带 Authorization: Bearer，且绝不会回退到 ABNORMAL_API_TOKEN。
CONDUIT_S2S_SECRET	HTTP 模式下必需	服务间密钥。使用 openssl rand -hex 32 生成。若该值为空或为已知占位符（changeme、placeholder、your-s2s-secret、replace-with-a-real-secret 以及类似的示例值），HTTP 服务会记录错误并以非零状态码退出。未设置此值时，Compose 不会启动。切勿提交真实值。此值不会被记录到日志中。
MCP_ALLOW_INSECURE_DEV	否	仅用于本地开发。仅将其设置为 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告、不强制要求 X-Gateway-S2S，且只绑定到 127.0.0.1。非环回地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录覆盖情况。已知的占位符密钥仍会被拒绝。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。未设置时默认为 127.0.0.1。设置密钥后，此值会生效。容器镜像将其设置为 0.0.0.0。未设置密钥时，不安全开发模式会强制使用 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。

/health 无需身份验证，也不会读取凭据。stdio 传输不使用 CONDUIT_S2S_SECRET。

X-Gateway-S2S 签名

当 MCP_TRANSPORT=http 且 CONDUIT_S2S_SECRET 是真实密钥时，每个 /mcp 请求都必须包含 X-Gateway-S2S。标头值为 t=<unix seconds>,v1=<hex>，其中 hex 是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 进行 HMAC-SHA256 运算得到的结果（64 个小写十六进制字符）。时间戳与服务器时钟的差值必须在 300 秒以内。若标头缺失或无效，则会在读取 Abnormal 令牌之前返回 401。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "Authorization: Bearer $ABNORMAL_API_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 模式下，必须提供 Authorization 标头，且它是唯一的凭据来源。AUTH_MODE=env 仍要求有效的 X-Gateway-S2S 标头；若请求未携带 Authorization，则使用环境变量中的 ABNORMAL_API_TOKEN。

独立运行（env 模式）

export ABNORMAL_API_TOKEN=your-api-token
node dist/index.js

Gateway 模式

部署在 MCP gateway 后时，请设置 AUTH_MODE=gateway。Gateway 会为每个 /mcp 请求签署 X-Gateway-S2S，并注入 Authorization: Bearer {token}。缺少该凭据标头的请求会被拒绝并返回 401。

运行

stdio（用于 Claude Desktop）

npm install
npm run build
node dist/index.js

HTTP Streamable（用于托管式/gateway 部署）

若 CONDUIT_S2S_SECRET 不是有效密钥，HTTP 将拒绝启动：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http AUTH_MODE=gateway node dist/index.js

不配置密钥的本地 HTTP 仅供开发使用。它只绑定到 127.0.0.1，并会记录警告：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

Docker

镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），且默认使用 AUTH_MODE=gateway。请在回环地址上发布端口，并传入 S2S 密钥。在 gateway 模式下，API 令牌会随每个请求通过 Authorization 传入；镜像不会读取 ABNORMAL_API_TOKEN。

docker build -t abnormal-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  abnormal-mcp

若未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；它会设置 AUTH_MODE=gateway，不会注入 ABNORMAL_API_TOKEN，并发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求配置 S2S 密钥，之后会使用 ABNORMAL_API_TOKEN：

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ABNORMAL_API_TOKEN=your-api-token \
  -p 127.0.0.1:8080:8080 \
  abnormal-mcp

开发

npm install
npm run dev          # watch mode
npm test             # run tests
npm run typecheck    # TypeScript type check
npm run build:ui     # rebuild the MCP Apps card bundle (only needed when ui/ changes)

许可证

Apache-2.0