DorkAgent

https://github.com/yee-yore/dorkagent
Admin
DorkAgent is an LLM-powered agent designed for automated Google Dorking, assisting in bug hunting...
Tokens:8,394
Snippets:61
Trust Score:6.5
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install DorkAgent Dependencies (Bash)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Lists the necessary Python packages for DorkAgent and provides a command for manual installation using pip. The application also attempts to auto-install missing dependencies on first run.

```bash
# Python 3.11.9 recommended
pip install python-dotenv crewai crewai-tools langchain-openai termcolor prompt-toolkit pyfiglet schedule
```

--------------------------------

### Run DorkAgent (Bash)

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This snippet shows how to clone the DorkAgent repository and run the main executable script. It outlines the automated processes including dependency installation, API key management, user prompts for configuration, and report generation.

```bash
# Clone and run DorkAgent
git clone https://github.com/yee-yore/DorkAgent.git
cd DorkAgent
python dorkagent.py

# The program will:
# 1. Auto-install required packages (crewai, crewai-tools, langchain-openai, etc.)
# 2. Prompt for API keys (SERPER_API_KEY required, plus one LLM provider key)
# 3. Save keys to .env file automatically
# 4. Display interactive menus for LLM, domain, and depth selection
# 5. Execute 30 Google Dork queries against target
# 6. Generate security assessment report in ./log/YYMMDD/YYMMDD_HHMMSS_domain.md
```

--------------------------------

### Dependency Auto-Installation Logic (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Illustrates the Python code responsible for automatically installing missing dependencies before importing third-party libraries. It uses a try-except block and exits after installation, prompting the user to restart the application.

```python
# Dependency auto-installation logic (dorkagent.py:1-52)
# Runs BEFORE any third-party imports to avoid ImportError
# Uses try/except block to detect missing packages
# Exits after installation with message to restart
# Warns if Python version differs from 3.11.9
```

--------------------------------

### Python Code Formatting: Good vs. Bad Examples

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Illustrates the preferred Python code formatting for function definitions and logic. The good example emphasizes readability with proper spacing and line breaks, while the bad example shows a condensed, less readable style.

```python
# Good example
def verify_api_key(llm_type):
    """Verify API key validity"""
    required_keys = ["SERPER_API_KEY"]

    if llm_type == "openai":
        required_keys.append("OPENAI_API_KEY")

    return required_keys

# Bad example
def verify_api_key(llm_type):
    required_keys=["SERPER_API_KEY"]
    if llm_type=="openai": required_keys.append("OPENAI_API_KEY")
    return required_keys
```

--------------------------------

### Clone and Run DorkAgent (Bash)

Source: https://github.com/yee-yore/dorkagent/blob/main/README.md

Instructions for cloning the DorkAgent repository and running the main Python script. This process includes automatic installation of dependencies and prompts for necessary API keys.

```bash
git clone https://github.com/yee-yore/DorkAgent.git
cd DorkAgent
python dorkagent.py
```

--------------------------------

### Orchestrate Workflow with CrewAI

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This Python code illustrates the setup and execution of the complete dorkagent workflow using CrewAI. It initializes the Language Model (LLM) based on user configuration, defines the agents involved, and retrieves necessary inputs like target domains, search depth, and user instructions. The code also sets up the output directory structure for logs and reports.

```python
import os
from datetime import datetime
from crewai import Crew
from config import select_llm, create_llm
from agents import agents as create_agents
from tasks import task
from utils import (
    get_target_domains, select_depth, adjust_depth,
    get_user_instructions, sanitize_filename
)

# Setup
provider, model = select_llm()
llm = create_llm(provider, model)
agent_list = create_agents(llm)

domains = get_target_domains()        # ["example.com"]
depth = select_depth()                 # "2"
target_domains = adjust_depth(domains, depth)  # ["*.example.com"]
user_instructions = get_user_instructions()

# Create output directory
date = datetime.now().strftime("%y%m%d")
LOG_DIR = os.path.join("./log", date)
os.makedirs(LOG_DIR, exist_ok=True)

```

--------------------------------

