Metadata-Version: 2.4
Name: skullmap
Version: 2.0.0
Summary: Multi-Cloud Attack Chain Intelligence Tool — See the full attack before the attacker does
Home-page: https://github.com/Talha-Imran-cloud/skullmap
Author: Talha Imran
Author-email: talhaimran20008@gmail.com
Project-URL: Website, https://cloudsentrix.netlify.app
Project-URL: LinkedIn, https://www.linkedin.com/in/talha-imran-583a44420
Project-URL: Bug Reports, https://github.com/Talha-Imran-cloud/skullmap/issues
Project-URL: Source, https://github.com/Talha-Imran-cloud/skullmap
Keywords: security,cloud,pentesting,gcp,aws,azure,oracle,attack-chain,misconfiguration,bug-bounty,soc,red-team
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: google-cloud-storage>=2.10.0
Requires-Dist: google-cloud-resource-manager>=1.10.3
Requires-Dist: google-cloud-iam>=2.12.1
Requires-Dist: google-cloud-compute>=1.14.1
Requires-Dist: google-cloud-functions>=1.13.0
Requires-Dist: google-auth>=2.23.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: botocore>=1.34.0
Requires-Dist: azure-identity>=1.15.0
Requires-Dist: azure-mgmt-storage>=21.0.0
Requires-Dist: azure-mgmt-authorization>=3.0.0
Requires-Dist: azure-mgmt-web>=7.0.0
Requires-Dist: azure-mgmt-network>=25.0.0
Requires-Dist: azure-mgmt-keyvault>=10.0.0
Requires-Dist: oci>=2.112.0
Requires-Dist: google-generativeai>=0.5.4
Requires-Dist: rich>=13.7.0
Requires-Dist: click>=8.1.7
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: schedule>=1.2.1
Requires-Dist: pyfiglet>=1.0.2
Requires-Dist: flask>=3.0.0
Requires-Dist: websockets>=12.0
Requires-Dist: PyGithub>=2.1.1
Requires-Dist: twilio>=8.10.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

⠀⠀⠀⠀⢀⣀⣤⣤⣤⣤⣄⡀⠀⠀⠀⠀
⠀⢀⣤⣾⣿⣾⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀
⢠⣾⣿⢛⣼⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⡀
⣾⣯⣷⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
⣿⡿⠻⢿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠻⢿⡵
⢸⡇⠀⠀⠉⠛⠛⣿⣿⠛⠛⠉⠀⠀⣿⡇
⢸⣿⣀⠀⢀⣠⣴⡇⠹⣦⣄⡀⠀⣠⣿⡇
⠈⠻⠿⠿⣟⣿⣿⣦⣤⣼⣿⣿⠿⠿⠟⠀
⠀⠀⠀⠀⠸⡿⣿⣿⢿⡿⢿⠇⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠈⠁⠈⠁⠀⠀⠀⠀⠀⠀


# 💀 SkullMap v2.0.0

### Multi-Cloud Attack Chain Intelligence Tool

