/gcpsight

Primary LanguagePythonMIT LicenseMIT

gcpsight - GCP Security Scanner with Gemini-Powered Queries

A powerful command-line tool for scanning Google Cloud Platform (GCP) projects for security misconfigurations. Features an AI-powered natural language interface using Google's Gemini model, comprehensive security scoring, and beautiful terminal reports.

🚀 Quick Install

pip install gcpsight

Or using uv

uv pip install gcpsight

✨ Features

  • 🔥 Firewall Scanning: Detects VPC firewall rules open to the internet (0.0.0.0/0)
  • 🪣 Public Storage Detection: Finds publicly accessible GCS buckets
  • 👥 IAM Analysis: Identifies overly permissive roles (Owner, Editor) with broad access
  • 📊 BigQuery Security: Checks for publicly accessible datasets
  • ⚡ Cloud Functions: Scans for insecure functions with public access or outdated runtimes
  • 🛡️ Security Scoring: Risk-based scoring with detailed remediation guidance
  • 🤖 AI-Powered Queries: Natural language security questions via Gemini
  • 🎨 Beautiful Reports: Colorful terminal output with emojis and structured tables

📋 Quick Start Examples

Basic Security Scan

# Run comprehensive security assessment
gcpsight security-assessment --project-id my-gcp-project

# Check specific security issues
gcpsight list-open-firewalls --project-id my-gcp-project
gcpsight check-public-buckets --project-id my-gcp-project

AI-Powered Natural Language Queries

# Ask questions in plain English
gcpsight ask --project-id my-gcp-project "are there any firewalls open to the world?"
gcpsight ask --project-id my-gcp-project "show me my security score"
gcpsight ask --project-id my-gcp-project "check my cloud functions for issues"

Sample Output

Security Assessment Report:

🛡️  GCP SECURITY ASSESSMENT REPORT  🛡️

📊 Overall Assessment
┌─────────────────┬────────────────────────────────┐
│ 🎯 Security Score │ 75/100 (75.0%)               │
│ ⚠️  Risk Level     │ HIGH                          │
└─────────────────┴────────────────────────────────┘

Security Score Progress ████████████████████████████████████████ 75.0%

📋 Findings Summary
┌─────────────┬───────┬──────────┐
│ Risk Level  │ Count │ Visual   │
├─────────────┼───────┼──────────┤
│ 🚨 CRITICAL │ 1     │ ●        │
│ ⚠️ HIGH      │ 2     │ ●●       │
└─────────────┴───────┴──────────┘

🔍 Detailed Findings

🚨 Open Firewall [CRITICAL]
┌─────────────────────────────────────────────────────────────┐
│ 🏷️  Resource: allow-ssh-from-anywhere                      │
│ 📝 Issue: Firewall rule allows unrestricted SSH access     │
│ 📉 Impact: -25 points                                      │
│ 🔧 Fix: Restrict source ranges to specific IP addresses    │
└─────────────────────────────────────────────────────────────┘

Project Structure

  • src/gcpsight/main.py: The main entry point for the CLI application, built using click.
  • src/gcpsight/gcp_scanner.py: Contains the core logic for interacting with GCP APIs.
  • src/gcpsight/gemini_processor.py: Handles interaction with the Gemini API.
  • src/gcpsight/security_scorer.py: Implements security scoring, risk assessment, and reporting functionality.
  • pyproject.toml: Defines project metadata, dependencies, and the CLI entry point for packaging.
  • requirements.txt: Lists project dependencies (primarily for reference).
  • README.md: This file.
  • .env (not included, but necessary for local development): Used for environment variables.

🔧 Setup & Configuration

Prerequisites

  • Python 3.9+
  • Google Cloud SDK installed and configured
  • Valid GCP project with appropriate permissions

1. Install gcpsight

pip install gcpsight

2. GCP Authentication

# Authenticate with your GCP account
gcloud auth application-default login

# Or set service account credentials
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

3. Required GCP Permissions

Your authenticated user/service account needs these IAM permissions:

  • compute.firewalls.list
  • storage.buckets.list & storage.buckets.getIamPolicy
  • resourcemanager.projects.getIamPolicy
  • bigquery.datasets.list & bigquery.datasets.get
  • cloudfunctions.functions.list & cloudfunctions.functions.getIamPolicy

