iamemirozturk/aws-vpc-flowlogs-anomaly-detection

# AWS VPC Flow Logs 集中式异常检测  [](https://github.com/iamemirozturk/aws-vpc-flowlogs-anomaly-detection/actions/workflows/terraform-ci.yml) [](https://developer.hashicorp.com/terraform) [](https://www.python.org/) [](LICENSE) 本仓库是一个可部署的参考实现，用于集中化处理来自多个 AWS 账户的 VPC Flow Logs，通过 Amazon Athena 查询丰富后的 Parquet 记录，并对异常庞大的接受出站流量（accepted egress）发出警报。它展示了 安全架构和工程实践；它不是一个托管检测 服务，也不能替代针对特定威胁的调优。 ## 已实现的功能 - 跨账户直接将 Flow Logs 传输到中心 S3。S3 传输不 使用 IAM 传输角色。 - 一个中心 Terraform state 以及每个分支 账户/Region 一个独立的 state，并带有 account-ID provider 安全防护。 - 丰富后的 Parquet 日志、按小时的 Hive 前缀，以及带有 Athena 分区投影（partition projection）的 Glue 表。无需 crawler 或分区注册任务。 - 延迟的精确滚动窗口查询，检查接受的出站流量，在可用时使用数据包 地址，处理 IPv4/IPv6 排除，并在应用阈值前 汇总每个源的所有外部目标。 - 每次运行提供一个有界的 SNS 通知，DynamoDB 窗口幂等性，预留的 Lambda 并发，EventBridge 重试，加密的 SQS 死信队列， 以及 CloudWatch 警报。 - 客户管理的 KMS 密钥，S3 Block Public Access，仅限 TLS 的策略， 版本控制，生命周期控制，访问日志记录，限定范围的检测器权限， 以及 Athena 扫描限制。 - Terraform 验证，TFLint，Flake8，单元测试，tfsec，Checkov，Dependabot， 以及 pre-commit hooks。 ## 检测边界 检测器会在配置的窗口内，识别超过静态阈值的基于流量的外部出站流量，针对每个 `(account, instance, source IP)` 进行检测。它是一个 透明的第一阶段分析，不能证明存在恶意意图。NAT gateway、 代理、共享接口、批准的批量导出，以及延迟或 `SKIPDATA` 记录会影响归因和完整性。 有关假设和残余风险，请参阅[威胁模型](docs/threat-model.md)。 ## 仓库布局 ``` . ├── athena/queries/ # Parameterized investigation queries ├── deployments/spoke/ # Separate spoke account/Region root ├── docs/ # Architecture, threat model, runbook, demo ├── examples/ │ ├── central/ # Central root variables │ └── spoke/ # One spoke deployment variables ├── lambda/ │ ├── detector.py │ └── tests/ ├── modules/ │ ├── central-logging/ # S3, KMS, Glue table, Athena, Lambda IAM │ ├── detection-engine/ # Lambda, SNS, state, DLQ, alarms │ └── spoke-account/ # VPC Flow Logs only ├── main.tf # Central account root └── versions.tf ``` ## 前置条件 - Terraform `>= 1.7, < 2.0` - AWS CLI v2 以及临时凭证 - 用于本地测试的 Python 3.12 - 唯一的中心日志桶名称 - 允许管理项目资源的中心主体 - 每个分支账户中一个可担（assumable）的部署角色，具有 描述 VPC 以及创建、更新、标记和删除 VPC Flow Logs 的权限 - 独立于本项目配置的远程 state 桶 本仓库不创建 Terraform backend 或跨账户部署 角色。这些引导资源通常具有不同的所有者和生命周期。 ## 部署 ### 1. 中心账户 ``` cp examples/central/terraform.tfvars.example terraform.tfvars # 编辑 terraform.tfvars。 # 推荐：在私有部署 repo 中复制、编辑并提交 backend.tf。 cp backend.tf.example backend.tf export AWS_PROFILE=security-logging terraform init terraform plan -out=central.tfplan terraform apply central.tfplan terraform output -raw central_log_bucket_arn ``` `log_sources` 既是允许列表也是 schema 输入。在创建其 Flow Logs 之前，请包含每个分支 账户/Region。更改会更新 S3 传输和 投影的分区值。 默认情况下 Object Lock 处于禁用状态。启用它是一个不可逆的桶 属性；COMPLIANCE 保留甚至可以阻止账户所有者删除 对象。请先测试治理、恢复和成本影响。 如果设置了 `alert_email`，请在测试前确认 SNS 订阅电子邮件。 ### 2. 某个分支账户和 Region ``` cd deployments/spoke cp ../../examples/spoke/terraform.tfvars.example terraform.tfvars # 编辑 account、Region、role ARN、VPC ID 和 central bucket ARN。 # 为此 account 和 Region 使用唯一的 backend key。 cp backend.tf.example backend.tf export AWS_PROFILE=organization-deployer terraform init terraform plan -out=spoke.tfplan terraform apply spoke.tfplan ``` 对每个账户/Region 使用不同的 backend 密钥重复此操作。不要使用 CLI 工作区或 `-target` 来模拟账户边界。Provider 会担任 `deployment_role_arn` 并拒绝在其他账户中操作。 向 S3 传输 Flow Logs 是尽力而为的，通常会延迟几分钟。 默认的 15 分钟查询延迟可避免扫描最新的不完整周期。 ## 本地验证 ``` terraform fmt -check -recursive terraform init -backend=false terraform validate terraform test terraform -chdir=deployments/spoke init -backend=false terraform -chdir=deployments/spoke validate terraform -chdir=deployments/spoke test tflint --init tflint --recursive python3 -m venv .venv .venv/bin/python -m pip install -r requirements-dev.txt .venv/bin/python -m pytest .venv/bin/python -m flake8 lambda ``` CI 会运行这些检查以及 tfsec 和 Checkov，且无需 AWS 凭证。两个根目录的 Provider 锁文件均已提交。 ## 检测器行为 对于时间 `T` 的 EventBridge 事件： ``` window_end = T - data_delay_minutes window_start = window_end - detection_window_minutes ``` SQL 枚举了触及的每个小时分区，并过滤记录的 `"start"`/`"end"` 时间戳。它会保留 `ACCEPT`、`egress`、`OK` 记录；首选 数据包地址；移除私有、环回、链路本地、运营商级 NAT 和 多播目标以及操作员排除项；并在 汇总每个源的所有目标后应用阈值。 EventBridge 重试会保留事件时间戳。只有在查询和警报成功后，窗口的哈希值才会 存储在 DynamoDB 中，因此会跳过已完成的重试。如果在 SNS 接受消息后但在写入 DynamoDB 之前发生崩溃，仍可能 导致警报重复；消费者应根据窗口进行去重。 ## 运维与调查 - [架构](docs/architecture.md) - [安全控制](docs/security-controls.md) - [威胁模型](docs/threat-model.md) - [运维手册](docs/runbook.md) - [演示与证据指南](docs/demo.md) - [成本模型](docs/cost-model.md) - [升级说明](docs/migration-v2.md) - [GitHub 仓库设置](docs/repository-settings.md) - [Athena 查询模板](athena/queries/) 检测器从不会更改网络策略或隔离工作负载。 ## 成本与保留 最大的成本驱动因素通常是已发布日志的传输、保留的 S3 数据、 Athena 扫描的字节数和 KMS 请求。流量和 Region 的影响通常大于 资源数量。请将[成本模型](docs/cost-model.md)与当前的 [VPC Flow Logs 定价](https://aws.amazon.com/cloudwatch/pricing/)、 [S3 定价](https://aws.amazon.com/s3/pricing/) 和 [Athena 定价](https://aws.amazon.com/athena/pricing/) 结合使用； 不要依赖静态的每月估算。 在销毁中心存储之前，请先销毁分支 Flow Logs。中心桶使用 `force_destroy = false`。在保留期允许之前，无法移除 Object-locked 对象。 ## 项目状态 此参考实现实现了确定性阈值检测。组织 事件驱动的接入、行为基线、SIEM 订阅者和受控的 集成测试属于未来的扩展，而非当前的功能。 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、[SECURITY.md](SECURITY.md) 和 [MIT 许可证](LICENSE)。维护者： [Emir Ozturk](https://github.com/iamemirozturk)。

标签：AWS, C语言, DPI, ECS, Terraform, VPC流日志, 异常检测, 网络安全, 逆向工具, 隐私保护