shankar121112/AIRSS

# AIRSS — 自动化事件响应模拟系统 **Tilak Maharashtra Vidyapeeth University, Pune** **计算机科学系 — BCA 2025–2026** **Shankar Shivhar Waghmare | PRN: 46423000820** ## 📋 目录 - [项目概述](#-project-overview) - [架构与组件](#-architecture--components) - [核心功能](#-core-features) - [系统流程](#-system-flow) - [技术栈](#-technical-stack) - [安装与设置](#-installation--setup) - [使用指南](#-usage-guide) - [API 文档](#-api-documentation) - [安全特性](#-security-features) - [故障排除](#-troubleshooting) ## 🎯 项目概述 ### 什么是 AIRSS？ AIRSS（自动化事件响应模拟系统）是一个全面的网络安全评估和漏洞管理平台，旨在模拟像 Nessus 或 OpenVAS 这样的企业级安全扫描工具。该系统在基于 Web 的界面中提供自动化网络发现、漏洞评估、合规性审计和事件响应功能。 ### 为什么选择 AIRSS？ **教育目的**：作为 BCA 毕业设计项目构建，旨在展示网络安全概念、Web 开发和系统集成的实际应用。 **学习目标**： - 网络扫描和发现技术 - 漏洞评估方法论 - 使用 WebSocket 进行实时 Web 应用程序开发 - 跨平台兼容性（Windows/Linux/macOS） - 安全合规框架 - PDF 报告生成 - 数据库集成和状态管理 **实际应用**：模拟网络安全专业人员用于网络评估、合规性审计和事件响应规划的专业安全工具。 ## 🏗️ 架构与组件 ### 系统架构 ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Web Browser │ │ FastAPI App │ │ Background │ │ (Frontend) │◄──►│ (Backend) │◄──►│ Services │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ HTML/CSS/JS │ │ Templates & │ │ Network │ │ Templates │ │ Static Files │ │ Scanning │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### 核心模块 #### 1. **main.py** - FastAPI 后端 - **用途**：处理 HTTP 请求、WebSocket 连接和业务逻辑的主应用服务器 - **关键组件**： - FastAPI 应用设置 - 会话管理 - 用于实时更新的 WebSocket 管理器 - 后台任务调度器 - 用于扫描、报告和管理的 API endpoint #### 2. **discover.py** - 网络发现引擎 - **用途**：核心网络扫描和设备发现功能 - **主要特性**： - 使用原始套接字进行 ICMP ping 扫射 - 针对 ICMP 被拦截的主机进行 TCP 端口探测 - ARP 表读取和 MAC 厂商查询 - 操作系统指纹识别 - 服务检测和端口映射 #### 3. **report_generator.py** - PDF 报告引擎 - **用途**：从扫描结果生成专业的 PDF 报告 - **特性**： - 带有页眉/页脚的结构化 PDF 布局 - 漏洞摘要 - 合规性报告 - 带时间戳和品牌化的报告 #### 4. **database.py** - Firebase Firestore 管理器 - **用途**：核心数据库操作和持久层 - **主要特性**： - Firebase Firestore 初始化和 schema 管理 - 带有版本控制的发现扫描集合 - 漏洞跟踪和存储 - 主机管理和历史记录 - 用于检索扫描的查询接口 - 通过 GOOGLE_APPLICATION_CREDENTIALS 支持 Firebase 凭据 #### 5. **db_integration.py** - 数据库集成层 - **用途**：高级数据库抽象和业务逻辑 - **主要特性**： - ScanManager：处理扫描生命周期和版本控制 - HostManager：管理发现的主机及其关系 - VulnerabilityManager：存储和检索漏洞数据 - PortManager：跟踪开放端口和服务 - LogManager：维护审计和操作日志 - HistoryManager：处理扫描历史和增量检测 #### 6. **setup_firebase.py** - Firebase 设置实用程序 - **用途**：初始化并测试 Firebase Firestore 连接 - **特性**： - 凭据验证 - 数据库连接测试 - 集合初始化 - 设置验证 #### 7. **generate_test_data.py** - 测试数据生成器 - **用途**：使用样本数据填充数据库以供开发使用 - **特性**： - 真实的测试扫描和主机 - 样本漏洞和端口 - 安全事件和日志 - 开发数据种子化 #### 8. 前端组件 - **templates/**：Jinja2 HTML 模板 - `login.html`：身份验证界面 - `dashboard.html`：主应用程序界面 - **static/**：静态资源 - `css/main.css`：样式和响应式设计 - `js/main.js`：客户端逻辑和 WebSocket 处理 ### 数据流 ``` User Request → FastAPI Routes → Background Tasks → Network Scanning ↓ ↓ ↓ ↓ WebSocket → Real-time Updates → Database Store → PDF Reports Updates → UI Updates → Scan History → Export ``` ## 🚀 核心功能 ### 🔐 身份验证系统 - 基于安全 cookie 的**会话身份验证** - **默认凭据**：`admin` / `Shankar` - 带有会话清理的**注销功能** ### 📊 仪表盘与分析 - **实时统计**：设备计数、风险等级、开放端口 - **网络拓扑可视化**（基于 SVG） - 带有实时 RX/TX 图形的**流量监控** - 使用 Chart.js 的**风险分布图表** - 带有版本控制的**扫描历史跟踪** - 由 Firebase 支持的历史数据**持久化** ### 🔍 网络扫描器 - **灵活的 IP 范围输入**：CIDR 表示法、范围、单个 IP - **双重扫描模式**： - **真实模式**：使用系统网络工具进行准确扫描 - **模拟模式**：生成用于测试的真实模拟数据 - 通过 WebSocket 的**实时进度更新** - **全面的设备画像**：IP、主机名、OS、MAC、厂商 - 在 Firebase Firestore 中的**持久扫描存储** ### 🎯 漏洞评估 - 基于开放端口和服务的**动态风险评分** - 带有真实漏洞数据的 **CVE 数据库集成** - **CISA KEV（已知被利用漏洞）**加权 - 具有已知漏洞端口的**服务映射** - **风险分类**：严重、高、中、低 ### 📋 合规与策略引擎 - 基于 JSON 的**策略定义** (`policies.json`) - 对照安全标准进行**自动化合规检查** - 带有修复指导的**结果报告** - **全网合规评分** ### ⚡ 攻击模拟控制台 - **多种攻击向量**： - 端口扫描（nmap 集成） - Ping 扫射 - SYN/UDP 泛洪攻击 - ARP 欺骗 - 操作系统指纹识别 - **可配置的强度等级**（低/中/高） - **实时攻击监控** - **安全控制**和持续时间限制 ### 🔄 自动扫描调度器 - 可配置间隔的**自动定期扫描** - 使用 asyncio 的**后台任务管理** - **扫描历史和增量检测** - 针对新漏洞的**警报系统** ### 📄 专业报告 - 带有结构化布局的 **PDF 报告生成** - **全面的扫描摘要** - 带有修复步骤的**漏洞详情** - **合规审计报告** - **带时间戳和版本控制的报告** ### 🌐 实时通信 - 基于 WebSocket 的**实时更新** - 用于多客户端同步的**广播系统** - 用于响应式 UI 的**事件驱动架构** - **连接状态监控** ## 🔄 系统流程 ``` 1. Admin Login └── Session creation and authentication 2. Dashboard Access ├── Real-time statistics loading ├── WebSocket connection establishment └── Background services initialization 3. Network Scanning ├── Target network specification ├── Scan profile selection (real/simulation) ├── Live progress updates via WebSocket └── Device discovery and profiling 4. Vulnerability Assessment ├── Port analysis and service detection ├── CVE database correlation ├── Risk score calculation └── Compliance policy evaluation 5. Device Management ├── Detailed device information display ├── Vulnerability drill-down └── Targeted rescanning 6. Attack Console ├── Target device selection ├── Attack vector configuration ├── Real-time execution monitoring └── Result logging 7. Reporting & Export ├── Scan result compilation ├── PDF report generation └── Download/export functionality ``` ## 🛠️ 技术栈 | 层级 | 技术 | |---|---| | **后端** | Python 3.11+、FastAPI、Uvicorn | | **数据库** | Firebase Firestore 持久化存储 | | **实时** | WebSocket（FastAPI 原生） | | **网络** | Scapy、Paramiko (SSH)、Raw Sockets | | **报告** | FPDF、ReportLab | | **模板** | Jinja2、HTML5/CSS3 | | **前端** | Vanilla JavaScript、Chart.js 4 | | **异步** | Asyncio、concurrent.futures | | **工具** | 用于 nmap 集成的 Subprocess、日志记录、线程 | ## 📁 项目结构 ``` final project/ ├── main.py # FastAPI backend, WebSocket handler, API routes ├── discover.py # Network discovery engine (ICMP, ARP, port scanning) ├── database.py # Firebase Firestore database manager ├── db_integration.py # High-level database abstraction layer ├── setup_firebase.py # Firebase setup and connection testing ├── generate_test_data.py # Test data generator for development ├── report_generator.py # PDF report generation engine ├── policies.json # Compliance policies and security rules ├── requirements.txt # Python dependencies ├── run.sh # Application startup script ├── set_credentials.ps1 # PowerShell script to set Firebase credentials ├── templates/ │ ├── login.html # Authentication page │ └── dashboard.html # Main application dashboard ├── static/ │ ├── css/main.css # Responsive stylesheet │ └── js/main.js # Client-side logic, WebSocket handler ├── FIREBASE_SETUP.md # Firebase database setup guide ├── DEBUGGING_NOTES.md # Development debugging notes ├── DATABASE.md # Database documentation ├── DATABASE_IMPLEMENTATION.md # Database implementation details ├── FLOWCHART.md # System architecture flowchart ├── QUICKSTART.md # Quick start guide └── README.md # This file ``` ## 📦 安装与设置 ### 前置条件 #### 系统要求 - **Python 3.11+** - 兼容 **Windows/Linux/macOS** - **管理员权限**（用于原始套接字操作） #### 可选依赖项 - **nmap**：用于高级端口扫描和操作系统检测 - **管理权限**：用于某些网络操作 ### 安装步骤 #### 1. 克隆/下载项目 ``` # 导航到项目目录 cd "final project" ``` #### 2. 安装 Python 依赖项 ``` # 安装所有必需的包 pip install -r requirements.txt ``` #### 3. 验证安装 ``` # 测试导入 python -c "import fastapi, uvicorn, scapy, paramiko, fpdf; print('All dependencies installed')" ``` ### 配置 #### 环境设置 - **虚拟环境**：建议使用以进行隔离 - **工作目录**：确保所有文件都在同一个目录中 - **文件权限**：对项目目录具有读/写访问权限 #### 可选配置 - **policies.json**：自定义合规规则 - **网络接口**：确保具有用于扫描的网络访问权限 - **防火墙规则**：允许必要的网络操作 #### Firebase Firestore 配置 应用程序使用 Firebase Firestore 进行扫描数据的持久化存储。请按照以下步骤设置您的数据库： **步骤 1：获取 Firebase 服务账号凭据** 1. 前往 [Firebase 控制台](https://console.firebase.google.com/project/airss-37fad) 2. 导航至 **项目设置** → **服务账号** 标签页 3. 点击 **生成新的私钥** 4. 将 JSON 文件保存到您的项目目录中（例如：`airss-37fad-firebase-adminsdk-fbsvc-xxxxx.json`） **步骤 2：设置凭据环境变量** ``` # Windows PowerShell（在项目目录中运行） .\set_credentials.ps1 # 或手动设置： $env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\airss-37fad-firebase-adminsdk-fbsvc-xxxxx.json" ``` **步骤 3：创建 Firestore 数据库** 1. 前往 [Firestore 数据库](https://console.firebase.google.com/project/airss-37fad/firestore) 2. 点击 **“创建数据库”** 3. 选择 **“以测试模式启动”**（用于开发） 4. 选择位置：`us-central1` 5. 点击 **“创建”** **步骤 4：测试 Firebase 连接** ``` # 测试设置 python setup_firebase.py # 生成测试数据（可选） python generate_test_data.py ``` **预期输出：** ``` ✓ Firebase credentials found ✓ Firebase initialized successfully ✓ discovery_scans: 0 documents ✓ hosts: 0 documents ✓ open_ports: 0 documents ✓ vulnerabilities: 0 documents ✓ log_scans: 0 documents ✓ scan_history: 0 documents ✓ Firebase database setup complete! ``` **其他凭据提供方式：** - 将 `FIREBASE_CREDENTIALS_PATH` 设置为 JSON 文件路径 - 将 `FIREBASE_CREDENTIALS_JSON` 设置为作为字符串的 JSON 内容 - 设置 `FIREBASE_PROJECT_ID`（默认为 `airss-37fad`） #### 数据库集合结构 AIRSS 使用 6 个主要的 Firestore 集合： **1. `discovery_scans`** - 网络扫描元数据 ``` { "scan_id": "scan_20240507_001", "scan_name": "Network Discovery Scan", "target_network": "192.168.1.0/24", "start_time": "2024-05-07T10:00:00Z", "end_time": "2024-05-07T10:05:00Z", "status": "completed", "total_hosts_found": 15, "total_vulnerabilities": 3, "scan_type": "network", "notes": "Full network inventory" } ``` **2. `hosts`** - 发现的网络设备 ``` { "host_id": "host_192_168_1_10", "scan_id": "scan_20240507_001", "ip_address": "192.168.1.10", "hostname": "router.local", "mac_address": "00:11:22:33:44:55", "vendor": "Cisco Systems", "os_type": "Linux", "status": "online", "open_ports_count": 5, "vulnerability_count": 2 } ``` **3. `open_ports`** - 开放端口和服务 ``` { "port_id": "port_host_192_168_1_10_22_tcp", "host_id": "host_192_168_1_10", "scan_id": "scan_20240507_001", "port_number": 22, "protocol": "tcp", "service_name": "ssh", "service_version": "OpenSSH 8.0", "state": "open" } ``` **4. `vulnerabilities`** - 安全漏洞详情 ``` { "vuln_id": "vuln_host_192_168_1_10_CVE_2024_1234", "host_id": "host_192_168_1_10", "scan_id": "scan_20240507_001", "port_id": "port_host_192_168_1_10_22_tcp", "vulnerability_name": "Weak SSH Configuration", "severity": "High", "cvss_score": 7.5, "cve_id": "CVE-2024-1234", "description": "SSH allows weak ciphers", "solution": "Disable weak ciphers in sshd_config" } ``` **5. `log_scans`** - 安全事件日志 ``` { "log_id": "log_20240507_001", "scan_id": "scan_20240507_001", "event_type": "PORT_SCAN", "severity": "Warning", "source_ip": "192.168.1.50", "target_ip": "192.168.1.10", "port": 22, "protocol": "tcp", "action": "DETECTED", "message": "Suspicious port scanning activity", "timestamp": "2024-05-07T10:02:00Z" } ``` **6. `scan_history`** - 变更跟踪 ``` { "history_id": "hist_20240507_001", "scan_id": "scan_20240507_001", "host_id": "host_192_168_1_10", "previous_state": "offline", "current_state": "online", "change_detected": true, "changed_at": "2024-05-07T10:01:00Z" } ``` ### 运行应用程序 #### 开发模式 ``` # 开启自动重载运行 uvicorn main:app --reload --host 127.0.0.1 --port 8000 ``` #### 生产模式 ``` # 运行生产服务器 uvicorn main:app --host 0.0.0.0 --port 8000 ``` #### 访问应用程序 - **URL**：`http://localhost:8000` - **默认登录**：`admin` / `Shankar` ## 📖 使用指南 ### 首次设置 1. **启动应用程序** uvicorn main:app --host 127.0.0.1 --port 8000 2. **访问 Web 界面** - 在浏览器中打开 `http://localhost:8000` - 使用默认凭据登录 3. **初始配置** - 查看仪表盘概览 - 如果需要，配置扫描设置 ### 网络扫描 #### 基本网络扫描 1. 导航至 **网络扫描器** 部分 2. 输入目标网络（例如：`192.168.1.0/24`） 3. 选择扫描配置文件（真实/模拟） 4. 点击 **开始扫描** 5. 实时监控进度 #### 高级扫描选项 - **自定义 IP 范围**：`10.0.0.1-50`、`192.168.1.100` - **单个主机**：`192.168.1.1` - **多个子网**：用逗号分隔 ### 设备分析 #### 查看设备详情 1. 扫描后转至 **设备** 部分 2. 点击任意设备行查看详细视图 3. 查看开放端口、服务和漏洞 4. 检查合规状态 #### 漏洞评估 - **风险评分**：颜色编码的严重性级别 - **CVE 详情**：点击查看漏洞信息 - **修复步骤**：为每个发现的问题提供 ### 攻击模拟 #### 运行攻击 1. 从 **设备** 列表中选择目标设备 2. 从 **攻击控制台** 选择攻击类型 3. 配置参数（、持续时间） 4. 执行并实时监控 #### 支持的攻击类型 - **端口扫描**：全面的端口枚举 - **Ping 扫射**：ICMP 网络发现 - **SYN 泛洪**：TCP SYN 数据包泛洪 - **UDP 泛洪**：UDP 数据包泛洪 - **ARP 欺骗**：ARP 缓存中毒 - **操作系统指纹识别**：操作系统检测 ### 报告 #### 生成报告 1. 完成网络扫描 2. 导航至 **日志和报告** 部分 3. 点击 **生成 PDF 报告** 4. 下载专业的 PDF 报告 #### 报告内容 - 执行摘要 - 设备清单 - 漏洞发现 - 合规状态 - 修复建议 ## 🔌 API 文档 ### 身份验证 Endpoint #### POST `/login` 对用户进行身份验证并创建会话 ``` { "username": "admin", "password": "Shankar" } ``` #### GET `/logout` 销毁用户会话 ### 扫描 Endpoint #### POST `/api/scan/network` 发起网络扫描 ``` { "target": "192.168.1.0/24", "profile": "real" } ``` #### GET `/api/devices` 检索发现的设备 #### GET `/api/device/{ip}` 获取详细的设备信息 ### WebSocket Endpoint #### WS `/ws` 实时通信通道 - 接收：设备发现、扫描进度、攻击结果 - 发送：UI 更新、警报、统计数据 ### 实用程序 Endpoint #### GET `/api/local-subnet` 自动检测本地网络 #### GET `/api/traffic` 获取网络流量统计信息 #### POST `/api/auto-scan` 配置自动扫描 ## 🔒 安全特性 ### 身份验证与授权 - 带有安全 cookie 的**基于会话的安全机制** - 通过会话验证进行 **CSRF 保护** - **注销清理**可防止会话劫持 ### 网络安全 - 用于底层网络访问的**原始套接字操作** - 带有可配置限制的**安全攻击模拟** - **网络隔离**感知 ### 数据保护 - 用于扫描数据存储的 **Firebase Firestore 数据持久化** - 使用环境变量的**安全凭据处理** - 对所有用户输入进行**输入验证** - 所有管理操作的**审计日志** - 基于云的**备份**和恢复功能 ### 运营安全 - 用于审计追踪的**日志系统** - **错误处理**可防止信息泄露 - 扫描操作的**资源限制** ## 🔧 故障排除 ### 常见问题 #### Firebase 连接问题 **症状**：“未找到 Firebase 凭据”或“数据库未初始化” **解决方案**： ``` # 为当前会话设置凭据 $env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\credentials.json" # 或使用辅助脚本 .\set_credentials.ps1 # 测试连接 python setup_firebase.py ``` #### 找不到 Firestore 数据库 **症状**：“(默认) 数据库不存在” **解决方案**： 1. 前往 [Firestore 控制台](https://console.firebase.google.com/project/airss-37fad/firestore) 2. 点击 **“创建数据库”** 3. 选择 **“以测试模式启动”** 4. 选择位置：`us-central1` 5. 等待 1-2 分钟，然后重试 #### 应用程序无法启动 **症状**：导入错误、缺少依赖项 **解决方案**： ``` # 重新安装依赖项 pip install -r requirements.txt # 检查 Python 版本 python --version # 验证虚拟环境 which python ``` #### 网络扫描失败 **症状**：未找到设备、超时错误 **解决方案**： - 检查网络连接 - 确认目标网络可访问 - 尝试使用模拟模式进行测试 - 检查防火墙设置 #### WebSocket 连接问题 **症状**：实时更新不起作用 **解决方案**： - 检查浏览器 WebSocket 支持 - 确认服务器在正确的端口上运行 - 检查网络防火墙/代理设置 #### PDF 生成错误 **症状**：报告生成失败 **解决方案**： - 验证 fpdf 安装 - 检查文件权限 - 确保有足够的磁盘空间 ### 性能优化 #### 扫描性能 - 使用适当的超时值 - 限制并发操作 - 考虑网络带宽 #### 内存使用 - 定期清理旧的扫描结果 - 监控后台任务使用情况 - 如有需要，重启应用程序 ### 日志和调试 #### 启用调试日志 ``` import logging logging.basicConfig(level=logging.DEBUG) ``` #### 检查应用程序日志 - 服务器启动消息 - 扫描操作日志 - 错误追踪和堆栈跟踪 ## 📈 未来增强 ### 计划中的功能 - 具有基于角色的访问控制 (RBAC) 的**用户管理** - 带有自定义图表和数据导出的**高级报告** - 用于第三方安全工具的**集成 API** - **移动响应式设计**改进 - 用于自定义网络探测的**插件系统** - 用于团队协作的**多租户支持** ### 技术改进 - 用于提升可扩展性的**微服务架构** - 使用 Docker 的**容器化部署** - 用于自动化测试的 **CI/CD pipeline** - **性能监控**和指标 - **安全强化**和渗透测试 ## 📚 参考与资源 ### 学术参考 - Tilak Maharashtra Vidyapeeth University BCA 课程体系 - 网络安全原则与实践 - Web 应用程序安全基础 ### 技术参考 - FastAPI 文档：https://fastapi.tiangolo.com/ - Scapy 文档：https://scapy.net/ - WebSocket RFC 6455 - CVE 数据库：https://cve.mitre.org/ ### 安全标准 - CISA 已知被利用漏洞 - 通用漏洞评分系统 (CVSS) - 安全合规框架 ## 👨‍💻 作者与致谢 **项目作者**：Shankar Shivhar Waghmare **PRN**：46423000820 **机构**：Tilak Maharashtra Vidyapeeth University, Pune **系别**：计算机科学 (BCA) **学年**：2025-2026 **特别感谢**： - 项目指导老师和指导教师 - 提供优秀库的开源社区 - 提供漏洞数据的安全研究社区 ## 📄 许可与免责声明 本项目作为学术课程的一部分，专为教育目的而开发。该系统模拟安全评估工具，应负责任且合乎道德地使用。 **重要提示**：此工具仅供教育和模拟使用。未经明确许可，请勿用于未经授权的网络扫描或安全测试。 *最后更新：2026年5月7日* *版本：2.2 - Firebase 数据库集成*

标签：AES-256, Python, 云存储安全, 实时处理, 插件系统, 无后门, 漏洞评估, 网络扫描, 网络调试, 自动化, 计算机取证, 逆向工具