JacksonMlk/sentinela

# Sentinela — AWS FinOps 与安全平台       ## 为什么我要构建这个 在咨询行业从事 FinOps 和云安全工作时，我针对每一个新客户账户不断重复着同样的手工周期： 1. 登录 AWS 控制台，打开 Cost Explorer，导出电子表格 2. 针对 IAM、S3、Security Groups 和 VPC 执行安全检查清单 3. 在 Excel 中交叉比对所有内容，拼凑出一张“昂贵**且**不安全”的幻灯片 4. 使用 `aws cli` 命令和节省估算编写可落地的速赢措施 每份报告需要花费 2-3 天的时间，而其中最难的部分——**将成本与风险联系起来**——往往因为赶不上截止日期而被舍弃。 Sentinela 的诞生正是为了端到端地自动化这一流程： - **STS AssumeRole** 消除了账户之间繁杂的凭证切换 - **并行收集** 在单次运行中抓取约 30 个 AWS 数据源（Cost Explorer、EC2、RDS、IAM、GuardDuty、Security Hub 等） - **Claude AI** 将原始数据转化为结合上下文的分析，而非千篇一律的检查清单式答案 - **组合矩阵** 揭示出那些既昂贵**又**不安全的资源 - **只读客户端门户** 无需重新导出 PDF 即可将报告交付给客户 结果便是：过去需要 2-3 天手工完成的工作，如今变成了约 10 分钟的自动化分析。 ## 截图

操作面板（管理员）

整合的客户投资组合、按优先级排序的告警，FinOps 和安全评分并排展示。 

FinOps 仪表板

12 个月成本趋势、按服务/UsageType 分类明细、异常及预测。 

安全仪表板

0-100 分评分，Critical/High/Medium 级别发现，按分数影响排名的首要问题。 

速赢措施 — FinOps

低投入操作及预估美元节省额、可直接运行的 `aws cli` 命令以及分步指南。 

速赢措施 — 安全

按严重程度分组的安全速赢措施，附带修复命令和分数影响估算。 

客户端门户

通过唯一 token 交付给客户的只读视图——概览、FinOps、安全及速赢措施。 

