VikkramVigneswaranJai/policy-as-code-platform

## Policy-as-Code 平台 一个基于 Flask 的综合授权系统，利用 Open Policy Agent (OPA) 实现基于属性访问控制 (ABAC) 的 Policy-as-Code 原则。 ### 🎯 项目概述 本平台展示了使用 Rego 编写的声明式策略的现代授权模式。它提供了一个完整的 Web 应用程序，包含用户管理、策略评估和全面的审计日志记录。 ## 主要特性 • 🔐 认证与授权**：基于 JWT 的认证与 OPA 策略评估 • 👥 用户管理**：完整的用户注册、登录和个人资料管理 • 📜 策略管理**：通过 Web 界面创建、更新和管理 Rego 策略 • 🔍 审计日志**：全面记录所有授权决策 • ⏰ 基于时间的访问控制**：考虑一天中的时间和一周中的某天的策略 • 🏢 基于部门的访问**：基于用户和资源部门的 ABAC 策略 • 🎨 现代 UI**：使用 Tailwind CSS 构建的精美、响应式界面 • 🧪 全面测试**：覆盖所有端点和边缘情况的完整测试套件 ## 📋 目录 - [安装](#installation) - [快速开始](#quick-start) - [架构](#architecture) - [API 文档](#api-documentation) - [策略示例](#policy-examples) - [测试](#testing) - [部署](#deployment) - [故障排除](#troubleshooting) ## 🚀 安装 ### 前置条件 - Python 3.8 或更高版本 - pip (Python 包管理器) - OPA (Open Policy Agent) - 可选但推荐 ### 第一步：克隆仓库 ``` git clone cd PolicyAsCodePlatform ``` ### 第二步：创建虚拟环境 ``` # Windows python -m venv venv venv\Scripts\activate # Linux/Mac python3 -m venv venv source venv/bin/activate ``` ### 第三步：安装依赖 ``` pip install -r requirements.txt ``` ### 第四步：安装 OPA（可选） #### Windows 1. 从此处下载 OPA：https://www.openpolicyagent.org/docs/latest/#running-opa 2. 或使用直接链接：https://openpolicyagent.org/downloads/latest/opa_windows_amd64.exe 3. 重命名为 `opa.exe` 并添加到 PATH #### Linux ``` curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64 chmod +x opa sudo mv opa /usr/local/bin/ ``` #### Mac ``` brew install opa ``` ### 第五步：初始化数据库 ``` python init_db.py ``` 这将创建 SQLite 数据库并用示例用户和策略填充它。 ## ⚡ 快速开始 ### 选项 1：集成启动（推荐） 同时启动 OPA 服务器和 Flask 应用程序： ``` python start_app.py ``` ### 选项 2：手动启动 **终端 1 - 启动 OPA 服务器：** ``` python start_opa.py # 或手动： opa run --server --addr localhost:8181 opa_policies/ ``` **终端 2 - 启动 Flask 应用程序：** ``` python run.py ``` ### 访问应用程序 - **Web 界面**：http://localhost:5000 - **仪表盘**：http://localhost:5000/dashboard - **登录**：http://localhost:5000/login - **注册**：http://localhost:5000/register - **API 文档**：http://localhost:5000/api-docs - **OPA 服务器**：http://localhost:8181 (如果正在运行) ### 默认测试凭据 | 用户名 | 密码 | 角色 | 部门 | |----------|----------|------|------------| | admin | admin123 | admin | management | | manager | manager123 | manager | engineering | | employee | employee123 | employee | engineering | | hr_manager | hr123 | manager | hr | | finance_employee | finance123 | employee | finance | ## 🏗️ 架构 ### 系统组件 ``` ┌─────────────────────────────────────────────────────────────┐ │ Web Browser (Client) │ └───────────────────────────┬─────────────────────────────────┘ │ HTTP/HTTPS ▼ ┌─────────────────────────────────────────────────────────────┐ │ Flask Application │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Auth Routes │ │Policy Routes │ │ Audit Routes │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ OPA Client Module │ │ │ └──────────────────────────────────────────────────────┘ │ └──────────────┬────────────────────────┬────────────────────┘ │ │ ▼ ▼ ┌───────────────────┐ ┌───────────────────────┐ │ SQLite Database │ │ OPA Server │ │ - Users │ │ - Policy Engine │ │ - Policies │ │ - Rego Policies │ │ - Audit Logs │ │ - REST API │ └───────────────────┘ └───────────────────────┘ ``` ### 技术栈 - **后端**：Flask 2.3.3 - **数据库**：SQLite 与 SQLAlchemy ORM - **认证**：JWT (Flask-JWT-Extended) - **策略引擎**：Open Policy Agent (OPA) - **策略语言**：Rego - **前端**：HTML5, Tailwind CSS, Vanilla JavaScript - **测试**：pytest ### 目录结构 ``` PolicyAsCodePlatform/ ├── app/ │ ├── __init__.py # Application factory │ ├── models.py # Database models │ ├── opa_client.py # OPA integration │ ├── routes.py # Main routes │ ├── auth/ │ │ └── routes.py # Authentication endpoints │ ├── policy/ │ │ └── routes.py # Policy management endpoints │ ├── resources/ │ │ └── routes.py # Resource access endpoints │ ├── audit/ │ │ └── routes.py # Audit log endpoints │ └── templates/ # HTML templates │ ├── base.html │ ├── login.html │ ├── register.html │ ├── dashboard.html │ └── ... ├── opa_policies/ │ ├── authz.rego # Main authorization policy │ ├── rbac.rego # Role-based access control │ ├── time_based.rego # Time-based policies │ └── department.rego # Department-based policies ├── config.py # Configuration settings ├── run.py # Application entry point ├── start_app.py # Integrated startup script ├── start_opa.py # OPA startup script ├── init_db.py # Database initialization ├── test_app.py # Comprehensive test suite ├── requirements.txt # Python dependencies └── README.md # This file ``` ## 📚 API 文档 ### 认证端点 #### POST /auth/register 注册一个新用户账户。 **请求体：** ``` { "username": "string", "email": "string", "password": "string", "role": "admin|manager|employee", "department": "string", "designation": "string (optional)" } ``` **响应 (201)：** ``` { "status": "success", "message": "User registered successfully", "data": { "user": { ... } } } ``` #### POST /auth/login 进行认证并接收 JWT token。 **请求体：** ``` { "username": "string", "password": "string" } ``` **响应 (200)：** ``` { "status": "success", "data": { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...", "token_type": "Bearer", "user": { ... } } } ``` #### GET /auth/profile 获取当前用户资料（需要认证）。 **请求头：** ``` Authorization: Bearer ``` **响应 (200)：** ``` { "status": "success", "data": { "user": { "id": 1, "username": "admin", "email": "admin@example.com", "role": "admin", "department": "management" } } } ``` ### 策略端点 #### POST /policy/evaluate 评估策略决策。 **请求头：** ``` Authorization: Bearer ``` **请求体：** ``` { "action": "read|write|delete", "resource": { "type": "document|report|settings", "department": "string", "id": "string (optional)" }, "environment": { "hour": 14, "day": "Monday" } } ``` **响应 (200)：** ``` { "status": "success", "data": { "allow": true, "reason": "Admin has full access to all resources" } } ``` ### 审计端点 #### GET /audit/logs 检索审计日志（仅限管理员）。 **查询参数：** - `page`：页码（默认：1） - `per_page`：每页条目数（默认：20） - `decision`：按决策筛选（allow/deny） - `action`：按操作筛选（read/write/delete） ## 🔒 策略示例 ### 示例 1：管理员完全访问权限 ``` allow if { input.user.role == "admin" } ``` ### 示例 2：经理办公时间 ``` allow if { input.user.role == "manager" input.environment.hour >= 9 input.environment.hour < 18 input.action in ["read", "write"] } ``` ### 示例 3：员工部门访问 ``` allow if { input.user.role == "employee" input.action == "read" input.user.department == input.resource.department } ``` ## 🧪 测试 ### 运行所有测试 ``` python -m pytest test_app.py -v ``` ### 运行特定测试类 ``` python -m pytest test_app.py::TestAuthEndpoints -v ``` ### 测试覆盖范围 测试套件涵盖： - ✅ 用户注册（成功、重复、验证） - ✅ 用户登录（成功、无效凭据） - ✅ JWT token 处理 - ✅ 策略评估（所有角色和场景） - ✅ 基于时间的访问控制 - ✅ 基于部门的访问控制 - ✅ 审计日志记录 - ✅ 边缘情况（SQL 注入、XSS、格式错误的输入） - ✅ 错误处理 ## 🌐 部署 ### 生产环境注意事项 1. **环境变量**：设置生产环境密钥 export SECRET_KEY="your-secret-key" export JWT_SECRET_KEY="your-jwt-secret" export FLASK_ENV="production" 2. **数据库**：使用 PostgreSQL 或 MySQL 代替 SQLite SQLALCHEMY_DATABASE_URI = "postgresql://user:pass@localhost/dbname" 3. **OPA 服务器**：将 OPA 作为单独的服务部署 opa run --server --addr 0.0.0.0:8181 /path/to/policies 4. **WSGI 服务器**：使用 Gunicorn 或 uWSGI gunicorn -w 4 -b 0.0.0.0:5000 run:app ## 🔧 故障排除 ### OPA 服务器无法启动 **问题**：找不到 OPA 可执行文件 **解决方案**： - 确保 OPA 已安装并在 PATH 中 - 或使用本地回退模式（应用程序可在没有 OPA 的情况下工作） ### 数据库错误 **问题**：数据库锁定或权限错误 **解决方案**： ``` # 删除并重建数据库 rm pac_platform.db python init_db.py ``` ### 端口已被占用 **问题**：端口 5000 或 8181 已被占用 **解决方案**： ``` # 更改 Flask 端口 export FLASK_PORT=8000 python run.py # 或杀死现有进程 # Windows netstat -ano | findstr :5000 taskkill /PID /F # Linux/Mac lsof -ti:5000 | xargs kill -9 ``` ### 登录无效 **问题**：Token 未被存储 **解决方案**： - 检查浏览器控制台是否有错误 - 确保已启用 JavaScript - 清除浏览器 localStorage - 尝试隐身/无痕模式 ## 📝 配置 ### 环境变量 - `FLASK_ENV`：环境（development/production/testing） - `FLASK_DEBUG`：启用调试模式（True/False） - `FLASK_HOST`：主机地址（默认：0.0.0.0） - `FLASK_PORT`：端口号（默认：5000） - `SECRET_KEY`：Flask 密钥 - `JWT_SECRET_KEY`：JWT 签名密钥 - `OPA_SERVER_URL`：OPA 服务器 URL（默认：http://localhost:8181） - `DATABASE_URL`：数据库连接字符串 ### 配置文件 - `config.py`：主配置 - `.env`：环境变量（从 `.env.example` 创建） ## 🤝 贡献 这是一个学术项目。如需改进： 1. Fork 仓库 2. 创建功能分支 3. 进行更改 4. 添加测试 5. 提交 Pull Request ## 📄 许可证 本项目为学术目的而创建。 ## 👥 作者 - 学术项目 - Policy-as-Code 平台 - Vikkram Vigneswaran KJ - Velmurugan A - Velsabarinaath B - Sri haran R ## 🙏 致谢 - Open Policy Agent (OPA) 团队 - Flask 框架贡献者 - Tailwind CSS 团队 ## 📞 支持 如有问题或疑问： - 查看故障排除部分 - 查看 API 文档 - 运行测试套件以验证设置 ## 邮件联系- - Vikkram Vigneswaran - vvigneswarankj@gmail.com **使用 Flask、OPA 和现代 Web 技术用 ❤️ 构建**

标签：ABAC, Flask, Groq API, JSONLines, JWT, OPA, PE 加载器, Policy-as-Code, Python, Rego, Streamlit, Tailwind CSS, 人工智能安全, 合规性, 后端开发, 基于属性的访问控制, 安全规则引擎, 审计日志, 授权系统, 无后门, 用户管理, 策略即代码, 结构化提示词, 聊天机器人安全, 访问控制, 逆向工具, 零信任, 靶场