# AWS Resource Scanner

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)
[![React](https://img.shields.io/badge/React-18.3+-61DAFB.svg)](https://reactjs.org)
[![Flask](https://img.shields.io/badge/Flask-3.0+-000000.svg)](https://flask.palletsprojects.com)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-3178C6.svg)](https://typescriptlang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

一个全栈Web应用，用于扫描AWS账号中的资源信息，并按照Word模板生成专业的项目报告文档。系统支持多账号、多区域并行扫描，具有完整的用户权限管理、任务调度和报告管理功能。

## ✨ 功能特性

### 🔐 用户认证与权限管理
- **JWT令牌认证** - 安全的用户会话管理
- **三级权限控制** - Admin、Power User、User角色
- **细粒度访问控制** - 基于角色的资源访问限制
- **用户管理** - 完整的用户生命周期管理

### 🔑 AWS凭证管理
- **多种认证方式** - 支持IAM Role和Access Key
- **智能Account ID检测** - Access Key类型自动获取账号ID
- **Assume Role支持** - 跨账号安全访问
- **凭证加密存储** - 敏感信息安全保护
- **凭证分配管理** - 灵活的用户-凭证关联

### 🚀 资源扫描引擎
- **多账号并行扫描** - 同时扫描多个AWS账号
- **多区域支持** - 自定义区域选择，自动包含全局资源
- **全面资源覆盖** - 支持30+AWS服务类型
- **异步任务处理** - Celery驱动的后台任务队列

### 📊 智能报告生成
- **Word模板引擎** - 基于专业模板自动生成报告
- **动态内容填充** - 自动替换模板占位符
- **资源分类展示** - 按服务类型组织资源信息
- **项目元数据集成** - 包含完整的项目信息

### 🎨 现代化Web界面
- **响应式设计** - 适配各种设备屏幕
- **实时状态更新** - 任务进度实时显示
- **直观操作界面** - 基于Ant Design的现代UI
- **数据可视化** - 清晰的数据展示和管理
- **Worker监控** - 实时查看Celery Worker状态和任务队列

## 🏗️ 技术架构

### 前端技术栈
- **React 18.3** + **TypeScript 5.6** - 现代化前端框架
- **Ant Design 5.21** - 企业级UI组件库
- **Vite 5.4** - 快速构建工具
- **React Router 6.28** - 单页应用路由
- **Axios 1.7** - HTTP客户端

### 后端技术栈
- **Python 3.8+** + **Flask 3.0** - 轻量级Web框架
- **SQLAlchemy 2.0** - ORM数据库操作
- **Celery 5.3** + **Redis** - 异步任务队列
- **boto3** - AWS SDK
- **python-docx** - Word文档处理
- **PyJWT** - JWT令牌认证

### 数据存储
- **PostgreSQL** (生产环境) - 关系型数据库
- **SQLite3** (开发/测试) - 轻量级数据库
- **Redis** - 缓存和消息队列

## 🚀 快速开始

### 环境要求

- **Python 3.8+**
- **Node.js 18+**
- **Redis** (必需，用于Celery任务队列)

### 1. 克隆项目并准备模板

```bash
git clone https://git.iaun.cn/iaun/cloud-reporter.git
cd cloud-reporter

mkdir sample-reports

# 复制报告模板到 sample-reports 文件夹
copy "[Client Name]-[Project Name]-Project-Report-v1.0.docx" sample-reports/
# Unix/Linux/macOS:
# cp "[Client Name]-[Project Name]-Project-Report-v1.0.docx" sample-reports/
```

### 2. 后端设置

```bash
# 进入后端目录
cd backend

# Windows用户
setup.bat

# Unix/Linux/macOS用户
chmod +x setup.sh && ./setup.sh

# 激活虚拟环境
# Windows:
activate_venv.bat
# Unix/Linux/macOS:
source activate_venv.sh

# 初始化数据库
python init_db.py

# 启动后端服务
python run.py
```

### 3. 启动Celery Worker

```bash
# 新开终端，进入后端目录并激活虚拟环境
cd backend
activate_venv.bat  # Windows
# 或 source activate_venv.sh  # Unix/Linux

# 启动Celery Worker
celery -A celery_worker.celery_app worker --loglevel=info --pool=solo
```

### 4. 前端设置

```bash
# 新开终端，进入前端目录
cd frontend

# Windows用户
setup.bat

# Unix/Linux/macOS用户
chmod +x setup.sh && ./setup.sh

# 启动前端服务
yarn dev
```

### 5. 访问应用

- **前端界面**: http://localhost:3000
- **后端API**: http://localhost:5000
- **默认管理员**: `admin` / `admin123`

## 📁 项目结构

```
cloud-reporter/
├── backend/                    # Python Flask后端
│   ├── app/                   # 应用核心代码
│   │   ├── api/              # REST API路由
│   │   ├── models/           # 数据模型
│   │   ├── services/         # 业务逻辑服务
│   │   ├── scanners/         # AWS扫描器模块
│   │   │   ├── services/    # 各服务扫描器实现
│   │   │   └── DEVELOPMENT_GUIDE.md  # 扫描器开发指南
│   │   ├── tasks/            # Celery异步任务
│   │   └── utils/            # 工具函数
│   ├── config/               # 配置文件
│   ├── migrations/           # 数据库迁移
│   ├── tests/                # 测试文件
│   ├── instance/             # 实例数据(数据库等)
│   ├── uploads/              # 上传文件存储
│   ├── reports/              # 生成的报告文件
│   └── requirements.txt      # Python依赖
├── frontend/                  # React前端
│   ├── src/                  # 源代码
│   │   ├── components/       # React组件
│   │   ├── pages/           # 页面组件
│   │   ├── services/        # API服务
│   │   ├── contexts/        # React Context
│   │   └── utils/           # 工具函数
│   ├── public/              # 静态资源
│   └── package.json         # 项目配置
├── sample-reports/           # 示例报告模板
├── .gitignore               # Git忽略文件
└── README.md                # 项目说明
```

## 🔧 配置说明

### 后端环境变量 (.env)

```env
# Flask配置
FLASK_ENV=development
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here

# 数据库配置
DATABASE_URL=sqlite:///dev.db
# 生产环境使用PostgreSQL:
# DATABASE_URL=postgresql://user:password@localhost/dbname

# Celery配置
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/1

# 加密密钥
ENCRYPTION_KEY=your-encryption-key-here

# 文件存储
UPLOAD_FOLDER=uploads
REPORTS_FOLDER=reports
```

### 前端环境变量 (.env.local)

```env
# API配置
VITE_API_BASE_URL=http://localhost:5000

# 应用配置
VITE_APP_TITLE=AWS Resource Scanner
VITE_DEBUG=true
```

## 📋 支持的AWS服务

### 网络服务
- **VPC**: VPCs, Subnets, Route Tables, Internet Gateways, NAT Gateways
- **安全**: Security Groups, VPC Endpoints, VPC Peering Connections
- **VPN**: Customer Gateways, Virtual Private Gateways, VPN Connections

### 计算服务
- **EC2**: Instances (含EBS卷、AMI信息), Elastic IPs
- **Auto Scaling**: Auto Scaling Groups (含Launch Templates)
- **EKS**: Kubernetes集群

### 负载均衡
- **ELB**: Application/Network/Classic Load Balancers, Target Groups

### 数据库服务
- **RDS**: 数据库实例
- **ElastiCache**: 缓存集群

### 存储服务
- **S3**: 存储桶, S3事件通知

### 无服务器
- **Lambda**: 函数

### 全局服务
- **CloudFront**: 分发 (全局)
- **Route 53**: 托管区域 (全局)
- **ACM**: SSL证书 (全局，当未选择us-east-1时自动在us-east-1扫描)
- **WAF**: Web应用防火墙 (全局)

### 监控和日志
- **CloudWatch**: 日志组
- **EventBridge**: 事件规则
- **CloudTrail**: 审计跟踪
- **Config**: 配置记录器

### 消息服务
- **SNS**: 主题和订阅

## 🔐 权限模型

### 角色定义

| 角色 | 权限范围 |
|------|----------|
| **Admin** | 系统全部权限：用户管理、凭证管理、所有报告、Worker管理 |
| **Power User** | 使用所有凭证、查看所有报告、创建扫描任务 |
| **User** | 仅使用分配的凭证、查看自己的报告、创建扫描任务 |

### 访问控制

- **用户认证**: JWT令牌机制，支持令牌刷新
- **权限验证**: 基于角色的访问控制(RBAC)
- **数据隔离**: 用户只能访问授权的资源
- **API保护**: 所有API端点都有权限验证

## 🛠️ 开发指南

### 扫描器开发

添加新的AWS服务扫描器时，请参考 [扫描器开发指南](backend/app/scanners/DEVELOPMENT_GUIDE.md)，其中包含：
- 架构概述和目录结构
- 添加新服务扫描器的完整步骤
- 代码规范和命名约定
- 错误处理和重试机制
- 测试要求和检查清单

### 后端开发

```bash
cd backend

# 激活虚拟环境
activate_venv.bat  # Windows
source activate_venv.sh  # Unix/Linux

# 启动开发服务器
python run.py

# 运行测试
pytest

# 数据库操作
python init_db.py --reset      # 重置数据库
python init_db.py --with-demo  # 创建示例数据

# 启动Celery Worker (必需，用于任务处理)
celery -A celery_worker.celery_app worker --loglevel=info --pool=solo
```

### 前端开发

```bash
cd frontend

# 启动开发服务器
yarn dev

# 构建生产版本
yarn build

# 运行测试
yarn test

# 代码检查
yarn lint

# 类型检查
npx tsc --noEmit
```

### API文档

#### 认证接口
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/refresh` - 刷新令牌
- `POST /api/auth/logout` - 用户登出
- `GET /api/auth/me` - 获取当前用户信息

#### 用户管理 (Admin)
- `GET /api/users` - 获取用户列表
- `POST /api/users/create` - 创建用户
- `POST /api/users/update` - 更新用户
- `POST /api/users/delete` - 删除用户

#### 凭证管理
- `GET /api/credentials` - 获取凭证列表
- `POST /api/credentials/create` - 创建凭证
- `POST /api/credentials/update` - 更新凭证
- `POST /api/credentials/delete` - 删除凭证

#### 任务管理
- `GET /api/tasks` - 获取任务列表
- `POST /api/tasks/create` - 创建扫描任务
- `GET /api/tasks/detail` - 获取任务详情
- `POST /api/tasks/delete` - 删除任务

#### 报告管理
- `GET /api/reports` - 获取报告列表
- `GET /api/reports/download` - 下载报告
- `POST /api/reports/delete` - 删除报告

#### Worker管理 (Admin)
- `GET /api/workers` - 获取Worker列表和状态
- `GET /api/workers/stats` - 获取Worker统计信息
- `POST /api/workers/purge` - 清空任务队列
- `POST /api/workers/revoke` - 取消指定任务

## 🧪 测试

### 运行测试

```bash
# 后端测试
cd backend
pytest

# 前端测试
cd frontend
yarn test

# 覆盖率测试
pytest --cov=app
yarn test --coverage
```

### 测试类型

- **单元测试**: 组件功能测试
- **集成测试**: API端点测试
- **属性测试**: 基于Hypothesis的属性验证
- **端到端测试**: 完整流程测试

## 📦 部署

### 生产环境部署

#### 后端部署

1. **环境准备**
```bash
# 安装PostgreSQL和Redis
sudo apt-get install postgresql redis-server

# 创建数据库
sudo -u postgres createdb aws_scanner
```

2. **应用部署**
```bash
# 设置生产环境变量
export FLASK_ENV=production
export DATABASE_URL=postgresql://user:pass@localhost/aws_scanner

# 安装依赖
pip install -r requirements.txt

# 数据库迁移
flask db upgrade

# 使用Gunicorn启动
gunicorn -w 4 -b 0.0.0.0:5000 run:app
```

3. **Celery Worker**
```bash
# 启动Celery Worker
celery -A celery_worker worker --loglevel=info --concurrency=4
```

#### 前端部署

```bash
# 构建生产版本
yarn build

# 部署到Nginx
sudo cp -r dist/* /var/www/html/
```

### Docker部署

```bash
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d
```

## 🔍 故障排除

### CloudShell Scanner (独立扫描工具)

除了完整的Web应用外，项目还提供了一个独立的CloudShell扫描脚本 `cloudshell_scanner.py`，可以直接在AWS CloudShell环境中运行，无需配置Access Key。

#### 功能特点
- **单文件脚本** - 仅依赖boto3和Python标准库
- **自动使用CloudShell IAM凭证** - 无需配置Access Key
- **多区域扫描** - 支持指定区域或扫描所有可用区域
- **进度显示** - 实时显示扫描进度
- **错误处理** - 自动重试和错误记录

#### 使用方法

```bash
# 在AWS CloudShell中运行

# 扫描所有区域
python cloudshell_scanner.py

# 扫描指定区域
python cloudshell_scanner.py --regions us-east-1,ap-northeast-1

# 指定输出文件
python cloudshell_scanner.py --output my_scan.json

# 扫描指定服务
python cloudshell_scanner.py --services ec2,vpc,rds
```

#### 支持的服务
与Web应用支持相同的30+AWS服务类型，包括VPC、EC2、RDS、S3、Lambda、EKS等。

#### 输出格式
扫描结果以JSON格式输出，可直接上传到Web应用生成报告。

### 常见问题

#### 后端问题

1. **虚拟环境问题**
```bash
# 重新创建虚拟环境
python setup_venv.py --clean
```

2. **数据库连接失败**
```bash
# 检查数据库配置
python verify_setup.py
```

3. **Celery Worker无法启动**
```bash
# 检查Redis连接
redis-cli ping

# 确保使用正确的启动命令
celery -A celery_worker.celery_app worker --loglevel=info --pool=solo
```

#### 前端问题

1. **依赖安装失败**
```bash
# 清理并重新安装
yarn cache clean
rm -rf node_modules yarn.lock
yarn install
```

2. **构建失败**
```bash
# 检查TypeScript错误
npx tsc --noEmit
```

### 日志查看

```bash
# 后端日志
tail -f backend/logs/app.log

# Celery日志
tail -f backend/logs/celery.log

# 前端开发日志
# 在浏览器开发者工具中查看
```

## 🤝 贡献指南

1. Fork项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

### 代码规范

- **Python**: 遵循PEP 8规范
- **TypeScript**: 使用ESLint和Prettier
- **提交信息**: 使用约定式提交格式

## 📄 许可证

本项目采用MIT许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Flask](https://flask.palletsprojects.com/) - Web框架
- [React](https://reactjs.org/) - 前端框架
- [Ant Design](https://ant.design/) - UI组件库
- [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) - AWS SDK
- [Celery](https://docs.celeryproject.org/) - 分布式任务队列

## 📞 支持

如果您遇到问题或有疑问，请：

查看[故障排除](#-故障排除)部分

---

**AWS Resource Scanner** - 让AWS资源管理变得简单高效 🚀