RodrigoCossi/Distributed-Vulnerability-Scanner

# 🛡️ VScan - 分布式安全扫描器 ## ⚠️ 法律免责声明 **本工具仅供授权的安全测试使用。** 仅在您拥有或获得明确书面测试许可的网络和系统上使用 VScan。未经授权扫描网络是违法行为。 ## 🌟 功能 ### 核心能力 - **🌐 分布式架构** - 中央 C2 服务器与多个扫描 agent - **🔍 端口扫描** - 支持可配置端口范围的 TCP connect 扫描 - **🔬 服务指纹识别** - 识别运行中的服务及版本 - **🛡️ 漏洞检测** - 检查已知的 CVE 和薄弱配置 - **📊 实时仪表盘** - 可视化 agent、任务和发现结果 - **🔐 安全通信** - JWT 身份验证、API 密钥和审计日志 ### 扫描模块 | 模块 | 描述 | |--------|-------------| | `port_scan` | 带有线程处理的 TCP 端口扫描 | | `service_fingerprint` | 服务识别与 banner grabbing | | `vuln_check` | CVE 检查与薄弱配置检测 | | `host_discovery` | 网络主机发现 | | `banner_grab` | 服务 banner 收集 | | `ssl_check` | SSL/TLS 证书分析 | ### 仪表盘功能 - 实时 agent 状态监控 - 任务创建与管理 - 扫描结果可视化 - 漏洞严重程度细分 - 审计日志追踪 ## 🚀 快速开始 ### 前置条件 - Python 3.11+ - Docker & Docker Compose（可选） - PostgreSQL（可选，开发环境下 SQLite 即可运行） ### 选项 1：本地开发 ``` # 克隆 repository git clone https://github.com/RodrigoCossi/vscan.git cd vscan # 创建虚拟环境（在本地安装 packages，而非系统范围） python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # 安装 dependencies pip install -r requirements.txt # 复制并配置 environment cp .env.example .env # 启动 C2 server python -m uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000 ``` 在一个新终端中，启动一个 agent： ``` # 安装 agent requirements pip install -r requirements-agent.txt # 运行 agent python -m agent.main --server http://localhost:8000 --name "Test-Agent" ``` ### 选项 2：本地 C2 服务器搭配分布式安装的 Agent 在每台远程机器上： ``` # 安装 Python 3.11+ # 克隆或复制 agent 代码 git clone https://github.com/RodrigoCossi/vscan.git cd vscan # 安装 agent dependencies pip install -r requirements-agent.txt # 运行 agent，指向你的 C2 server 的 IP/domain python -m agent.main --server http://:8000 --name "Agent-Machine1" ``` ### 选项 3：Docker Compose（本地） ``` # 启动所有 services cd docker docker-compose up -d # 查看 logs docker-compose logs -f server # 启动额外的 agents docker-compose up -d --scale agent-1=3 ``` ### 选项 4：远程机器上的 Docker Compose 在每台安装了 Docker 的远程机器上： ``` # 拉取或复制 agent Docker image docker pull /vscan-agent # not published yet # 或者在远程机器上本地 build git clone https://github.com/RodrigoCossi/vscan.git cd vscan docker build -f docker/Dockerfile.agent -t vscan-agent . ``` ``` # 运行 agent container docker run -d --name vscan-agent vscan-agent --server http://:8000 --name "Agent1" # 或者在每个远程机器上创建一个简单的 remote-agent-compose.yml： version: '3.8' services: agent: image: vscan-agent command: --server http://:8000 --name "Agent-Location1" restart: unless-stopped # 然后运行：docker-compose -f remote-agent-compose.yml up -d ``` 重要提示：确保您的 C2 服务器可被访问 您的 C2 服务器必须能从远程机器上访问： - 绑定到 0.0.0.0 而不是 127.0.0.1 ``` python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 ``` - 在您的防火墙中开放 8000 端口 在 Windows 上： 打开 Windows Defender 防火墙设置。 为 TCP 端口 8000 添加一个入站规则。 在 Linux 上： 使用 UFW： sudo ufw allow 8000/tcp 使用 firewalld： sudo firewall-cmd --add-port=8000/tcp --permanent && sudo firewall-cmd --reload 在生产环境中，请使用带有有效证书的 HTTPS。 Agent 会在首次连接时自动向 C2 服务器注册，并获取用于身份验证的唯一 API 密钥。 ``` python -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --ssl-keyfile=key.pem --ssl-certfile=cert.pem ``` ### 访问仪表盘 打开浏览器并导航至： - **仪表盘**：http://localhost:8000 - **API 文档**：http://localhost:8000/api/docs - **ReDoc**：http://localhost:8000/api/redoc ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ OPERATOR │ │ (Web UI / CLI / API) │ └─────────────────────┬───────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ C2 SERVER │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ REST API │ │ Task │ │ Agent Registry │ │ │ │ (FastAPI) │ │ Scheduler │ │ & Authentication │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Dashboard │ │ Results │ │ Audit Logging │ │ │ │ (Jinja2) │ │ Ingestor │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────┬───────────────────────────────────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ AGENT 1 │ │ AGENT 2 │ │ AGENT N │ │ ┌───────┐ │ │ ┌───────┐ │ │ ┌───────┐ │ │ │ Port │ │ │ │Service│ │ │ │ Vuln │ │ │ │Scanner│ │ │ │Finger │ │ │ │Checker│ │ │ └───────┘ │ │ └───────┘ │ │ └───────┘ │ └───────────┘ └───────────┘ └───────────┘ ``` ### 通信流程 1. **Agent 注册**：Agent 发送心跳 → 服务器分配 ID 和 API 密钥 2. **任务分配**：Agent 轮询任务 → 服务器返回待处理任务 3. **执行**：Agent 运行扫描模块 → 收集结果 4. **报告**：Agent 提交结果 → 服务器存储并可视化 ## 📁 项目结构 ``` vscan/ ├── backend/ # C2 Server │ └── app/ │ ├── api/ # API endpoints │ │ ├── agents.py # Agent management │ │ ├── tasks.py # Task management │ │ ├── auth.py # Authentication │ │ └── dashboard.py # Dashboard API │ ├── models/ # Database models │ │ ├── agent.py │ │ ├── task.py │ │ ├── task_result.py │ │ ├── scan_event.py │ │ └── audit_log.py │ ├── schemas/ # Pydantic schemas │ ├── templates/ # Jinja2 templates │ ├── web/ # Web dashboard │ ├── config.py # Configuration │ ├── database.py # DB connection │ └── main.py # FastAPI app ├── agent/ # Scanning Agent │ ├── modules/ # Scan modules │ │ ├── port_scanner.py │ │ ├── service_fingerprinter.py │ │ └── vuln_checker.py │ ├── client.py # C2 client │ ├── config.py # Agent config │ └── main.py # Agent entry ├── docker/ # Docker configs │ ├── Dockerfile.server │ ├── Dockerfile.agent │ └── docker-compose.yml ├── requirements.txt # Server deps ├── requirements-agent.txt # Agent deps └── README.md ``` ## 📡 API 参考 ### 身份验证 ``` # 注册用户 curl -X POST http://localhost:8000/api/v1/auth/register \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "securepass123"}' # 登录 curl -X POST http://localhost:8000/api/v1/auth/login \ -d "username=admin&password=securepass123" ``` ### 任务 ``` # 创建 port scan task curl -X POST http://localhost:8000/api/v1/tasks \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "type": "port_scan", "target": "192.168.1.0/24", "parameters": { "ports": "22,80,443,3389", "timeout_ms": 1000 } }' # 列出 tasks curl http://localhost:8000/api/v1/tasks \ -H "Authorization: Bearer " ``` ### Agent ``` # 列出 agents curl http://localhost:8000/api/v1/agents \ -H "Authorization: Bearer " # 获取 agent details curl http://localhost:8000/api/v1/agents/ \ -H "Authorization: Bearer " ``` ### Agent 协议 ``` # Agent heartbeat（注册/check-in） POST /api/v1/agents/heartbeat { "agent_id": null, # null for new registration "name": "Scanner-1", "hostname": "scanner.local", "os": "Linux", "capabilities": ["port_scan", "service_fingerprint"] } # 获取 tasks POST /api/v1/agents/{agent_id}/tasks/fetch Header: X-API-Key: { "max_tasks": 5, "capabilities": ["port_scan"] } # 提交 results POST /api/v1/agents/{agent_id}/tasks/{task_id}/results Header: X-API-Key: { "status": "success", "summary": "Scanned 254 hosts, found 12 open ports", "details": { ... } } ``` ## 🔐 安全模型 ### 身份验证层 | 层级 | 方法 | 使用场景 | |-------|--------|----------| | 用户身份验证 | JWT Tokens | 仪表盘与 API 访问 | | 用户 API 密钥 | 静态密钥 | 程序化访问 | | Agent 身份验证 | 独立 Agent API 密钥 | Agent 通信 | ### 安全特性 - **JWT 身份验证** - 用于用户会话的短期 token - **API 密钥身份验证** - 每个 agent 独有的密钥 - **审计日志** - 追踪所有操作的执行者、IP 和时间戳 - **输入验证** - 基于 Pydantic schema 的验证 - **速率限制** - 可配置的请求限制（已具备实现基础） ### 计划中的安全增强功能 - [ ] 用于 agent 通信的双向 TLS (mTLS) - [ ] 加密任务 payload - [ ] 结果签名与验证 - [ ] 基于角色的访问控制 (RBAC) ## 🧪 任务类型与参数 ### 端口扫描 ``` { "type": "port_scan", "target": "192.168.1.1", "parameters": { "ports": "1-1024", "scan_type": "tcp_connect", "timeout_ms": 1000, "threads": 10 } } ``` ### 服务指纹 ``` { "type": "service_fingerprint", "target": "192.168.1.1", "parameters": { "ports": "22,80,443", "grab_banner": true, "check_ssl": true } } ``` ### 漏洞检查 ``` { "type": "vuln_check", "target": "192.168.1.1", "parameters": { "check_cve": true, "severity_threshold": "medium" } } ``` ## 📈 数据库 Schema ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ agents │ │ tasks │ │ task_results │ ├──────────────┤ ├──────────────┤ ├──────────────┤ │ id │◄────│ agent_id │◄────│ task_id │ │ name │ │ id │ │ agent_id │ │ status │ │ type │ │ id │ │ api_key │ │ target │ │ status │ │ capabilities │ │ status │ │ details │ │ last_seen │ │ parameters │ │ received_at │ └──────────────┘ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ scan_events │ ├──────────────┤ │ id │ │ task_id │ │ event_type │ │ target │ │ severity │ │ data │ └──────────────┘ ``` ## 🛠️ 开发 ### 运行测试 ``` pytest tests/ -v ``` ### 代码格式化 ``` black backend/ agent/ isort backend/ agent/ flake8 backend/ agent/ ``` ### 数据库迁移 ``` # 初始化 Alembic（首次） alembic init alembic # 创建 migration alembic revision --autogenerate -m "Description" # 应用 migrations alembic upgrade head ``` ## 📋 路线图 - [x] 包含 REST API 的核心 C2 服务器 - [x] Agent 注册与心跳 - [x] 端口扫描模块 - [x] 服务指纹识别模块 - [x] 漏洞检查模块 - [x] Web 仪表盘 - [x] Docker 部署 - [ ] WebSocket 实时更新 - [ ] mTLS agent 身份验证 - [ ] CVE 数据库集成 (NVD API) - [ ] 报告生成 (PDF/HTML) - [ ] 定时/周期性扫描 - [ ] Agent 健康监控 - [ ] 多用户 RBAC ## 📄 简历要点 描述该项目时可使用以下内容： ## 📜 许可证 本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。 ## 🤝 贡献 欢迎您的贡献！在提交 PR 之前，请阅读我们的贡献指南。

**为符合道德规范的安全研究与教育而构建** [⬆ 返回顶部](#-vscan---distributed-security-scanner)

标签：AV绕过, Docker, Facebook API, FastAPI, GraphQL安全矩阵, Python, 分布式架构, 安全扫描器, 安全防御评估, 插件系统, 数据统计, 无后门, 测试用例, 端口扫描, 请求拦截, 逆向工具