RailSecure 将多项相关工作整合于一处。 无需在钓鱼邮件训练器、预案手册文档、漏洞订阅源、标准参考页面以及独立的 AI 聊天之间来回切换，该应用将所有这些工作流集中在一个工作区中。其目的是让日常的网络防御准备工作更快捷、更不分散。 ## 目录 - [概览](#at-a-glance) - [平台涵盖内容](#what-the-platform-covers) - [功能图](#feature-map) - [应用结构](#how-the-app-fits-together) - [架构](#architecture) - [AI 工作流与防护机制](#ai-workflow-and-guardrails) - [设计系统](#design-system) - [技术栈](#tech-stack) - [页面与用户流程](#pages-and-user-flows) - [API 路由](#api-routes) - [快速开始](#getting-started) - [环境变量](#environment-variables) - [可用脚本](#available-scripts) - [在 Vercel 上部署](#deployment-on-vercel) - [项目结构](#project-structure) - [实现说明](#implementation-notes) - [验证](#verification) ## 概览 | 领域 | 摘要 | | --- | --- | | 目的 | 面向铁路行业的网络防御准备工作区，提供引导式培训与运营支持 | | 前端 | Next.js App Router 与 React 19 | | AI 模型默认值 | `claude-opus-4-8` | | AI 风格 | 具有结构化输出的任务特定工作流，而非通用的聊天机器人 | | 数据源 | Claude API (Anthropic Messages API) 与 NVD CVE API 2.0 | | 存储 | 当前版本中无数据库 | | 密码处理 | 仅在浏览器端进行本地生成与强度检查 | | 部署 | 托管于 Vercel，访问地址为 [railsecure.vercel.app](https://railsecure.vercel.app) | ## 平台涵盖内容 RailSecure 包含： - 钓鱼模拟与邮件分类 - 密码生成与本地强度检查 - 安全事件场景演练 - 安全事件预案生成 - 预案草案比对 - 限定范围的合规支持 - 精选参考指南 - 实时 NVD 漏洞审查 - 围绕真实铁路与交通事件构建的安全意识内容 这种组合是刻意设计的。该应用可帮助用户从意识培养、到分类排查、再到采取行动，全程不会丢失上下文。 ## 功能图 | 线路 | 路径 | 功能 | 重要性 | | --- | --- | --- | --- | | 概览 | `/` | 介绍平台并提供各模块链接 | 为应用提供一个清晰的入口 | | 01 钓鱼实验室 | `/phishing` | 生成钓鱼模拟、对分析师的回复进行评分，并对粘贴的邮件进行分类 | 适用于安全意识培训与一线邮件审查 | | 02 密码工作室 | `/passwords` | 在浏览器中生成密码并在本地检查密码强度 | 避免将敏感密码输入发送至后端 | | 03 事件实验室 | `/incident-lab` | 生成逼真的事件场景并评估响应策略 | 支持演练与桌面推演 | | 04 预案手册 | `/playbooks` | 构建特定场景的预案并将其与用户草案进行比对 | 帮助提升响应质量与一致性 | | 05 知识问答 | `/quiz` | 创建简短的单项选择意识测试，并支持逐题回顾 | 适用于快速知识抽查与研讨会使用 | | 06 合规中心 | `/compliance` | 回答关于控制措施、报告、治理与防御工具的限定范围问题 | 将标准与义务转化为实用指南 | | 07 漏洞订阅源 | `/vulnerabilities` | 从 NVD 获取 CVE，支持过滤，并添加 AI 解释 | 使漏洞审查比平铺直叙的列表更有用 | | 08 参考库 | `/references` | 精选的标准与指南库，以及限定范围的解释器助手 | 让官方依据始终伴随答案呈现 | | 09 宣传墙 | `/awareness` | 在时间轴上展示真实的交通与铁路事件，包含复发模式与讨论提示 | 适用于意识培训会话与弹性对话 | ## 应用结构 ``` flowchart TD A["User"] --> B["Next.js App Router UI"] B --> C["Page Components"] C --> D["/api/ai"] C --> E["/api/cves"] D --> R["Rate limit and input validation"] R --> G["Guardrails and safety screen"] G --> H["Task-specific AI workflows"] H --> I["Claude API (Messages)"] E --> J["NVD CVE API 2.0"] H --> K["Structured output parsing"] K --> C J --> C ``` 主要的设计决策在于，RailSecure 的表现并不像一个自由格式的聊天应用。每项功能都运行着一个狭窄且定义明确的工作流，其背后有 schema 支撑，这使得结果可预测，并能在 UI 中简洁呈现。 ## 架构 ### 高层视图 ``` flowchart LR subgraph Frontend A1["App Router pages"] A2["Reusable UI components"] A3["Client helpers"] end subgraph Server B1["API routes"] B2["Guardrails"] B3["AI orchestration"] B4["NVD fetch layer"] B5["Schemas"] B6["Rate limiter"] end subgraph External services C1["Claude API"] C2["NVD API"] end A1 --> A2 A2 --> A3 A1 --> B1 B1 --> B6 B1 --> B2 B1 --> B3 B1 --> B4 B3 --> B5 B3 --> C1 B4 --> C2 ``` ### 设计选择 | 选择 | 重要性 | | --- | --- | | 基于路由的模块 | 每个工作流都有明确的归属，使应用更易于导航与维护 | | 使用 Zod 的结构化 AI 输出 | UI 接收的是经过类型验证的数据，而非自由格式的文本 | | 服务端防护机制 | 减少 prompt injection、范围偏移与格式错误的请求 | | 仅限本地的密码检查 | 敏感输入无需离开浏览器 | | 专用的 NVD 路由 | 漏洞获取与标准化独立于 UI 关注点 | | 按客户端的速率限制 | AI 和 CVE 路由限制了请求突发频率，防止脚本耗尽 API key | | 共享的后续操作与导出操作 | 结果可被快速复制、下载、简化或重构 | ## AI 工作流与防护机制 RailSecure 通过官方的 Anthropic TypeScript SDK (`@anthropic-ai/sdk`) 调用 Claude，并在 `lib/railsecure-ai.ts` 中使用特定于任务的辅助函数。 每个 AI 工作流都遵循相同的结构： 1. 使用 Zod 验证请求结构与操作名称 2. 对自由文本进行清理与长度限制，剥离控制字符与零宽字符 3. 针对 prompt injection 模式筛查自由文本 4. 对于限定范围的助手，确认问题在处理范围内 5. 对自由文本运行 Claude 安全筛查 6. 运行带有自适应思考的特定任务 Claude 工作流，并采用受 schema 约束的响应格式 7. 根据 Zod schema 解析返回的 JSON（修复过长的字符串），然后再发送给 UI ### AI 请求流程 ``` sequenceDiagram participant U as User participant UI as UI module participant API as /api/ai participant G as Guardrails participant AI as RailSecure AI layer participant C as Claude API U->>UI: Submit a task UI->>API: POST action and payload API->>API: Rate-limit by client API->>G: Validate, limit, and scope-check G-->>API: Safe input or refusal API->>AI: Run task-specific workflow AI->>C: messages.create with schema-constrained format C-->>AI: Schema-shaped JSON AI->>AI: Parse and repair against Zod schema AI-->>API: Typed result API-->>UI: JSON response UI-->>U: Render structured output ``` ### 防护层 | 层级 | 检查内容 | | --- | --- | | 枚举验证的选择器 | 下拉菜单驱动的输入（邮件类型、事件类别）仅接受标准选项，因此这些操作无法通过任意文本驱动 | | 输入清理与限制 | 拦截空输入与超大文本，剥离可能会绕过模式筛查的控制字符与零宽字符 | | Prompt injection 模式 | 试图覆盖工作流、采用新角色、泄露隐藏指令或注入聊天模板 token 的行为 | | Claude 安全筛查 | 一次低开销的结构化 Claude 调用，从两个维度（有害内容与针对助手的注入）对自由文本进行分类，并经过调优以确保合法的防御性培训内容能顺利通过 | | 数据隔离 | 用户与第三方内容被包装在系统提示词视为数据的标记块中，因此粘贴邮件或 CVE 记录中的指令会被分析，而不是被执行 | | 范围检查 | 阻止在限定范围的助手中使用通用编程或无关的提示词 | | 结构化输出验证 | 响应格式被限制为 JSON schema，服务端在任何内容到达 UI 前会使用 Zod 进行验证（并修复过长字符串） | | 拒绝处理 | 如果 Claude 拒绝请求，路由会返回明确的 400 错误，而不是损坏的结果 | ### 限定范围助手的行为 合规与参考助手的设计是刻意收窄范围的。 - 合规助手涵盖铁路行业的网络安全合规、控制措施、报告、治理、安全意识以及防御工具。 - 参考助手涵盖标准、官方指南、行业实践及相关解释。 - 两个助手均不作为通用编程助手。 ### 当前模型默认值 | 变量 | 默认值 | 用途 | | --- | --- | --- | | `ANTHROPIC_MODEL` | `claude-opus-4-8` | 模拟、场景生成、预案手册、评估、限定范围的回答 | | `ANTHROPIC_FAST_MODEL` | `claude-opus-4-8` | 问答、后续重写、CVE 解释器以及安全筛查 | 两者默认均为 Claude Opus 4.8。为了在较轻量的任务上换取更低的成本与延迟，可以将 `ANTHROPIC_FAST_MODEL` 指向更小的模型，例如 `claude-haiku-4-5`。 ## 设计系统 界面采用了为铁路环境量身定制的控制室视觉语言： - **信号调色板。** 采用一种绿色强调色承载品牌标识，琥珀色和红色保留用于表示警告与严重程度，这与铁路信号惯例相同。 - **字体。** 标题使用 Space Grotesk，正文使用 IBM Plex Sans，标签、代码与数据使用 IBM Plex Mono。这三种字体均通过 `next/font` 加载，并在构建时自托管。 - **图形元素。** 模块以发车显示板索引上的编号线路呈现（01 至 09），状态显示为发光的信号点，时间轴沿着带有站点节点的铁路线延伸。 - **状态。** CVE 订阅源与生成流程提供骨架加载器，结果呈现带有入场动画，可见的焦点环，一个跳过链接，并支持减少动态效果。 - **响应式。** 布局在小屏幕上折叠为单列，表单控件保持 16px 以避免 iOS 上的聚焦缩放，主导航在低于大断点时变为汉堡包抽屉菜单。 ## 技术栈 | 类别 | 技术 | 用途 | | --- | --- | --- | | 框架 | Next.js 16.2 | 路由、渲染与生产构建流水线 | | UI | React 19 | 组件模型与交互式客户端功能 | | 样式 | Tailwind CSS 4 | 布局、设计 token 与实用样式 | | AI SDK | `@anthropic-ai/sdk` | 具有结构化输出的 Claude Messages API | | 校验 | Zod | 输入与输出 schema | | 字体 | `next/font` | 自托管的 Space Grotesk, IBM Plex Sans, IBM Plex Mono | | 密码强度评估 | `zxcvbn` | 本地浏览器端密码强度分析 | | 漏洞数据 | NVD CVE API 2.0 | 实时 CVE 订阅源与支持 KEV 的过滤 | | 图标 | `lucide-react` | UI 图标 | ## 页面与用户流程 ### 1. 钓鱼实验室 钓鱼模块支持两项工作： - 生成安全的钓鱼模拟，以邮件客户端预览的形式展示 - 审查粘贴的邮件是否存在潜在的钓鱼风险 它还支持对任何结果进行后续操作： - 简单解释 - 首要行动 - 管理者简报 - 深入分析 ### 2. 密码工作室 密码模块刻意采用了本地优先的设计。 - 密码生成使用浏览器密码学 - 密码强度评估使用 `zxcvbn` 与分段强度计 - 手动密码检查保留在浏览器中进行 由于它依赖于浏览器密码学，该模块仅在客户端渲染，从而避免将其随机输出纳入服务端渲染。 ### 3. 事件实验室 此页面生成一个逼真的场景作为事件简报，随后审查提议的首次响应。反馈涵盖： - 遏制 - 升级 - 沟通 - 证据处理 - 恢复优先级 - 报告考量 ### 4. 预案手册 预案构建器使用六阶段结构： | 阶段 | | --- | | 准备 | | 识别 | | 遏制 | | 根除 | | 恢复 | | 经验教训 | 用户可以将自己的草案与生成的预案进行比对，以找出： - 一致的领域 - 缺失的领域 - 高风险的差距 - 下一步改进措施 ### 5. 知识问答 问答模块创建简短的单项选择测试，具有： - 2 到 6 个问题 - 每个问题四个回答选项 - 即时评分，提交后将每个选项标记为正确或错误 - 每道题的解析 ### 6. 合规中心 此页面将控制措施与工具图谱与一个限定范围的助手相结合，可回答关于以下方面的问题： - NIS2 - GDPR - CER - ISO 27001 - IEC 62443 - 治理 - 控制措施 - 安全意识计划设计 - 防御性 OT 与 IT 工具 ### 7. 漏洞订阅源 漏洞页面将 NVD 订阅源转化为更实用的操作员视图： - 关键词搜索 - 严重性过滤器 - 日期范围过滤器 - 仅显示 KEV 过滤 - 从 CVSS 向量解码的攻击画像上下文 - AI 生成的 CVE 摘要 - 导与后续操作 ### 8. 参考库 此模块结合了： - 精选的官方链接 - 标准与指南参考 - 限定范围的解释器助手 - 在相关处提供附带来源链接的输出 ### 9. 宣传墙 意识页面支持讨论与研讨会。它展示了： - 2017 年至 2025 年时间轴上的交通与铁路网络安全事件 - 这些事件中反复出现的模式 - 带编号的桌面推演讨论提示 ## API 路由 | 路由 | 方法 | 用途 | | --- | --- | --- | | `/api/ai` | `POST` | 处理结构化的 AI 操作，例如钓鱼生成、场景审查、预案生成、合规解答、CVE 解释与后续重写 | | `/api/cves` | `GET` | 为漏洞订阅源获取、标准化并过滤 NVD 漏洞数据 | 这两个路由均按客户端 IP 进行速率限制：`/api/ai` 每分钟 30 次请求，`/api/cves` 每分钟 60 次。超过限制后，路由将返回 `429` 及 `Retry-After` header。 ### 支持的 AI 操作 | 操作 | | --- | | `phishing.generate` | | `phishing.evaluate` | | `phishing.analyze` | | `scenario.generate` | | `scenario.evaluate` | | `guide.generate` | | `guide.compare` | | `compliance.answer` | | `reference.answer` | | `cve.explain` | | `followup.rewrite` | | `quiz.generate` | ### 错误响应 `/api/ai` 返回包含 `error` 消息与 UI 可据此操作的 `code` 的 JSON body： | 代码 | 状态码 | 含义 | | --- | --- | --- | | `RATE_LIMITED` | 429 | 该客户端的请求过多 | | `INVALID_REQUEST` | 400 | 操作或 payload 未通过验证 | | `EMPTY_INPUT`, `INPUT_TOO_LONG` | 400 | 自由文本输入为空或超过长度限制 | | `PROMPT_INJECTION`, `MODERATION_BLOCKED` | 400 | 输入被防护机制或安全筛查拦截 | | `OUT_OF_SCOPE` | 400 | 向限定范围的助手询问了其职责范围外的问题 | | `ASSISTANT_DECLINED` | 400 | Claude 拒绝了该请求 | | `ASSISTANT_NOT_CONFIGURED` | 500 | 缺少 `ANTHROPIC_API_KEY` 或其无效 | | `ASSISTANT_BUSY` | 429 | Claude 上游返回了速率限制错误 | | `ASSISTANT_UNREACHABLE` | 502 | 无法连接到 Claude API | | `ASSISTANT_UNAVAILABLE` | 500 | 处理请求时出现的任何其他意外故障 | ## 快速开始 ### 前置条件 - 推荐使用 Node.js 20 或更高版本 - npm - 一个 Anthropic API key - 可选：一个 NVD API key，以便在漏洞请求中获得更好的速率限制余量 ### 1. 安装依赖 ``` npm install ``` ### 2. 添加本地环境变量 在项目根目录下创建一个 `.env.local` 文件，并添加所需的变量： ``` ANTHROPIC_API_KEY=your_anthropic_api_key ANTHROPIC_MODEL=claude-opus-4-8 ANTHROPIC_FAST_MODEL=claude-opus-4-8 NVD_API_KEY=your_nvd_api_key ``` `.env.local` 已被 git 忽略，因此密钥不会进入版本控制。 ### 3. 启动开发服务器 ``` npm run dev ``` 然后打开 [http://localhost:3000](http://localhost:3000)。 ## 环境变量 | 变量 | 必需 | 用途 | | --- | --- | --- | | `ANTHROPIC_API_KEY` | 是 | 对发往 Claude API 的请求进行身份验证 | | `ANTHROPIC_MODEL` | 否 | 用于结构化生成任务的主要模型（默认为 `claude-opus-4-8`） | | `ANTHROPIC_FAST_MODEL` | 否 | 用于问答、后续重写、CVE 解释器以及安全筛查等轻量级任务的模型（默认为 `claude-opus-4-8`） | | `NVD_API_KEY` | 否 | 调用 NVD 时使用，以获得更好的速率限制余量 | ## 可用脚本 | 脚本 | 功能 | | --- | --- | | `npm run dev` | 启动本地开发服务器 | | `npm run build` | 创建生产构建 | | `npm run start` | 运行生产服务器 | | `npm run lint` | 在整个应用中运行 ESLint | ## 在 Vercel 上部署 生产构建已部署并托管于 Vercel，地址为 [railsecure.vercel.app](https://railsecure.vercel.app)。 ### 部署你自己的实例 1. 将项目推送到 Git 仓库。 2. 将项目导入 Vercel。 3. 在 Vercel 控制台中添加环境变量。 4. 部署。 ### 部署说明 - 该应用使用 App Router，符合标准的 Vercel 部署模型。 - AI 与 NVD 路由运行在 Node.js runtime 上，`/api/ai` 设置了 `maxDuration = 60`，为较长的生成过程留出空间。 - 当前版本无需进行数据库设置。 - 敏感值应存放在环境变量中，而不是已提交的源代码中。 - 速率限制是基于内存的，因此每个 serverless 实例都会保留自己的计数器。若需实现严格的全局限制，请使用 Vercel KV 或 Upstash 等共享存储来支撑限制器。 ## 项目结构 ``` railsecure/ +-- app/ | +-- api/ | | +-- ai/route.ts | | \-- cves/route.ts | +-- awareness/page.tsx | +-- compliance/page.tsx | +-- incident-lab/page.tsx | +-- passwords/page.tsx | +-- phishing/page.tsx | +-- playbooks/page.tsx | +-- quiz/page.tsx | +-- references/page.tsx | +-- vulnerabilities/page.tsx | +-- globals.css | +-- layout.tsx | +-- not-found.tsx | \-- page.tsx +-- components/ | +-- assistant-guidance-panel.tsx | +-- compliance-workbench.tsx | +-- follow-up-panel.tsx | +-- incident-lab.tsx | +-- password-studio.tsx | +-- password-studio-lazy.tsx | +-- phishing-lab.tsx | +-- playbook-builder.tsx | +-- quiz-board.tsx | +-- reference-library.tsx | +-- result-actions.tsx | +-- section-intro.tsx | +-- shell-card.tsx | +-- site-footer.tsx | +-- site-header.tsx | +-- status-pill.tsx | \-- vulnerability-explorer.tsx +-- lib/ | +-- anthropic.ts | +-- client.ts | +-- content.ts | +-- guardrails.ts | +-- nvd.ts | +-- railsecure-ai.ts | +-- rate-limit.ts | +-- schemas.ts | \-- utils.ts +-- public/ | \-- assets/ \-- README.md ``` ### 快速文件指南 | 文件 | 作用 | | --- | --- | | `app/layout.tsx` | 全局外壳、字体、页眉、页脚与页面框架 | | `app/page.tsx` | 带有模块展示板的概览页 | | `lib/anthropic.ts` | Claude 客户端与模型配置 | | `lib/railsecure-ai.ts` | 特定任务的 AI 编排与结构化输出处理 | | `lib/guardrails.ts` | 输入检查、Claude 安全筛查与范围强制执行 | | `lib/rate-limit.ts` | 用于 API 路由的基于内存的按客户端速率限制器 | | `lib/nvd.ts` | NVD 获取与标准化层 | | `lib/content.ts` | 静态内容、模块选项、参考、事件与页面文案 | | `lib/schemas.ts` | AI 操作的输入与输出 schema | | `components/site-header.tsx` | 带有当前页面指示器的导航栏 | | `components/result-actions.tsx` | 用于生成内容的复制与下载操作 | | `components/follow-up-panel.tsx` | 对现有结果的重写与替代视图 | ## 实现说明 ### 结构化输出 每个 AI 工作流都使用 Claude 结构化输出。Zod schema 被转换为 JSON schema 并通过 `output_config.format` 传递，因此模型返回的 JSON 会与 schema 结构相匹配。由于 API 并不强制执行字符串长度限制，服务端会使用 Zod schema 验证返回的 JSON，并修复 API 无法保证的一件事：如果一个字段超出了其限制几个字符，就会将其截断至该限制，而不是导致整个请求失败。 这些工作流调用带有 schema 约束格式的 `messages.create` 并自行解析结果，这正是实现修复步骤的关键所在。轻量级的安全筛查直接使用 `messages.parse`，因为其输出不需要如此高的容错性。 如果响应被拒绝或截断： - 拒绝会以带有 `ASSISTANT_DECLINED` 代码的明确 400 错误呈现 - 截断或格式不正确的输出将触发一次具有更大输出预算的重试 - 过长的字符串会被截断至其 schema 最大长度，而不会报错 - 身份验证、速率限制与连接失败将映射至[错误响应](#error-responses)项下列出的特定错误代码 ### Prompt injection 处理 AI 模块的构建方式确保了不受信任的内容无法重定向该助手： - 生成选择器根据固定枚举进行验证，因此这些操作只会在已知良好的选项上运行 - 自由文本会剥离控制字符与零宽字符，针对注入模式进行筛查，然后由 Claude 安全筛查从两个维度进行分类（有害内容与针对助手的注入） - 用户输入与第三方数据（粘贴的邮件、CVE 记录、预案草案）被包装在标记块中，系统提示词会严格将其视为数据 - 每个模块的系统提示词都声明了其单一任务，并告知模型将任何嵌入的指令视为要分析的素材，而不是要遵循的指令 粘贴邮件分析器是注入拦截机制的一个刻意设计的例外。包含注入内容的邮件是值得研究的真实攻击，因此它会被当作数据进行分析，任何嵌入的注入都会被作为特征报告，而不是被拒绝。 ### 速率限制 两个 API 路由都应用了基于内存、以转发客户端 IP 为键的按客户端固定窗口限制器（`lib/rate-limit.ts`）： - `/api/ai` 每分钟允许 30 次请求，`/api/cves` 为 60 次 - 超过限制后，路由将返回 `429` 及 `Retry-After` header - 如果无法识别客户端，限制器会实行失败放行 设定这些限制是为了阻止对消耗资金的 endpoint 的自动化滥用，同时为一个企业出口 IP 后面的整个团队留出足够的余量。状态存在于进程内存中，因此在多实例的 serverless 部署中，限制是按实例应用的。使用共享存储将使其成为严格意义上的全局限制。 ### NVD 处理 NVD 层会： - 将 `days` 与 `limit` 值限制在安全范围内（请求窗口保持在 NVD 最大 120 天的限制内） - 支持关键词与严重性过滤 - 支持 KEV 专用过滤 - 标准化 CVSS 与弱点数据 - 添加超时机制，防止请求无限期挂起 来自 NVD 的描述可能会超出 CVE 解释器的输入限制，因此漏洞订阅源在发送摘要进行解释之前会先对其进行修剪。 ### 密码安全 密码工具特意设计为完全基于本地： - 生成使用 `crypto.getRandomValues` - 检查在浏览器中使用 `zxcvbn` - 手动密码分析无需服务端往返 ### 当前的非目标 当前版本不包含： - 用户账户 - 游戏化机制 - 持久化的用户历史记录 - 数据库存储 对于当前版本，这是刻意为之的。 ## 验证 该项目已通过以下检查： ``` npm run lint npm run build ``` 这两条命令在当前的 codebase 上均能通过。 ## 结语 RailSecure 的构建初衷是为了投入使用，而不仅仅是为了演示。它旨在帮助用户开展演练、向管理者作简报、审查漏洞或完善响应计划，而无需在多个不同的工具之间切换，也无需一遍又一遍地重新表述相同的问题。

标签：Claude API, GPT, 合规管理, 安全运营, 库, 应急响应, 扫描框架, 漏洞管理, 自动化攻击, 钓鱼演练