### Python File Naming Convention

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Specifies that all Python files within the project should use lowercase with underscores. Examples include `dorkagent.py` and `dorkagent_cli.py`.

```text
dorkagent.py
dorkagent_cli.py
```

--------------------------------

### Python Naming Convention: Classes (PascalCase)

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Establishes the convention for naming Python classes using PascalCase, where each word starts with an uppercase letter. This distinguishes class names from other identifiers.

```python
class DorkAgent:      # Good
class dork_agent:     # Bad
```

--------------------------------

### Configure DorkAgent Environment Variables (Bash)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Shows how to set up the `.env` file for DorkAgent, specifying required and optional API keys for different LLM providers and services like Serper.dev.

```bash
SERPER_API_KEY=        # Required - https://serper.dev/
OPENAI_API_KEY=        # Optional - set if using OpenAI
ANTHROPIC_API_KEY=     # Optional - set if using Anthropic
GEMINI_API_KEY=        # Optional - set if using Gemini (recommended for free usage)
```

--------------------------------

### Run DorkAgent Tool (Bash)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Provides instructions on how to run the DorkAgent tool. Currently, only interactive mode is supported via the main Python script. CLI mode is noted as not yet implemented.

```bash
# Interactive mode (menu-driven interface)
python dorkagent.py

# Note: CLI mode (dorkagent-cli.py) is not yet implemented
```

--------------------------------

### LLM Provider and Model Selection (Python)

Source: https://context7.com/yee-yore/dorkagent/llms.txt

Demonstrates the interactive LLM selection process using the `select_llm` and `create_llm` functions from `config.py`. It allows users to choose between OpenAI, Anthropic, and Google Gemini providers and dynamically fetches available models for the selected provider.

```python
from config import select_llm, create_llm

# Interactive LLM selection (prompts user for provider and model)
provider, model = select_llm()

# Provider options:
# 1. OpenAI (GPT-4, GPT-5 models)
# 2. Anthropic (Claude models)
# 3. Google Gemini (Gemini models)

# Create LLM instance for use with CrewAI
llm = create_llm(provider, model)

# Example output during selection:
# [?] Choose LLM Provider (1 - 3): 2
# [+] Fetching available models for Anthropic...
# Available models:
# 1. Claude 3.5 Sonnet
# 2. Claude 3 Opus
# 3. Claude 3 Haiku
# [?] Choose model (1 - 3): 1
```

--------------------------------

### Environment Configuration for API Keys (Bash)

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This bash snippet shows the required format for the `.env` file used by DorkAgent to manage API keys. It lists the mandatory SERPER_API_KEY and one of the optional keys for LLM providers (OpenAI, Anthropic, or Gemini).

```bash
# Required .env file contents:
SERPER_API_KEY=your_serper_api_key_here

# Plus ONE of the following (based on selected provider):
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AI...

# Get SERPER_API_KEY from: https://serper.dev/
# The tool will prompt for missing keys and save them automatically
```

--------------------------------

### Customize Reports and Integrate Notifications

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This Python code snippet shows how to customize report generation instructions and integrate with the ProjectDiscovery notify tool for notifications. `get_user_instructions` allows users to provide specific requirements for the report content and style. `integrate_notify` prompts the user about notification preferences, and `send_notification` sends the generated report path to the notify tool if enabled.

```python
from utils import get_user_instructions, integrate_notify, send_notification

# Get custom report instructions
instructions = get_user_instructions()
# Default: "Generate a comprehensive security report with clear findings..."
# Custom examples:
#   - "Write the report in Korean"
#   - "Focus on critical vulnerabilities only"
#   - "Use formal technical language"

# Ask about notification integration
notify_choice = integrate_notify()  # Returns "Y", "y", "N", or "n"

# Send notification (requires notify tool installed)
# https://github.com/projectdiscovery/notify
report_path = "./log/250611/250611_143022_example.md"
if notify_choice.lower() == "y":
    send_notification(report_path)
# Executes: notify -data ./log/250611/250611_143022_example.md
```

--------------------------------

### LLM Configuration and Selection (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Details the Python functions for configuring and selecting the Large Language Model (LLM) provider. This includes selecting the LLM type, ensuring API keys are present, and instantiating the appropriate LLM object based on the chosen provider.

