Carlixgonzam/TerraScan

# TerraScan：Terraform 安全缺陷检测器 **TerraScan** 是一款使用 **Rascal 元编程语言** 和 **Kotlin** 桌面桥接程序构建的静态分析工具。它能够识别 **Terraform (HCL)** 文件中的安全缺陷和基础设施配置错误，从而为云部署启用左移安全策略。 ## 概述 现代基础设施即代码 经常面临配置漂移和安全疏忽的问题。TerraScan 利用 Rascal 的具体语法定义将 HCL 文件解析为类型化 AST，运行多检查分析流水线，并报告包含确切源位置的结果。Kotlin 包装器提供了一个桌面 GUI，具备文件选择、颜色编码的结果表和风险评分功能。 ## 核心功能 * **HCL 子集语法** (`lang::terraform::Syntax`)：解析 `resource` 块、嵌套块（`ingress`、`server_side_encryption_configuration`）、包含转义序列的字符串、整数、布尔值和列表。 * **安全缺陷检测** (`check::SecurityAnalyzer`)： * **无限制入口**：标记对 `0.0.0.0/0` 开放的 SSH (22) 和 MySQL (3306) 端口。 * **缺少加密**：检测没有 `server_side_encryption_configuration` 或 `enabled = false` 的 S3 存储桶。 * **IAM 通配符 (Wildcard IAM)**：捕捉 IAM 策略 JSON 字符串中的 `"Action": "*"` 或 `"Resource": "*"`。 * **多格式报告** (`check::Reporter`)：用于工具集成的 JSON 导出和用于学术论文的 LaTeX `longtable` 导出。 * **技术债务评分**：Critical = 10 分，Warning = 5 分，Info = 1 分。 * **Kotlin 桌面 GUI**：基于 Swing 的界面，包含 `JFileChooser`、带有颜色编码严重性行的 `JTable`、风险评分徽章以及“扫描另一个文件”的工作流。 * **错误处理**：针对 `.tf` 文件中的解析错误、文件缺失和 Rascal 进程故障进行优雅报告。 ## 系统架构 该框架通过分层流水线运行： 1. **解析器** (`lang::terraform::Syntax`)：定义 Terraform HCL 子集的具体语法定义，并将 `.tf` 源代码转换为类型化解析树。 2. **分析器** (`check::SecurityAnalyzer`)：使用 Rascal 的 `visit` 和具体语法模式匹配遍历解析树。运行三个检测器（`findUnrestrictedIngress`、`checkS3Encryption`、`checkIAMWildcards`）并通过 `analyze` 汇总结果。 3. **报告器** (`check::Reporter`)：将 `SecurityFinding` 列表格式化为 JSON 或 LaTeX。包含 `escapeJson` 和 `escapeLatex` 净化器。 4. **CLI 桥接** (`TerraScanCLI`)：接受文件路径，运行完整流水线，并输出结构化 JSON，其中包含供 Kotlin 进程使用的标记。 5. **Kotlin GUI** (`TerraScanApp.kt`)：通过 `ProcessBuilder` 调用 Rascal shell，解析 JSON 输出，并在带有 `JTable` 的 Swing `JFrame` 中渲染结果。 ## 仓库结构 ``` src/ ├── TerraScanCLI.rsc # CLI entry point for Kotlin bridge ├── lang/terraform/ │ └── Syntax.rsc # HCL concrete syntax grammar ├── check/ │ ├── SecurityAnalyzer.rsc # Detection logic and risk scoring │ └── Reporter.rsc # JSON and LaTeX report generation └── demo/ └── SecurityTest.rsc # Interactive test with sample resources kotlin/ └── TerraScanApp.kt # Kotlin desktop bridge and Swing GUI examples/ ├── secure_baseline.tf # Clean configuration (0 findings) ├── open_ports.tf # SSH + MySQL open to 0.0.0.0/0 ├── s3_encryption.tf # Missing and disabled encryption ├── iam_wildcards.tf # Wildcard Action/Resource policies └── full_stack_vulnerable.tf # Multi-tier stack with all smell types META-INF/ └── RASCAL.MF # Rascal project manifest ``` ## 前置条件 * **JDK 11+** * **Rascal Shell** (`rascal-shell-stable.jar`) — 从 [rascal-mpl.org](https://www.rascal-mpl.org/docs/GettingStarted/DownloadAndInstallation) 下载并放置在项目根目录下。 * **Kotlin 编译器** (`kotlinc`) — 通过 `brew install kotlin` 安装。 ## 用法 ### Rascal REPL (交互式) ``` java -jar rascal-shell-stable.jar rascal> import demo::SecurityTest; rascal> main(); ``` ### Rascal CLI (单文件) ``` cd src java -Xmx1G -Xss32m -jar ../rascal-shell-stable.jar TerraScanCLI.rsc /path/to/file.tf ``` ### Kotlin GUI ``` # 编译 kotlinc kotlin/TerraScanApp.kt -include-runtime -d TerraScanApp.jar # 使用文件选择对话框运行 java -jar TerraScanApp.jar # 使用特定文件运行 java -jar TerraScanApp.jar examples/full_stack_vulnerable.tf ``` ## 示例输出 ``` Analyzing: full_stack_vulnerable.tf +----------+------------------------------+-----------------------------------------------------------+------+ | Severity | Resource | Description | Line | +----------+------------------------------+-----------------------------------------------------------+------+ | Critical | aws_security_group.jump_box | Sensitive ingress port 22 is open to 0.0.0.0/0 | 2 | | Critical | aws_security_group.rds_mysql | Sensitive ingress port 3306 is open to 0.0.0.0/0 | 20 | | Warning | aws_s3_bucket.app_data | S3 bucket is missing server-side encryption configuration | 35 | | Warning | aws_s3_bucket.backups | S3 bucket is missing server-side encryption configuration | 39 | | Critical | aws_iam_policy.ci_pipeline | IAM policy contains wildcard Action or Resource | 44 | +----------+------------------------------+-----------------------------------------------------------+------+ Total: 5 finding(s) [Critical: 3, Warning: 2] Risk Score: 40 ``` ## 测试示例 | 文件 | 预期发现 | 风险评分 | |---|---|---| | `secure_baseline.tf` | 0 | 0 | | `open_ports.tf` | 2 Critical | 20 | | `s3_encryption.tf` | 3 Warning | 15 | | `iam_wildcards.tf` | 2 Critical | 20 | | `full_stack_vulnerable.tf` | 3 Critical + 2 Warning | 40 |

标签：CISA项目, DevSecOps, EC2, ECS, GUI, HCL, IaC, IAM策略分析, Java Swing, JS文件枚举, Kotlin, Rascal, S3加密检测, Shift-Left, SSH暴露检测, Terraform, URL发现, 上游代理, 元编程, 安全检测, 安全漏洞扫描, 桌面应用, 网络管理, 误配置检测, 错误基检测, 静态代码分析