DimKouts84/black_glove_agent

# 🖤 Black Glove 🖤 *一款使用自然语言进行家庭和小型企业安全测试的渗透测试 agent* [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](#) [](https://www.sqlite.org/) [](https://www.trychroma.com/) [](https://lmstudio.ai/) [](https://ollama.ai/) [](https://typer.tiangolo.com/) ## 🎯 目的 Black Glove 是一款本地优先、CLI 驱动、LLM 辅助的渗透测试 agent，专为家庭托管服务和小型企业网络的授权安全测试而设计。它可帮助您在保持完全可审计性和人工监督的同时，安全地发现漏洞并确定其优先级。

## 工作原理 ``` flowchart TD subgraph UserLayer["User"] U[User CLI - Typer] end subgraph ControlLayer["Control / Orchestration"] O[Agent Orchestrator - Validation, Policies, Scheduling] PM[Plugin Manager - Adapter Discovery] P[Planner LLM - Risk Assessment RAG] HUI[Human Review - Typed Approval] end subgraph ExecutionLayer["Execution / Tools"] TA[Tool Adapters - Nmap, Gobuster, ZAP] EX[Exploit Adapters - lab-mode gated] end subgraph DataLayer["Storage & Reporting"] RP[Results Processor - Normalization] DB[SQLite Findings DB] RL[Audit Logger - append-only] RE[Reporting Engine - Markdown/JSON] end U -->|cli command| O O -->|request + context| P P -->|proposed plan| O O -->|present plan| HUI HUI -->|approve / reject| O O -->|assemble adapters| PM PM --> TA O -->|schedule| TA TA --> EX TA -->|raw output| RP RP --> DB RP --> RL DB -->|context| P DB --> RE RP --> P P --> RE RL --> RE classDef danger fill:#390D0D,stroke:#2b0000,color:#fff,font-weight:bold; class CS,EX danger ```
1. **添加资产**：通过 CLI 定义您的目标（IP、域名） 2. **被动侦察**：自动收集公开信息 3. **主动扫描**：审查并批准建议的扫描 4. **分析**：LLM 解读结果并识别漏洞 5. **报告**：获取包含修复步骤的优先级排序结果 ## 🚀 核心功能 ### 🔒 安全第一 - **强制法律声明**：首次运行需确认对负责任使用的承诺 - **Human-in-the-Loop**：所有主动扫描均需输入批准 - **速率限制**：可配置的流量限制，以防止意外的 DoS - **实验模式**：对 exploit 工具实施特殊限制 ### 🧠 LLM 驱动的分析 - **本地 LLM 支持**：兼容 LMStudio、Ollama、OpenAI 和 Anthropic - **Agentic Workflow**：具有 ROOT、Planner、Researcher 和 Analyst agent 的多 agent 架构 - **交互式聊天**：通过 `agent chat` 提供用于安全任务的自然语言界面 - **智能规划**：LLM 基于具备上下文感知的发现结果建议下一步操作 -. **结果解读**：在 RAG 的支持下，将原始工具输出转化为可操作的洞察 - **风险评估**：对潜在影响提供清晰的解释 - **对话记忆**：在会话内的多次交互中保持上下文 - **检索增强生成**：使用 ChromaDB 通过安全知识库增强响应 - **推理模型支持**：兼容思考/推理模型（例如 Qwen-Thinking） ### 🌐 Web 应用（本地优先） - **React UI**：与 CLI 美学相匹配的终端主题 Web 界面 - **单一命令**：`black-glove serve` 在 `http://127.0.0.1:8787` 上运行 API + UI - **完整的配置编辑器**：通过 UI 更改 LLM 提供商、模型、API 密钥和批准开关 - **会话历史**：查看所有聊天会话、子 agent 跟踪记录和工具发现 - **实时编排**：WebSocket 流式传输 agent 思考、工具调用和批准过程 有关架构和 API 参考，请参阅 [docs/webapp.md](docs/webapp.md)。 ### 🛠️ 模块化架构 - **工具适配器**：用于安全工具（Nmap、Gobuster、ZAP 等）的标准化接口 - **插件系统**：易于通过新工具和功能进行扩展 - **配置驱动**：基于 YAML 的自定义配置，包括针对不稳定 endpoint 调整的 **LLM 重试逻辑**。 - **审计日志**：所有操作的完整不可变记录 - **便携式工具**：自动下载并配置便携版 Nmap 和 Gobuster（包括 Windows 支持），简化设置过程。 ### 📊 全面测试 - **被动侦察**：DNS、子域名枚举、技术检测和历史数据收集 - **OSINT 适配器**：DnsLookup、Sublist3r、Wappalyzer、Shodan（API）、ViewDNS（API）、**OSINT Harvester**（电子邮件/文档）、**DNS Recon**（区域传送） - **主动扫描**：Nmap、Gobuster、**Web 服务器扫描器**、**SQL 注入扫描器**、**Web 漏洞扫描器**、**凭证测试器**（受实验室门控） - **专用适配器**：Camera Security Adapter v1.1.0，用于 IP 摄像头漏洞评估 - **漏洞分析**：带有严重性评级的规范化发现 - **报告**：生成 Markdown 和 JSON 报告 ## 📋 系统要求 - **Python**：3.8 或更高版本 - **LLM 服务**：LMStudio、Ollama 或 OpenRouter 账户 - **操作系统**：Windows、macOS 或 Linux - **Nmap 和 Gobuster**： - **Windows**：由 agent 自动作为便携版二进制文件安装。 - **Linux/macOS**：建议通过包管理器（例如 `apt install nmap gobuster`）安装，尽管 agent 也可以尝试进行便携式设置。 ## 🛠️ 安装说明 ### 快速设置 1. **克隆代码仓库：** git clone https://github.com/mitsos-pc/black-glove.git cd black-glove 2. **创建虚拟环境：** python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate 3. **安装依赖：** pip install -e . 4. **构建 Web UI（可选）：** cd frontend && npm install && npm run build 5. **启动 Web UI：** black-glove serve # 打开 http://127.0.0.1:8787 **Windows 一键启动：** 双击 `scripts/launch-web.bat` —— 首次运行时使用 `uv sync`（安装了 `uv` 的情况下）来引导 `.venv` 和依赖项，构建前端，然后启动服务器并打开浏览器。如果没有 `uv`，则回退使用 `pip install -e .`。CLI 中的等效命令：`black-glove launch-web`。 ### 配置说明 1. **初始化 agent：** agent init 此命令执行以下初始化流程： - 检查当前目录（`./config.yaml`）或主目录（`~/.homepentest/config.yaml`）中的现有配置 - 如果不存在配置：显示法律声明 -> 需要确认 -> 运行配置向导 -> 创建配置文件 -> 初始化数据库和目录 -> 启动聊天 - 如果存在配置：跳过向导并直接进入聊天模式 - 配置向导将引导您完成 LLM 提供商设置，并在当前目录中创建 `config.yaml` 2. **编辑配置：** agent 首先查找 `./config.yaml`（当前目录），然后回退到 `~/.homepentest/config.yaml`。您可以根据需要编辑生成的配置文件来调整设置（参见下方的完整示例）。 3. **（可选）配置 API 密钥：** 将 `.env.example` 复制为 `.env` 并添加您的 API 密钥： cp .env.example .env # 编辑 .env 并添加你的 SHODAN_API_KEY 和 VIEWDNS_API_KEY } ## 🎮 基本用法 ### 1. 初始化 Agent ``` agent init ``` 启动交互式聊天界面以执行自然语言安全任务： 交互示例： - "检查我的公共 IP" - "扫描 my_domain_here.com 的 DNS 记录" - "检查 192.168.1.0/24 上暴露的摄像头" - "my_domain_here.com 的 SSL 状态是什么？" ### 2. 管理资产 **通过 CLI：** ``` # 添加 assets agent add-asset --name home-router --type host --value 192.168.1.1 agent add-asset --name personal-website --type domain --value my_domain_here.com # 列出 assets agent list-assets # 移除 asset（通过 ID） agent remove-asset 1 ``` **通过交互式聊天：** 您也可以在 `agent init` 中使用自然语言管理资产： - "将 example.com 添加为域名资产" - "列出我的所有资产" - "移除名为 personal-website 的资产" ### 3. 运行被动侦察 ``` agent recon passive --asset personal-website ``` ### 4. 规划主动扫描 ``` agent recon active --asset home-router --preset fingerprint ``` ### 5. 审查并批准 ``` # 查看建议的操作 # 输入 'approve ' 以继续 ``` ### 6. 生成报告 ``` agent report --asset home-router ``` ## 🏗️ 项目结构 ``` black-glove/ ├── src/ │ ├── agent/ # Core agent components │ │ ├── cli.py # Command-line interface │ │ ├── executor.py # AgentExecutor (agentic loop) │ │ ├── definitions.py # Agent schema definitions │ │ ├── agent_library/ # Agent definitions (root, planner, etc) │ │ ├── tools/ # Tool registry and wrappers │ │ ├── agentic_workflow.md # Architecture documentation │ │ ├── db.py # Database management │ │ ├── models.py # Data models and validation │ │ └── __init__.py # Package initialization │ ├── adapters/ # Tool adapters │ └── utils/ # Utility functions (tool_setup.py, etc.) ├── bin/ # Portable tools (Nmap, Gobuster) ├── config/ # Configuration templates ├── config/ # Configuration templates ├── docker/ # Container definitions ├── docs/ # Documentation ├── examples/ # Example configurations ├── tests/ # Test suite └── assets/ # Images and media ``` ## 🔧 配置说明 Black Glove 从 `~/.homepentest/config.yaml` 读取设置。首次运行时，此文件将根据 `config/default_config.yaml` 创建。以下是带有内嵌指南的完整示例： ``` # Black Glove 默认配置模板 # 此模板用于在首次运行时创建 ~/.homepentest/config.yaml # 使用你的特定设置和授权目标自定义此文件 # LLM 设置 # 配置你的 LLM provider 和 endpoint llm_provider: "llm_local_or_cloud_provider" # Options: lmstudio, ollama, openrouter llm_endpoint: "http://localhost:1234/v1" # Update with your LLM service URL llm_model: "local-model" # The model name here. For small reasoning LLMs we tested `qwen3-4b-thinking-2507` (locally with LM Studio) and it works surprisingly well. llm_temperature: 0.1 # Controls randomness (0.0 = deterministic, 1.0 = creative) llm_retry_attempts: 5 # Number of retries for failed API calls llm_retry_backoff_factor: 2.0 # Exponential backoff factor (e.g., 2s, 4s, 8s...) enable_rag: true # Enable Retrieval-Augmented Generation with ChromaDB rag_db_path: "~/.homepentest/chroma_db" # Path to ChromaDB vector store # 扫描设置 # 配置扫描行为和限制 default_rate_limit: 50 # Default packets per second max_rate_limit: 100 # Maximum allowed rate limit scan_timeout: 300 # Scan timeout in seconds # 日志设置 # 配置日志行为 log_level: "INFO" # Options: DEBUG, INFO, WARNING, ERROR log_retention_days: 90 # Log retention period in days # 安全设置 # 安全和防护控制 require_lab_mode_for_exploits: true # Require lab mode for exploit tools enable_exploit_adapters: false # Enable exploit adapters (disabled by default for safety) # 证据存储 # 配置证据文件的存储位置 evidence_storage_path: "~/.homepentest/evidence" # Per-adapter 设置（由 PluginManager 在加载前合并） adapters: sublist3r: threads: 20 nmap: timeout: 300 # Asset 管理设置 blocked_targets: # Explicitly block specific targets # Example: # - "192.168.1.1" # Block specific IP # - "blocked-domain.com" # Block specific domain # 附加设置 # 根据需要取消注释并进行自定义 # extra_settings: # custom_field: "value" # api_keys: # shodan: "your-shodan-api-key" # virustotal: "your-virustotal-api-key" ``` ## 🧪 测试 运行测试套件以验证功能： ``` # 运行所有测试 python -m pytest tests/ # 运行 coverage python -m pytest tests/ --cov=agent # 运行特定的测试文件 python -m pytest tests/test_init_command.py -v ``` ## 🚀 部署 为 Unix 系统和 Windows 提供了简化的部署脚本： ``` # 类 Unix 系统（Linux/macOS） ./scripts/deploy.sh --full # Windows scripts\deploy.bat --full ``` 部署选项： - `--check-only`：验证系统先决条件 - `--setup`：设置环境和依赖项 - `--test`：运行完整的测试套件 - `--package`：创建部署包 - `--full`：完整的部署过程（默认） 部署过程将： 1. 检查先决条件（Python 3.8+、Nmap、Gobuster） 2. 设置虚拟环境 3. 安装依赖项 4. 运行所有测试 5. 创建部署包 ## 📚 文档 - [**系统架构**](docs/ARCHITECTURE.md) - 高层设计和组件交互。 - [**Agentic Workflow**](src/agent/agentic_workflow.md) - 深入了解多 agent 系统（Root、Planner、Researcher、Analyst）。 - [**项目需求**](docs/project_requirements_plan.md) - 功能和非功能需求。 - [**开发任务**](docs/project_tasks.md) - 当前的路线图和任务跟踪。 - [**示例工作流**](examples/workflows.md) - 常见使用模式。 ## 🛡️ 安全控制 ### 法律合规 - 首次运行强制确认 - 授权验证 - 遵守当地法律 ### 人工监督 - 主动扫描需输入批准 - 执行前进行风险解释 - exploit 的多重确认步骤 ### 技术保障 - 每个工具的速率限制 - 专用网络保护 - 输入清理（白名单验证） - 容器沙盒机制 # 其他信息 ## 📄 许可证 本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## ⚠️ 免责声明 本工具仅供教育和授权安全测试使用。开发者不对本工具造成的任何误用或损坏负责。在测试任何系统之前，请务必确保您已获得明确许可。 ## 📞 支持 如遇问题、疑问或功能请求，请提交 GitHub issue。 *由 Dimitris Koutsomichalis 和 AI 助手倾注 ❤️ 构建*

标签：AI代理, AI风险缓解, CTI, Python, XXE攻击, 主机安全, 安全测试, 密码管理, 插件系统, 攻击性安全, 无后门, 本地大语言模型, 调试插件, 逆向工具