Zero-Trust Explainer (ZTE)

Human-readable IAM diffs for Cloud Run - find risk, explain blast radius, ship the least-privilege patch (with proofs).

Comment 2

About the Project

What Inspired Me

Security teams working with Google Cloud Run services face a critical challenge: identifying and understanding IAM misconfigurations across dozens or hundreds of services. Traditional security tools provide raw findings like "Service X has over-permissive IAM" but lack the business context, risk prioritization, and remediation guidance that security teams desperately need.

When scanning Cloud Run services, traditional tools typically output findings like:

Finding: test-vulnerable-service allows unauthenticated access
Severity: CRITICAL
Recommendation: Restrict access to authenticated users only

This is technically accurate but missing crucial context:

  • What's the business impact?
  • What's the blast radius of this vulnerability?
  • How urgent is this fix?
  • What's the compliance impact?
  • How do I actually fix this with Terraform?

This lack of context makes security teams spend hours researching each finding—from 20-30 hours for just 10 findings. In an enterprise environment with hundreds of services, this becomes a bottleneck that prevents timely remediation.

I was inspired to solve this by combining Cloud Run, Google AI Studio, and Gemini Pro to create an intelligent security analysis platform that transforms raw technical findings into actionable intelligence with production-ready remediation code.

How I Built It

Zero-Trust Explainer is a multi-component Cloud Run application designed for scalability and reliability:

Architecture Components

Frontend (Cloud Run Service): React/Vite application serving the user interface

  • Modern UI with AI-powered indicators
  • Real-time scan progress and results
  • Modal displays for AI-generated content

Backend API (Cloud Run Service): FastAPI application serving as the orchestration layer

  • RESTful API for all operations
  • AI Studio integration for intelligent analysis
  • Async job triggering via Pub/Sub

Scan Processor (Cloud Run Job): Background worker that performs security scanning

  • Scans Cloud Run services for IAM misconfigurations
  • Identifies unauthenticated access, over-permissive roles, exposed secrets
  • Writes findings to BigQuery

Propose Job (Cloud Run Job): AI-powered report generator

  • Retrieves findings from BigQuery
  • Generates AI-powered analysis via Gemini Pro
  • Creates comprehensive reports with Terraform code
  • Uploads to Cloud Storage

Data Layer:

  • Pub/Sub: Event-driven scan request queue
  • BigQuery: Findings data warehouse with partitioning
  • Cloud Storage: Report storage with signed URLs
  • Secret Manager: Secure storage for Gemini API key

AI Studio Integration

The core innovation is the integration with Google AI Studio and Gemini Pro. I built three AI-powered features:

  1. Security Finding Explanations: Transform technical findings into business language with blast radius analysis
  2. Executive Scan Summaries: High-level summaries perfect for executive reporting
  3. Automated Terraform Fix Generation: AI-generated Terraform code with implementation guides

Infrastructure as Code

All infrastructure is deployed using Terraform:

  • Artifact Registry for container images
  • Cloud Run Services with auto-scaling
  • IAM roles with least-privilege principles
  • BigQuery tables with partitioning
  • Cloud Storage buckets with lifecycle policies

Technology Stack

  • Frontend: React 18, Vite, Modern CSS
  • Backend: FastAPI, Python 3.11+
  • AI: Google AI Studio, Gemini Pro (gemini-2.0-flash)
  • Cloud: Google Cloud Run, Pub/Sub, BigQuery, Cloud Storage
  • Infrastructure: Terraform
  • Container: Docker

Challenges I Faced

Challenge 1: AI Model Availability

Problem: Gemini API models change frequently, causing initialization failures.

Solution: Implemented robust fallback logic with multiple model options:

models_to_try = [
    'gemini-2.0-flash',
    'gemini-1.5-flash',
    'gemini-1.5-pro',
    # ... more fallback options
]

Challenge 2: JSON Parsing from AI Responses

Problem: Gemini sometimes returns JSON wrapped in markdown code fences (```json).

Solution: Strip markdown before parsing:

text_to_parse = text.replace("```json\n", "") \
                    .replace("```\n", "") \
                    .replace("```", "") \
                    .strip()

Challenge 3: Async Job Triggering

Problem: Traditional Cloud Run client libraries have authentication issues when triggering jobs from within a Cloud Run service.

Solution: Use direct REST API calls with access tokens, using the Google Cloud credentials library to get fresh tokens for each request.

Challenge 4: Frontend Data Normalization

Problem: AI responses can come in various formats (objects, strings, arrays), causing rendering errors.

Solution: Implemented comprehensive data normalization in the frontend to handle all response formats, ensuring recommendations and remediation roadmaps are always properly formatted arrays before rendering.

What I Learned

Cloud Run is Powerful

  • Serverless architecture scales effortlessly
  • Cloud Run Jobs are perfect for async workloads
  • Integration with GCP services is seamless
  • Auto-scaling to zero reduces costs when idle

AI Studio + Gemini Pro is a Game Changer

  • Natural language understanding enables business-focused security analysis
  • Code generation saves hours of manual work
  • Intelligent prioritization helps security teams focus on what matters
  • The JSON response format is consistent and reliable with proper prompt engineering

Infrastructure as Code is Essential

  • Terraform makes deployments repeatable and auditable
  • Version control for infrastructure is a must
  • Modular Terraform structure improves maintainability
  • Declarative infrastructure reduces deployment errors

Real-World Impact

The solution delivers significant time savings:

  • Before: 20-30 hours to research and remediate 10 findings
  • After: < 1 hour for the same 10 findings
  • Time savings: ~90% reduction in remediation time

Key Features

  1. 🤖 AI-Powered Explanations: Transform technical findings into business language with blast radius analysis
  2. 🎯 Smart Risk Prioritization: AI-driven priority scoring and remediation urgency assessment
  3. 🛠️ Automated Fixes: Generate production-ready Terraform code with step-by-step implementation guides
  4. 📋 Executive Summaries: High-level reporting with compliance impact for stakeholders
  5. 🔍 Real-Time Scanning: Scan actual Cloud Run services for IAM misconfigurations
  6. 📁 Signed Reports: Generate and download comprehensive security reports via signed Cloud Storage URLs

Results

Zero-Trust Explainer successfully transforms raw security findings into actionable intelligence:

  • 90% reduction in remediation time
  • AI-powered risk analysis and prioritization
  • Production-ready Terraform code generation
  • Executive-ready compliance reporting

The application is open-source and available on GitHub, demonstrating the power of combining Cloud Run, AI Studio, and Gemini Pro to solve real-world security challenges.

Built With

  • bigquery
  • cloud
  • cloud-pub/sub
  • cloud-run-jobs
  • docker
  • fastapi
  • gcs
  • gemini-pro
  • google-ai-studio
  • google-cloud-run-services
  • javascript
  • python
  • react
  • secretmanager
  • terraform
  • vite
Share this project:

Updates