feat: implement Ghaymah CLI Pre-Deployment Scanner and add associated audit and integration documentation

PreDeployScanner/docs/Ghaymah_CLI_Scanner_Integration_Guide.md

@@ -0,0 +1,114 @@
+# Ghaymah CLI: Pre-Deployment Security Scanner Integration Guide
+
+## 1. Executive Overview
+
+The **Ghaymah Pre-Deployment Security Scanner** introduces a critical "Shift-Left" security control directly into the Ghaymah CLI. By executing locally on the developer's machine immediately upon invoking the `deploy` command, this scanner identifies and mitigates severe security misconfigurations *before* any artifact is packaged or transmitted to the cloud backend.
+
+This proactive approach addresses two primary threat vectors:
+1.  **Sensitive Data Leakage (Dockerfile Anti-Patterns):** Prevents the accidental inclusion of `.env` files, `.git` histories, and hardcoded secrets into Docker image layers caused by wildcard copy instructions (e.g., `COPY . /`) combined with missing or incomplete `.dockerignore` files.
+2.  **Configuration Poisoning & Denial of Service (DoS):** Inspects `.gy.json` and `.env` files for malformed data, shell command substitutions (`$(...)`), unclosed quotes, and control characters. These anomalies can cause backend CI/CD parsers to crash, hang indefinitely, or execute arbitrary commands, leading to infrastructure DoS or RCE. 
+
+By blocking these deployments on the client side, we significantly reduce the noise, compute waste, and security risks on the backend Kubernetes clusters, while providing immediate, actionable feedback to the developer.
+
+---
+
+## 2. Code Walkthrough & Parsing Logic
+
+The scanner (`gy-scanner.go`) is a standalone Go script designed for speed and reliability, with zero external dependencies beyond the standard library.
+
+### 2.1 Dockerfile Parsing Phase
+The script reads the `Dockerfile` line by line, applying a series of compiled regular expressions to detect anti-patterns:
+*   **Wildcard Copying:** `(?i)^\s*(COPY|ADD)\s+(\.\s|\.\/\s|\.\s+\/|\.\s+\.\s|\.\/\s+\.\/?)` detects instructions that pull the entire context into the image.
+*   **Root Execution:** Tracks `USER` directives. If no non-root user is declared before the end of the file, it raises a warning.
+*   **Secret Leakage:** `(?i)^\s*(ARG|ENV)\s+\S*(PASSWORD|SECRET|TOKEN|API_KEY|PRIVATE_KEY|AWS_SECRET|DB_PASS)\S*\s*=\s*\S+` detects hardcoded secrets.
+*   **Insecure Operations:** Flags `chmod 777` and `curl ... | bash` patterns.
+*   **Build Reliability:** Ensures a valid `FROM` instruction exists and verifies that `EXPOSE` port values are valid integers within the TCP range (1-65535).
+
+### 2.2 Environment & Configuration Parsing Phase
+The scanner inspects `.gy.json` and standard environment files (`.env`, `.env.local`, etc.):
+*   **JSON Validation:** Ensures `.gy.json` is syntactically valid and validates fields like `port` and `app` (checking for injection payloads).
+*   **Key Validation:** Ensures `.env` keys match `^[A-Za-z_][A-Za-z0-9_]*$`.
+*   **Shell Substitution & Operators:** Scans values for `$(...)`, backticks, `;`, `&&`, and `||`. These indicate potential shell injection attempts that could compromise the backend evaluator.
+*   **Unclosed Quotes:** Counts occurrences of `'` and `"`. An odd number triggers a warning, as unclosed quotes frequently cause backend parsers to hang indefinitely (DoS).
+*   **Leakage Prevention:** Checks if a `.dockerignore` file exists and explicitly excludes `.env` files. If wildcard copying is used and `.env` is not ignored, the scan fails with a `CRITICAL` severity.
+
+---
+
+## 3. Integration Guide: Hooking into the CLI
+
+To integrate the scanner natively into the Ghaymah CLI `gy-linux-amd64` binary, the core development team must hook it into the deployment execution flow **before** the tar.gz artifact is constructed.
+
+### Recommended Integration Point: `cmd/deploy.go`
+
+```mermaid
+flowchart TD
+    A[User executes 'gy deploy'] --> B(Resolve Deploy Path)
+    B --> C(Detect Project Type)
+    
+    %% Scanner Hook
+    C --> D{Run gy-scanner}
+    D -- Critical Issues --> E[Block Deployment & Show Report]
+    D -- Warnings / Pass --> F(Proceed with warnings)
+    
+    F --> G(buildpack.createArtifact)
+    G --> H(GraphQL Mutation to Backend)
+    
+    style D fill:#f9f,stroke:#333,stroke-width:2px,color:#000
+    style E fill:#ffcccc,stroke:#f00,stroke-width:2px,color:#000
+    style G fill:#ccf,stroke:#333,stroke-width:2px,color:#000
+```
+
+In the deployment command handler (e.g., inside the `RunE` function of the `deploy` command), execute the scanning logic immediately after project type detection but before calling `buildpack.createArtifact()`.
+
+```go
+import (
+	"fmt"
+	"os"
+	// Import the scanner package (assuming it's moved to pkg/scanner)
+	"gitlab.com/ghaymahdevqateam/ghaymahcli/ghaymah-cli/pkg/scanner" 
+)
+
+func runDeploy(cmd *cobra.Command, args []string) error {
+	// ... (Step 3: Resolve Deploy Path & Step 4: Detect Project Type)
+
+	fmt.Println("🔍 Running pre-deployment security scan...")
+	
+	// Initialize and run the scanner on the target directory
+	deployDir := resolveDeployDir(args)
+	secScanner := scanner.NewScanner(deployDir)
+	report := secScanner.Run()
+
+	// Evaluate the report summary
+	if report.Summary.Critical > 0 {
+		// Output the report to the user
+		scanner.PrintHumanReport(report)
+		return fmt.Errorf("deployment blocked: %d critical security issues found. Please fix them before deploying", report.Summary.Critical)
+	}
+
+	if report.Summary.Warning > 0 {
+		// Output warnings but allow deployment to continue
+		scanner.PrintHumanReport(report)
+		fmt.Println("⚠️ Proceeding with deployment despite warnings...")
+	} else {
+		fmt.Println("✅ Security scan passed.")
+	}
+
+	// ... (Proceed to Step 8: buildpack.createArtifact() and Step 9: GraphQL Mutation)
+}
+```
+
+By placing the hook here, you guarantee that maliciously malformed `.env` files or insecure Dockerfiles never reach the packaging phase, saving bandwidth and backend processing time.
+
+---
+
+## 4. 🚨 MANDATORY SECURITY WARNING 🚨
+
+> [!CAUTION]
+> **Client-Side Validation is Not a Security Boundary**
+>
+> While this pre-deployment scanner significantly improves the developer experience and prevents accidental Denial of Service (DoS) caused by malformed configurations, **it relies entirely on client-side execution.**
+>
+> A malicious actor can easily bypass this scanner by using a modified CLI binary, manipulating the HTTP traffic via a proxy, or interacting directly with the GraphQL API (`insert_ghaymah_cloud_resources_one`).
+>
+> **The Backend Infrastructure Team MUST implement strict, redundant server-side validation.** 
+> Every environment variable, port number, and application name received by the backend API must be heavily sanitized and validated before being passed to Kubernetes or the build pipeline. Failure to do so will leave the platform vulnerable to direct API manipulation, leading to RCE and infrastructure compromise.