EmaConor/PoC
GitHub: EmaConor/PoC
一个基于 Flask 构建的安全登录概念验证应用，通过深度防御策略演示生产级别的用户身份验证标准与安全编码实践。
Stars: 0 | Forks: 0
# 安全登录 PoC
这是一个用于演示用户身份验证行业标准的 Web 应用概念验证。它基于 Flask 构建，展示了如何通过深度防御实现一个可用于生产环境的登录系统。
[阅读西班牙语版本](README.es.md)
## 关于本项目
本项目由 Equipo SECURITY 开发，是网络安全学习实践的一部分。其目的是说明如何通过安全编码实践来缓解常见的 Web 漏洞，而无需依赖第三方身份验证服务。
每一层——从数据库查询到 HTTP 响应头——都经过了刻意的强化，可作为安全 Flask 开发的参考实现。
## 演示的安全特性
| # | 控制 | 实现 |
|---|---------|---------------|
| 1 | 防止 SQL 注入 | 通过 SQLAlchemy 进行基于 ORM 的查询 (`User.query.filter_by()`) |
| 2 | 密码哈希 | Werkzeug `generate_password_hash` / `check_password_hash` (pbkdf2:sha256) |
| 3 | 输入验证 | 白名单正则表达式 `^[a-zA-Z0-9_.]+$`，最大长度为 50 |
| 4 | 速率限制 | Flask-Limiter（每个 IP 每天 200 次请求，每小时 50 次） |
| 5 | 安全会话 Cookie | `HttpOnly`, `Secure`, `SameSite=Lax` |
| 6 | 安全 HTTP 标头 | CSP, X-XSS-Protection, X-Frame-Options, HSTS |
| 7 | TLS 终止 | 使用 HTTPS 的 Nginx 反向代理（用于开发的自签名证书） |
| 8 | 最小权限 (Docker) | 容器内的非 root 用户 `appuser` |
| 9 | 访问控制 | 受保护路由上的 `@login_required` 装饰器 |
| 10 | 无硬编码机密 | 从环境变量获取 `SECRET_KEY` |
## 构建技术
- **Flask 3.0** -- Web 框架
- **Flask-SQLAlchemy 3.1** -- ORM 和数据库管理
- **Flask-Login 0.6** -- 用户会话管理
- **Flask-Limiter 3.7** -- 速率限制
- **Werkzeug 3.0** -- 密码哈希工具
- **Gunicorn 22** -- 生产环境 WSGI 服务器
- **Nginx** -- 带 TLS 终止的反向代理
- **Docker / Docker Compose** -- 容器化与编排
- **SQLite** -- 数据库引擎（开发环境）
## 快速开始
### 前置条件
- Python 3.11 或更高版本
- pip (Python 包管理器)
- （可选）Docker 和 Docker Compose
### 安装说明
请按照以下步骤在本地运行应用程序：
**1. 克隆仓库**
```
git clone https://github.com/EmaConor/PoC.git
cd PoC
```
**2. 创建并激活虚拟环境**
```
python -m venv venv
```
- Windows (PowerShell):
.\venv\Scripts\Activate.ps1
- Linux / macOS:
source venv/bin/activate
**3. 安装依赖**
```
pip install -r requirements.txt
```
**4. 配置环境变量**
复制示例环境文件并调整相关值：
```
cp .env.example .env
```
打开 `.env` 并配置以下变量：
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `SECRET_KEY` | 用于会话签名和 CSRF token。请生成一个强随机密钥。 | `change-this-to-a-random-secret-key` |
| `DATABASE_URL` | 数据库连接字符串。开发环境使用 SQLite 路径，生产环境使用 PostgreSQL/MySQL。 | `sqlite:///app.db` |
| `FLASK_ENV` | 应用程序环境。设置为 `development` 用于调试模式，或设置为 `production` 用于强化配置。 | `development` |
**5. 初始化数据库**
这将创建所有数据表并插入测试用户：
```
python init_db.py
```
**6. 运行应用程序**
```
python app.py
```
服务器将在 **http://127.0.0.1:5000** 启动。
### 使用 Docker 运行
若要使用 Nginx 和 HTTPS 运行类似生产环境：
```
docker-compose up --build -d
docker-compose exec web python init_db.py
```
这将启动两个容器：
- **web** -- 运行在 5000 端口（仅限内部）的 Gunicorn 上的 Flask 应用程序
- **nginx** -- 在 80 和 443 端口上具有 TLS 的反向代理
访问 **https://localhost** 即可使用该应用程序。
## 默认凭据
种子脚本会创建以下测试用户：
| 用户名 | 密码 | 角色 |
|----------|----------|------|
| admin | admin123 | admin |
| ema | emaema | user |
| yuri | yuri123 | user |
| gene | gene123 | user |
## API Endpoints
| 路由 | 方法 | 描述 | 需要身份验证 |
|-------|--------|-------------|---------------|
| `/` | GET, POST | 登录页面。POST 提交凭据进行身份验证。 | 否 |
| `/dashboard` | GET | 显示已登录用户信息的受保护仪表板。 | 是 |
| `/logout` | GET | 终止会话并重定向到登录页面。 | 是 |
## 项目结构
```
PoC/
├── app.py # Flask application entry point (routes, security headers, rate limiting)
├── config.py # Configuration classes (Development, Production)
├── models.py # SQLAlchemy User model with password hashing
├── init_db.py # Database seeder (creates tables + test users)
├── requirements.txt # Python dependencies
├── .env # Environment variables (not committed)
├── .env.example # Environment variable template
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Docker Compose orchestration (Flask + Nginx)
├── nginx/
│ ├── nginx.conf # Nginx configuration (HTTPS, reverse proxy)
│ └── certs/ # SSL certificates (self-signed for development)
├── templates/
│ ├── login.html # Login form template
│ └── dashboard.html # Dashboard template
└── instance/
└── app.db # SQLite database file (generated at runtime)
```
## 配置
### 环境变量
所有运行时配置均从 `.env` 文件加载（参见 `.env.example`）：
- **SECRET_KEY** -- 用于加密签名的随机字符串。在生产环境中必填。
- **DATABASE_URL** -- 数据库 URI。默认为 `sqlite:///app.db`。
- **FLASK_ENV** -- 控制 `development` 与 `production` 模式。在生产模式下，调试被禁用，测试关闭，并启用 CSRF 保护。
### 配置类
在 `config.py` 中定义：
| 设置 | Development | Production |
|---------|-------------|------------|
| DEBUG | True | False |
| TESTING | True | False |
| WTF_CSRF_ENABLED | False | True |
| TEMPLATES_AUTO_RELOAD | True | False |
| SESSION_COOKIE_SECURE | True | True |
| SESSION_COOKIE_HTTPONLY | True | True |
| SESSION_COOKIE_SAMESITE | Lax | Lax |
| PERMANENT_SESSION_LIFETIME | 30 分钟 | 30 分钟 |
| REMEMBER_COOKIE_DURATION | 7 天 | 7 天 |
[阅读西班牙语版本](README.es.md)
标签：Flask, Syscall, Web开发, 安全最佳实践, 安全编码示例, 版权保护, 请求拦截, 逆向工具