salah23222/secure-web-baseline
GitHub: salah23222/secure-web-baseline
一个安全优先的轻量级 PHP MVC 框架，内置 Session 加固、CSRF 保护、CSP 安全头等防御机制，用于构建安全可审计的 Web 应用。
Stars: 1 | Forks: 0
# 安全 Web 基线
一个轻量级、安全优先的 PHP MVC 起始框架，用于构建安全的 Web 应用程序。
没有沉重的框架。没有魔法。只有内置安全最佳实践的、清晰且可审计的 PHP 代码。
## 关键特性
- **Session 加固** — httponly, secure, samesite=strict cookies；空闲超时；定期 ID 重新生成；基于浏览器/IP 指纹的劫持检测。
- **CSRF 保护** — 单 Session token 配合恒定时间验证；Origin/Referer 头验证；在每次 POST 请求时自动验证。
- **Content Security Policy** — 严格的 CSP，配合每次请求的 nonce；无 `unsafe-inline` 或 `unsafe-eval`。
- **安全的 HTTP Headers** — X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy，可选 HSTS。
- **PDO 数据库层** — 单例模式封装，支持预处理语句；query, fetch, insert, update, delete 辅助方法；事务支持。
- **输入验证** — 流式验证器，支持 required, email, minLength, maxLength, integer, numeric, url, in, confirmed 和 regex 规则。
- **认证流程** — 注册、登录（含 Session 固定防护）、登出、受保护的控制面板。
- **清晰的 MVC 结构** — Controllers, Models, Views, Core 类，以及简单的基于 URI 的路由器。
## 项目结构
```
secure-web-baseline/
├── app/
│ ├── Controllers/
│ │ ├── HomeController.php # Landing page & health check
│ │ ├── AuthController.php # Register, login, logout
│ │ └── DashboardController.php # Protected dashboard
│ ├── Core/
│ │ ├── bootstrap.php # Autoloader, session, headers, helpers
│ │ ├── Router.php # URI-based GET/POST router
│ │ ├── Session.php # Secure session management
│ │ ├── CSRF.php # CSRF token generation & verification
│ │ ├── SecurityHeaders.php # HTTP security headers + CSP nonce
│ │ ├── Validator.php # Fluent input validator
│ │ └── Database.php # Singleton PDO wrapper
│ ├── Models/
│ │ └── User.php # User CRUD operations
│ └── Views/
│ ├── auth/login.php
│ ├── auth/register.php
│ ├── dashboard/index.php
│ ├── home/index.php
│ └── errors/403.php, 404.php
├── config/
│ └── database.php # Database credentials
├── public/
│ ├── index.php # Front controller
│ └── .htaccess # Apache URL rewriting
├── scripts/
│ └── schema.sql # Database schema
├── .htaccess # Root rewrite to public/
├── README.md
├── SECURITY.md
├── CONTRIBUTING.md
├── ROADMAP.md
├── CHANGELOG.md
├── LICENSE # MIT
└── VERSION
```
## 环境要求
- PHP 8.1 或更高版本
- MySQL 5.7+ 或 MariaDB 10.3+
- 启用 `mod_rewrite` 的 Apache（或具有等效重写规则的 Nginx）
## 安装说明
1. **克隆仓库：**
git clone https://github.com/salah23222/secure-web-baseline.git
cd secure-web-baseline
2. **创建数据库：**
mysql -u root -p < scripts/schema.sql
3. **配置数据库凭据：**
编辑 `config/database.php`，填入您的 MySQL 主机、用户名、密码和数据库名。
4. **设置 Web 服务器：**
**选项 A — Apache Virtual Host (推荐)：**
将文档根目录指向 `public/` 目录：
ServerName secure-baseline.local
DocumentRoot /path/to/secure-web-baseline/public
AllowOverride All
Require all granted
**选项 B — XAMPP / localhost：**
将项目放置在 `htdocs/` 中，通过 `http://localhost/secure-web-baseline/` 访问。根目录下的 `.htaccess` 会将请求路由到 `public/index.php`。
5. **在浏览器中打开：**
访问 `http://secure-baseline.local/`（或您配置的 URL）。
## 可用路由
| Method | Path | Description | Auth Required |
| ------ | ----------- | ------------------------------ | ------------- |
| GET | `/` | 首页 | No |
| GET | `/health` | JSON 健康检查 | No |
| GET | `/register` | 注册表单 | No |
| POST | `/register` | 处理注册 | No |
| GET | `/login` | 登录表单 | No |
| POST | `/login` | 处理登录 | No |
| GET | `/logout` | 登出并销毁 Session | No |
| GET | `/dashboard`| 受保护的用户控制面板 | Yes |
## 认证流程
1. 在 `/register` **注册**，填写姓名、邮箱和密码（至少 8 个字符）。
2. 在 `/login` **登录**。成功后，Session ID 会被重新生成（防止 Session 固定），用户被重定向到 `/dashboard`。
3. **控制面板** 是受保护的 —— 未认证用户会被重定向到 `/login`。
4. 在 `/logout` **登出** 以销毁 Session 并返回登录页面。
## 安全说明
| Layer | Implementation |
| ------------------ | --------------------------------------------------------------------------- |
| Sessions | httponly, secure (HTTPS), samesite=strict, 30 分钟空闲超时, 15 分钟重新生成, 指纹检查 |
| CSRF | 64 字节 token, 恒定时间比较, Origin/Referer 验证, POST 时自动验证 |
| CSP | `default-src 'self'`; 脚本和样式需要每次请求的 nonce |
| Headers | DENY framing, nosniff, 严格的 referrer 策略, permissions 策略, HSTS |
| SQL Injection | 所有查询使用 PDO 预处理语句 |
| XSS | 所有输出通过 `e()` 辅助函数使用 `htmlspecialchars()` |
| Session Fixation | 登录时执行 `session_regenerate_id(true)` |
| User Enumeration | 登录失败时显示通用错误消息 |
| Password Storage | 使用 `PASSWORD_DEFAULT`（当前为 bcrypt）的 `password_hash()` |
## 路线图
请参阅 [ROADMAP.md](ROADMAP.md) 查看计划中的改进，包括 RBAC、速率限制、审计日志、中间件、API 认证等。
## 贡献指南
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解相关准则。
## 许可证
[MIT](LICENSE)
标签：API密钥检测, CISA项目, Clean Architecture, CSP, CSRF防护, DNS解析, httponly, MVC框架, OpenVAS, PDO, PHP, Session安全, SQL注入防护, Web安全, XML 请求, XSS防御, 中间件, 会话固化, 内容安全策略, 后端开发, 安全基线, 安全开发, 安全架构, 安全标准, 安全标头, 开源项目, 教学环境, 网络安全, 蓝队分析, 规则仓库, 认证系统, 轻量级框架, 输入验证, 隐私保护