childrda/CyberGuard

# CyberGuard – 内部钓鱼意识平台 [](https://opensource.org/licenses/MIT) [](https://laravel.com) [](https://php.net) [](https://workspace.google.com/) 生产就绪的内部钓鱼意识平台，**仅用于在你自己的 Google Workspace 域上进行授权的安全意识测试**。 ## 截图与架构 | 架构 | 演示 | |--------------|------| | [](docs/architecture.svg) | [](docs/logo.png) | 高层流程：**Gmail Add-on** (报告钓鱼 / 垃圾邮件 / 安全) → **CyberGuard 后端** (webhook, ReportedMessage, ShieldPoints, 审计) → **管理界面** (报告, 补救)。补救作为任务运行 (ProcessRemediationJob, MailboxActionLog)。详情请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 概述 要运行 CyberGuard： 1. **安装** – 克隆仓库，运行 `composer install`，复制 `.env.example` 到 `.env`，并生成一个 app key。 2. **配置** – 编辑 `.env` 设置你的数据库凭据以及（用于 Gmail add-on 的）webhook secret。参见下方的 [分步安装](#step-by-step-installation)。 3. **数据库** – 创建一个空的 MySQL 数据库，然后运行 `php artisan migrate` 和 `php artisan db:seed`（seed 仅用于本地开发）。 4. **运行** – 使用 `php artisan serve` 启动应用并打开 http://localhost:8000。使用种子账户登录（参见 [首次登录](#5-first-login-local-dev-only)）。 对于 Gmail 报告钓鱼插件，请在应用运行后按照 [Gmail 报告钓鱼插件设置](#gmail-report-phish-add-on-setup) 操作。 **快速参考 – 最小命令集（在你创建数据库并编辑 .env 之后）：** ``` composer install && cp .env.example .env && php artisan key:generate php artisan migrate && php artisan db:seed php artisan serve ``` 然后打开 http://localhost:8000 并使用 **admin@example.com** / **password** 登录。 ## 环境要求 | 需求 | 备注 | |-------------|--------| | **PHP ^8.2** | 必须与 `composer.json` 匹配。扩展：mbstring, xml, pdo_mysql, json, openssl, tokenizer | | **Composer** | [getcomposer.org](https://getcomposer.org) | | **MySQL 8+** | 或 MariaDB 10.3+ | | **Redis** (可选) | 用于生产队列/缓存；本地可以使用 `CACHE_STORE=file` 和 `QUEUE_CONNECTION=sync` | ## 分步安装 按顺序执行以下步骤。所有命令均从项目根目录（包含 `artisan` 的文件夹）运行。 ### 1. 克隆仓库并安装依赖 ``` git clone CyberGuard cd CyberGuard composer install cp .env.example .env php artisan key:generate ``` - 将 `` 替换为你实际的 Git 仓库 URL（例如 `https://github.com/yourorg/CyberGuard.git`）。 - 你应该看到：**Application key set successfully.** ### 2. 配置环境 在文本编辑器中打开 `.env` 文件。至少设置以下内容。 **数据库（必需）** 设置这些值以匹配你的 MySQL 服务器。在运行迁移之前，数据库必须存在。 ``` DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=cyberguard DB_USERNAME=root DB_PASSWORD=your_mysql_password ``` 在 MySQL 中创建数据库（在 MySQL 或你的数据库工具中运行此命令）： ``` CREATE DATABASE cyberguard CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` **Webhook secret（Gmail add-on 必需）** 生成一个长随机字符串并将其放入 `.env`。你将在 Gmail Apps Script 项目（脚本属性）中使用**相同的值**。 ``` PHISHING_WEBHOOK_SECRET=your-secret-at-least-32-characters-long ``` 生成 secret： ``` php -r "echo bin2hex(random_bytes(24));" ``` **本地开发（无 Redis）** 如果你不使用 Redis，请设置： ``` CACHE_STORE=file QUEUE_CONNECTION=sync ``` **保持原样以进行安全的本地测试（不发送真实邮件）：** ``` PHISHING_SIMULATION_ENABLED=false PHISHING_ALLOWED_DOMAINS=example.com ``` ### 3. 运行迁移和数据填充（仅限本地 / 开发） 从项目根目录： ``` php artisan migrate php artisan db:seed ``` - **迁移**会创建表。它们应该无错误完成。 - **填充**会创建一个默认租户、管理员用户、一个示例模板和一个示例活动。**仅用于本地开发。** 在生产环境中，除非你在 `.env` 中设置 `SEEDER_ALLOW_PRODUCTION=true` 和 `SEEDER_DEFAULT_PASSWORD`，否则 `php artisan db:seed` 会被阻止（参见 [安全](#security-production-checklist)）。 ### 4. 启动应用程序 从项目根目录： ``` php artisan serve ``` 在浏览器中打开 **http://localhost:8000**。你应该会看到登录页面。 ### 5. 首次登录（仅限本地开发） **这些凭据仅用于本地开发。请勿在生产环境中使用它们。** 在生产环境中，请通过你自己的流程创建用户和租户。 使用**其中**一个账户登录： | 邮箱 | 密码 | 角色 | 你可以做什么 | |-------|----------|------|-----------------| | platform_admin@example.com | password | Superadmin | 访问**所有租户**；使用侧边栏中的租户切换器在它们之间切换 | | admin@example.com | password | Superadmin | 仅访问**默认租户** (example.com) | | viewer@example.com | password | Viewer | 对默认租户的只读访问权限 | - **租户切换器**：登录后，左侧侧边栏会显示一个 **Tenant** 下拉菜单。使用它来切换上下文。平台超级管理员可以看到所有租户；其他人只能看到自己的租户。 - **添加你自己的管理员**：使用适当的 `tenant_id` 和角色（例如 analyst, campaign_admin）创建用户。请参阅你的部署文档或应用程序的用户管理来了解如何创建用户。 ### 6. （可选）运行队列 worker 和调度器 这些**仅在你实际发送钓鱼模拟或运行补救时才需要**。在单独的终端中从**项目根目录**运行它们（或在生产环境中作为后台进程 / systemd 服务运行）。 **当发送钓鱼模拟时**（在你设置 `PHISHING_SIMULATION_ENABLED=true` 之后）： ``` php artisan queue:work --queue=phishing-send ``` **当运行补救时**（从邮箱中移除已确认的钓鱼邮件）： ``` php artisan queue:work --queue=remediation ``` **使用一个 worker 运行两个队列：** ``` php artisan queue:work --queue=phishing-send,remediation ``` **活动发送窗口（在日期范围内分散邮件）：** 如果你创建了一个带有**发送窗口**（起始/截止日期）且**每个收件人的邮件数** > 1 的活动，邮件将被创建为*计划中*并随时间发送。你必须运行以下任一命令： - Laravel 调度器（推荐）：添加到你的 crontab： `* * * * * cd /path/to/your/project && php artisan schedule:run` （Laravel 将每 5 分钟运行一次 `phishing:send-scheduled`），或 - 直接按计划运行命令（例如每 5 分钟）： `php artisan phishing:send-scheduled` ## Gmail 报告钓鱼插件设置 **Google Workspace add-on** 包含在此仓库中（`google-addon/` 文件夹）。部署后，当用户打开邮件时，它会出现在 **Gmail 内部**：他们会看到 **"CyberGuard Report Phish"** 以及 **报告钓鱼**、**报告垃圾邮件**或**标记为安全**的选项。点击报告钓鱼会将邮件详情发送到你的 CyberGuard 后端，以便分析师审查。你可以通过在 `google-addon/appsscript.json` 中设置 `logoUrl` 来为插件使用盾牌图标（参见 [Logo 和品牌](#logo-and-branding))。 **在** Laravel 应用运行且你在 `.env` 中设置了 `PHISHING_WEBHOOK_SECRET` **之后**设置插件。 1. **创建 Apps Script 项目** - 前往 [script.google.com](https://script.google.com)。 - 点击 **New project**。 - 在项目中，打开默认的 `Code.gs` 和 `appsscript.json`。将其内容替换为 CyberGuard 仓库中 **`google-addon/Code.gs`** 和 **`google-addon/appsscript.json`** 的内容（复制并粘贴，然后保存）。 2. **设置脚本属性** - 在 Apps Script 中：**Project settings**（齿轮图标）→ **Script properties**（或 File → Project properties → Script properties）。 - 添加两个属性（为每个属性点击 **Add script property**）： | 属性名称 | 值 | |---------------|--------| | **WEBHOOK_URL** | 你的 CyberGuard 报告 API URL。生产环境：`https://your-domain.com/api/webhook/report`。本地测试（使用 ngrok）：`https://your-ngrok-url.ngrok.io/api/webhook/report` | | **WEBHOOK_SECRET** | 与 Laravel `.env` 文件中的 `PHISHING_WEBHOOK_SECRET` **完全相同**的值 | 如果 secret 不匹配，webhook 将以 401 拒绝报告。 3. **部署插件** - 点击 **Deploy** → **New deployment**。 - 选择类型 **Add-on**（或 **Test deployment** / **Internal**，具体取决于你的 Workspace）。 - 将插件限制为你的 Google Workspace 域，以便只有你的用户能在 Gmail 中看到它。有关分步部署（测试与内部/全域），请参阅仓库中的 **`google-addon/README.md`**。 4. **多租户（可选）** 如果你有多个租户（例如不同的域），插件可以发送报告所属的租户。在来自插件的 webhook 请求中，包含标头： **`X-Tenant-Domain: yourdomain.com`** 该值必须匹配 CyberGuard 数据库中租户的**域**（设置 / 租户配置）。 ## Google Workspace 部署（生产环境） - **Laravel:** 部署到你的服务器（推荐 PHP, MySQL, Redis）。在 `.env` 中设置 `APP_URL` 和 `PHISHING_WEBHOOK_SECRET`。插件调用 **POST** `/api/webhook/report`；服务器使用标头 `X-Phish-Signature: sha256=` 验证请求。 - **Gmail 移除（补救）：** 要允许分析师从用户邮箱中移除已确认的钓鱼邮件： 1. 在 `.env` 中设置： `PHISHING_GMAIL_REMOVAL_ENABLED=true` `GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json` `GOOGLE_WORKSPACE_DOMAIN=yourdomain.com` `GOOGLE_ADMIN_USER=admin@yourdomain.com` 2. 在 Google 管理控制台中，授予服务账号**全域委派**权限，范围如下： - Gmail API (根据移除需要 read/send/modify)。 - Admin SDK Directory API: `https://www.googleapis.com/auth/admin.directory.user.readonly`（用于列出用户）。 3. 在 CyberGuard **设置**中，配置每个**租户**及其域、服务账号 JSON 的路径（或使用全局 `.env` 凭据）和补救策略。 - **活动群组目标（发送到 Google Group）：** 为了让在活动中选择“Group”时拉取每个成员并向每人发送一封邮件，服务账号还需要在全域委派中拥有此范围： **`https://www.googleapis.com/auth/admin.directory.group.member.readonly`** 在管理控制台中将其与其他 Directory 范围一起添加。确保每个使用群组目标的租户在设置中配置了 **Google 凭据**（和管理员用户）。 ## 功能（概述） - **多租户**：独立的租户（例如员工与学生），拥有各自的域、凭据、webhook secret 和补救策略。管理侧边栏中的租户切换器。 - **模拟活动**：模板、目标用户/群组/CSV、审批工作流。可选的**攻击库**：多种钓鱼消息变体（例如“账户停用”、“Duo 通知”），带有难度评级；在活动中附加多个以混合每个收件人的内容。 - **Gmail 插件**：报告钓鱼（可选“我点击了链接”/“我输入了信息”）、报告垃圾邮件、标记为安全。Webhook 将报告与模拟匹配并授予 Shield 积分。 - **补救**：当报告被确认为真实钓鱼时，批准补救任务（可选 **dry run** 以模拟而不移除），然后运行以跨域邮箱移除该邮件。计数包括已移除、已跳过、dry-run（模拟）和失败；每个邮箱操作的完整日志。 - **Shield 积分和排行榜**：每个租户的积分账本和月度排行榜。 - **管理界面**：深色主题仪表板（指标、近期报告、活动、补救任务、顶级报告者、审计日志）、报告、补救、活动、攻击库、排行榜、审计日志、设置。RBAC：superadmin, campaign_admin, analyst, viewer。 详情：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## API 唯一公开的 API 端点是下面的报告 webhook。`/api` 路由还包括一组受 Sanctum 保护的组，保留供未来的内部管理工具使用；目前它是占位符，没有路由。 ### Webhook（用于插件） **POST** `/api/webhook/report- **Headers:** `Content-Type: application/json`, `X-Phish-Signature: sha256=` - **Optional:** `X-Tenant-Domain: yourdomain.com` 用于多租户 **示例主体：** ``` { "report_type": "phish", "reporter_email": "user@yourdomain.com", "gmail_message_id": "18c2a1b2e3d4f5g6", "gmail_thread_id": "...", "subject": "Urgent: Verify your account", "from": "IT Support ", "from_address": "support@example.com", "to_addresses": "user@yourdomain.com", "date": "Mon, 7 Mar 2025 12:00:00 +0000", "snippet": "Please click here to verify...", "headers": {}, "user_actions": ["clicked_link"] } ``` **响应：** `200` OK 并返回 `{ "ok": true, "reported_message_id": 1, "correlation_id": "uuid" }`；`401` 签名无效；`422` 验证错误；`503` 插件已禁用。 ## 配置参考 这些设置在 **`.env`** 中（或在应用程序的租户 **设置** 中，如所述）。 | 变量 | 描述 | 示例 | |----------|-------------|--------| | PHISHING_SIMULATION_ENABLED | 当为 `false` 时，不发送模拟邮件。仅在你准备好发送时设置为 `true`。 | `false` (开发) | | GMAIL_REPORT_ADDON_ENABLED | 当为 `false` 时，报告 webhook 返回 503（插件已禁用）。 | `true` | | PHISHING_ALLOWED_DOMAINS | 允许接收模拟邮件的域的逗号分隔列表。 | `example.com` | | PHISHING_WEBHOOK_SECRET | 必须**完全匹配**你的 Gmail Apps Script 项目中的 WEBHOOK_SECRET。 | 长随机字符串 | | PHISHING_GMAIL_REMOVAL_ENABLED | 当为 `true` 时，补救可以从邮箱中移除邮件（需要 Google 凭据）。 | `false` (开发) | | PHISHING_OPEN_TRACKING | 跟踪模拟中的链接打开情况。 | `true` | ## 测试 ``` composer test # 或 php artisan test ``` 功能测试覆盖：认证和仪表板访问、webhook（签名、未知租户、带租户的有效负载）、跟踪、**租户隔离**（范围受限用户无法查看其他租户的报告；中间件覆盖被篡改的会话；平台管理员可以使用任何租户）、**补救**（report_only 租户无法批准；dry-run 批准和完成状态；运行需要已批准的任务；dry-run 与真实移除计数器和最终状态）、**积分授予**（simulation_reported 和 reported_phish 账本；排行榜总和）以及**角色执行**（viewer 无法确认钓鱼或批准补救；analyst 可以）。 ## Logo 和品牌 - **管理应用：** 将你的 logo 放置在 `public/images/cyberguard-logo.png`。 - **Gmail 插件（盾牌图标）：** 在 `google-addon/appsscript.json` 中，将 **`logoUrl`** 设置为你的盾牌或报告钓鱼图标的公开可访问 URL（例如 `https://your-domain.com/images/report-phish-shield.png`）。用户将在 Gmail 中的 "CyberGuard Report Phish" 旁边看到此图标。 ## 安全（生产检查清单） - **填充：** 在生产环境中，除非你在 `.env` 中设置 `SEEDER_ALLOW_PRODUCTION=true`，否则 `php artisan db:seed` 会被**阻止**。仅用于一次性引导；将 `SEEDER_DEFAULT_PASSWORD` 设置为强值（当 `APP_ENV=production` 时必需）。 - **调试：** 切勿在生产环境中运行 `APP_DEBUG=true`。设置 `APP_DEBUG=false` 并将 `APP_URL` 设置为你的真实 URL（用于重定向和链接）。 - **Webhook secret：** 保持 `PHISHING_WEBHOOK_SECRET` 长且随机。Webhook 会拒绝签名无效的请求。如果泄露，请轮换 secret 并在 `.env` 和 Gmail Apps Script 项目中更新。 - **插件和管理访问：** 仅将 Gmail 插件部署到你的 Google Workspace 域。为应用使用 HTTPS，并尽可能将管理路由限制为受信任的网络或 VPN。 - **凭据：** 不要提交 `.env`。将 Google 服务账号 JSON 存储在 web 根目录之外，并通过路径引用它。 - **租户隔离：** 每个租户都有自己的数据范围；不要在租户之间重复使用相同的 webhook secret。 - **落地页：** 来自数据库的训练/落地 HTML 会被清理。仅允许受信任的管理员创建或编辑落地页。 - **重定向：** 跟踪重定向仅限于 `APP_URL` 中的主机；在生产环境中正确设置 `APP_URL`。 ## 许可证 MIT.

标签：Cloudflare, ESC8, ffuf, Gmail 插件, Google Workspace, Laravel, MITRE ATT&CK, OpenVAS, PHP, Webhook, 企业安全, 内部安全测试, 力导向图, 后台管理面板, 威胁情报, 安全教育, 安全运营, 开发者工具, 开源安全工具, 扫描框架, 搜索引擎查询, 社会工程学, 网络资产管理, 网络钓鱼防御, 逆向工程平台, 邮件举报, 邮件安全