```python
# LLM Configuration (config.py)

def select_llm_type():
    # Interactive menu returns string identifier ('openai', 'anthropic', or 'gemini')
    pass

def ensure_api_keys():
    # Reads/writes .env, prompts for missing keys using getpass
    pass

def create_llm(llm_type):
    # Instantiates provider-specific objects:
    # OpenAI: ChatOpenAI with `gpt-4.1-mini-2025-04-14`
    # Anthropic: CrewAI LLM wrapper with `anthropic/claude-3-5-haiku-20241022`
    # Gemini: CrewAI LLM wrapper with `gemini/gemini-2.5-flash`
    pass
```

--------------------------------

### Configure Target Domains and Search Depth

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This Python code demonstrates utility functions for handling user input related to target domains and search depth. `get_target_domains` retrieves domains from user input, supporting single domains or lists from files. `select_depth` allows users to choose the search scope (exact domain, subdomains, or deeper subdomains), and `adjust_depth` modifies the domain list based on the selected depth.

```python
from utils import get_target_domains, select_depth, adjust_depth

# Get target domains from user (single or from file)
domains = get_target_domains()
# Option 1: Single domain -> ["example.com"]
# Option 2: Multi domain from file -> ["example.com", "test.com", "demo.org"]

# Select search depth
depth = select_depth()
# 1: target.com (exact domain only)
# 2: *.target.com (include subdomains)
# 3: *.*.target.com (include deeper subdomains)

# Apply depth to domains
target_domains = adjust_depth(domains, depth)
# Input: ["example.com"], depth="2"
# Output: ["*.example.com"]
#
# Input: ["example.com"], depth="3"
# Output: ["*.*.example.com"]
```

--------------------------------

### Depth Adjustment Logic for Domains (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Explains the logic for adjusting search depth in DorkAgent, defining wildcard patterns for different levels (1-3) and how wildcard characters in domain names are sanitized for filenames.

```python
# Depth Adjustment Logic (utils.py:74-91)

# Level 1: domain.com
# Level 2: *.domain.com
# Level 3: *.*.domain.com
# Wildcard domains sanitized in filenames: `*` -> `wildcard` (utils.py:93-101)
```

--------------------------------

### Run DorkAgent for Multiple Domains (Python)

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This Python code iterates through a list of domains, initiating a DorkAgent crew for each. It configures the crew with agents, tasks, and settings like API rate limiting and output logging. The results are then saved to timestamped Markdown files.

```python
for i, domain in enumerate(domains):
    target_domain = target_domains[i]
    tasks = task(target_domain, domain, agent_list)

    crew = Crew(
        agents=agent_list,
        tasks=tasks,
        verbose=1,
        max_rpm=15,              # Rate limit for API calls
        output_log_file=True,    # Save execution log
    )

    result = crew.kickoff(inputs={'user_instructions': user_instructions})

    # Save report
    timestamp = datetime.now().strftime("%y%m%d_%H%M%S")
    safe_domain = sanitize_filename(domain)
    report_path = os.path.join(LOG_DIR, f"{timestamp}_{safe_domain}.md")

    with open(report_path, 'w', encoding='utf-8') as f:
        f.write(str(result))

    print(f"[+] Report saved to: {report_path}")
```

--------------------------------

### Agent Definitions and Tools (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Describes the configuration of specialized AI agents (searcher, bughunter, writer) within the DorkAgent using the CrewAI framework. It specifies the tools they utilize, such as SerperDevTool and ScrapeWebsiteTool, and notes that agents operate independently.

```python
# Agent Configuration (agents.py)

# Three specialized agents: searcher (Google Dorking), bughunter (vulnerability analysis), writer (report generation)
# All agents share same LLM instance passed from main
# Tools: SerperDevTool for searches, ScrapeWebsiteTool for content analysis
# No agent delegation (each operates independently)
```

--------------------------------

### Configure Google Search Result Duration (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/README.md

Shows how to set the time duration for Google search results using the `tbs` parameter in the `_make_api_request` method. Options include 'qdr:w' for the past week and 'qdr:m' for the past month.

