🖤 Black Glove 🖤

A pentest agent for home and small business security testing that uses natural language

---

🎯 Purpose

Black Glove is a local-first, CLI-driven, LLM-assisted penetration testing agent designed for authorized security testing of home-hosted services and small business networks. It helps you safely discover and prioritize vulnerabilities while maintaining full auditability and human oversight.

⚠️ Legal Notice:
This tool is designed exclusively for authorized security testing of systems you own or have explicit written permission to test.
Unauthorized scanning or penetration testing is illegal and unethical.

---

How It Works

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

Loading

Note: Nodes highlighted in dark red (Exploit Adapters) indicate high-risk execution paths — these steps are subject to rate-limiting and lab-mode gating, and require explicit, typed human approval before any active or exploit-class scans are executed.
All approvals and raw outputs are recorded in the append-only audit log for full traceability.

1. Add Assets: Define your targets (IPs, domains) via CLI
2. Passive Recon: Automatically gather public information
3. Active Scanning: Review and approve suggested scans
4. Analysis: LLM interprets results and identifies vulnerabilities
5. Reporting: Get prioritized findings with remediation steps

---

🚀 Key Features

🔒 Safety First

• Mandatory Legal Notice: First-run acknowledgment of responsible use
• Human-in-the-Loop: Typed approval required for all active scans
• Rate Limiting: Configurable traffic throttling to prevent accidental DoS
• Lab Mode: Special restrictions for exploit tools

🧠 LLM-Powered Analysis

• Local LLM Support: Works with LMStudio, Ollama, OpenAI, and Anthropic
• Agentic Workflow: Multi-agent architecture with ROOT, Planner, Researcher, and Analyst agents
• Interactive Chat: Natural language interface for security tasks via agent chat
• Intelligent Planning: LLM suggests next steps based on findings with context awareness
• Result Interpretation: Converts raw tool output into actionable insights with RAG support
• Risk Assessment: Provides clear explanations of potential impact
• Conversation Memory: Maintains context across multiple interactions within a session
• Retrieval-Augmented Generation: Enhances responses with security knowledge base using ChromaDB
• Reasoning Model Support: Compatible with thinking/reasoning models (e.g., Qwen-Thinking)

🛠️ Modular Architecture

• Tool Adapters: Standardized interface for security tools (Nmap, Gobuster, ZAP, etc.)
• Plugin System: Easy to extend with new tools and capabilities
• Configuration-Driven: YAML-based configuration for customization, including tuned LLM retry logic for unstable endpoints.
• Audit Logging: Complete immutable record of all actions
• Portable Tooling: Automatically downloads and configures portable versions of Nmap and Gobuster (Windows support included), simplifying setup.

📊 Comprehensive Testing

• Passive Recon: DNS, subdomain enumeration, technology detection, and historical data gathering
• OSINT Adapters: DnsLookup, Sublist3r, Wappalyzer, Shodan (API), ViewDNS (API), OSINT Harvester (emails/docs), DNS Recon (zone transfers)
• Active Scanning: Nmap, Gobuster, Web Server Scanner, SQL Injection Scanner, Web Vulnerability Scanner, Credential Tester (lab-gated)
• Specialized Adapters: Camera Security Adapter v1.1.0 for IP camera vulnerability assessment
• Vulnerability Analysis: Normalized findings with severity ratings
• Reporting: Markdown and JSON report generation

📋 Requirements

• Python: 3.8 or higher
• LLM Service: LMStudio, Ollama, or OpenRouter account
• Operating System: Windows, macOS, or Linux
• Nmap & Gobuster:
  • Windows: Automatically installed as portable binaries by the agent.
  • Linux/macOS: Recommended to install via package manager (e.g., apt install nmap gobuster), though the agent can attempt portable setup.

🛠️ Installation

Quick Setup

1. Clone the repository:

   git clone https://github.com/mitsos-pc/black-glove.git
   cd black-glove

2. Create virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   pip install -e .

Configuration

1. Initialize the agent:

   agent init

   This command implements the following initialization flow:

   • Checks for existing configuration in current directory (./config.yaml) or home directory (~/.homepentest/config.yaml)
   • If no config exists: Shows legal notice → Requires acknowledgment → Runs configuration wizard → Creates config file → Initializes database and directories → Starts chat
   • If config exists: Skips wizard and jumps directly to chat mode
   • The configuration wizard guides you through LLM provider setup and creates config.yaml in the current directory

