oguarni/terrasafe

### ✨ 亮点 - 🔐 **混合评分** — 60% 基于规则 + 40% ML 异常检测，实现全面覆盖 - ⚡ **亚秒级扫描** — 使用训练好的 Isolation Forest 模型，每个文件约 0.027s - 🌐 **REST API** — 生产级 FastAPI，支持 bcrypt 认证、速率限制和异步 I/O - 🛡️ **DevSecOps 流水线** — Bandit SAST、Safety 依赖检查、GitLeaks、Trivy 容器扫描 ## 📑 目录 - [功能特性](#-features) - [快速开始](#-quick-start) - [架构设计](#️-architecture) - [CLI 使用](#-cli-usage) - [REST API](#-rest-api) - [质量指标](#-quality-metrics) - [DevSecOps 流水线](#-devsecops-pipeline) - [Docker 部署](#-docker-deployment) - [监控与可观测性](#-monitoring--observability) - [技术栈](#-technology-stack) - [截图](#-screenshots) - [学术背景](#-academic-context) - [局限性与未来工作](#️-limitations--future-work) - [参考资料](#-references) - [许可证](#-license) ## 🚀 功能特性 ### 安全扫描器 - 针对 **6 类漏洞**的模式匹配：开放端口、硬编码机密、未加密存储、公开 S3 存储桶、IAM 配置错误以及权限过大的安全组 - 严重性分类：`CRITICAL` (严重) · `HIGH` (高危) · `MEDIUM` (中危) · `LOW` (低危) - 针对每项发现提供可操作的修复建议 ### 机器学习引擎 - **Isolation Forest** 异常检测（无监督 — 无需标记数据） - 5 维特征向量：开放端口、硬编码机密、公开访问、未加密存储、资源数量 - 通过 Joblib 实现模型持久化，支持自动重新训练 - 基于异常距离的置信度评分 ### REST API - FastAPI，提供 `/docs` 上的 OpenAPI/Swagger 文档 - Bcrypt 哈希 API 密钥认证 - 基于 Redis 的缓存和速率限制 - 具有可配置超时的异步文件处理 - `/metrics` 端点提供 Prometheus 指标 - 所有请求的相关性 ID 追踪 ### DevSecOps - 包含 5 阶段流水线的 GitHub Actions CI/CD - SAST (Bandit)、依赖扫描、机密检测 - Docker 镜像安全扫描 - 用于本地开发的 Pre-commit hooks - SBOM 生成 ## 🏁 快速开始 ### 前置条件 - Python 3.10+ - Git ### 安装 ``` # 克隆 repository git clone https://github.com/oguarni/terrasafe.git cd terrasafe # 安装所有内容（创建 venv，安装 deps） make install ``` ### 运行演示 ``` # 扫描所有三个测试配置 make demo # 或扫描特定文件 python -m terrasafe.cli test_files/vulnerable.tf python -m terrasafe.cli test_files/secure.tf python -m terrasafe.cli test_files/mixed.tf ``` ### 运行测试 ``` make test # All tests make coverage # With coverage report make lint # Code quality (Pylint + Flake8) make security-scan # Bandit SAST + Safety dependency check ``` ## 🏗️ 架构设计 TerraSafe 遵循 **整洁架构 (Clean Architecture)**，具有清晰的关注点分离： ``` terrasafe/ ├── domain/ # Business rules, severity levels, vulnerability models ├── application/ # Use cases — IntelligentSecurityScanner orchestrator ├── infrastructure/ # Adapters — HCL parser, ML model, database, API ├── config/ # Settings, logging configuration ├── cli.py # Command-line interface ├── api.py # FastAPI REST server └── metrics.py # Prometheus instrumentation ``` ### 扫描流水线 ``` graph TD A[Terraform .tf File] --> B[HCL2 Parser] B --> C[Feature Extraction Engine] C --> D[Rule-based Detection] C --> E[ML Feature Vectorization] D --> F[Pattern Matching
6 vulnerability categories] E --> G[Isolation Forest
Anomaly Detection] F --> H[Risk Score Aggregator
0.6 × Rules + 0.4 × ML] G --> H H --> I[Scan Report
Score · Vulnerabilities · Confidence] style C fill:#e1f5ff,stroke:#0288d1,stroke-width:2px,color:#01579b style H fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100 style I fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20 ``` ### 评分系统 | 权重 | 组件 | 方法 | |--------|-----------|--------| | **60%** | 基于规则 | 确定性模式匹配 — CRITICAL (30分), HIGH (20分), MEDIUM (10分) | | **40%** | ML 异常 | Isolation Forest 偏离安全基线的程度 | **分数范围：** `0–30` 安全 ✅ · `31–60` 建议审查 ⚠️ · `61–100` 需紧急处理 ❌ ## 💻 CLI 使用 ``` # 扫描 Terraform 文件 python -m terrasafe.cli # 通过 Makefile 扫描 make scan FILE=test_files/vulnerable.tf ``` ### 示例输出 — 存在漏洞的配置 ``` 🔐 TerraSafe - Intelligent Terraform Security Scanner 🤖 Using hybrid approach: Rules (60%) + ML Anomaly Detection (40%) ============================================================ 🔍 TERRAFORM SECURITY SCAN RESULTS ============================================================ 📁 File: test_files/vulnerable.tf ❌ HIGH RISK 📊 Final Risk Score: 81/100 ├─ Rule-based Score: 100/100 ├─ ML Anomaly Score: 54.7/100 └─ Confidence: LOW 🚨 Detected Vulnerabilities: [CRITICAL] Open security group - SSH port 22 exposed to internet 📍 Resource: web_sg 💡 Fix: Restrict SSH access to specific IP ranges [CRITICAL] Hardcoded password detected 📍 Resource: Database/Instance 💡 Fix: Use variables or secrets manager for sensitive data [HIGH] Unencrypted RDS instance 📍 Resource: main_db 💡 Fix: Enable storage_encrypted = true [HIGH] Unencrypted EBS volume 📍 Resource: data_volume 💡 Fix: Enable encrypted = true [HIGH] S3 bucket with public access enabled 📍 Resource: public_bucket 💡 Fix: Enable all public access blocks ``` ### 示例输出 — 安全的配置 ``` ✅ LOW RISK 📊 Final Risk Score: 18/100 ├─ Rule-based Score: 0/100 ├─ ML Anomaly Score: 46.0/100 └─ Confidence: LOW ✅ No security issues detected! ✓ All resources properly configured ✓ Encryption enabled where required ✓ Network access properly restricted ``` ## 🌐 REST API ### 启动 API 服务器 ``` # 本地开发 make api # 生产环境 (Docker) docker-compose up -d ``` ### 端点 | 方法 | 端点 | 认证 | 描述 | |--------|----------|------|-------------| | `GET` | `/health` | 无 | 健康检查（含数据库状态） | | `POST` | `/scan` | API Key | 扫描 Terraform 文件 | | `GET` | `/metrics` | 无 | Prometheus 指标 | | `GET` | `/docs` | 无 | OpenAPI/Swagger（仅限开发环境） | ### 通过 curl 扫描 ``` curl -X POST \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@terraform.tf" \ http://localhost:8000/scan ``` ### 通过 Python 扫描 ``` import requests response = requests.post( "http://localhost:8000/scan", headers={"X-API-Key": "YOUR_API_KEY"}, files={"file": open("terraform.tf", "rb")} ) print(response.json()) ``` ### 响应格式 ``` { "file": "vulnerable.tf", "score": 85, "rule_based_score": 90, "ml_score": 75.5, "confidence": "HIGH", "vulnerabilities": [ { "severity": "CRITICAL", "points": 20, "message": "Hardcoded AWS credentials detected", "resource": "aws_instance.web", "remediation": "Use AWS IAM roles or environment variables" } ], "summary": { "critical": 1, "high": 2, "medium": 0, "low": 0 }, "performance": { "scan_time_seconds": 0.234, "file_size_kb": 1.5, "from_cache": false } } ``` ## 📊 质量指标 | 类别 | 指标 | 结果 | |----------|--------|--------| | **测试** | 测试套件 | **272 项通过**, 1 项跳过 — 19.31s | | **测试** | 基准测试 (扫描) | 平均 ~27 ms | | **测试** | 基准测试 (解析器) | 平均 34.68 µs, 28,837 ops/s | | **代码质量** | Pylint 评分 | **9.24 / 10** | | **代码质量** | 代码库规模 | 3,098 行（应用代码） | | **安全性** | SAST (Bandit) | **0 个问题** — 0 High, 0 Medium, 0 Low | | **安全性** | 依赖 | 139 个包中 **0 个漏洞** | | **性能** | 扫描时间 | 每个 Terraform 文件约 **0.027s** | ## 🛡️ DevSecOps 流水线 包含 5 个阶段的 GitHub Actions 流水线： ``` graph LR A[Security Scan] --> B[Unit Tests] B --> C[Integration Scan] B --> D[Docker Build + Trivy] C --> E[Deploy Staging] D --> E style A fill:#ffebee,stroke:#c62828,color:#b71c1c style B fill:#e3f2fd,stroke:#1565c0,color:#0d47a1 style C fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20 style D fill:#fff3e0,stroke:#ef6c00,color:#e65100 style E fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c ``` | 阶段 | 工具 | 目的 | |-------|------|---------| | **SAST** | Bandit | Python 安全问题的静态代码分析 | | **依赖** | Safety | 对所有 pip 包进行已知漏洞检查 | | **机密** | GitLeaks | 检测硬编码的机密和凭证 | | **容器** | Trivy | Docker 镜像漏洞扫描 | | **覆盖率** | Codecov | 测试覆盖率跟踪与报告 | ### 本地安全扫描 ``` make security-scan # Run all security checks make security-deps # Dependency vulnerabilities only make security-sast # SAST only make setup-hooks # Install pre-commit hooks ``` ## 🐳 Docker 部署 ### 快速运行 ``` # 构建并扫描 docker build -t terrasafe:latest . docker run --rm -v /path/to/terraform:/scan:ro terrasafe:latest /scan/main.tf ``` ### 完整技术栈 ``` docker-compose up -d ``` | 服务 | 端口 | 目的 | |---------|------|---------| | **terrasafe-api** | 8000 | FastAPI 应用程序 | | **PostgreSQL** | 5432 | 持久化扫描存储 | | **Redis** | 6379 | 缓存与速率限制 | | **Prometheus** | 9090 | 指标收集 | | **Grafana** | 3000 | 仪表盘与可视化 | Docker 镜像以**非 root 用户**运行，建议使用 `--read-only` 文件系统和 `--security-opt=no-new-privileges`。 ## 📈 监控与可观测性 - **Prometheus** 每 10s 抓取一次 `/metrics` — 扫描速率、缓存命中数、延迟、错误率 - **Grafana** 仪表盘 (`TerraSafe Overview`) 包含预配置的面板： - 扫描速率与缓存命中率 - 按严重性和类别分布的漏洞 - P95/P99 扫描持续时间 - API 请求延迟与错误率 - 带有相关性 ID 的**结构化 JSON 日志**，用于请求追踪 - `/health` 端点的**健康检查**，包含数据库连接状态 ## 💻 技术栈 | 组件 | 技术 | 目的 | |-----------|------------|---------| | 语言 | Python 3.10+ | ML 生态系统，语法简洁 | | ML 框架 | scikit-learn (Isolation Forest) | 异常检测模型 | | 解析器 | python-hcl2 | 原生 Terraform HCL2 解析 | | API 框架 | FastAPI + Uvicorn | 支持 OpenAPI 文档的异步 REST API | | 数据库 | PostgreSQL + SQLAlchemy (异步) | 扫描历史持久化 | | 缓存 | Redis | LRU 缓存，速率限制 | | 认证 | bcrypt | API 密钥哈希 | | 监控 | Prometheus + Grafana | 指标与仪表盘 | | 容器 | Docker + Docker Compose | 多服务部署 | | CI/CD | GitHub Actions | DevSecOps 自动化 | | 数值计算 | NumPy | 特征向量运算 | | 模型持久化 | Joblib | 序列化 scikit-learn 模型 | ## 📸 截图