```python
# https://serper.dev/playground

def _make_api_request(self, search_query: str, search_type: str) -> dict:
    ...
    payload = json.dumps({"q": search_query, "num": self.n_results, "tbs": "qdr:m"}) # Past week: "qdr:w", Past month: "qdr:m"
    ...
```

--------------------------------

### Agent Creation for DorkAgent (Python)

Source: https://context7.com/yee-yore/dorkagent/llms.txt

Illustrates how to create the specialized CrewAI agents used by DorkAgent. The `agents` function in `agents.py` instantiates a searcher, a bug hunter, and a writer agent, each with specific roles and tools required for the reconnaissance and reporting workflow.

```python
from agents import agents as create_agents
from config import create_llm

# Create LLM instance
llm = create_llm("gemini", "gemini-2.0-flash")

# Create the three agents
agent_list = create_agents(llm)

# agent_list contains:
# [0] searcher - Google Dorking expert with SerperDevTool
#     Role: Performing advanced Google searches using Google Dorks
#     Tools: SerperDevTool (requires SERPER_API_KEY)
#
# [1] bughunter - Penetration tester with ScrapeWebsiteTool
#     Role: Identifying attack surfaces and vulnerabilities
#     Tools: ScrapeWebsiteTool
#
# [2] writer - Technical writer with FileWriterTool
#     Role: Generating structured security reports
#     Tools: FileWriterTool
```

--------------------------------

### Configure Number of Google Results (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/README.md

Demonstrates how to customize the number of Google search results returned by the SerperDevTool. This involves modifying the `n_results` attribute within the `SerperDevTool` class.

```python
class SerperDevTool(BaseTool):
    ...
    args_schema: Type[BaseModel] = SerperDevToolSchema
    base_url: str = "https://google.serper.dev"
    n_results: int = 10 # min: 10, max: 100
    ...
```

--------------------------------

### Google Dork Query Structure and Filtering (Python)

Source: https://github.com/yee-yore/dorkagent/blob/main/CLAUDE.md

Details the structure of Google Dork queries used by the 'searcher' agent in DorkAgent. It outlines the 30 hardcoded queries targeting various vulnerability categories, the extensive exclusion criteria for filtering false positives, and the JSON output format.

```python
# Google Dork Query Structure (tasks.py:6-120)

# 30 hardcoded queries targeting different vulnerability categories:
# Queries 1-15: Attack vectors (file exposure, admin panels, injection points, APIs)
# Queries 16-30: Information disclosure (errors, logs, cloud storage, PII, infrastructure)
# Extensive exclusion criteria to filter false positives (tasks.py:59-90)
# JSON-structured output format for consistent parsing
# Must execute ALL 30 queries sequentially
```

--------------------------------

### Task Definition for DorkAgent Reconnaissance (Python)

Source: https://context7.com/yee-yore/dorkagent/llms.txt

Shows the definition of tasks for DorkAgent's reconnaissance workflow using the `task` function from `tasks.py`. This includes setting up tasks for Google Dorking, vulnerability analysis, and report generation, with specific inputs like target domain and agent list.

```python
from tasks import task
from agents import agents as create_agents
from config import create_llm

llm = create_llm("openai", "gpt-4o")
agent_list = create_agents(llm)

# Create tasks for a target domain
target_domain = "example.com"      # Domain with wildcard prefix applied
domain = "example.com"             # Original domain input
tasks = task(target_domain, domain, agent_list)

# tasks contains 3 Task objects:
# Task 1 (searcher): Execute 30 Google Dork queries
#   - Searches for: index of, .env, config files, admin panels, API endpoints
#   - Sensitive data: credentials, tokens, PII in various file formats
#   - Cloud storage, WordPress vulnerabilities, subdomains, error pages
#   - Output: DorkingResults (Pydantic model)
#
# Task 2 (bughunter): Analyze results for vulnerabilities
#   - Classifies findings as Vulnerability or Attack Vector
#   - Categories: IDOR, XSS, SQL Injection, Admin Panel, etc.
#   - Assigns severity: Critical, High, Medium, Low, Info
#   - Output: VulnerabilityAnalysis (Pydantic model)
#
# Task 3 (writer): Generate security assessment report
#   - Executive summary, attack vector analysis, technical findings
#   - Risk prioritization matrix with testing recommendations
```