2. Edit configuration: The agent first looks for ./config.yaml (current directory), then falls back to ~/.homepentest/config.yaml. You can edit the generated config file to adjust settings as needed (see full sample below).

3. (Optional) Configure API keys: Copy .env.example to .env and add your API keys:

   cp .env.example .env
   # Edit .env and add your SHODAN_API_KEY and VIEWDNS_API_KEY
   }
   

🎮 Basic Usage

1. Initialize the Agent

agent init

Start the interactive chat interface for natural language security tasks:

Example interactions:

• "Check my public IP"
• "Scan my_domain_here.com for DNS records"
• "Check for exposed cameras on 192.168.1.0/24"
• "What is SSL status for my_domain_here.com?"

2. Manage Assets

Via CLI:

# Add 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

# List assets
agent list-assets

# Remove asset (by ID)
agent remove-asset 1

Via Interactive Chat: You can also manage assets using natural language within agent init:

• "Add example.com as a domain asset"
• "List all my assets"
• "Remove the asset named personal-website"

3. Run Passive Reconnaissance

agent recon passive --asset personal-website

4. Plan Active Scanning

agent recon active --asset home-router --preset fingerprint

5. Review and Approve

# Review suggested actions
# Type 'approve <id>' to proceed

6. Generate Report

agent report --asset home-router

---

🏗️ Project Structure

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

---

🔧 Configuration

Black Glove reads settings from ~/.homepentest/config.yaml. On first run, this file is created from config/default_config.yaml. Here’s the full sample with inline guidance:

# Black Glove Default Configuration Template
# This template is used to create ~/.homepentest/config.yaml on first run
# Customize this file with your specific settings and authorized targets

# LLM Settings
# Configure your LLM provider and 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

# Scan Settings
# Configure scanning behavior and limits
default_rate_limit: 50  # Default packets per second
max_rate_limit: 100  # Maximum allowed rate limit
scan_timeout: 300  # Scan timeout in seconds

# Logging Settings
# Configure logging behavior
log_level: "INFO"  # Options: DEBUG, INFO, WARNING, ERROR
log_retention_days: 90  # Log retention period in days

# Safety Settings
# Security and safety controls
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
# Configure where evidence files are stored
evidence_storage_path: "~/.homepentest/evidence"

# Asset Management Settings
blocked_targets:
   # Explicitly block specific targets
   # Example:
   # - "192.168.1.1"     # Block specific IP
   # - "blocked-domain.com"  # Block specific domain

# Additional Settings
# Uncomment and customize as needed
# extra_settings:
#   custom_field: "value"
#   api_keys:
#     shodan: "your-shodan-api-key"
#     virustotal: "your-virustotal-api-key"

---

🧪 Testing

Run the test suite to verify functionality:

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=agent

# Run specific test file
python -m pytest tests/test_init_command.py -v

🚀 Deployment

Simplified deployment scripts are provided for both Unix-like systems and Windows:

# Unix-like systems (Linux/macOS)
./scripts/deploy.sh --full

# Windows
scripts\deploy.bat --full

Deployment options:

• --check-only: Verify system prerequisites
• --setup: Setup environment and dependencies
• --test: Run complete test suite
• --package: Create deployment package
• --full: Complete deployment process (default)

The deployment process will:

1. Check prerequisites (Python 3.8+, Nmap, Gobuster)
2. Setup virtual environment
3. Install dependencies
4. Run all tests
5. Create deployment package

---

📚 Documentation

• System Architecture - High-level design and component interaction.
• Agentic Workflow - Deep dive into the multi-agent system (Root, Planner, Researcher, Analyst).
• Project Requirements - Functional and non-functional requirements.
• Development Tasks - Current roadmap and task tracking.
• Example Workflows - Common usage patterns.

---

🛡️ Safety Controls

Legal Compliance

• First-run mandatory acknowledgment
• Authorization verification
• Compliance with local laws

Human Oversight

• Typed approval for active scans
• Risk explanations before execution
• Multiple confirmation steps for exploits

Technical Safeguards

• Rate limiting per tool
• Private network protection
• Input sanitization (allow-list validation)
• Container sandboxing

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Please ensure all tests pass and follow the existing code style.

---

Other Information

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This tool is provided for educational and authorized security testing purposes only. The developers are not responsible for any misuse or damage caused by this tool. Always ensure you have explicit permission before testing any system.

📞 Support

For issues, questions, or feature requests, please open a GitHub issue.

---

Built with ❤️ for the Dimitris Koutsomichalis & an AI Assistant