Vulnerability Detection

Secure Infrastructure Analysis

ML Model Training

## 🎓 学术背景 | | | |---|---| | **课程** | 毕业设计 I 和 II (Capstone Project I and II) | | **机构** | 巴西巴拉那联邦理工大学 | | **专业** | 软件工程学士，第 8 学期 | | **类型** | 技术报告 | ### 为什么选择 Isolation Forest？ - **无监督** — 不需要标记的攻击数据集 - **高效** — 在结构化配置数据上训练和推理速度快 - **对小数据友好** — 适用于合成的安全基线 - **可解释** — 特征重要性和异常分数提供透明度 ### 为什么不选择其他算法？ | 算法 | 未选择的原因 | |-----------|-------------------| | 神经网络 | 对结构化配置数据过于繁重；需要大量训练集 | | 遗传算法 | 适用于优化问题，而非异常检测 | | 决策树 | 过于僵化；检测新型异常模式的能力较差 | ### 创新点 1. **混合方法** — 结合确定性规则与概率 ML，实现深度防御 2. **自学习** — 随着分析更多配置，模型不断改进 3. **可解释 AI** — 特征向量和置信度提供完全透明度 4. **实时** — 亚秒级扫描性能，适合 CI/CD 集成 ## ⚠️ 局限性与未来工作 ### 当前局限性 - 训练数据基于合成的安全基线 - 不支持 Terraform 模块或远程状态 - 漏洞描述仅限英文 ### 路线图 - 用于复杂模式识别的深度学习模型 - 多云支持 - 自定义策略定义语言 - Terraform 模块和 Provider 分析 - 与云服务商安全 API 集成 ## 📚 参考资料 - Gartner (2024). *Cloud Security Failures Report* - IBM Security (2024). *Cost of a Data Breach Report* - HashiCorp. *Terraform Security Best Practices* - Liu, F. T., Ting, K. M., & Zhou, Z. H. (2008). *Isolation Forest* ## 📄 许可证 本项目采用 **CC BY-NC-SA 4.0** 许可。该许可证涵盖所有当前及历史提交。详情请参见 [LICENSE](LICENSE) 文件。

由 **Gabriel Felipe Guarnieri** 开发 — UTFPR 软件工程 [快速入门指南](QUICKSTART.md) · [API 文档](http://localhost:8000/docs) · [反馈问题](https://github.com/oguarni/terrasafe/issues)

标签：AI安全, Apex, AV绕过, Chat Copilot, CISA项目, DevSecOps, Docker, ECS, FastAPI, IaC安全, Isolation Forest, Python, REST API, SAST, Terraform, Terraform扫描器, Windows日志分析, 上游代理, 基礎設施即代碼, 存储加密, 安全助手, 安全防御评估, 开源安全工具, 异常检测, 搜索引擎查询, 无后门, 机器学习, 测试用例, 混合检测, 盲注攻击, 端口检测, 网络安全, 网络测绘, 自动修复建议, 自定义请求头, 请求拦截, 逆向工具, 逆向工程平台, 错误基检测, 隐私保护, 静态代码分析