fgravato/Lookout_Device_dashboard

# Lookout MRA 设备仪表板 用于通过 Lookout Mobile Risk API v2 管理移动设备的 Flask Web 应用程序。提供实时仪表板、设备过滤、Excel 导出、CVE 漏洞扫描、多租户支持和智能缓存功能。 ## 功能特性 - **设备仪表板** — 实时设备库存，含连接、暂存、断开等状态摘要 - **高级过滤** — 按平台、风险等级、保护状态、连接状态、自上次检查以来的天数等条件过滤 - **Excel 导出** — 使用 openpyxl 导出带汇总页的过滤设备数据 - **CVE 漏洞扫描** — 对设备舰队进行已知 CVE 扫描 - **多租户支持** — 从单个仪表板管理多个 Lookout 租户 - **智能缓存** — 内存与 SQLite 持久化结合，后台刷新与增量同步 - **身份验证** — 可选的 HTTP Basic 身份验证，配合 Werkzeug 密码哈希 - **速率限制** — 内置 Flask-Limiter 对 API 端点的保护 ## 先决条件 - Python 3.8 或更高版本 - 拥有 Lookout Mobile Endpoint Protection 账户并具备 API 访问权限（或开发模式下使用示例数据） ## 安装 ### macOS / Linux ``` # 解压 ZIP 文件 unzip Lookout-Reporting_tool_version1.zip cd Lookout-Reporting_tool_version1 # 创建虚拟环境（推荐） python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt ``` ### Windows **选项 A — 使用命令提示符：** ``` :: Extract the zip file to a folder, then open Command Prompt and navigate to it cd C:\Users\YourName\Downloads\Lookout-Reporting_tool_version1 :: Create a virtual environment python -m venv venv :: Activate the virtual environment venv\Scripts\activate.bat :: Install dependencies pip install -r requirements.txt ``` **选项 B — 使用 PowerShell：** ``` # 将 ZIP 文件解压到文件夹，然后打开 PowerShell 并导航到该文件夹 cd C:\Users\YourName\Downloads\Lookout-Reporting_tool_version1 # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # 注意：如果遇到执行策略错误，请先运行以下命令： # Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser venv\Scripts\Activate.ps1 # 安装依赖 pip install -r requirements.txt ``` **验证安装：** ``` python -c "import flask; print('Flask', flask.__version__)" ``` 若看到 `Flask 3.0.0`，则安装成功。 ### 依赖项 | 包 | 用途 | |----|------| | Flask 3.0 | Web 框架 | | requests 2.31 | Lookout API 的 HTTP 客户端 | | openpyxl 3.1 | Excel 文件生成 | | python-dotenv 1.0 | 环境变量管理 | | Flask-HTTPAuth 4.8 | HTTP Basic 身份验证 | | Flask-Limiter 3.5 | API 速率限制 | | python-dateutil 2.8 | 日期/时间工具 | ## 配置 复制示例环境文件并编辑： ``` cp .env.example .env # macOS/Linux copy .env.example .env # Windows ``` 在任意文本编辑器中打开 `.env` 并更新适用于你环境的值。 ### 必需设置 | 变量 | 描述 | |------|------| | `LOOKOUT_APPLICATION_KEY` | 你的 Lookout API 应用程序密钥（若使用示例数据则不需要） | ### 通用设置 | 变量 | 默认值 | 描述 | |------|--------|------| | `USE_SAMPLE_DATA` | `false` | 使用内置示例数据而非真实 API | | `AUTH_ENABLED` | `false` | 启用 HTTP Basic 身份验证 | | `AUTH_USERS` | — | 用户凭据，格式为 `user:pass,user2:pass2` | | `HOST` | `127.0.0.1` | 服务器绑定地址 | | `PORT` | `5000` | 服务器端口 | | `DEBUG` | `false` | 启用 Flask 调试模式 | | `FLASK_ENV` | `default` | 环境：`development`、`production` 或 `testing` | | `LOG_LEVEL` | `INFO` | 日志级别：DEBUG、INFO、WARNING、ERROR | ### 缓存设置 | 变量 | 默认值 | 描述 | |------|--------|------| | `CACHE_ENABLED` | `true` | 启用内存缓存 | | `CACHE_MAX_AGE_MINUTES` | `60` | 缓存 TTL（分钟） | | `ENABLE_DISK_CACHE` | `true` | 将缓存持久化到 SQLite（重启后保留） | | `CACHE_FILE_PATH` | `./device_cache.db` | SQLite 缓存文件位置 | | `AUTO_REFRESH_ON_STARTUP` | `true` | 应用启动时获取设备数据 | | `BACKGROUND_REFRESH_ENABLED` | `false` | 启用后台缓存刷新线程 | | `BACKGROUND_REFRESH_INTERVAL_MINUTES` | `30` | 后台刷新间隔 | | `ENABLE_DELTA_SYNC` | `true` | 刷新时仅获取已更改设备 | | `DELTA_SYNC_LOOKBACK_HOURS` | `24` | 增量同步时间窗口 | ### 多租户设置 | 变量 | 默认值 | 描述 | |------|--------|------| | `ENABLE_MULTI_TENANT` | `false` | 启用多租户模式 | | `TENANTS_CONFIG_FILE` | `./tenants.json` | 租户配置文件路径 | ### API 设置 | 变量 | 默认值 | 描述 | |------|--------|------| | `API_TIMEOUT` | `30` | API 请求超时（秒） | | `API_RETRY_ATTEMPTS` | `3` | 失败重试次数 | | `MAX_DEVICES_PER_REQUEST` | `1000` | 每页设备数（最大 1000） | ### 获取 Lookout 应用程序密钥 1. 以管理员身份登录 [Lookout 控制台](https://app.lookout.com) 2. 导航至 **System > Application Keys** 3. 点击 **GENERATE KEY** 并输入标签 4. 立即复制生成的密钥（之后无法检索） 5. 将其添加到 `.env` 文件中 ## 运行应用程序 ### 开发模式（使用示例数据） 无需 API 密钥。 **macOS / Linux：** ``` USE_SAMPLE_DATA=true python app.py ``` **Windows（命令提示符）：** ``` set USE_SAMPLE_DATA=true python app.py ``` **Windows（PowerShell）：** ``` $env:USE_SAMPLE_DATA="true" python app.py ``` ### 生产环境 ``` python run_dashboard.py ``` 启动脚本会检查依赖项和配置，打印状态摘要并自动打开浏览器。 或者直接运行： ``` python app.py ``` 仪表板默认地址为 `http://localhost:5001`。 ### 按舰队规模推荐配置 **小型舰队（< 1,000 设备）：** ``` CACHE_MAX_AGE_MINUTES=30 BACKGROUND_REFRESH_ENABLED=false ENABLE_DISK_CACHE=false ``` **中型舰队（1,000 - 10,000 设备）：** ``` CACHE_MAX_AGE_MINUTES=60 BACKGROUND_REFRESH_ENABLED=true BACKGROUND_REFRESH_INTERVAL_MINUTES=30 ENABLE_DISK_CACHE=true ``` **大型舰队（10,000+ 设备）：** ``` CACHE_MAX_AGE_MINUTES=120 BACKGROUND_REFRESH_ENABLED=true BACKGROUND_REFRESH_INTERVAL_MINUTES=60 ENABLE_DISK_CACHE=true ENABLE_DELTA_SYNC=true ``` ## API 端点 所有端点在 `AUTH_ENABLED=true` 时均需身份验证（`/health` 除外）。 | 方法 | 端点 | 描述 | |------|------|------| | `GET` | `/` | 仪表板 UI | | `GET` | `/health` | 健康检查（无需身份验证） | | `GET` | `/api/devices` | 带缓存元数据的过滤设备列表 | | `GET` | `/api/device/` | 单个设备及风险分析 | | `POST` | `/api/refresh` | 触发缓存刷新 | | `GET` | `/api/export/excel` | 导出过滤设备为 Excel | | `GET/POST` | `/api/cve/*` | CVE 漏洞扫描端点 | | `GET/POST` | `/api/tenants/*` | 租户管理端点 | | `GET` | `/api/cache/*` | 缓存状态与管理 | ### 设备过滤查询参数 ``` GET /api/devices?platform=IOS&security_status=THREATS_HIGH&min_last_seen_days=7&max_last_seen_days=30 ``` ## 项目结构 ``` Lookout-Reporting_tool_version1/ ├── app.py # App factory (create_app), error handlers, background refresh ├── config.py # Configuration classes (Dev/Prod/Test) from env vars ├── run_dashboard.py # Production launcher with dependency checks ├── lookout_client.py # LookoutMRAClient — OAuth2 API client with retry logic ├── device_cache.py # DeviceCache — thread-safe in-memory + SQLite persistence ├── auth/ │ └── manager.py # AuthManager — HTTP Basic auth with password hashing ├── routes/ # Flask Blueprints │ ├── devices.py # Device listing and detail endpoints │ ├── export.py # Excel/CSV export endpoints │ ├── cve.py # CVE scanning endpoints │ ├── tenants.py # Multi-tenant management │ └── cache.py # Cache status and control ├── services/ # Business logic layer │ ├── device_service.py # Device fetching, caching, delta sync │ ├── risk_service.py # Per-device risk analysis │ ├── export_service.py # Excel/CSV generation │ ├── cve_service.py # CVE vulnerability scanning │ ├── tenant_service.py # Multi-tenant client management │ └── export/sheets/ # Excel sheet generators ├── utils/ │ ├── device_filters.py # Query-parameter filtering logic │ └── time_utils.py # Date/time helpers ├── templates/ # Jinja2 HTML templates ├── static/ # CSS, JS, images ├── tests/ │ ├── conftest.py # Test fixtures and TestConfig │ ├── unit/ # Unit tests │ └── integration/ # Integration tests ├── requirements.txt # Python dependencies ├── setup.cfg # Pytest configuration ├── .env.example # Environment variable template ├── tenants.json.example # Multi-tenant configuration template └── sample_data.json # Built-in sample device data ``` ## 架构 应用程序采用 **Flask 应用工厂模式**，结合 Blueprints 进行路由，使用服务类处理业务逻辑。 ``` Request → Blueprint route (routes/) → Service class (services/) → LookoutMRAClient / DeviceCache → Response ``` 服务通过 `app.extensions` 注入到应用，并在路由处理程序中访问。 ### 缓存策略 针对大型设备舰队的两层缓存设计以提升性能： 1. **内存字典** — 主缓存，通过 `threading.RLock` 保证线程安全 2. **磁盘上的 SQLite** — 可选持久层，重启后保留数据 后台刷新与增量同步可最小化 API 调用。增量同步仅在配置的时间窗口内获取已变更设备。 ## 测试 ``` # 运行所有测试 pytest # 仅运行单元测试 pytest tests/unit/ # 仅运行集成测试 pytest tests/integration/ # 单个测试 pytest -k "test_name" # 带覆盖率 pytest --cov ``` 测试使用 `TestingConfig`，启用示例数据、禁用身份验证与缓存，服务通过 `app.extensions` 模拟。 ## 故障排除 | 问题 | 解决方案 | |------|----------| |来自 Lookout API 的 401 未经授权** | 验证 `LOOKOUT_APPLICATION_KEY` 是否正确且未过期 | | **429 请求过多** | 降低刷新频率；启用增量同步与磁盘缓存 | | **大型舰队启动缓慢** | 启用 `ENABLE_DISK_CACHE=true` — 后续启动从 SQLite 加载，约 2 秒 | | **每次重启缓存为空** | 确保 `ENABLE_DISK_CACHE=true` 且 `CACHE_FILE_PATH` 可写 | | **端口已被占用** | 在 `.env` 中修改 `PORT` 或停止其他进程 | | **缺少依赖项** | 运行 `pip install -r requirements.txt` | | **`python` 在 Windows 上无法识别** | 重新安装 Python 并勾选 **"Add Python to PATH"**，或使用完整路径 `C:\Python3x\python.exe` | | **PowerShell 脚本执行错误** | 运行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` 后重试 | | **`venv` 文件夹已在压缩包中** | 删除现有 `venv` 文件夹，并使用 `python -m venv venv` 重新创建 | ## 许可证 内部应用程序。根据组织需求进行修改。

标签：Excel导出, Flask, Flask-Limiter, HTTP基本认证, Lookout Mobile Risk API, Python, SQLite, Werkzeug密码哈希, 仪表盘, 保护状态过滤, 后台刷新, 增量同步, 多平台, 大舰队, 实时过滤, 平台过滤, 开发运维, 性能优化, 无后门, 检测绕过, 正则匹配, 目录枚举, 看板, 移动安全, 移动设备管理, 缓存, 设备体检, 设备清单, 连接状态过滤, 风险监控, 风险等级过滤