feat: enhance execution metadata handling and improve reporting pipeline

Author: Wellington Gonzalez

.github/workflows/terraform-aws-security-analysis.yml

@@ -70,16 +70,24 @@ jobs:
 
       - run: mkdir -p reports_output
 
+      - name: Prepare execution metadata
+        id: metadata
+        run: |
+          echo "BRANCH_NAME=${GITHUB_REF_NAME}" >> $GITHUB_ENV
+          echo "RUN_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> $GITHUB_ENV
+
       - name: Run analyzer (Docker)
         env:
           GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
         run: |
           docker run --rm \
             -e GEMINI_API_KEY="$GEMINI_API_KEY" \
+            -e BRANCH_NAME="$BRANCH_NAME" \
+            -e RUN_TIMESTAMP="$RUN_TIMESTAMP" \
             -v "$GITHUB_WORKSPACE:/repo" \
             -v "$GITHUB_WORKSPACE/reports_output:/app/reports_output" \
             -w /repo \
-            wellingtoong/cloud-security-analyzer:1.0.0 \
+            wellingtoong/cloud-security-analyzer:1.0.1 \
             artifacts_in/plan.json
 
       - name: Upload HTML report artifact

Dockerfile

@@ -30,9 +30,4 @@ RUN mkdir -p reports_output
 
 # Define o comando padrão para executar a aplicação
 # O usuário deve passar o caminho do arquivo de plano como argumento ao rodar o container
-ENTRYPOINT ["python", "src/main.py"]
-
-# Exemplo de uso:
-# export GEMINI_API_KEY=xxxxx
-# docker build -t terraform-security-analyzer:local .
-# docker run --rm -e GEMINI_API_KEY -v "$(pwd):/repo" -w /repo terraform-security-analyzer:local terraform/examples/vpc-network/artifacts/tfplan.json
+ENTRYPOINT ["python", "src/main.py"]

README.md