4. Gemini API Key (for AI features)

# Set your Gemini API key as environment variable
export GEMINI_API_KEY="your-gemini-api-key-here"

# Or create a .env file in your working directory
echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env

📖 All Available Commands

Security Assessment (Recommended)

# Comprehensive security report with scoring
gcpsight security-assessment --project-id my-project

# JSON output for automation
gcpsight security-assessment --project-id my-project --output-format json

# Table format for quick overview
gcpsight security-assessment --project-id my-project --output-format table

Individual Security Checks

# Check firewall rules
gcpsight list-open-firewalls --project-id my-project

# Check storage buckets
gcpsight check-public-buckets --project-id my-project

# Check IAM roles  
gcpsight check-overly-permissive-iam-roles --project-id my-project

# Check BigQuery datasets
gcpsight check-public-bigquery-datasets --project-id my-project

# Check Cloud Functions
gcpsight check-insecure-cloud-functions --project-id my-project

# Run all individual checks
gcpsight run-all-checks --project-id my-project

AI-Powered Natural Language Queries

# Ask security questions in plain English
gcpsight ask --project-id my-project "are there any firewalls open to the world?"
gcpsight ask --project-id my-project "show me public buckets"
gcpsight ask --project-id my-project "check for overly permissive IAM roles"
gcpsight ask --project-id my-project "are there any public BigQuery datasets?"
gcpsight ask --project-id my-project "check my cloud functions for issues"
gcpsight ask --project-id my-project "run all checks"
gcpsight ask --project-id my-project "give me a security assessment"
gcpsight ask --project-id my-project "what's my security score?"

Example Command Outputs

Firewall Check:

🔍 Checking open firewall rules for project my-project...

🔥 Open Firewall Rules
┌─────────────────────┬─────────┬──────────────┬─────────────────┐
│ Name                │ Network │ Source Range │ Allowed Ports   │
├─────────────────────┼─────────┼──────────────┼─────────────────┤
│ allow-ssh-anywhere  │ default │ 0.0.0.0/0    │ tcp:22          │
│ allow-http-https    │ default │ 0.0.0.0/0    │ tcp:80,tcp:443  │
└─────────────────────┴─────────┴──────────────┴─────────────────┘

Security Assessment Table Format:

🛡️  Security Assessment Summary
┌─────────────────┬────────────────────────┐
│ 🎯 Security Score │ 75/100 (75.0%)       │
│ ⚠️  Risk Level     │ HIGH                  │
│ 📊 Total Findings │ 3                     │
└─────────────────┴────────────────────────┘

🔍 Detailed Security Findings
┌──────────────────────┬─────────────────────┬─────────────┬──────────────┐
│ Check Type           │ Resource            │ Risk Level  │ Score Impact │
├──────────────────────┼─────────────────────┼─────────────┼──────────────┤
│ Open Firewall        │ allow-ssh-anywhere  │ 🚨 CRITICAL │ -25          │
│ Public Bucket        │ my-public-bucket    │ ⚠️ HIGH      │ -15          │
│ Insecure Function    │ my-function         │ ⚡ MEDIUM    │ -10          │
└──────────────────────┴─────────────────────┴─────────────┴──────────────┘

🛠️ Development Installation

For contributors and developers who want to work on gcpsight:

# Clone the repository
git clone https://github.com/rishabkumar7/gcpsight
cd gcpsight

# Install in development mode
pip install -e .

# Or build and install locally
python -m pip install build
python -m build
pip install dist/gcpsight-*.whl

🚀 How it Works

  1. CLI Interface: Built with click library for intuitive command-line interaction
  2. GCP API Integration: Uses official Google Cloud client libraries for secure API access
  3. Security Analysis: Comprehensive checks across compute, storage, IAM, and serverless resources
  4. Risk Scoring: Intelligent scoring system with weighted impact based on security severity
  5. AI Integration: Gemini AI translates natural language queries into specific security checks
  6. Rich Output: Beautiful terminal reports with colors, emojis, and structured tables

Future Enhancements

  • Add more GCP security checks.
  • Improve output formatting.
  • More sophisticated error handling and logging.
  • Scan multiple projects or an entire GCP organization.
  • Automated remediation suggestions/actions (with caution!).

Contributing

Contributions are welcome! Please open an issue.

License

This is under the MIT License.