# 🛡️ CloudScope - 企业级云安全态势管理 (CSPM)
选择您的语言 / Dilinizi seçin:
* [🇹🇷 Türkçe](#-türkçe)
* [🇺🇸 English](#-english)
# 🇹🇷 土耳其语
CloudScope, bulut altyapınızın güvenliğini gerçek zamanlı olarak izleyen, analiz eden ve iyileştirme önerileri sunan kapsamlı ve modern bir **Cloud Security Posture Management (CSPM)** platformudur. AWS, Azure, GCP ve On-Premise Docker ortamlarınızı endüstri standartlarına (CIS, GDPR, HIPAA, PCI-DSS) göre denetler ve **Yapay Zeka (GPT-4o)** destekli çözüm önerileriyle güvenlik risklerinizi minimize eder.
## 📋 目录
1. [✨ Temel Özellikler](#temel-özellikler)
2. [🛠️ Teknoloji Yığını](#teknoloji-yığını)
3. [📂 Proje Yapısı](#proje-yapısı)
4. [🚀 Kurulum ve Yapılandırma](#kurulum-ve-yapılandırma)
- [Gereksinimler](#gereksinimler)
- [1. Depoyu Klonlayın](#1-depoyu-klonlayın)
- [2. Backend Kurulumu](#2-backend-kurulumu)
- [3. Frontend Kurulumu](#3-frontend-kurulumu)
5. [💻 Çalıştırma Yöntemleri](#çalıştırma-yöntemleri)
- [Yöntem A: Tek Tuşla Başlatma (Önerilen)](#yöntem-a-tek-tuşla-başlatma-önerilen)
- [Yöntem B: Manuel Başlatma](#yöntem-b-manuel-başlatma)
- [Yöntem C: Docker Compose ile Dağıtım](#yöntem-c-docker-compose-ile-dağıtım)
6. [⚙️ Ortam Değişkenleri (Environment Variables)](#ortam-değişkenleri)
7. [🔌 Önemli API Uç Noktaları (Endpoints)](#önemli-api-uç-noktaları)
8. [🔒 Güvenlik & Gizlilik Mimarisi](#güvenlik--gizlilik-mimarisi)
9. [📄 Lisans](#lisans)
### ✨ 核心功能
* **🌐 Çoklu Bulut (Multi-Cloud) Desteği:** Tek bir arayüzden **AWS**, **Azure** ve **GCP** hesaplarınızı bağlayın. AWS için güvenli **IAM Role (STS Cross-Account)** kimlik doğrulamasını veya AES-256 şifreli API anahtarlarını kullanabilirsiniz.
* **🐳 Zero-Trust Ajan Taraması:** Güvenlik duvarınızı (firewall) açmadan On-Premise veya izole Docker/Kubernetes ortamlarınızı "CloudScope Agent" üzerinden token tabanlı güvenli webhook mimarisiyle (Push-based) denetleyin.
* **💻 IaC & Shift-Left Güvenliği:** Altyapı kodlarınızı (Terraform `.tf` / CloudFormation) sunucuya deploy edilmeden önce **Checkov** motoru ile tarayıp zafiyetleri erken aşamada yakalayın.
* **🤖 AI Destekli İyileştirme (Auto-Fix):** Güvenlik açıklarını sadece tespit etmekle kalmaz, OpenAI GPT-4o kullanarak "Nasıl Çözerim?" adımlarını ve hazır CLI komutlarını üretir.
* **📊 Varlık Envanteri (Asset Inventory):** Bulut ortamınızdaki tüm sunucuları, veritabanlarını, diskleri ve ağ bileşenlerini tek bir envanter ekranından merkezi olarak takip edin.
* **🔐 Rol Bazlı Erişim Kontrolü (RBAC):** `Admin`, `Analyst` ve `Viewer` rolleriyle organizasyonunuzu yönetin. Ayrıca takım arkadaşlarınızı (Invite User) davet ederek takım çalışması yürütebilirsiniz.
* **🌙 Gece Taramaları & Otomasyon:** APScheduler entegrasyonu sayesinde hesaplarınız her gece otomatik taranır. Yeni bir kritik bulgu tespit edildiğinde **Slack** veya **MS Teams Webhook** üzerinden anında ekibinize bildirilir.
* **🛡️ Prowler Entegrasyonu:** Endüstri lideri Prowler aracını kullanarak tam kapsamlı derin güvenlik (500+ Kontrol) denetimleri gerçekleştirin.
* **📉 Uyumluluk & Trend Analizi (Compliance):** Geçmiş taramalarla mevcut taramaları kıyaslayarak (Delta) risk gidişatını (Trend) gözlemleyin. Ayrıca CIS, GDPR, HIPAA, PCI-DSS uyumluluk oranlarınızı dashboard üzerinden anlık görün.
* **📄 Executive PDF Raporlama:** Yönetim ve denetim ekipleri için tek tuşla yönetici özet (Executive Summary) PDF raporları oluşturun.
### 🛠️ 技术栈
#### Frontend
* **React 19 & TypeScript:** Modern ve tip güvenli UI geliştirme.
* **Vite:** Ultra hızlı geliştirme ve build süreci.
* **Tailwind CSS:** Esnek, responsive ve modern arayüz tasarımı.
* **Framer Motion:** Akıcı, dinamik ve premium animasyonlar.
* **Recharts:** Veri görselleştirme, trend grafikleri ve uyumluluk metrikleri.
#### Backend
* **FastAPI (Python):** Yüksek performanslı, asenkron ve standart API sunucusu.
* **SQLAlchemy & Alembic:** Veritabanı yönetim, ORM ve geçiş (migration) katmanı.
* **APScheduler:** Zamanlanmış arka plan görevleri ve otomatik taramalar.
* **Boto3 (STS Destekli) & Azure SDK & GCP Client:** Cloud platformlarıyla doğrudan SDK entegrasyonu.
* **Prowler & Checkov:** Güvenlik ve IaC denetimi motorları.
* **ReportLab:** Sunucu tabanlı kurumsal PDF rapor üretimi.
* **SlowAPI:** Rate limiting (İstek sınırlandırma) sistemi.
### 📂 项目结构
```
CloudScope/
├── backend/ # FastAPI Backend Servisi
│ ├── alembic/ # Veritabanı Migrations (Geçiş Dosyaları)
│ ├── services/ # Çekirdek Analiz ve Hesaplama Servisleri
│ │ ├── report_generator.py # PDF Rapor Üretim Motoru (ReportLab)
│ │ └── risk_engine.py # Risk Puanı Hesaplama Motoru
│ ├── ai_remediation.py # OpenAI GPT-4o ile Çözüm Önerisi Üretimi
│ ├── aws_scanner.py # AWS Kaynak Taraması (Boto3)
│ ├── azure_scanner.py # Azure Kaynak Taraması
│ ├── gcp_scanner.py # GCP Kaynak Taraması
│ ├── docker_scanner.py # On-Premise / Docker Ajan Taraması
│ ├── iac_scanner.py # IaC Terraform Güvenlik Analizi (Checkov)
│ ├── prowler_scanner.py # Detaylı Prowler Analiz Tetikleyicisi
│ ├── scheduler.py # APScheduler Zamanlanmış Görevleri
│ ├── main.py # API Giriş Noktası ve Yönlendiriciler
│ ├── database.py # SQLite/PostgreSQL Bağlantısı ve ORM Modelleri
│ ├── requirements.txt # Python Bağımlılıkları Listesi
│ └── alembic.ini # Alembic Yapılandırma Dosyası
├── src/ # React Frontend Servisi
│ ├── components/ # Yeniden Kullanılabilir UI Bileşenleri (Sidebar, Layout vs.)
│ ├── pages/ # Uygulama Sayfaları (Dashboard, Scan, Inventory vs.)
│ ├── services/ # API Entegrasyon Katmanı ve İstekler
│ ├── assets/ # Statik Görseller ve İkonlar
│ ├── App.tsx # Ana Uygulama Bileşeni ve Rotalar
│ └── main.tsx # Uygulama Başlangıç Dosyası
├── Dockerfile # Backend için Dockerfile
├── Dockerfile.frontend # Frontend için Dockerfile
├── docker-compose.yml # Geliştirme Ortamı Docker Compose Yapılandırması
├── docker-compose.prod.yml # Canlı Ortam Docker Compose Yapılandırması
├── start.sh # Backend ve Frontend'i Birlikte Başlatan Bash Betiği
└── README.md # Proje Dokümantasyonu
```
### 🚀 安装与配置
#### 要求
Projeyi yerel makinenizde çalıştırmak için aşağıdaki araçların yüklü olması gerekir:
* **Python 3.10+**
* **Node.js 18+ & npm**
* **Docker & Docker Compose**
#### 1. 克隆仓库
```
git clone https://github.com/your-username/CloudScope.git
cd CloudScope
```
#### 2. Backend 设置
```
cd backend
python3 -m venv .venv
source .venv/bin/activate # Windows için: .venv\Scripts\activate
pip install -r requirements.txt
```
Ortam değişkenlerini yapılandırmak için `.env.example` dosyasını `.env` olarak kopyalayın ve gerekli değerleri doldurun:
```
cp .env.example .env
```
#### 3. Frontend 设置
```
cd ..
npm install
```
### 💻 运行方式
#### 方式 A：一键启动（推荐）
Geliştirme aşamasında hem frontend hem de backend uygulamasını aynı anda başlatmak için `start.sh` betiğini kullanabilirsiniz:
```
chmod +x start.sh
npm start
# 或直接：./start.sh
```
#### 方式 B：手动启动
##### 1. 启动 Backend 服务：
```
cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000
```
##### 2. 启动 Frontend 服务：
```
cd ..
npm run dev
```
#### 方式 C：使用 Docker Compose 部署
##### 开发环境：
```
docker-compose up --build
```
##### 生产环境：
```
docker-compose -f docker-compose.prod.yml up --build -d
```
### ⚙️ 环境变量
#### Backend 配置（`backend/.env`）
| Değişken | Açıklama | Varsayılan Değer |
| :--- | :--- | :--- |
| `DATABASE_URL` | Veritabanı bağlantı adresi | `sqlite:///./cloudscope.db` |
| `JWT_SECRET` | Token şifreleme için kullanılan gizli anahtar | `your-very-secret-key-...` |
| `JWT_ALGORITHM` | Şifreleme algoritması | `HS256` |
| `JWT_EXPIRE_MINUTES` | Token geçerlilik süresi (dakika) | `1440` |
| `APP_ENV` | Çalışma ortamı (`development`/`production`) | `development` |
| `OPENAI_API_KEY` | OpenAI API Key (AI Auto-Fix için) | *(İsteğe bağlı)* |
| `SLACK_WEBHOOK_URL` | Alarm bildirimleri için Slack URL | *(İsteğe bağlı)* |
### 🔌 重要 API 端点
Swagger dokümantasyonunu `http://localhost:8000/docs` adresinden inceleyebilirsiniz.
#### 身份验证与用户管理
* `POST /api/auth/register` - Kayıt oluşturur.
* `POST /api/auth/login` - Giriş yapar ve JWT Token döner.
* `GET /api/auth/me` - Aktif profil bilgilerini döner.
* `POST /api/users/invite` - Yeni takım üyesi davet eder.
#### 云账户
* `GET /api/accounts` - Tanımlı bulut hesaplarını listeler.
* `POST /api/accounts/aws` / `azure` / `gcp` - İlgili bulut hesabını ekler.
#### 扫描与发现
* `POST /api/scans` - Tarama tetikler (QUICK / FULL).
* `POST /api/scans/iac` - Terraform dosyası üzerinde IaC analizi yapar.
* `GET /api/findings` - Güvenlik açıklarını listeler.
* `POST /api/findings/{finding_id}/auto-fix` - AI destekli iyileştirme çözümü üretir.
* `PATCH /api/findings/{finding_id}/dismiss` - Bulguyu yoksayar/onaylar.
* `GET /api/findings/export/pdf` - Bulguların PDF raporunu indirir.
### 🔒 安全与隐私架构
* **Veri Gizliliği:** Tanımlanan tüm bulut API Anahtarları ve gizli şifreler veritabanında **AES-256 Fernet** standardı kullanılarak şifrelenmiş olarak depolanır.
* **STS Assume Role:** AWS entegrasyonlarında uzun ömürlü AWS IAM anahtarları paylaşmak yerine geçici oturum anahtarları üreten güvenli AWS STS Assume Role mimarisi desteklenmektedir.
* **Zero-Trust Ajanı:** Docker tarayıcısı, dışarıdan erişilemeyen izole iç ağlardaki verileri CloudScope API'sine push-based mimariyle ileterek port açma gereksinimini ortadan kaldırır.
### 📄 许可证
Bu proje **MIT Lisansı** altında lisanslanmıştır.
# 🇺🇸 英语
CloudScope is a comprehensive and modern **Cloud Security Posture Management (CSPM)** platform that monitors, analyzes, and provides remediation suggestions for your cloud infrastructure in real-time. It audits AWS, Azure, GCP, and On-Premise Docker environments against industry standards (CIS, GDPR, HIPAA, PCI-DSS) and minimizes security risks using AI (GPT-4o) powered remediation steps.
## 📋 目录
1. [✨ Core Features](#core-features)
2. [🛠️ Technology Stack](#technology-stack)
3. [📂 Project Structure](#project-structure)
4. [🚀 Installation and Configuration](#installation-and-configuration)
- [Requirements](#requirements-1)
- [1. Clone the Repository](#1-clone-the-repository)
- [2. Backend Setup](#2-backend-setup)
- [3. Frontend Setup](#3-frontend-setup)
5. [💻 Running Methods](#running-methods)
- [Method A: One-Click Startup (Recommended)](#method-a-one-click-startup-recommended)
- [Method B: Manual Startup](#method-b-manual-startup)
- [Method C: Deployment with Docker Compose](#method-c-deployment-with-docker-compose)
6. [⚙️ Environment Variables](#environment-variables-1)
7. [🔌 Key API Endpoints](#key-api-endpoints)
8. [🔒 Security & Privacy Architecture](#security--privacy-architecture)
9. [📄 License](#license-1)
### ✨ 核心功能
* **🌐 Multi-Cloud Support:** Connect your **AWS**, **Azure**, and **GCP** accounts through a single UI. **IAM Role (STS Cross-Account)** authentication or AES-256 encrypted API keys can be used for AWS integration.
* **🐳 Zero-Trust Agent Scanning:** Audit your On-Premise or isolated Docker/Kubernetes environments securely using "CloudScope Agent" via a token-based push webhook architecture, removing the need to modify firewalls.
* **💻 IaC & Shift-Left Security:** Scan infrastructure-as-code files (Terraform `.tf` / CloudFormation) using **Checkov** before deployment to catch vulnerabilities early.
* **🤖 AI-Powered Remediation (Auto-Fix):** Generates remediation steps and ready-to-run CLI commands using OpenAI GPT-4o instead of just identifying vulnerabilities.
* **📊 Asset Inventory:** Centralized tracking for all servers, databases, disks, and network components.
* **🔐 Role-Based Access Control (RBAC):** Manage your organization with `Admin`, `Analyst`, and `Viewer` roles. Invite team members (Invite User) to work collaboratively.
* **🌙 Scheduled Scans & Automation:** Accounts are scanned automatically every night using APScheduler. Slack or MS Teams Webhooks notify your team immediately when a new critical finding is detected.
* **🛡️ Prowler Integration:** Run deep, full-scale security checks (500+ controls) using the industry-leading Prowler auditing tool.
* **📉 Compliance & Trend Analysis:** Track your security posture progress by comparing past and current scans (delta). View CIS, GDPR, HIPAA, and PCI-DSS compliance metrics in real-time.
* **📄 Executive PDF Reporting:** Create one-click corporate Executive Summary PDF reports for management and auditing teams.
### 🛠️ 技术栈
#### Frontend
* **React 19 & TypeScript:** Modern and type-safe UI development.
* **Vite:** Ultra-fast development and build process.
* **Tailwind CSS:** Responsive, modern, and utility-first design.
* **Framer Motion:** Smooth, dynamic, and premium animations.
* **Recharts:** Interactive compliance charts and trend graphs.
#### Backend
* **FastAPI (Python):** High-performance, asynchronous REST API.
* **SQLAlchemy & Alembic:** Database management, ORM, and migration layer.
* **APScheduler:** Scheduled background tasks and scan automation.
* **Boto3 (STS Support) & Azure SDK & GCP Client:** Cloud platform SDK integrations.
* **Prowler & Checkov:** Security and IaC auditing engines.
* **ReportLab:** Server-side corporate PDF report generator.
* **SlowAPI:** Rate limiting system.
### 📂 项目结构
```
CloudScope/
├── backend/ # FastAPI Backend Service
│ ├── alembic/ # Database Migrations
│ ├── services/ # Core Scan & Risk Engines
│ │ ├── report_generator.py # PDF Report Generator (ReportLab)
│ │ └── risk_engine.py # Risk Score Calculation Engine
│ ├── ai_remediation.py # OpenAI GPT-4o Remediation Generator
│ ├── aws_scanner.py # AWS Resource Scanner (Boto3)
│ ├── azure_scanner.py # Azure Resource Scanner
│ ├── gcp_scanner.py # GCP Resource Scanner
│ ├── docker_scanner.py # On-Premise / Docker Agent Scanner
│ ├── iac_scanner.py # IaC Terraform Security Scanner (Checkov)
│ ├── prowler_scanner.py # Prowler Security Check Trigger
│ ├── scheduler.py # APScheduler Task Automations
│ ├── main.py # API Entrypoint & Routers
│ ├── database.py # SQLite/PostgreSQL Setup & ORM Models
│ ├── requirements.txt # Python Dependencies
│ └── alembic.ini # Alembic Config
├── src/ # React Frontend Service
│ ├── components/ # Reusable UI components (Sidebar, Layout, etc.)
│ ├── pages/ # Page Components (Dashboard, Scan, Inventory, etc.)
│ ├── services/ # API Integration Layer
│ ├── assets/ # Static Images & Icons
│ ├── App.tsx # Main Application & Router
│ └── main.tsx # App Bootstrap
├── Dockerfile # Backend Dockerfile
├── Dockerfile.frontend # Frontend Dockerfile
├── docker-compose.yml # Dev Docker Compose Configuration
├── docker-compose.prod.yml # Production Docker Compose Configuration
├── start.sh # Bash Script to Run Frontend & Backend Simultaneously
└── README.md # Project Documentation
```
### 🚀 安装与配置
#### 要求
To run this project locally, you need the following installed:
* **Python 3.10+**
* **Node.js 18+ & npm**
* **Docker & Docker Compose**
#### 1. 克隆仓库
```
git clone https://github.com/your-username/CloudScope.git
cd CloudScope
```
#### 2. Backend 设置
```
cd backend
python3 -m venv .venv
source .venv/bin/activate # For Windows: .venv\Scripts\activate
pip install -r requirements.txt
```
To configure environments, copy `.env.example` as `.env` and fill in the parameters:
```
cp .env.example .env
```
#### 3. Frontend 设置
```
cd ..
npm install
```
### 💻 运行方式
#### 方式 A：一键启动（推荐）
You can use the `start.sh` script to run both frontend and backend concurrently in development:
```
chmod +x start.sh
npm start
# 或直接：./start.sh
```
#### 方式 B：手动启动
##### 1. 启动 Backend：
```
cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000
```
##### 2. 启动 Frontend：
```
cd ..
npm run dev
```
#### 方式 C：使用 Docker Compose 部署
##### 开发环境：
```
docker-compose up --build
```
##### 生产环境：
```
docker-compose -f docker-compose.prod.yml up --build -d
```
### ⚙️ 环境变量
#### Backend 配置（`backend/.env`）
| Variable | Description | Default Value |
| :--- | :--- | :--- |
| `DATABASE_URL` | Database connection string | `sqlite:///./cloudscope.db` |
| `JWT_SECRET` | Secret key for JWT encryption | `your-very-secret-key-...` |
| `JWT_ALGORITHM` | Encryption algorithm | `HS256` |
| `JWT_EXPIRE_MINUTES` | Token expiration duration (minutes) | `1440` |
| `APP_ENV` | Application environment (`development`/`production`) | `development` |
| `OPENAI_API_KEY` | OpenAI API Key (for AI Auto-Fix recommendations) | *(Optional)* |
| `SLACK_WEBHOOK_URL` | Slack Webhook URL for real-time security alerts | *(Optional)* |
### 🔌 重要 API 端点
Interactive Swagger documentation is available at `http://localhost:8000/docs`.
#### 身份验证与用户管理
* `POST /api/auth/register` - Creates a new user profile.
* `POST /api/auth/login` - Authenticates user and returns a JWT.
* `GET /api/auth/me` - Returns active session profile.
* `POST /api/users/invite` - Invites a new team member via email.
#### 云账户
* `GET /api/accounts` - Lists all connected cloud accounts.
* `POST /api/accounts/aws` / `azure` / `gcp` - Connects a new cloud account.
#### 扫描与发现
* `POST /api/scans` - Triggers a scan (QUICK / FULL).
* `POST /api/scans/iac` - Performs IaC static check on Terraform files.
* `GET /api/findings` - Returns list of all vulnerability findings.
* `POST /api/findings/{finding_id}/auto-fix` - Generates AI remediation.
* `PATCH /api/findings/{finding_id}/dismiss` - Dismisses or ignores a finding.
* `GET /api/findings/export/pdf` - Generates and downloads scan report as PDF.
### 🔒 安全与隐私架构
* **Data Protection:** Cloud API Keys and Client Secrets are stored encrypted in the database using the **AES-256 Fernet** encryption library.
* **STS Assume Role:** For AWS scanner connection, using short-lived temporary session tokens generated via AWS STS Assume Role is supported instead of hardcoding persistent IAM keys.
* **Zero-Trust Agent:** The On-Premise Docker Agent uses a push-based model. It sends collected metadata directly to the CloudScope API, eliminating the need to expose public ingress ports on your local firewalls.
### 📄 许可证
This project is licensed under the **MIT License**.