CloudSentrix 🔐

GCP IAM Privilege-Escalation Attack-Path Analyzer

CloudSentrix is a free, open-source command-line tool that scans Google Cloud Platform IAM policy exports for privilege-escalation risks, generates interactive attack-path graphs, scores your security posture, and produces client-ready PDF reports — all without any paid APIs.

What It Does

• Detects 5 GCP IAM privilege-escalation patterns (mapped to MITRE ATT&CK Cloud Matrix)
• Scores your project's security posture from 0–100
• Calculates blast radius — if one account is compromised, how much can an attacker reach?
• Generates remediation — exact gcloud CLI commands to fix each finding
• Exports results as JSON, CSV, SARIF, Interactive HTML Dashboard, or client-ready PDF
• Live scanning — fetch and scan a live GCP project directly (no file needed)
• Watches a folder and auto-rescans whenever an IAM file changes
• AI summaries — plain-language executive summaries via Google Gemini

Requirements

• Python 3.10 or higher
• pip

Installation

Windows

git clone https://github.com/Talha-Imran-cloud/cloudsentrix.git
cd cloudsentrix
python -m venv venv
venv\Scripts\activate
pip install -e .

Linux / macOS (Kali, Ubuntu, Debian)

git clone https://github.com/Talha-Imran-cloud/cloudsentrix.git
cd cloudsentrix
python3 -m venv venv
source venv/bin/activate
pip install -e .

Verify installation

cloudsentrix --version

Getting Your GCP IAM Policy File

gcloud projects get-iam-policy YOUR_PROJECT_ID --format=json > my_project_iam.json

Two sample files are included for testing:

• sample_data/sample_gcp_iam.json — basic 5-principal example
• sample_data/demo_enterprise_iam.json — realistic enterprise scenario

Commands

scan — Full pipeline scan

cloudsentrix scan --file sample_data/sample_gcp_iam.json
cloudsentrix scan --file my_project.json --severity high
cloudsentrix scan --file my_project.json --top 10

live-scan — Scan a live GCP project directly ⚡ NEW

# Requires: gcloud CLI authenticated
gcloud auth application-default login

# Fetch and scan live IAM policy
cloudsentrix live-scan --project my-gcp-project-id

# Scan and save the fetched policy
cloudsentrix live-scan --project my-gcp-project-id --save fetched_policy.json

# Filter by severity
cloudsentrix live-scan --project my-gcp-project-id --severity critical

blast-radius — Blast radius for one principal

cloudsentrix blast-radius --file my_project.json --principal admin@company.com

principal-path — Escalation path between two principals

cloudsentrix principal-path --file my_project.json \
  --source intern@company.com \
  --target app-backend@my-project.iam.gserviceaccount.com

mitre-map — Map findings to MITRE ATT&CK Cloud Matrix

cloudsentrix mitre-map --file my_project.json

remediate — Generate exact gcloud fix commands

cloudsentrix remediate --file my_project.json
cloudsentrix remediate --file my_project.json --project my-real-project-id
cloudsentrix remediate --file my_project.json --severity critical

score — Security score only (for CI/CD badges)

cloudsentrix score --file my_project.json
cloudsentrix score --file my_project.json --json
cloudsentrix score --file my_project.json --min-score 70

validate — Check file format before scanning

cloudsentrix validate --file my_project.json

compare — Compare two IAM exports (detect new risks)

cloudsentrix compare --old january.json --new february.json

export — Export results to JSON, CSV, HTML, or SARIF

# JSON export
cloudsentrix export --file my_project.json --output report.json

# CSV export
cloudsentrix export --file my_project.json --output report.csv

# Interactive HTML Dashboard (open in browser)
cloudsentrix export --file my_project.json --output dashboard.html

# SARIF export (GitHub Code Scanning compatible) ⚡ NEW
cloudsentrix export --file my_project.json --output results.sarif

Opening the HTML Dashboard:

Windows:

start dashboard.html

Linux / macOS:

xdg-open dashboard.html

The HTML dashboard includes:

• Security score card
• Finding counts by severity
• Interactive attack graph (drag nodes, scroll to zoom, hover for details)
• Full findings table with MITRE mapping
• Blast radius table

report — Generate a client-ready PDF report

# Without AI summary
cloudsentrix report --file my_project.json --output my_report.pdf --no-ai

# With Gemini AI summary (set API key first — see below)
cloudsentrix report --file my_project.json --output my_report.pdf

watch — Auto-rescan when file changes

# Watch a single file
cloudsentrix watch --path my_project.json

# Watch a folder (rescans any .json file that changes)
cloudsentrix watch --path /path/to/iam/exports/

# Custom poll interval (seconds)
cloudsentrix watch --path my_project.json --interval 5

Press Ctrl+C to stop watching.

rules — List all detection rules

cloudsentrix rules

list-principals — List all principals and their roles

cloudsentrix list-principals --file my_project.json

SARIF Export — GitHub Code Scanning ⚡ NEW

SARIF (Static Analysis Results Interchange Format) output is compatible with:

• GitHub Code Scanning — upload directly to your repo's Security tab
• VS Code SARIF Viewer extension
• Azure DevOps security dashboards
• Any SARIF 2.1.0-compatible tool

cloudsentrix export --file my_project.json --output results.sarif

Upload to GitHub:

gh api repos/OWNER/REPO/code-scanning/sarifs \
  -F sarif=@results.sarif \
  -F ref=refs/heads/main \
  -F commit_sha=$(git rev-parse HEAD)

Gemini AI Summary (Optional)

The report command can generate a plain-language AI summary using Google Gemini.

Step 1 — Get a free API key from Google AI Studio

Step 2 — Set the environment variable:

Windows:

$env:GEMINI_API_KEY = "your_api_key_here"

Linux / macOS:

export GEMINI_API_KEY="your_api_key_here"

Step 3 — Run:

cloudsentrix report --file my_project.json --output report.pdf

If no API key is set, a built-in template summary is used automatically.

Exit Codes

Detection Rules

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Expected output: 144 passed

Project Structure

cloudsentrix/
├── src/
│   ├── cli.py              # CLI entry point (15 commands)
│   ├── parser.py           # GCP IAM JSON parser
│   ├── graph.py            # IAM permission graph engine
│   ├── detection.py        # Privilege-escalation detection rules
│   ├── risk_score.py       # 0-100 security scoring engine
│   ├── blast_radius.py     # Attack-path blast radius calculator
│   ├── watch_handler.py    # File system watcher
│   ├── live_scanner.py     # Live GCP project scanner
│   ├── pdf_report.py       # PDF report generator
│   └── ai_summary.py       # Gemini AI summary integration
├── tests/                  # 144 pytest tests
├── sample_data/
│   ├── sample_gcp_iam.json         # Basic test file
│   └── demo_enterprise_iam.json    # Realistic enterprise demo
├── .github/workflows/ci.yml        # GitHub Actions CI
├── pyproject.toml                  # Packaging configuration
└── README.md

Roadmap 🗺️

Coming Soon

AWS Support (Preview)

When AWS support ships, usage will look like:

# Export AWS IAM data
aws iam get-account-authorization-details --output json > aws_iam.json

# Scan AWS
cloudsentrix scan --file aws_iam.json --cloud aws

Azure Support (Preview)

# Export Azure RBAC
az role assignment list --all --output json > azure_rbac.json

# Scan Azure
cloudsentrix scan --file azure_rbac.json --cloud azure

License

MIT License — free to use, modify, and distribute.

Author

Talha Imran — SOC Analyst | Cloud Security | Pentesting