[![Python](https://img.shields.io/badge/Python-3.10+-red?style=flat-square&logo=python)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-red?style=flat-square)](LICENSE)
[![Clouds](https://img.shields.io/badge/Clouds-GCP%20%7C%20AWS%20%7C%20Azure%20%7C%20Oracle-red?style=flat-square)](https://github.com)
[![AI](https://img.shields.io/badge/AI-Claude%20%7C%20Gemini-red?style=flat-square&logo=anthropic)](https://anthropic.com)

> **"See the full attack chain before the attacker does — across every cloud."**

Built by **Talha Imran** — SOC Analyst | Cloud Security | Pentesting

</div>

---

## 🔥 What is SkullMap?

SkullMap is the world's first **Multi-Cloud Attack Chain Intelligence Tool** that:

- 🔗 **Discovers attack chains** — not just individual misconfigurations
- 🧠 **AI-powered narratives** — tells the full attacker story in human language
- 💀 **Multi-cloud coverage** — GCP, AWS, Azure, Oracle Cloud, Kubernetes
- ⚡ **Real-time monitoring** — live watch mode with instant alerts
- 🎯 **Bug bounty ready** — CVSS scores and HackerOne/Bugcrowd format reports
- 🔐 **Zero Trust assessment** — NIST SP 800-207 based scoring
- 💥 **Blast Radius Calculator** — domino effect of any breach
- 💰 **Breach Cost Estimator** — financial impact in dollars for management
- 🪞 **Digital Twin** — simulate attacks on virtual copy, real infra untouched
- 🌑 **Dark Web Monitor** — proactive breach detection before it happens
- ⚔️ **Red vs Blue Simulator** — live battle simulation on your infra

**No other tool combines all of these features in one place.**

---

## 🚀 Quick Start

### Installation

```bash
git clone https://github.com/Talha-Imran-cloud/skullmap
cd skullmap
pip install -r requirements.txt
```

### Setup

```bash
cp .env.example .env
# Edit .env with your cloud credentials
```

### First Scan

```bash
# GCP scan
python -m cli.main scan --project your-gcp-project-id

# AWS scan
python -m cli.main aws-scan --region us-east-1

# Azure scan
python -m cli.main azure-scan --subscription your-subscription-id

# Full scan with all features
python -m cli.main scan --project my-project --ai --predict --economics --dna --executive
```

---

## ☁️ Supported Clouds

| Cloud | Status | Features |
|-------|--------|---------|
| ☁️ Google Cloud (GCP) | ✅ Full Support | Storage, IAM, Functions, Compute |
| 🟡 AWS | ✅ Full Support | S3, IAM, Lambda, Security Groups, CloudTrail |
| 🔵 Azure | ✅ Full Support | Storage, RBAC, Functions, Key Vault, NSG |
| 🟠 Oracle Cloud | ✅ Full Support | Object Storage, IAM, Network, Compute |
| ⚙️ Kubernetes | ✅ Full Support | Dashboard, RBAC, Pods, Secrets, Network |
| 🔴 Cross-Cloud | ✅ Full Support | GCP + AWS + Azure combined chains |

---

## 💀 Features — 35+ Unique Capabilities

### 🔗 Core — Attack Chain Engine
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| Chain Discovery | `--` (auto) | Links misconfigs into multi-step attack paths |
| Visual Kill Chain | `--` (auto) | S3 → Lambda → RDS → EC2 visual map |
| Risk Scoring | `--` (auto) | 0-100 risk score per chain |
| Chain DNA | `--dna` | SHA fingerprint + real-world breach matching |
| Smart Fix | `--optimize` | One fix that breaks maximum chains |

### 🧠 AI Features
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| AI Attack Narrative | `--ai` | Full attacker story in human language |
| Attacker Persona Mode | `--persona` | Script kiddie, APT, ransomware perspectives |
| Predictive AI | `--predict` | Minority Report — next attack steps |
| Attacker Brain | `--brain` | AI simulates attacker's actual thinking |
| AI Security Chat | `--chat` / `chat` | Interactive AI security consultant |
| NLP Scan | `ask` command | Ask security questions in plain English |

### 💥 NEW — Unique Features (Not in Any Other Tool)
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| **Blast Radius Calculator** | `--blast-radius` / `blast` | If resource is compromised, what's the domino effect? Shows ALL affected resources |
| **Breach Cost Estimator** | `--breach-cost` / `breach-cost` | Financial impact in dollars — GDPR fines, downtime, legal, forensics |
| **Security Timeline** | `--timeline` / `timeline` | ASCII graph of security score over time — show your progress |
| **Digital Twin** | `--twin` / `twin` | NASA-level concept — clone infra, simulate attacks, real infra untouched |
| **Red vs Blue Simulator** | `--simulate` / `simulate` | Live battle — see where your defenses fail against real attack techniques |
| **Dark Web Monitor** | `dark-web` command | Check if your emails, domain, IPs are on dark web/breach databases |
| **Gamification / XP** | `--gamify` / `profile` | Level up your security — XP, achievements, ranks |
| **Geo Attack Tracker** | `--geo` / `geo` | Real-time attacker IP location mapping |
| **Evidence Generator** | `--evidence` / `evidence` | Court-ready HTML/PDF/JSON reports |
| **GitHub PR Review** | `pr-review` command | Auto security scan on every pull request — blocks dangerous PRs |

### 💰 Business Intelligence
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| Attacker Economics | `--economics` | Financial ROI per attack chain |
| Executive Dashboard | `--executive` | One-page CISO/CEO report |
| Industry Benchmark | `--benchmark` | Compare vs industry average |
| Bug Bounty Mode | `--bounty` | CVSS + HackerOne/Bugcrowd format |
| Compliance Blast Radius | `--blast-radius` | SOC2, ISO27001, GDPR, PCI DSS status |

### 🔐 Advanced Security
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| Zero Trust Score | `--zero-trust` | NIST SP 800-207 assessment |
| Dark Web Linker | `--darkweb` | Leaked creds merged into chains |
| Supply Chain Scan | `--supply-chain` | Secrets, packages, IaC, GitHub Actions |
| Attack Heatmap | `--heatmap` | Which resource gets attacked first (%) |
| Attack Replay Timeline | `--replay` | Cinematic timeline of the attack |

### 📡 Monitoring & Alerts
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| Live Watch Mode | `watch` | Continuous scan every X minutes |
| Threat Intelligence | `monitor` | Live threat feed + IP reputation |
| Slack Alerts | `--slack` | Real-time war room notifications |
| Teams Alerts | `--teams` | Microsoft Teams blast |
| Telegram Alerts | `--telegram` | Instant mobile notifications |
| WhatsApp Alerts | `--whatsapp` | Twilio WhatsApp alerts |

### 🛠️ Tools
| Feature | Flag/Command | Description |
|---------|---------|-------------|
| Auto-Retest | `retest` | Verify fixes with before/after comparison |
| Training Mode | `train` / `learn` | Learn cloud security with AI + quiz |
| GitHub PR Review | `pr-review` | Auto security review on pull requests |
| Geo Tracker | `geo` | Attacker location + block recommendations |
| Evidence Generator | `evidence` | Court-ready PDF/HTML/JSON reports |

---

## 📖 All Commands

### `scan` — GCP Scan
```bash
python -m cli.main scan --project PROJECT_ID [OPTIONS]

Options:
  -p, --project TEXT         GCP Project ID [required]
  -w, --watch                Enable watch mode
  -i, --interval INT         Watch interval in seconds (default: 300)
  --ai                       Generate AI attack narrative
  --predict                  Predict next attack steps
  --darkweb                  Check dark web leaks
  -e, --emails TEXT          Emails to check on dark web
  --persona [script_kiddie|apt|ransomware]
  --slack                    Send Slack alerts
  --teams                    Send Teams alerts
  --telegram                 Send Telegram alerts
  --whatsapp                 Send WhatsApp alerts
  --economics                Show attacker economics
  --dna                      Generate chain DNA fingerprint
  --optimize                 Show max chain disruption fix
  --k8s                      Include Kubernetes scan
  --replay                   Show attack replay timeline
  --supply-chain             Scan supply chain
  --executive                Show executive dashboard
  --retest                   Auto retest after fix
  --bounty                   Bug bounty mode
  -t, --target TEXT          Bug bounty target name
  --zero-trust               Zero trust assessment
  --brain                    Attacker brain simulator
  --threat-intel             Live threat intelligence
  --heatmap                  Attack probability heatmap
  --benchmark                Industry benchmark comparison
  --industry TEXT            Industry for benchmark
  # ── NEW FLAGS ─────────────────────────────────────
  --blast-radius             💥 Blast radius — domino effect of breach
  --breach-cost              💰 Financial breach cost in dollars
  --timeline                 📈 Security posture timeline graph
  --twin                     🪞 Digital twin attack simulation
  --simulate                 ⚔️  Red vs Blue team battle simulation
  --gamify                   🎮 Gamification — XP & achievements
  --nlp                      💬 Natural language scan mode
  --evidence                 📸 Generate court-ready evidence report
  --geo                      🌍 Geo-location attack tracker
  --chat                     🤖 AI security chat mode
  -o, --output TEXT          Output directory (default: reports)
```

### `aws-scan` — AWS Scan
```bash
python -m cli.main aws-scan [OPTIONS]

Options:
  -r, --region TEXT          AWS Region (default: us-east-1)
  -p, --profile TEXT         AWS Profile name
  --ai / --economics / --dna / --optimize
  --replay / --executive / --bounty
  --zero-trust / --brain / --heatmap / --benchmark
  # ── NEW FLAGS ─────────────────────────────────────
  --blast-radius             💥 Blast radius calculator
  --breach-cost              💰 Breach cost estimator
  --twin                     🪞 Digital twin simulation
  --simulate                 ⚔️  Red vs Blue simulation
  --evidence                 📸 Evidence report generator
  --slack / --teams / --telegram / --whatsapp
  --chat / -o, --output TEXT
```

### `azure-scan` — Azure Scan
```bash
python -m cli.main azure-scan --subscription SUBSCRIPTION_ID [OPTIONS]

Options:
  -s, --subscription TEXT    Azure Subscription ID [required]
  --ai / --economics / --dna / --optimize
  --replay / --executive / --bounty
  --zero-trust / --brain / --heatmap / --benchmark
  # ── NEW FLAGS ─────────────────────────────────────
  --blast-radius             💥 Blast radius calculator
  --breach-cost              💰 Breach cost estimator
  --twin                     🪞 Digital twin simulation
  --simulate                 ⚔️  Red vs Blue simulation
  --evidence                 📸 Evidence report generator
  --slack / --teams / --telegram / --whatsapp
  --chat / -o, --output TEXT
```

### `oracle-scan` — Oracle Cloud Scan
```bash
python -m cli.main oracle-scan --tenancy TENANCY_ID [OPTIONS]

Options:
  -t, --tenancy TEXT         Oracle Tenancy ID [required]
  -r, --region TEXT          Oracle Region (default: us-ashburn-1)
  --ai / --economics / --dna / --optimize
  --replay / --executive / --bounty
  --zero-trust / --brain / --heatmap
  # ── NEW FLAGS ─────────────────────────────────────
  --blast-radius             💥 Blast radius calculator
  --breach-cost              💰 Breach cost estimator
  --evidence                 📸 Evidence report generator
  --slack / --teams / --telegram / --whatsapp
  -o, --output TEXT
```

### `cross-scan` — Cross-Cloud Scan
```bash
python -m cli.main cross-scan --project PROJECT --subscription SUB [OPTIONS]

Options:
  -p, --project TEXT         GCP Project ID [required]
  -s, --subscription TEXT    Azure Subscription ID [required]
  -r, --region TEXT          AWS Region (default: us-east-1)
  --ai / --economics / --dna / --optimize
  --replay / --executive / --bounty
  --zero-trust / --brain / --heatmap
  # ── NEW FLAGS ─────────────────────────────────────
  --blast-radius             💥 Blast radius calculator
  --breach-cost              💰 Breach cost estimator
  --twin                     🪞 Digital twin simulation
  --simulate                 ⚔️  Red vs Blue simulation
  --evidence                 📸 Evidence report generator
  --slack / --teams / --telegram / --whatsapp
  -o, --output TEXT
```

---

## 🆕 NEW Standalone Commands

### `blast` — Blast Radius Calculator
```bash
python -m cli.main blast --project PROJECT_ID [--resource RESOURCE]

# Examples:
python -m cli.main blast --project my-gcp-project
python -m cli.main blast --project my-gcp-project --resource "gs://my-bucket"

# Output:
# 💥 Blast Radius: CATASTROPHIC (89%)
# → Storage Buckets exposed
# → Lambda Functions exposed
# → RDS Databases accessible
# → 47 IAM roles affected
```

### `breach-cost` — Breach Cost Estimator
```bash
python -m cli.main breach-cost --project PROJECT_ID [OPTIONS]

Options:
  -p, --project TEXT         Project ID [required]
  -n, --records INT          Records at risk (default: 500000)
  -d, --data [PII|Financial|Healthcare|Generic]
  -i, --industry TEXT        Industry sector (default: tech)
  -t, --downtime INT         Downtime hours (default: 24)

# Examples:
python -m cli.main breach-cost --project my-gcp-project
python -m cli.main breach-cost --project my-gcp --records 2000000 --data Healthcare --industry healthcare

# Output:
# 💰 Estimated Breach Cost: $8,742,000
# ├── Data Breach Liability:  $4,200,000
# ├── Downtime Cost:          $2,400,000
# ├── GDPR Fine:              $1,200,000
# ├── Legal Fees:             $580,000
# └── Forensics + PR:         $362,000
# 💡 Fix now costs: ~$175,000 (50x cheaper!)
```

### `timeline` — Security Posture Timeline
```bash
python -m cli.main timeline --project PROJECT_ID

# Output:
# 📈 Security Score Over Time
# 100 ░░░░░░░░░░░░░░░░░░░░
#  80 ░░░░░░░░░░░░░██████
#  60 ░░░░░░░░██████████
#  40 ████████░░░░░░░░░░
#     Jan Feb Mar Apr Aug
#
# 📈 Score change: +36 points (38 → 74)
```

### `twin` — Digital Twin Attack Simulation
```bash
python -m cli.main twin --project PROJECT_ID [--rounds N]

Options:
  -p, --project TEXT         Project ID [required]
  -n, --rounds INT           Attack rounds (default: 4)

# Examples:
python -m cli.main twin --project my-gcp-project
python -m cli.main twin --project my-gcp-project --rounds 6

# Output:
# 🪞 Building Digital Twin of my-gcp-project...
# → Cloned: Cloud SQL Database
# → Cloned: IAM Roles
# → Cloned: Storage Buckets
# ✅ Digital Twin ready — 8 resources cloned
#
# ⚔️  Attack Simulation Starting (real infra is SAFE)
# 🎯 Testing: SQL Injection
#   ✓ Fingerprinting database type...
#   🛡 BLOCKED: UNION-based extraction
#   ✅ BLOCKED — defense held (1.2s)
#
# 🎯 Testing: IAM Privilege Escalation
#   ✓ Enumerating attached policies...
#   ✓ Found wildcard permissions...
#   ❌ VULNERABLE — attack succeeded in 3.7s
```

### `simulate` — Red vs Blue Team Simulator
```bash
python -m cli.main simulate --project PROJECT_ID [--rounds N]

Options:
  -p, --project TEXT         Project ID [required]
  -n, --rounds INT           Battle rounds (default: 4)

# Examples:
python -m cli.main simulate --project my-gcp-project
python -m cli.main simulate --project my-gcp-project --rounds 6

# Output:
# ⚔️  Red Team vs Blue Team Simulator
# ━━━ Round 1: S3 Bucket Takeover ━━━
# 🔴 RED TEAM:  Attempting public bucket access...
# 🔵 BLUE TEAM: Checking bucket ACL policies...
# ❌ RED WINS   Found public bucket! Downloading data...
#    Detection time: 14 minutes (too late!)
#
# ━━━ Round 2: IAM Privilege Escalation ━━━
# 🔴 RED TEAM:  Enumerating IAM permissions...
# 🔵 BLUE TEAM: CloudTrail monitoring IAM calls...
# ✅ BLUE WINS  Alert triggered — anomaly detected.
#    Blocked in 2 seconds
#
# 🏆 WINNER: 🔵 BLUE TEAM (3/4 rounds)
# 🚨 Weak points: S3 Bucket Takeover, Metadata SSRF
```

### `dark-web` — Dark Web Monitor
```bash
python -m cli.main dark-web --domain DOMAIN [OPTIONS]

Options:
  -d, --domain TEXT          Company domain [required]
  -p, --project TEXT         Project ID
  -e, --emails TEXT          Extra emails to check (multiple allowed)

# Examples:
python -m cli.main dark-web --domain mycompany.com
python -m cli.main dark-web --domain mycompany.com \
  --emails ceo@mycompany.com --emails admin@mycompany.com

# Output:
# 🌑 Dark Web Asset Monitor — mycompany.com
#
# 📧 Email breach check:
#   💀 admin@mycompany.com — found in 3 breaches!
#      → RockYou2024 (10B records) CRITICAL
#      → LinkedIn 2021 (700M records) HIGH
#   ✅ ceo@mycompany.com — clean
#
# 🌐 Dark web mentions:
#   🔴 VPN access for sale — BreachForums ($2,000)
#   🟠 Internal docs leaked — Telegram channel (Free)
#   🟠 API keys bundle — GitHub dork (Free)
```

### `ask` — Natural Language Scanner
```bash
python -m cli.main ask --project PROJECT_ID [--question "YOUR QUESTION"]

Options:
  -p, --project TEXT         Project ID [required]
  -q, --question TEXT        Security question (optional — opens interactive mode if omitted)

# Examples:
python -m cli.main ask --project my-gcp --question "Is my S3 bucket safe?"
python -m cli.main ask --project my-gcp --question "What can a hacker do to my AWS?"
python -m cli.main ask --project my-gcp --question "Am I GDPR compliant?"
python -m cli.main ask --project my-gcp   # Opens interactive REPL mode

# Output:
# 💬 Question: Is my S3 bucket safe?
# 🧠 Detected intent: storage
# 🔍 Scanning cloud storage buckets...
#
# Resource              Issue                    Severity
# gs://my-bucket-prod   Public read access       🔴 CRITICAL
# gs://backup-2024      No versioning enabled    🟡 MEDIUM
```

### `geo` — Geo-Location Attack Tracker
```bash
python -m cli.main geo --project PROJECT_ID [--interval SECONDS]

Options:
  -p, --project TEXT         Project ID [required]
  -i, --interval INT         Refresh interval for continuous mode

# Output:
# 🌍 Geo-Location Attack Tracker
# IP Address        Location              Action                    Threat
# 185.220.101.45    🇩🇪 Frankfurt, Germany  Storage Enumeration      🔴 CRITICAL
# 193.32.127.232    🇷🇺 Moscow, Russia       IAM Brute-force          🔴 CRITICAL
# 45.33.32.156      🇺🇸 Fremont, USA         Port Scan               🟡 MEDIUM
#
# 🚨 Block Recommendation:
# gcloud compute firewall-rules create block-attackers \
#   --action=DENY --source-ranges=185.220.101.45,193.32.127.232
```

### `evidence` — Evidence Generator
```bash
python -m cli.main evidence --project PROJECT_ID [--output DIR]

Options:
  -p, --project TEXT         Project ID [required]
  -o, --output TEXT          Output directory (default: reports)

# Output:
# 📸 Evidence Generator
# ✅ HTML report:  reports/evidence_20260820_143022.html
# ✅ JSON dump:    reports/evidence_20260820_143022.json
# ✅ PDF report:   reports/evidence_20260820_143022.pdf
# ⚖️  Court-ready evidence saved.
```

### `profile` — Gamification & XP
```bash
python -m cli.main profile --project PROJECT_ID

# Output:
# 💀 SkullMap Security Profile
# ⚔️  Penetration Tester  •  3,450 XP
#
# ████████████████░░░░░░  3,450/6,000 XP to 🧠 Red Team Lead
#
# 🏆 Achievements:
# ✅ 🩸 First Blood      +100 XP
# ✅ ✅ Patch Master      +500 XP
# ✅ 🪣 Bucket Bouncer   +300 XP
# ❌ 🔐 Double Lock      (Enable MFA on all accounts)
# 🔒 ??? Secret          (???)
```

### `pr-review` — GitHub PR Security Review
```bash
python -m cli.main pr-review --owner OWNER --repo REPO --pr NUMBER [--demo]

Options:
  -o, --owner TEXT           GitHub owner/org [required]
  -r, --repo TEXT            Repository name [required]
  -n, --pr INT               PR number [required]
  --demo                     Run demo scan (no GitHub token needed)

# Examples:
python -m cli.main pr-review --owner myorg --repo myapp --pr 42
python -m cli.main pr-review --demo   # demo mode — no token needed

# Output:
# 🔍 Scanning PR #42 — myorg/myapp
#   ⚠ config.py — 2 issue(s)
#   ✓ routes.py
#
# File        Type    Issue                    Severity  Fix
# config.py   Secret  AWS Credential           🔴 CRITICAL  Rotate + use Secret Manager
# config.py   Secret  Hardcoded Password       🔴 CRITICAL  Move to env variable
#
# ❌ PR BLOCKED — 2 CRITICAL issues found!
```

---

## 💡 Usage Examples

```bash
# Basic GCP scan
python -m cli.main scan --project my-gcp-project

# Full scan with AI + all new features + alerts
python -m cli.main scan --project my-gcp-project \
  --ai --predict --economics --dna --executive \
  --blast-radius --breach-cost --timeline \
  --twin --simulate --evidence \
  --slack --telegram

# Bug bounty mode
python -m cli.main scan --project my-gcp-project \
  --bounty --target "company-name" --dna --evidence

# APT attacker perspective
python -m cli.main scan --project my-gcp-project \
  --ai --persona apt --brain --replay --twin

# Management report (dollars + compliance)
python -m cli.main scan --project my-gcp-project \
  --executive --breach-cost --blast-radius --evidence

# Full AWS scan with new features
python -m cli.main aws-scan --region us-east-1 \
  --ai --economics --zero-trust --heatmap \
  --blast-radius --breach-cost --simulate

# Cross-cloud with everything
python -m cli.main cross-scan \
  --project my-gcp \
  --subscription my-azure-sub \
  --region us-east-1 \
  --ai --economics --executive \
  --blast-radius --twin --evidence

# Check dark web exposure
python -m cli.main dark-web --domain mycompany.com \
  --emails admin@mycompany.com --emails ceo@mycompany.com

# Ask in plain English
python -m cli.main ask --project my-gcp \
  --question "Am I GDPR compliant?"

# Simulate attacks
python -m cli.main twin --project my-gcp --rounds 6
python -m cli.main simulate --project my-gcp --rounds 4

# Track security progress over time
python -m cli.main timeline --project my-gcp

# See how much a breach would cost
python -m cli.main breach-cost --project my-gcp \
  --records 1000000 --data PII --industry tech

# Continuous watch + Telegram alerts
python -m cli.main watch --project my-gcp-project --interval 300
python -m cli.main monitor --project my-gcp-project --interval 60

# GitHub PR review
python -m cli.main pr-review --owner myorg --repo myapp --pr 42

# Train yourself
python -m cli.main train

# AI chat
python -m cli.main chat --project my-gcp-project
```

---

## ⚙️ Configuration

### `.env` File
```env
# GCP
GCP_PROJECT_ID=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=path/to/gcp-key.json

# AWS
AWS_ACCESS_KEY_ID=your-key-id
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1

# Azure
AZURE_SUBSCRIPTION_ID=your-subscription-id
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

# Oracle
ORACLE_TENANCY_ID=your-tenancy-id
ORACLE_USER_ID=your-user-id
ORACLE_FINGERPRINT=your-fingerprint
ORACLE_KEY_FILE=path/to/oracle-key.pem
ORACLE_REGION=us-ashburn-1

# AI
GEMINI_API_KEY=your-gemini-key
ANTHROPIC_API_KEY=your-anthropic-key

# Alerts
SLACK_WEBHOOK_URL=https://hooks.slack.com/...
TEAMS_WEBHOOK_URL=https://outlook.office.com/...
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_CHAT_ID=your-chat-id
TWILIO_ACCOUNT_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_WHATSAPP_FROM=+14155238886
TWILIO_WHATSAPP_TO=+923001234567

# GitHub
GITHUB_TOKEN=your-github-token

# Dark Web — get key from: https://haveibeenpwned.com/API/Key
HIBP_API_KEY=your-hibp-key

# Geo Tracker — ip-api.com used by default (free, no key needed)
GEO_API_KEY=

# Scan Settings
WATCH_INTERVAL=300
OUTPUT_DIR=reports
```

---

## 📁 Project Structure

```
skullmap/
├── cli/
│   ├── scanner/
│   │   ├── gcp_scanner.py          # GCP misconfiguration scanner
│   │   ├── aws_scanner.py          # AWS misconfiguration scanner
│   │   ├── azure_scanner.py        # Azure misconfiguration scanner
│   │   ├── oracle_scanner.py       # Oracle Cloud scanner
│   │   ├── k8s_scanner.py          # Kubernetes scanner
│   │   └── live_watch.py           # Continuous watch mode
│   ├── engine/
│   │   ├── chain_builder.py        # Attack chain discovery
│   │   ├── risk_scorer.py          # Risk scoring + compliance
│   │   ├── economics.py            # Attacker economics engine
│   │   ├── chain_dna.py            # Chain DNA fingerprinting
│   │   ├── smart_fix.py            # Auto-remediation suggester
│   │   ├── replay_timeline.py      # Attack replay timeline
│   │   ├── supply_chain.py         # Supply chain detector
│   │   ├── executive_dashboard.py  # Executive report
│   │   ├── auto_retest.py          # Auto-retest engine
│   │   ├── bug_bounty.py           # Bug bounty mode
│   │   ├── zero_trust.py           # Zero trust scorer
│   │   ├── attacker_brain.py       # Attacker brain simulator
│   │   ├── threat_intel.py         # Live threat intelligence
│   │   ├── heatmap.py              # Attack probability heatmap
│   │   ├── benchmarking.py         # Industry benchmarking
│   │   ├── ai_chat.py              # AI security chat
│   │   ├── training_mode.py        # Security training
│   │   ├── gamification.py         # 🆕 XP system & achievements
│   │   ├── nlp_scan.py             # 🆕 Natural language scanner
│   │   ├── evidence_generator.py   # 🆕 Court-ready evidence reports
│   │   ├── geo_tracker.py          # 🆕 Geo attack tracker
│   │   ├── github_pr_review.py     # 🆕 GitHub PR security reviewer
│   │   ├── blast_radius.py         # 🆕 Blast radius calculator
│   │   ├── breach_cost.py          # 🆕 Breach cost estimator
│   │   ├── security_timeline.py    # 🆕 Security posture timeline
│   │   ├── digital_twin.py         # 🆕 Digital twin simulator
│   │   ├── darkweb_monitor.py      # 🆕 Dark web monitor
│   │   └── redblue_sim.py          # 🆕 Red vs Blue simulator
│   ├── ai/
│   │   ├── narrator.py             # AI attack narrative
│   │   ├── predictor.py            # Predictive AI
│   │   └── darkweb.py              # Dark web linker
│   ├── alerts/
│   │   ├── slack_alert.py          # Slack war room
│   │   ├── teams_alert.py          # Teams alerts
│   │   ├── telegram_alert.py       # Telegram alerts
│   │   └── whatsapp_alert.py       # WhatsApp alerts
│   ├── config.py                   # Configuration
│   └── main.py                     # CLI entry point
├── web/                            # Web dashboard
├── docs/                           # Documentation
├── reports/                        # Scan reports & evidence
├── requirements.txt
├── setup.py
└── README.md
```

---

## 🔧 Requirements

```
Python 3.10+
google-cloud-storage
google-cloud-iam
google-cloud-compute
google-cloud-functions
google-auth
boto3
azure-identity
azure-mgmt-storage
azure-mgmt-authorization
oci
google-generativeai
anthropic
rich
click
requests
python-dotenv
schedule
pyfiglet
flask
reportlab          # Optional — for PDF evidence reports
```

---

## 👨‍💻 Author

**Talha Imran**
- 🔐 SOC Analyst | Cloud Security | Pentesting
- 🌐 Website: [cloudsentrix.netlify.app](https://cloudsentrix.netlify.app)
- 💼 LinkedIn: [talha-imran-583a44420](https://www.linkedin.com/in/talha-imran-583a44420)
- 🐙 GitHub: [Talha-Imran-cloud](https://github.com/Talha-Imran-cloud)
- 📦 PyPI: [talha_imran01](https://pypi.org/user/talha_imran01)

---

## 📄 License

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

---

## ⭐ Support

If SkullMap helped you find security issues, please:
- ⭐ **Star this repo** on GitHub
- 🐛 **Report bugs** via Issues
- 🔀 **Submit PRs** for improvements

---

<div align="center">

**💀 SkullMap — See the full attack chain before the attacker does**

*Built with ❤️ by Talha Imran*

</div>