--------------------------------

### Define Pydantic Models for Dorking and Vulnerability Data

Source: https://context7.com/yee-yore/dorkagent/llms.txt

This Python code defines Pydantic models for structuring and validating data related to search results and vulnerability findings. It includes models for individual search results, aggregated dorking results, specific vulnerability findings, and overall vulnerability analysis. These models ensure consistent and reliable data formats for AI agent outputs.

```python
from models import DorkingResults, VulnerabilityAnalysis, SearchResult, VulnerabilityFinding

# SearchResult - Individual search result from Google Dorking
search_result = SearchResult(
    query_no=1,
    url="https://example.com/.env",
    title="Environment Configuration",
    description="Exposed environment file",
    snippet="DB_PASSWORD=secret123"
)

# DorkingResults - Aggregated results from Task 1
dorking_results = DorkingResults(
    total_queries=30,
    queries_with_results=5,
    total_urls_found=12,
    search_results=[search_result]
)

# VulnerabilityFinding - Individual security finding
finding = VulnerabilityFinding(
    url="https://example.com/admin/login.php",
    classification="Web Page",
    discovery_type="Attack Vector",
    category="Admin Panel",  # One of 26 predefined categories
    severity="High",
    description="Exposed administrative login interface",
    test_method="Attempt default credentials, test for SQL injection",
    mitigation="Restrict access via IP whitelist, implement MFA",
    false_positive=False,
    fp_reason=None
)

# VulnerabilityAnalysis - Aggregated findings from Task 2
analysis = VulnerabilityAnalysis(findings=[finding])

# Available categories for classification:
# Directory Listing, Information Disclosure, Sensitive Data Exposure, IDOR,
# Admin Panel, Configuration Files, API Exposure, File Upload/Download,
# LFI/RFI, Social Engineering, Open Redirect, Cloud Storage Misconfiguration,
# Token Exposure, XSS, Cross Site Scripting, SQL Injection, Command Injection,
# CSRF, Clickjacking, Server Side Request Forgery, Path Traversal, Backup Files,
# Development Environment, WordPress Vulnerabilities, Subdomain Enumeration,
# OSINT, Misc
```

--------------------------------

### Python Import Order Convention

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Demonstrates the standard order for Python imports, categorized into standard library, third-party libraries, and local modules. This helps maintain code readability and organization.

```python
# 1. Standard library
import sys, re, os, pyfiglet
from datetime import datetime

# 2. Third-party libraries
from dotenv import load_dotenv
from crewai import Crew, LLM, Task, Agent
from langchain_openai import ChatOpenAI
from termcolor import colored
from prompt_toolkit import prompt
from prompt_toolkit.completion import PathCompleter
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

# 3. Local modules
from local_module import function
```

--------------------------------

### Python Docstring Style Convention

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Outlines the standard for Python docstrings, requiring single-line, concise, and descriptive docstrings for all functions and classes. This promotes clear documentation within the code.

```python
def adjust_depth(target_domains, depth):
    """Adjust domain search depth based on specified depth level"""
    pass

def verify_api_key(llm_type):
    """Verify required API keys are present in environment"""
    pass

class DorkAgent:
    """Main agent class for Google Dorking operations"""
    pass
```

--------------------------------

### Python Naming Convention: Constants (UPPERCASE_SNAKE_CASE)

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Defines the convention for naming constants in Python, which should be in uppercase with underscores separating words. This clearly distinguishes constants from regular variables.

```python
MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30
```

--------------------------------

### Python Naming Convention: Functions and Variables (snake_case)

Source: https://github.com/yee-yore/dorkagent/blob/main/CONVENTIONS.md

Specifies the use of snake_case for function and variable names in Python. This convention enhances code readability by clearly separating words within identifiers.

```python
def send_notification(message):  # Good
def sendNotification(message):   # Bad

target_domain = "example.com"    # Good
targetDomain = "example.com"     # Bad
```
Tokens:
Raw