## 概览 **Sentinela** 将以往的手工操作自动化：连接到每个客户的 AWS 账户，收集成本与安全数据，进行交叉比对，并生成一份按优先级排序的报告。借助集成到每项分析中的 **Claude AI (Anthropic)**，每一条洞察都结合了账户的真实数据生成——而非泛泛的通用建议。 ### 平台功能 | 模块 | 功能描述 | |--------|--------------| | **FinOps 仪表板** | 月度成本、12 个月趋势、按服务和 UsageType 分类明细、已检测到的异常 | | **成熟度模型** | 涵盖 5 个维度的评分：标签、资源适度调整、承诺折扣、浪费消除、治理 | | **闲置资源** | 未挂载的 EBS 卷、未使用的 EIP、已停止的实例、无流量的 Load Balancer | | **安全仪表板** | 0-100 分评分、Critical/High/Medium 级别发现、IAM、S3、Security Groups、加密 | | **组合分析** | 成本与风险交叉的优先级矩阵——识别出同时昂贵且不安全的资源 | | **速赢措施** | 低投入操作及预估美元节省额和分步指南 | | **项目** | 具有预期投资回报率 (ROI) 的中期战略举措 | | **客户端门户** | 带有唯一 token 的只读链接，供客户跟进进度 | ## 架构 ``` flowchart TD Admin("👤 Operator / Admin"):::navy subgraph Platform[" Sentinela Platform "] API("⚡ FastAPI + Jinja2"):::navy subgraph Engine[" Analysis Engine "] AWS("☁️ AWS Analyzer\nboto3"):::orange AI("🤖 Claude AI\nAnthropic API"):::pink end DB[("🗄️ Database\nSQLite / PostgreSQL")]:::blue subgraph Views[" Dashboards "] V1("Admin Panel"):::chip V2("FinOps Dashboard"):::chip V3("Security Dashboard"):::chip V4("Client Portal"):::chip end end CA("💼 Client A\nAWS Account"):::client CB("💼 Client B\nAWS Account"):::client CC("💼 Client C\nAWS Account"):::client Admin -->|HTTPS| API API --> AWS API --> AI API --> DB AWS -.->|STS AssumeRole| CA AWS -.->|STS AssumeRole| CB AWS -.->|STS AssumeRole| CC classDef navy fill:#0B1956,stroke:none,color:#fff classDef orange fill:#FF9900,stroke:none,color:#fff classDef pink fill:#FF679A,stroke:none,color:#fff classDef blue fill:#3B5EDB,stroke:none,color:#fff classDef chip fill:#EEF2F9,stroke:#0B1956,color:#0B1956 classDef client fill:#fff,stroke:#0B1956,color:#0B1956 ``` ### 分析流程 ``` 1. Admin registers a client with an IAM Role ARN │ ▼ 2. Operator triggers analysis via /admin/clients/{id}/analyze │ ▼ 3. aws_analyzer assumes the client's role via STS and collects ~30 data sources in parallel: Cost Explorer, EC2, RDS, EKS, Lambda, S3, IAM, GuardDuty, Security Hub, CloudTrail… │ ▼ 4. claude_analyzer sends the data to Claude AI and receives structured JSON analysis: • FinOps: score, savings, maturity, quick wins • Security: score, findings, quick wins • Combined: cross-priority matrix │ ▼ 5. Results stored in the database and surfaced in the admin dashboards + client portal ``` 详细的技术决策（为什么使用 SQLite + PostgreSQL，为什么使用 STS AssumeRole，为什么选择 Jinja2 而不是 SPA 等）详见 **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。 ## 技术栈 | 层级 | 技术 | |-------|-----------| | 后端 | Python 3.10+, FastAPI, SQLAlchemy | | 前端 | Jinja2, 原生 HTML/CSS/JS, Chart.js | | AI | Anthropic Claude API (claude-opus / claude-sonnet) | | AWS SDK | boto3 | | 数据库 | SQLite (开发环境) / PostgreSQL (生产环境) | | 容器化 | Docker | | 编排 | Kubernetes (EKS) | | 调度 | APScheduler (自动周期性分析) | ## 收集的数据 ### FinOps | 数据 | AWS 服务 | |------|-------------| | 按服务和 UsageType 划分的成本（12 个月） | Cost Explorer | | 下个月预测 | Cost Explorer | | 检测到的成本异常 | Cost Explorer | | 资源适度调整建议 | Compute Optimizer | | RI / Savings Plans 建议 | Cost Explorer | | 未挂载的 EBS 卷 | EC2 | | 未使用的 Elastic IP | EC2 | | 旧快照（+90 天） | EC2 | | 已停止的实例 | EC2 | | 闲置的 Load Balancer | ELBv2 | | S3 存储桶（大小、生命周期） | S3 + CloudWatch | | 每个实例的 CPU/内存指标 | CloudWatch | | 延长支持版本 (RDS, EKS, Lambda) | RDS / EKS / Lambda | ### 安全 | 数据 | AWS 服务 | |------|-------------| | Root MFA，密码策略 | IAM | | 未启用 MFA 的用户 | IAM | | 旧的访问密钥（+90 天） | IAM | | 过于宽松的策略 | IAM | | 非活跃用户 | IAM | | 公开的 S3 存储桶 | S3 | | 未加密的 S3 存储桶 | S3 | | 对 0.0.0.0/0 开放的 Security Groups | EC2 | | 未启用 Flow Logs 的 VPC | EC2 | | 未加密的 EBS 卷 | EC2 | | 未加密的 RDS 实例 | RDS | | 各区域的 GuardDuty | GuardDuty | | CloudTrail 状态 | CloudTrail | | Security Hub 发现 | Security Hub | | AWS Config 未通过的规则 | Config | ## 快速开始 ### 前置条件 - Python 3.10+ - 已在本地配置好 AWS 凭证（CLI 或环境变量） - 一个 [Anthropic API 密钥](https://console.anthropic.com) ### 本地运行 ``` # 1. Clone 并准备环境 git clone https://github.com/jacksonmlk/sentinela-opensource.git cd sentinela-opensource python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt # 2. 配置环境变量 cp .env.example .env # 编辑 .env 并至少填写： # ANTHROPIC_API_KEY=sk-ant-... # ADMIN_SECRET_TOKEN=something-secure # AWS_DEFAULT_REGION=us-east-1 # 3. 启动应用 uvicorn app.main:app --reload --port 8000 # 4. 打开 open http://localhost:8000 # 你将被重定向到 /admin/login — 请使用来自 .env 的 ADMIN_SECRET_TOKEN ``` ### 接入你的第一个客户 在客户的 AWS 账户中，创建一个信任你的操作员账户的角色，并附加 `ReadOnlyAccess` + `SecurityAudit` 策略。完整的操作步骤（信任策略、`aws cli` 命令、凭证模式）详见 **[SETUP.md](SETUP.md)**。 ### 生产环境部署 (EKS) ``` # 在 deploy.sh 中配置变量并运行： ./deploy.sh ``` Kubernetes manifests 位于 `k8s/` 目录下。你需要： - 创建一个 ECR 仓库 - 使用 `.env.example` 中的变量配置 `sentinela-env` Secret - 在 `k8s/ingress.yaml` 中调整 IAM Role ARN 和域名 ## 环境变量 | 变量 | 是否必须 | 描述 | |----------|----------|-------------| | `ANTHROPIC_API_KEY` | ✅ | Anthropic API 密钥 | | `ANTHROPIC_MODEL` | ✅ | Claude 模型（例如 `claude-sonnet-4-6`） | | `ADMIN_SECRET_TOKEN` | ✅ | 管理员面板密码 | | `DATABASE_URL` | ✅ | SQLite 或 PostgreSQL | | `AWS_DEFAULT_REGION` | ✅ | 默认 AWS 区域 | | `FINOPS_AWS_PROFILE` | 开发环境 | 用于开发的本地 AWS Profile | | `COGNITO_*` | 生产环境 | 用于企业身份验证的 OIDC 设置 | ## 状态与已知局限 Sentinela 目前处于 **beta** 阶段——它可以端到端地工作并已应用于生产环境，但仍存在一些不足之处： - **尚无自动化测试。** 迄今为止的重点是通过真实客户验证整个流程。添加冒烟测试和 CI 已被提上日程。 - **Schema 迁移通过在 FastAPI `lifespan` ([app/main.py](app/main.py)) 中手动执行 `ALTER TABLE` 实现**——适用于当前的 schema，但引入 Alembic 是自然的下一步。 - **仅支持 AWS。** GCP 和 Azure 目前不在考虑范围内。 - **基于行的多租户，而非基于数据库。** 适合咨询业务工作流；但尚未针对公共 SaaS 模式进行安全强化。 - **每次分析的 Anthropic API 成本。** 根据账户大小和所用模型（Sonnet vs Opus），一次完整分析的成本从几美分到几美元不等。 - **葡萄牙语 UI。** 模板、提示词和报告均为 PT-BR。尚未实现国际化。 ## 未来构想 ### 重点方向 — Sentinela v2：自主修复代理 目前的 Sentinela 负责分析和报告。v2 版本将形成闭环： - 操作员在仪表板中审查发现，并**批准**需要修复的内容 - 由 Claude 驱动的代理执行修复：应用存储桶策略、收紧 IAM、针对基础设施级别的更改发起 Terraform PR - **Dry-run 模式** 在任何操作触及账户之前，展示确切将要应用的 diff 差异 - 每一项操作都会记录审批人、理由以及回滚步骤 这是从*“我该怎么做？”*到*“在我的批准下替我执行”*的自然演进。 ### 其他方向 这并非正式的路线图——只是一些合乎逻辑的发展方向。暂无时间表。 - [ ] 多云支持（先支持 GCP，然后是 Azure） - [ ] 在 GitHub Actions 上的冒烟测试 + CI - [ ] 将 schema 管理迁移至 Alembic - [ ] 后台任务导出 PDF/Docx（目前为同步执行） - [ ] 分析完成后的 Webhook 通知（Slack/Teams/Discord） - [ ] 同一客户连续分析结果之间的历史差异对比 - [ ] 偏差检测——在两次运行之间分数下降时发出告警 - [ ] 英语 UI / i18n 欢迎贡献代码——参见 **[CONTRIBUTING.md](CONTRIBUTING.md)**。 ## 安全 发现了漏洞？请**不要公开提 issue**。请查看 **[SECURITY.md](SECURITY.md)** 以了解负责任的披露渠道。 ## 许可证 [MIT](LICENSE) © Jackson Santos

标签：AV绕过, AWS, Claude AI, DPI, EC2, FastAPI, FinOps, GuardDuty, IaC, IAM, Python, RDS, S3, Security Hub, VPC, 云合规, 云成本管理, 后端开发, 子域名突变, 开源, 成本分析, 无后门, 测试用例, 自动化报告, 请求拦截, 逆向工具