@@ -1 +1,332 @@
-# cloud-security-analyzer
+# 🛡️ Cloud Security Analyzer
+
+[![CI](https://github.com/wellingtoong/cloud-security-analyzer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/wellingtoong/cloud-security-analyzer/actions/workflows/ci.yml)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![Docker Pulls](https://img.shields.io/docker/pulls/wellingtoong/cloud-security-analyzer)](https://hub.docker.com/r/wellingtoong/cloud-security-analyzer)
+
+
+## 🔎 Code Quality
+
+[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=ncloc&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=duplicated_lines_density&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=sqale_rating&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=security_rating&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=reliability_rating&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=vulnerabilities&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=code_smells&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=wellingtoong_cloud-security-analyzer&metric=bugs&token=f7ddc671d11a54faa1805b801607b69466f276a4)](https://sonarcloud.io/summary/new_code?id=wellingtoong_cloud-security-analyzer)
+
+
+## 🌟 Community
+
+![Open Source Love](https://img.shields.io/badge/Open%20Source-%E2%9D%A4-red)
+![GitHub stars](https://img.shields.io/github/stars/wellingtoong/cloud-security-analyzer?style=social)
+![GitHub forks](https://img.shields.io/github/forks/wellingtoong/cloud-security-analyzer?style=social)
+
+---
+
+A powerful, AI-driven tool for analyzing Terraform Plan JSON files to identify security vulnerabilities and generate actionable recommendations. Built for DevSecOps workflows, it leverages Google Gemini AI to provide intelligent insights into cloud infrastructure configurations, ensuring compliance with best practices like CIS Benchmarks.
+
+
+## 📘 Overview
+
+Infrastructure as Code (IaC) tools like Terraform enable rapid deployment of cloud resources, but misconfigurations can introduce critical security risks.
+
+Cloud Security Analyzer addresses this by applying AI-driven contextual analysis to Terraform Plan (JSON) files before deployment, allowing teams to detect and remediate risks proactively.
+
+It provides:
+
+- 🔍 **Static Analysis**: Scanning Terraform plans for vulnerabilities without executing changes.
+- 🤖 **AI-Powered Insights**: Detecting nuanced security issues beyond traditional rule-based checks.
+- 📊 **Comprehensive Reporting**: Generating structured JSON outputs and executive-ready HTML reports with severity scores, risk assessments, and remediation guidance.
+- 🔄 **CI/CD Integration**: Seamlessly integrating into pipelines for automated infrastructure security reviews.
+
+This tool is particularly valuable for teams deploying to AWS (with roadmap support for Azure and GCP), helping prevent breaches caused by exposed databases, overly permissive security groups, unencrypted storage, and other misconfigurations.
+
+
+## 🎯 Why Cloud Security Analyzer?
+
+- 🛡️ Prevent security misconfigurations before deployment  
+- 🤖 AI-enhanced contextual risk detection  
+- 📊 Executive-ready HTML and JSON reports  
+- 🔄 CI/CD native integration  
+- ☁️ Built for AWS (Azure & GCP roadmap)  
+- 🧱 Designed for scalable DevSecOps environments  
+
+
+## 📘 Overview
+
+Infrastructure as Code (IaC) tools like Terraform enable rapid deployment of cloud resources, but misconfigurations can introduce critical security risks. Cloud Security Analyzer addresses this by:
+
+- 🔍 **Static Analysis**: Scanning Terraform plans for vulnerabilities without executing changes.
+- 🤖 **AI-Powered Insights**: Using advanced AI to detect nuanced issues beyond rule-based checks.
+- 📊 **Comprehensive Reporting**: Generating structured JSON outputs and visually appealing HTML reports with severity scores, risk assessments, and remediation steps.
+- 🔄 **CI/CD Integration**: Seamlessly integrating into pipelines for automated security reviews.
+
+This tool is particularly valuable for teams deploying to AWS (with roadmap support for Azure and GCP), helping prevent breaches from exposed databases, overly permissive security groups, unencrypted storage, and more.
+
+## ⚙️ How It Works
+
+1. 📥 **Input**: Provide a Terraform Plan JSON file (generated via `terraform plan -out=tfplan.binary && terraform show -json tfplan.binary > plan.json`).
+2. 🧠 **Analysis**: The tool sends the plan to Google Gemini AI, guided by a specialized prompt template, to identify vulnerabilities, assign severities (CRITICAL, HIGH, MEDIUM, LOW), and suggest fixes.
+3. 📤 **Output**:
+   - 🧾 **JSON Report**: Structured data for programmatic consumption or further processing.
+   - 🖥️ **HTML Report**: Interactive, Tailwind CSS-styled dashboard with executive summaries, vulnerability cards, code recommendations, and references to AWS documentation.
+4. 🏷️ **Metadata Enrichment**: Automatically captures execution context like branch, timestamp, Terraform version, and environment for traceability.
+
+The process is fast, typically completing in seconds, and supports both local execution and containerized runs.
+
+## 🏗️ Architecture
+
+The project follows a modular Python architecture for maintainability and extensibility:
+
+- 🧠 **`core/`**: Core logic, including the `TerraformAnalyzer` class that interfaces with Google Gemini AI for analysis.
+- 📂 **`data/`**: Data handling modules for loading Terraform plans and prompts.
+- 📝 **`reports/`**: Report generation, featuring Jinja2 templates for HTML rendering and utility functions for severity classification and formatting.
+- 🖥️ **`cli/`**: Command-line interface for user interaction, path resolution, and orchestration.
+
+Key dependencies include `google-generativeai` for AI integration, `jinja2` for templating, and standard libraries for JSON handling. The design emphasizes separation of concerns, making it easy to extend for multi-cloud support or alternative AI models.
+
+## 📦 Installation
+
+### 📋 Prerequisites
+
+- Python 3.12+
+- Google Gemini API Key (obtain from [Google AI Studio](https://makersuite.google.com/app/apikey))
+- Terraform (for generating plan files)
+
+### 🖥️ Local Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/wellingtoong/cloud-security-analyzer.git
+   cd cloud-security-analyzer
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install -r src/requirements.txt
+   ```
+
+3. Set environment variables:
+   ```bash
+   export GEMINI_API_KEY="your-api-key-here"
+   export GEMINI_MODEL="gemini-2.0-flash"  # Optional, defaults to this model
+   export BRANCH_NAME="develop"
+   export RUN_TIMESTAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+   ```
+
+4. Generate a Terraform plan (example for AWS):
+   ```bash
+   cd terraform/examples/aws/vpc-network/env/dev
+   terraform init
+   terraform plan -out=tfplan.binary
+   terraform show -json tfplan.binary > ../../plans/tfplan.json
+   ```
+
+## 🚀 Usage
+
+### 🖥️ Local Execution
+
+Run the analyzer on a plan file:
+```bash
+python src/main.py terraform/examples/aws/vpc-network/artifacts/tfplan.json 
+```
+
+Outputs will be generated in `reports_output/`:
+- `terraform_security_report.json`
+- `terraform_security_report.html`
+
+### 🐳 Docker Execution
+
+1. Build the image:
+   ```bash
+   docker build -t cloud-security-analyzer .
+   ```
+
+2. Run the container:
+   ```bash
+   docker run --rm \
+     -e GEMINI_API_KEY="your-api-key-here" \
+     -e BRANCH_NAME \
+     -e RUN_TIMESTAMP \
+     -e ENVIRONMENT="dev" \
+     -v "$(pwd):/app" \
+     terraform-security-analyzer \
+     terraform/examples/aws/vpc-network/artifacts/tfplan.json
+   ```
+
+### 🔄 CI/CD Pipeline (GitHub Actions)
+
+Integrate into your workflow for automated analysis. Example `.github/workflows/security-analysis.yml`:
+
+```yaml
+name: Security Analysis
+
+on:
+  pull_request:
+    paths:
+      - 'terraform/**'
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.6.0"
+      - name: Generate Plan
+        run: |
+          cd terraform/examples/your-example/env/dev
+          terraform init
+          terraform plan -out=tfplan.binary
+          terraform show -json tfplan.binary > ../../../../plans/tfplan.json
+      - name: Run Security Analyzer
+        run: |
+          docker build -t analyzer .
+          docker run --rm \
+            -e GEMINI_API_KEY="${{ secrets.GEMINI_API_KEY }}" \
+            -v "$(pwd):/app" \
+            analyzer \
+            plans/tfplan.json
+      - name: Upload Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: security-report
+          path: reports_output/
+```
+
+This pipeline generates plans, runs analysis, and publishes HTML reports as artifacts for review.
+
+## 🗂️ Project Structure
+
+```
+cloud-security-analyzer/
+├── .github/
+│   └── workflows/          # CI/CD pipelines
+├── src/
+│   ├── main.py             # Entry point
+│   ├── requirements.txt    # Python dependencies
+│   ├── terraform_analyzer/
+│   │   ├── cli.py          # CLI logic
+│   │   ├── config.py       # Configuration management
+│   │   ├── core/
+│   │   │   ├── execution_metadata.py # Metadata utility
+│   │   │   └── analyzer.py # AI analysis engine
+│   │   ├── data/
+│   │   │   ├── plan_loader.py    # Terraform plan loading
+│   │   │   └── prompt_loader.py  # Prompt template handling
+│   │   └── reports/
+│   │       ├── html_renderer.py  # HTML generation
+│   │       └── utils.py          # Report utilities
+├── reports/
+│   ├── templates/          # Jinja2 templates
+│   └── examples/           # Sample reports
+├── terraform/
+│   └── examples/           # Terraform configurations for testing
+├── prompts/                # AI prompt templates
+├── tests/                  # Unit tests
+├── Dockerfile              # Container definition
+└── README.md               # This file
+```
+
+## 🚀 Roadmap
+
+> The items below represent potential roadmap initiatives and planned evolutions of the platform.  
+> They reflect strategic directions and may be progressively implemented in future releases.
+
+### 🔐 Security & Compliance
+- Support for CIS, NIST, ISO 27001 and SOC2 mappings
+- Automatic control mapping by compliance framework
+- Aggregated security score per environment
+- SARIF export for GitHub Advanced Security
+- Integration with AWS Security Hub
+
+### ☁️ Multi-Cloud Support
+- Full Azure and GCP support
+- Automatic provider detection from Terraform plan
+- Cloud-specific AI prompt templates
+- Cross-cloud severity normalization
+
+### 🤖 AI & Intelligence
+- Smart caching for repeated analyses
+- Incremental analysis (plan diff only)
+- False-positive classification layer
+- Explainability: "why is this a risk?"
+- Full Terraform remediation snippet generation
+
+### 🔎 DevSecOps Integrations
+- Official GitHub Action release
+- Official Docker image release
+- GitLab CI integration
+- Azure DevOps integration
+- Slack / Microsoft Teams webhook notifications
+
+### 📊 Visualization & UX
+- Web dashboard (SaaS mode)
+- Historical analysis per branch
+- Baseline vs current comparison
+- Security maturity metrics
+- Dynamic security score badge
+
+### ⚡ Performance & Scalability
+- Parallel processing for large plans
+- Support for very large plans (>50MB)
+- JSON chunking for AI token optimization
+- Streaming-based AI analysis
+
+### 🧱 Enterprise Features
+- Multi-tenant architecture
+- RBAC for report access
+- Structured logs for SIEM ingestion
+- Public REST API for integrations
+- Custom policy-as-code validation
+
+## ⚠️ Limitations
+
+> The limitations listed below represent current technical and architectural constraints.  
+> Some of these constraints may be addressed and improved in future releases as the platform evolves.
+
+### 🤖 AI Dependency
+- Requires a valid Google Gemini API key
+- Results are probabilistic (not deterministic)
+- Possible false positives and false negatives
+- Requires internet connectivity for AI analysis
+
+### ☁️ Cloud Provider Constraints
+- Azure and GCP require valid credentials for `terraform plan`
+- Fully offline mode currently supported only for AWS (via LocalStack)
+- Limited support for newly released provider resources
+
+### 📦 Technical Scope
+- Focused exclusively on Terraform
+- Does not support CloudFormation, Pulumi or ARM templates
+- No runtime (dynamic) security analysis
+- Does not replace traditional SAST/DAST scanners
+
+### 📊 Scalability Constraints
+- Very large plans may increase analysis latency
+- AI token usage may generate cost depending on plan size
+- No built-in rate limiting or quota management yet
+
+### 🔐 Governance Constraints
+- Does not automatically block deployments (advisory analysis only)
+- No native SIEM integration yet
+- No persistent historical storage outside generated reports
+
+## 🤝 Contributing
+
+We welcome contributions! Please follow these steps:
+
+1. Fork the repository and create a feature branch.
+2. Ensure code adheres to PEP 8 and includes tests.
+3. Run tests: `pytest tests/`
+4. Submit a pull request with a clear description of changes.
+
+For issues or feature requests, use the [GitHub Issues](https://github.com/wellingtoong/cloud-security-analyzer/issues) page.
+
+## 📄 License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

prompts/terraform_security_analysis.prompt

@@ -146,7 +146,7 @@ Formato exato de saída (siga esta estrutura e nomes de campos):
 
 Contexto fixo do relatório:
 - tool.name = "Cloud Security Analyzer"
-- tool.version = "v2.4.0"
+- tool.version = "v1.0.1"
 - provider = "AWS"
 - reportTitle = "Análise de Terraform Plan - Revisão de Segurança"
 - environment = "MVP"

reports/examples/base.empty.html

@@ -243,7 +243,7 @@ <h3 class="font-semibold">Próximos Passos Recomendados</h3>
           <div class="text-center sm:text-right">
             <p class="text-xs text-slate-500 mb-1">Análise gerada por</p>
             <p class="font-semibold text-slate-900">Cloud Security Analyzer</p>
-            <p class="text-xs text-slate-500 mt-1">v2.4.0 • CIS Benchmark AWS 2.0</p>
+            <p class="text-xs text-slate-500 mt-1">v1.0.1 • CIS Benchmark AWS 2.0</p>
           </div>
         </div>
       </section>