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:

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.
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`

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().

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.

6.6 KiB خام اللوم التاريخ