nssriraam/marrow

⚠️ **关于在线演示的说明：** 公开部署有意在未提供实时 Fireworks API key 的情况下运行，因此它始终使用 Marrow 的确定性后备推理器——这可以防止公共流量消耗 API 额度。仪表盘、PDF 导出、置信度评分和高管摘要的工作方式完全相同；只有推理来源有所不同。要获得由 AMD Instinct MI300X 上的 DeepSeek V4 Pro 提供支持的真正 AI 生成建议，请克隆此代码仓库并添加你自己的 key（参见[安装说明](#installation)）——或者查看下方的 **在线 API 推理示例**，其中展示了开发期间捕获的真实模型输出。 ## ⚡ 给评委的 TL;DR * **问题所在：** FinOps 看到的是成本，SecOps 看到的是风险，但双方都看不到全局。企业团队浪费了数小时去争论该先关停哪台闲置服务器。 * **解决方案：** Marrow 将你的 AWS 账单数据与 Security Hub 的发现关联起来，生成一个统一的仪表盘，只需点击一下即可解决成本和风险问题。 * **AMD 集成：** 每一项建议（及其理由）均由 **通过 Fireworks AI 托管的 AMD 模型** 进行实时推理，每次扫描处理结构化的 JSON payload。 * **置信度感知：** 建议包含一项自评确定性分数，对于真正模棱两可的情况会标记为需人工审核，而不是假装每次判断都清晰明确。 * **优势所在：** 它不是一个通用的 RAG 聊天机器人。它是一个确定性、自主的工作流，可输出面向利益相关者的 PDF 报告和严格的 `terminate/patch` 决策。 ## 目录 - [问题所在](#somebody-is-paying-rent-on-a-house-with-the-door-unlocked) - [Marrow 的作用](#what-marrow-does) - [功能](#features) - [架构](#architecture) - [AMD + Fireworks 实战](#amd--fireworks-in-action) - [截图](#screenshots) - [为什么没有其他工具能做到这一点](#why-nothing-else-does-this) - [技术栈](#tech-stack) - [前置条件](#prerequisites) - [安装说明](#installation) - [选项 A: Docker（推荐）](#option-a--docker-recommended) - [选项 B: 本地 Python 设置](#option-b--local-python-setup) - [配置](#configuration) - [用法](#usage) - [Web 仪表盘](#web-dashboard) - [CLI 命令](#cli-commands) - [REST API](#rest-api) - [数据格式参考](#data-format-reference) - [示例演练](#example-walkthrough) - [项目结构](#project-structure) - [故障排除](#troubleshooting) - [路线图](#roadmap) - [贡献](#contributing) - [作者](#author) - [License](#license) ## 有人正在为一栋大门敞开的房子支付租金 此刻，你的 AWS 账户中存在一个无人记得创建过的 EC2 实例。它每月花费 200 美元。而且它还拥有一个暴露在互联网上的开放端口。 你的 FinOps 工具看到了这 200 美元。你的 Security 工具看到了开放端口。**双方都不知道他们看的是同一个机器。** 这不是工具上的差距。这是两个完整部门多年来一直忽视的盲点，因为划分“浪费”和“危险”之间界限的软件，从一开始就不是为了同时观察这两者而构建的。 Marrow 能同时看到这两者。然后它会告诉你解决这两个问题的唯一行动。 ``` 🔴 What you have today 🟢 What Marrow gives you ────────────────────── ────────────────────────── "$200/mo, flagged as waste" "$200/mo, 3 open findings. - your cost tool Terminate it. Save $2,400/yr. "3 findings, HIGH severity" Remove 3 attack vectors." - your security tool Two tools. Two teams. One verdict. Zero guesswork. Zero conversation. ``` ## Marrow 的作用 Marrow 接入大多数公司已有的两种数据源：**账单/成本数据** 和 **安全态势发现**。它按云资源将它们连接起来，并将关联后的数据集交给 AI 推理层。模型针对每个资源只问一个问题：*成本、风险，还是两者兼有——该怎么做？* 每个资源都会得到一个明确的裁定，附带一个具体的金额数字和通俗易懂的理由——而不是只有安全工程师才能看懂的风险评分。 | | 行动 | 代表的含义 | |---|---|---| | 🔴 | **terminate** | 不仅耗费成本，还存在暴露风险。直接关停它。 | | 🟡 | **rightsize** | 你在为没人使用的容量付费。缩减它的规格。 | | 🟠 | **patch** | 保留该资源，修复发现的漏洞。 | | 🔵 | **restrict-access** | 关闭暴露面，不要动该资源本身。 | | ⚪ | **ignore** | 一切正常。不要动它。 | ## 功能 - 🔗 **跨域关联**：在 `resource_id` 上连接成本和安全数据，这是任何单独的成本工具或安全工具在原生层面上都做不到的 - 🧠 **AI 生成的推理**：每项建议都由通过 Fireworks AI 托管的 AMD 模型生成，而不是静态的规则表 - 🎯 **置信度评分**：每项建议都包含 0-100 的置信度评级；任何低于 70 的建议都会被标记以供人工审核 - 📝 **AI 生成的高管摘要**：由同一个模型生成的通俗英文扫描概述，可直接提交给利益相关者 - 📊 **风险评分**：基于权重计算的严重性评分（`CRITICAL`/`HIGH`/`MEDIUM`/`LOW`），按各个资源进行汇总 - 🗂️ **扫描历史**：每次扫描都会持久化保存到 SQLite 中，因此你可以追踪攻击面是否随着时间推移而缩小 - 💻 **实时仪表盘**：经过排名、带有颜色编码的建议卡片，并配有成本/风险可视化图表 - 📄 **可导出的 PDF 报告**：使用 ReportLab 生成、与仪表盘颜色编码相匹配且可直接提交给利益相关者的单页报告 - ⌨️ **功能完整的 CLI** — 提供 `scan`、`history` 和 `report` 命令，专为不想使用浏览器的人设计 - 🐳 **完全容器化**：只需执行一次 `docker compose up` 即可运行整个技术栈，无需进行本地 Python 设置 - 🔌 **REST endpoint** — 提供 `/api/recommendations`，方便任何人将其接入到其他工具中 ## 架构 ``` flowchart TD A[📊 Billing Data
AWS Cost Explorer format] --> C B[🔒 Security Findings
AWS Security Hub format] --> C C[⚙️ Correlator
joins on resource_id
computes risk score] --> D D{{"🧠 AI Reasoner
AMD-hosted model via Fireworks AI"}} --> E D -.->|structured JSON| E E[(🗄️ SQLite
scan + recommendation history)] --> F[💻 Flask Dashboard
ranked action cards] E --> G[📄 PDF Report
ReportLab export] style A fill:#1e293b,stroke:#475569,stroke-width:1px,color:#f8fafc style B fill:#1e293b,stroke:#475569,stroke-width:1px,color:#f8fafc style C fill:#0f172a,stroke:#475569,stroke-width:1px,color:#f8fafc style D fill:#312e81,stroke:#6366f1,stroke-width:2px,color:#f8fafc style E fill:#0f172a,stroke:#475569,stroke-width:1px,color:#f8fafc style F fill:#1e293b,stroke:#475569,stroke-width:1px,color:#f8fafc style G fill:#1e293b,stroke:#475569,stroke-width:1px,color:#f8fafc ``` 这里没有任何内容是由模型凭空捏造的。每一项裁定都可以追溯到真实的明细成本和真实的漏洞发现。AI 是基于你实际关联后的数据进行推理的，而不是凭空生成看似合理的文本。 ## AMD + Fireworks 实战 如果去掉推理层，Marrow 只是一个连接两个 JSON 文件的脚本。加回推理层后，每一项裁定（行动、金额数字、理由）均由 **通过 Fireworks AI 运行的 DeepSeek V4 Pro 生成**，该模型作为其 FireAttention V3 推理栈的一部分，在 AMD Instinct MI300X 基础设施上运行。 ### 在线 API 推理示例 以下是扫描期间由 Fireworks AI endpoint 返回的真实、未经编辑的 payload。请注意，模型在最终确定其裁定之前，是如何利用 `reasoning_content` 块透明地权衡成本与风险的。 ``` { "model": "accounts/fireworks/models/deepseek-v4-pro", "choices": [ { "message": { "role": "assistant", "reasoning_content": "We need to decide the best action based on utilization and security posture. Let's analyze each resource:\n\n1. rds-0efg5678hij90123e: RDS, cost $325, utilization 12.3%, findings: PUBLIC_ACCESS (CRITICAL), UNENCRYPTED_VOLUME (HIGH), MISSING_MFA (MEDIUM). Total risk 75. Low utilization, high cost, critical security issues. Action: terminate? Could also restrict-access for public access, but unencrypted volume and missing MFA are also issues. Terminate would save cost and eliminate all risks. Rightsize might be possible but utilization is very low, and security issues are severe. Terminate seems best. Monthly savings: $325, annual: $3900. Risk reduction: \"Resolved 1 CRITICAL, 1 HIGH, 1 MEDIUM findings\". Priority score: high due to cost and risk. Justification: \"Resource is severely underutilized (12.3%) and has critical security vulnerabilities including public access and unencrypted volume. Termination eliminates all risks and saves $325/month.\"\n\n... (evaluation continues for all resources) ...", "content": "{\n\"recommendations\": [\n{\n\"resource_id\": \"rds-0efg5678hij90123e\",\n\"action\": \"terminate\",\n\"monthly_savings_usd\": 325.0,\n\"annual_savings_usd\": 3900.0,\n\"risk_reduction\": \"Resolved 1 CRITICAL, 1 HIGH, 1 MEDIUM findings\",\n\"priority_score\": 90,\n\"justification\": \"Resource is severely underutilized (12.3%) and has critical security vulnerabilities including public access and unencrypted volume. Termination eliminates all risks and saves $325/month.\"\n}\n... ]}" } } ] } ``` Marrow 将完整的关联数据集作为单个批量请求发送，而不是为每个资源调用一次 API。这使得模型能够一次性对整个账户的成本和风险态势进行推理。然后，它会返回受 schema 约束的结构化 JSON，而不是自由格式的文本。 ## 截图 ## 为什么没有其他工具能做到这一点 | | 看到成本 | 看到风险 | 将两者关联起来 | |---|:---:|:---:|:---:| | CloudHealth / Vantage | ✅ | ❌ | ❌ | | Wiz / Security Hub / Prisma Cloud | ❌ | ✅ | ❌ | | **Marrow** | ✅ | ✅ | ✅ | 成本工具和安全工具是由不同的团队构建的，解决的是同一个问题的不同方面。Marrow 是双方都没有构建的关联层，因为双方以前从未在同一个房间里同时审视过这两个数据集。 ## 技术栈 | 层级 | 技术 | |---|---| | 后端 | Python 3.13, Flask | | AI 推理 | Fireworks AI API (DeepSeek V4 Pro, AMD MI300X 基础设施) | | 数据库 | SQLite | | CLI | Click, Rich | | 报告生成 | ReportLab (PDF 生成) | | 前端 | HTML/CSS (深色玻璃拟态主题), Chart.js | | 容器化 | Docker, Docker Compose | ## 前置条件 - **Docker** 和 **Docker Compose**（[安装指南](https://docs.docker.com/get-docker/)），用于推荐的安装设置 - *（仅限本地设置）* Python 3.13+ 和 pip - 一个 **Fireworks AI API key**：[在此注册](https://fireworks.ai)（提供免费额度；本次黑客马拉松的构建版本是通过 Fireworks 在 AMD 托管的计算资源上运行的） - Git ## 安装说明 ### 选项 A: Docker（推荐） 这是最快的途径，并且与黑客马拉松提交版本的测试环境完全一致。 ``` # 1. Clone the repo git clone https://github.com/nssriraam/marrow.git cd marrow # 2. 设置你的环境文件 cp .env.example .env # 打开 .env 并添加你的 FIREWORKS_API_KEY # 3. 构建并启动 container docker compose up --build ``` 构建完成后，仪表盘可通过以下地址访问： ``` http://localhost:5005 ``` 停止应用： ``` docker compose down ``` 停止应用 **并** 清除已存储的扫描历史： ``` docker compose down -v ``` ### 选项 B: 本地 Python 设置 如果你不想使用 Docker： ``` # 1. Clone the repo git clone https://github.com/nssriraam/marrow.git cd marrow # 2. 创建并激活 virtual environment python -m venv .venv # 在 Windows 上： .venv\Scripts\activate # 在 macOS/Linux 上： source .venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt # 4. 设置你的环境文件 cp .env.example .env # 添加你的 FIREWORKS_API_KEY # 5. 运行 app python run.py ``` 仪表盘将通过 `http://localhost:5000` 提供。 ## 配置 所有配置都位于 `.env` 文件中（复制 `.env.example` 即可开始）。变量说明： | 变量 | 是否必需 | 描述 | |---|---|---| | `FIREWORKS_API_KEY` | 是* | 你的 Fireworks AI API key。如果缺失或为空，Marrow 会自动回退到基于规则的模拟推理器，以便应用依然能进行端到端运行。 | | `MODEL_NAME` | 否 | 用于推理的 Fireworks 模型标识符。如果未设置，默认使用一个合理的 AMD 托管模型。 | | `DB_PATH` | 否 | SQLite 数据库文件的路径。默认为根文件夹下的 `marrow.db`。 | | `BILLING_DATA_PATH` | 否 | 账单 JSON 文件的路径。默认为 `data/sample_billing.json`。 | | `FINDINGS_DATA_PATH` | 否 | 安全发现 JSON 文件的路径。默认为 `data/sample_findings.json`。 | \* *Marrow 可以在模拟模式下在没有它的情况下运行，但真正由 AI 生成的建议需要提供有效的 key。* ## 用法 ### Web 仪表盘 1. 启动应用（Docker 或本地环境——参见[安装说明](#installation)）。 2. 在浏览器中打开 `http://localhost:5000`。 3. 点击 **Run Scan** 以关联当前的账单 + 漏洞发现数据，并生成最新的建议。 4. 查看经过排名、带有颜色编码的行动卡片——按优先级分数从高到低排序。 5. 点击任意扫描结果上的 **Download Report** 以导出 PDF 摘要。 6. 访问 **History** 查看过去每一次的扫描记录，以及建议随着时间的推移发生了怎样的变化。 ### CLI 命令 如果使用 Docker，请在每个命令前加上 `docker exec marrow`。如果在本地运行，请忽略该前缀。 ``` # 运行新的扫描（关联数据，生成建议，保存到 DB） docker exec marrow python -m app.cli scan # 查看所有过往扫描 docker exec marrow python -m app.cli history # 为最近的扫描生成 PDF 报告 docker exec marrow python -m app.cli report # 为特定扫描生成 PDF 报告 docker exec marrow python -m app.cli report --scan-id 3 ``` ### REST API | Endpoint | 方法 | 描述 | |---|---|---| | `/` | GET | 仪表盘主页 | | `/scan` | POST | 触发新的扫描 | | `/history` | GET | 扫描历史页面 | | `/api/recommendations` | GET | 以 JSON 格式返回最新扫描的建议 | | `/report/` | GET | 下载指定扫描 ID 的 PDF 报告 | 示例： ``` curl http://localhost:5000/api/recommendations ``` ``` [ { "resource_id": "i-0abc123def456", "action": "terminate", "monthly_savings_usd": 200.00, "annual_savings_usd": 2400.00, "risk_reduction": "Resolved 1 CRITICAL and 2 MEDIUM findings", "priority_score": 92, "confidence": 95, "justification": "Resource is severely underutilized (3.2%) with critical public access findings. Termination eliminates 3 attack vectors and saves $200/month." } ] ``` ## 数据格式参考 Marrow 需要两个通过 `resource_id` 连接的 JSON 文件**账单数据** (`sample_billing.json`)： ``` { "resource_id": "i-0abc123def456", "service": "EC2", "monthly_cost_usd": 200.00, "utilization_pct": 3.2, "region": "us-east-1", "tags": { "env": "dev", "owner": "unknown" } } ``` **安全发现** (`sample_findings.json`)： ``` { "resource_id": "i-0abc123def456", "finding_type": "OPEN_SECURITY_GROUP", "severity": "HIGH", "description": "Port 22 open to 0.0.0.0/0", "compliance_ref": "CIS 4.1" } ``` 这两个文件都可以替换为从 AWS Cost Explorer 和 AWS Security Hub 导出的真实数据。关联器只需要 `resource_id` 字段能够一一对应即可。 ## 示例演练 1. Marrow 加载 `sample_billing.json` 和 `sample_findings.json`。 2. 关联器将它们连接起来：一个每月花费 **$200** 且利用率仅为 **3.2%** 的 EC2 实例，被匹配到了同一个 `resource_id` 下的 **3 项漏洞发现**（一个 `HIGH`，两个 `MEDIUM`）。 3. 系统会根据发现的严重程度为该资源计算出一个 `total_risk_score`。 4. 关联后的记录被发送给 AI 推理器，返回结果如下： 5. 模型还会生成一个 3 句话的高管摘要，重点显示总节省成本和最高优先级的行动。 6. 建议被保存到 SQLite 中，并在仪表盘上显示为红色的 **terminate** 卡片，按优先级排在靠近顶部的位置。 7. 点击 **Download Report** 会生成一份包含相同数字的 PDF，可直接转发给主管。 ## 项目结构 ``` marrow/ ├── app/ │ ├── __init__.py │ ├── config.py # loads .env, centralizes settings │ ├── correlator.py # joins billing + findings on resource_id │ ├── reasoner.py # AI reasoning → structured JSON verdicts │ ├── models.py # SQLite schema + queries │ ├── routes.py # Flask routes │ ├── cli.py # scan / history / report commands │ └── report.py # PDF generation ├── data/ │ ├── sample_billing.json │ └── sample_findings.json ├── static/ # CSS, JS, dashboard theme ├── templates/ # Flask HTML templates ├── reports/ # generated PDF output ├── Dockerfile ├── docker-compose.yml ├── requirements.txt ├── .env.example └── README.md ``` ## 故障排除 **启动应用后仪表盘没有显示数据** 请先运行一次扫描——该应用在首次启动时不会自动填充数据。请使用 **Run Scan** 按钮或运行 `docker exec marrow python -m app.cli scan`。 **建议看起来很笼统/基于规则，而不是 AI 生成的** 请检查 `.env` 中的 `FIREWORKS_API_KEY` 是否设置正确，并确保在编辑后重新构建了容器（`docker compose up --build`）。如果没有有效的 key，Marrow 会有意回退到模拟推理器，而不是直接崩溃。 **`docker compose up` 找不到 `.env`** 请确保在启动容器之前运行了 `cp .env.example .env`，并且 `.env` 文件与 `docker-compose.yml` 一起位于项目根目录下。 **重启容器后扫描历史消失** 请确认 `docker-compose.yml` 中的 SQLite volume 挂载是否完好。只有在将 `data/` 作为 volume 挂载时才会保留历史记录，如果只是固化在镜像中则不会。 **PDF 报告生成失败** 请先运行一次扫描——`marrow report` 至少需要数据库中存在一条已有的扫描记录。 **扫描需要几分钟才能完成** 这完全正常。由 AMD 托管的 DeepSeek V4 Pro 模型正在一次性对所有资源进行深度的 Chain-of-Thought 推理。去喝杯咖啡，让 AI 完成它的分析吧！ ## 路线图 - [ ] Azure 和 GCP 支持：使用相同的关联引擎，支持更多的云服务提供商 - [ ] 审批控制的自动修复（而非盲目执行） - [ ] 当建议超过优先级阈值时触发 Slack / PagerDuty 警报 - [ ] 多账户 / 多区域聚合 ## 贡献 这是为了一个为期 5 天的黑客马拉松而独立构建的，但在提交之后，我们也欢迎提交 issue 和 PR。如果你发现了一个 bug 或有好的想法，请在 GitHub 上提交 issue。 ## 作者 **Sriraam Nagarajan** — [`@nssriraam`](https://github.com/nssriraam) ## License MIT。详情请参阅 [LICENSE](LICENSE)。

标签：AWS, DPI, FinOps, GPT, SecOps, 云安全态势管理, 云安全架构, 前端应用, 成本优化, 漏洞管理, 网络测绘, 请求拦截, 逆向工具