Metadata-Version: 2.4
Name: atdork
Version: 1.3.8
Summary: dorking tools with ddgs metasearch OSINT tool
Author-email: alzzmarket <alzzmarket@proton.me>
License-Expression: MIT
Project-URL: Homepage, https://github.com/amnottdevv/atdork
Project-URL: Bug Reports, https://github.com/amnottdevv/atdork/issues
Project-URL: Source Code, https://github.com/amnottdevv/atdork
Keywords: osint,dork,pentest,security,duckduckgo,metasearch
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ddgs>=7.0
Requires-Dist: rich>=13.0
Requires-Dist: pyfiglet>=0.8
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: safety>=3.0; extra == "dev"
Dynamic: license-file


# AtDork – Professional OSINT Dorking Tool

![Version](https://img.shields.io/badge/version-1.3.8-blue.svg)
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)
![Tests](https://img.shields.io/badge/tests-114%20passed-brightgreen)
![Lines](https://img.shields.io/badge/total%20lines-11%2C000%2B-orange)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/atdork?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=pypi+downloads)](https://pepy.tech/projects/atdork)

**AtDork** is a powerful, ethical OSINT tool that performs advanced search queries (Google Dorks) across multiple search engines simultaneously. Designed for security researchers, penetration testers, and bug bounty hunters, it automates the discovery of exposed documents, vulnerable parameters, misconfigured servers, and other sensitive information available on the public web.

---

## Why AtDork?

- 🚀 **Blazing fast** – Multi‑threaded batch processing with configurable concurrency.
- 🔍 **Multi‑engine** – Queries DuckDuckGo, Google, Bing, Startpage, Yandex, Yahoo, and more.
- 🛡️ **Anonymous** – Built‑in proxy rotation, Tor integration, strict mode to prevent IP leaks. **NEW: IP leak detection (`--ip-guard`)** stops the scan immediately if your real IP is exposed.
- 🧹 **Clean results** – Automatic spam filtering, URL validation, and deduplication.
- 📊 **Professional output** – Export to JSON, CSV, TXT; SQLite database for history and resume. **CSV exports are now protected against formula injection.**
- 🎯 **Smart filtering** – Vulnerability signature detection for WordPress, Joomla, SQLi, and more.
- 📝 **Template system** – Curated YAML‑based dork collections for instant productivity.
- ⚙️ **Highly configurable** – **50+ CLI flags** to control every aspect of your search.
- 🔧 **Post‑processing** – Execute external commands on discovered URLs (`--exec`).
- 💾 **Caching** – Cache search results locally to avoid redundant requests and enable offline access.
- 🔒 **Safe logging** – Proxy credentials are automatically redacted from log files to prevent accidental leaks.

---

## Installation

### From PyPI (Recommended)
```bash
pip install atdork
```

### From Source
```bash
git clone https://github.com/amnottdevv/atdork.git
cd atdork
pip install .
```

### Verify Installation
```bash
atdork --version
# Output: atdork 1.3.8
```

---

## Quick Start

### 1. Your First Search
```bash
atdork -q "site:gov filetype:pdf" -r 10
```
This finds PDF files on government websites and displays the top 10 results.

### 2. Save Results to a File
```bash
atdork -q "intitle:index.of mp3" -r 20 --format json -o music.json
```

### 3. Batch Processing
Create a file `dorks.txt`:
```text
site:edu filetype:xls
inurl:admin login
intitle:"index of" "backup"
```

Run them all at once:
```bash
atdork --batch-file dorks.txt -r 30 --format csv -o results.csv
```

### 4. Search with Proxy (Anonymous)
```bash
atdork -q "confidential filetype:docx" --proxy "http://user:pass@proxy:8080" --strict
```

---

## Detailed Usage

### Single Query
```bash
atdork -q "inurl:product.php?id=" -r 50 --backend google --region uk-en --safesearch off
```

| Flag | Purpose |
|------|---------|
| `-q` | Your dork query |
| `-r` | Number of results (max 100) |
| `--backend` | Search engine: `google`, `bing`, `duckduckgo`, `startpage`, `yandex`, `auto` |
| `--region` | Region code: `us-en`, `uk-en`, `de-de`, `ru-ru`, etc. |
| `--safesearch` | `on`, `moderate`, `off` |

### Batch Processing with Multi‑Threading
```bash
atdork --batch-file dorks.txt -r 40 --concurrency 5 --delay 2 --format json -o batch_results.json
```

| Flag | Purpose |
|------|---------|
| `--batch-file` | Text file with one dork per line |
| `--concurrency` | Number of parallel threads (1‑10) |
| `--delay` | Seconds between requests (avoid rate limits) |
| `-o` | Save all results to a single file |
| `--output-dir` | Save each query result as a separate file |

### Template Dorks (Pre‑Built)
List available templates:
```bash
atdork --list-templates
```

Use a template:
```bash
atdork --template sqli --target example.com -r 30
```

Combine multiple templates with custom queries:
```bash
atdork --template sqli,wordpress,exposed_config -q "site:gov filetype:pdf" -r 25
```

Preview what a template will do:
```bash
atdork --template login_panels --preview
```

Run only specific dorks from a template:
```bash
atdork --template sqli --select 1,3,5 -r 20
```

| Flag | Purpose |
|------|---------|
| `--template` | Template name(s), comma‑separated |
| `--target` | Domain to substitute `{target}` in template dorks |
| `--select` | Run specific dork numbers from template |
| `--list-templates` | Show all available templates |
| `--preview` | Show dorks without executing |
| `--template-path` | Custom template folder |

### Proxy & Anonymity
```bash
# Single proxy
atdork -q "target" --proxy "http://user:pass@host:8080"

# Multiple proxies (comma‑separated)
atdork -q "target" --proxy "http://p1:8080,socks5://p2:1080"

# From file
atdork -q "target" --proxy-file proxies.txt

# Tor integration
atdork -q "target" --tor --strict

# Strict mode (fail if all proxies down)
atdork -q "target" --proxy-file proxies.txt --strict

# Proxy management
atdork -q "target" --proxy-file proxies.txt --proxy-cooldown 120 --max-failures 3
```

**Proxy file format (`proxies.txt`):**
```text
# HTTP proxies
http://user:pass@dc1.provider.com:3128
http://user:pass@dc2.provider.com:3128

# SOCKS proxies
socks5://res1.provider.com:1080
socks5h://res2.provider.com:1080

# Comments with # are ignored
```

### Vulnerability Filtering
```bash
# Basic WordPress detection
atdork -q "inurl:wp-content" -r 30 --filter-vuln wordpress

# Link‑only filter (only matches URLs)
atdork -q "site:example.com" --filter-vuln wordpress-link
```

Create your own wordlist files in `wordlists/` folder:
```text
# wordlists/myplatform.txt
wp-content
wp-admin
wp-includes
```

### Resilience & Rate Limiting
```bash
# Enable circuit breaker & backend fallback
atdork --batch-file dorks.txt --resilient

# Adaptive delay based on backend response
atdork --batch-file dorks.txt --adaptive-delay

# Combined
atdork --batch-file dorks.txt --resilient --adaptive-delay --concurrency 5 --delay 2
```

### Output Validation
```bash
# Disable all filtering (keep raw results)
atdork -q "test" --no-validate

# Strict filtering (require non‑empty snippet)
atdork -q "test" --strict-filter

# Granular control
atdork -q "test" --validate-url only --validate-title 10 --validate-desc 50 --validate-spam true
```

### Database & History
```bash
# Resume interrupted batch
atdork --resume

# View search history
atdork --history

# Export database to JSON/CSV
atdork --export-db all_results.json

# Disable duplicate URL detection
atdork -q "test" --no-dedup
```

### IP Leak Detection (NEW)
```bash
# Halt immediately if your real IP is exposed while using proxies
atdork --batch-file dorks.txt --proxy-file proxies.txt --strict --ip-guard
```

### Post‑Processing (NEW)
```bash
# Run a command for every discovered URL
atdork -q "inurl:admin" -r 10 --exec "curl -I {} | grep Server"

# Run a command only on URLs flagged as vulnerable
atdork -q "inurl:wp-content" -r 30 --filter-vuln wordpress --exec-on-vuln "wpscan --url {}"
```

### Cache Results (NEW)
```bash
# Cache search results for 24 hours (default)
atdork -q "site:gov filetype:pdf" -r 20 --cache

# Use cached results only (offline mode)
atdork -q "site:gov filetype:pdf" -r 20 --cache-only

# Clear all cached data
atdork --clear-cache
```

---

## Complete Flag Reference

| Flag | Description | Default |
|------|-------------|---------|
| `-q`, `--query` | Search dork query | |
| `-r`, `--max-results` | Maximum results (1‑100) | 20 |
| `--batch-file` | File with one query per line | |
| `--batch-separator` | Separator for inline queries | `;` |
| `-o`, `--output` | Save results to file | |
| `--output-dir` | Save each query to separate file | |
| `--format` | Output format: `txt`, `json`, `csv` | `txt` |
| `-v`, `--verbose` | Show results in batch mode | |
| `--no-snippet` | Hide snippets in terminal | |
| `--template` | Load dork template(s) | |
| `--target` | Domain for template substitution | |
| `--select` | Select specific dorks from template | |
| `--list-templates` | List available templates | |
| `--template-path` | Custom template directory | |
| `--preview` | Preview template dorks | |
| `--region` | Search region | `us-en` |
| `--safesearch` | `on`, `moderate`, `off` | `moderate` |
| `--timelimit` | `d`, `w`, `m`, `y` | |
| `--backend` | Search engine(s) | `auto` |
| `--user-agent` | Custom User‑Agent | auto‑rotate |
| `--timeout` | Request timeout (seconds) | 10 |
| `--retries` | Retry attempts on failure | 2 |
| `--delay` | Delay between requests (seconds) | 0 |
| `--proxy` | Comma‑separated proxy URLs | |
| `--proxy-file` | File with proxy URLs | |
| `--tor` | Use Tor SOCKS5 proxy | |
| `--strict` | Fail if all proxies down | |
| `--proxy-cooldown` | Cooldown after proxy failure (seconds) | 60 |
| `--max-failures` | Remove proxy after N failures | 3 |
| `--concurrency` | Parallel threads for batch | 1 |
| `--resilient` | Enable circuit breaker & fallback | |
| `--adaptive-delay` | Enable adaptive rate limiting | |
| `--ip-guard` | Enable IP leak detection | |
| `--exec` | Execute command on each result URL | |
| `--exec-on-vuln` | Execute command on vulnerable results | |
| `--exec-parallel` | Parallel `--exec` processes | 1 |
| `--exec-timeout` | Timeout per `--exec` command (seconds) | 30 |
| `--cache` | Enable result caching | |
| `--cache-db` | Cache database path | `atdork_cache.db` |
| `--cache-ttl` | Cache TTL in hours | 24 |
| `--cache-only` | Use cache only, no network requests | |
| `--clear-cache` | Delete all cache before starting | |
| `--no-validate` | Disable spam filtering | |
| `--strict-filter` | Strict validation | |
| `--validate-url` | URL validation mode | `all` |
| `--validate-title` | Minimum title length | 5 |
| `--validate-desc` | Minimum description length | 10 |
| `--validate-spam` | Enable spam detection | `true` |
| `--filter-vuln` | Vulnerability platform filter | |
| `--no-fallback-backends` | Disable backend fallback | |
| `--no-verify` | Disable SSL verification | |
| `--log-file` | Log file path | `atdork.log` |
| `--db-path` | Database path | `atdork.db` |
| `--resume` | Resume pending queries | |
| `--history` | Show search history | |
| `--no-dedup` | Disable URL deduplication | |
| `--export-db` | Export database to file | |
| `--config` | YAML config file path | |
| `--interactive` | Interactive mode | |
| `--debug` | Enable debug logging | |
| `--version` | Show version and exit | |

---

## Real‑World Use Cases

### Bug Bounty Reconnaissance with Full Protection
```bash
atdork --template sqli,xss,lfi --target target.com \
  --proxy-file proxies.txt --strict --resilient --ip-guard \
  --format json -o recon.json
```

### Exposed Database Credentials
```bash
atdork -q 'filetype:env "DB_PASSWORD"' -r 50 --no-validate -v
```

### Finding Admin Panels
```bash
atdork -q 'intitle:"admin panel" inurl:login' -r 30 --backend google --region uk-en
```

### WordPress Vulnerability Scanning with Post‑Processing
```bash
atdork -q "inurl:wp-content site:example.com" -r 40 \
  --filter-vuln wordpress \
  --exec-on-vuln "wpscan --url {} --enumerate p" \
  --exec-parallel 2 --exec-timeout 60
```

### Automated Weekly Monitoring
```bash
# Add to crontab (Linux/macOS)
0 6 * * 1 cd /path/to/atdork && atdork --batch-file weekly_dorks.txt --format csv --output-dir /reports/$(date +\%Y-\%W)/

# AtDork – Professional OSINT Dorking Tool

![Version](https://img.shields.io/badge/version-1.3.8-blue.svg)
![Python](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)
![Tests](https://img.shields.io/badge/tests-114%20passed-brightgreen)
![Lines](https://img.shields.io/badge/total%20lines-10%2C000%2B-orange)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/atdork?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=pypi+downloads)](https://pepy.tech/projects/atdork)

**AtDork** is a powerful, ethical OSINT tool that performs advanced search queries (Google Dorks) across multiple search engines simultaneously. Designed for security researchers, penetration testers, and bug bounty hunters, it automates the discovery of exposed documents, vulnerable parameters, misconfigured servers, and other sensitive information available on the public web.

---

## Why AtDork?

- 🚀 **Blazing fast** – Multi‑threaded batch processing with configurable concurrency.
- 🔍 **Multi‑engine** – Queries DuckDuckGo, Google, Bing, Startpage, Yandex, Yahoo, and more.
- 🛡️ **Anonymous** – Built‑in proxy rotation, Tor integration, strict mode to prevent IP leaks. **NEW: IP leak detection (`--ip-guard`)** stops the scan immediately if your real IP is exposed.
- 🧹 **Clean results** – Automatic spam filtering, URL validation, and deduplication.
- 📊 **Professional output** – Export to JSON, CSV, TXT; SQLite database for history and resume. **CSV exports are now protected against formula injection.**
- 🎯 **Smart filtering** – Vulnerability signature detection for WordPress, Joomla, SQLi, and more.
- 📝 **Template system** – Curated YAML‑based dork collections for instant productivity.
- ⚙️ **Highly configurable** – **50+ CLI flags** to control every aspect of your search.
- 🔧 **Post‑processing** – Execute external commands on discovered URLs (`--exec`).
- 💾 **Caching** – Cache search results locally to avoid redundant requests and enable offline access.
- 🔒 **Safe logging** – Proxy credentials are automatically redacted from log files to prevent accidental leaks.

---

## Installation

### From PyPI (Recommended)
```bash
pip install atdork
```

### From Source
```bash
git clone https://github.com/amnottdevv/atdork.git
cd atdork
pip install .
```

### Verify Installation
```bash
atdork --version
# Output: atdork 1.3.8
```

---

## Quick Start

### 1. Your First Search
```bash
atdork -q "site:gov filetype:pdf" -r 10
```
This finds PDF files on government websites and displays the top 10 results.

### 2. Save Results to a File
```bash
atdork -q "intitle:index.of mp3" -r 20 --format json -o music.json
```

### 3. Batch Processing
Create a file `dorks.txt`:
```text
site:edu filetype:xls
inurl:admin login
intitle:"index of" "backup"
```

Run them all at once:
```bash
atdork --batch-file dorks.txt -r 30 --format csv -o results.csv
```

### 4. Search with Proxy (Anonymous)
```bash
atdork -q "confidential filetype:docx" --proxy "http://user:pass@proxy:8080" --strict
```

---

## Detailed Usage

### Single Query
```bash
atdork -q "inurl:product.php?id=" -r 50 --backend google --region uk-en --safesearch off
```

| Flag | Purpose |
|------|---------|
| `-q` | Your dork query |
| `-r` | Number of results (max 100) |
| `--backend` | Search engine: `google`, `bing`, `duckduckgo`, `startpage`, `yandex`, `auto` |
| `--region` | Region code: `us-en`, `uk-en`, `de-de`, `ru-ru`, etc. |
| `--safesearch` | `on`, `moderate`, `off` |

### Batch Processing with Multi‑Threading
```bash
atdork --batch-file dorks.txt -r 40 --concurrency 5 --delay 2 --format json -o batch_results.json
```

| Flag | Purpose |
|------|---------|
| `--batch-file` | Text file with one dork per line |
| `--concurrency` | Number of parallel threads (1‑10) |
| `--delay` | Seconds between requests (avoid rate limits) |
| `-o` | Save all results to a single file |
| `--output-dir` | Save each query result as a separate file |

### Template Dorks (Pre‑Built)
List available templates:
```bash
atdork --list-templates
```

Use a template:
```bash
atdork --template sqli --target example.com -r 30
```

Combine multiple templates with custom queries:
```bash
atdork --template sqli,wordpress,exposed_config -q "site:gov filetype:pdf" -r 25
```

Preview what a template will do:
```bash
atdork --template login_panels --preview
```

Run only specific dorks from a template:
```bash
atdork --template sqli --select 1,3,5 -r 20
```

| Flag | Purpose |
|------|---------|
| `--template` | Template name(s), comma‑separated |
| `--target` | Domain to substitute `{target}` in template dorks |
| `--select` | Run specific dork numbers from template |
| `--list-templates` | Show all available templates |
| `--preview` | Show dorks without executing |
| `--template-path` | Custom template folder |

### Proxy & Anonymity
```bash
# Single proxy
atdork -q "target" --proxy "http://user:pass@host:8080"

# Multiple proxies (comma‑separated)
atdork -q "target" --proxy "http://p1:8080,socks5://p2:1080"

# From file
atdork -q "target" --proxy-file proxies.txt

# Tor integration
atdork -q "target" --tor --strict

# Strict mode (fail if all proxies down)
atdork -q "target" --proxy-file proxies.txt --strict

# Proxy management
atdork -q "target" --proxy-file proxies.txt --proxy-cooldown 120 --max-failures 3
```

**Proxy file format (`proxies.txt`):**
```text
# HTTP proxies
http://user:pass@dc1.provider.com:3128
http://user:pass@dc2.provider.com:3128

# SOCKS proxies
socks5://res1.provider.com:1080
socks5h://res2.provider.com:1080

# Comments with # are ignored
```

### Vulnerability Filtering
```bash
# Basic WordPress detection
atdork -q "inurl:wp-content" -r 30 --filter-vuln wordpress

# Link‑only filter (only matches URLs)
atdork -q "site:example.com" --filter-vuln wordpress-link
```

Create your own wordlist files in `wordlists/` folder:
```text
# wordlists/myplatform.txt
wp-content
wp-admin
wp-includes
```

### Resilience & Rate Limiting
```bash
# Enable circuit breaker & backend fallback
atdork --batch-file dorks.txt --resilient

# Adaptive delay based on backend response
atdork --batch-file dorks.txt --adaptive-delay

# Combined
atdork --batch-file dorks.txt --resilient --adaptive-delay --concurrency 5 --delay 2
```

### Output Validation
```bash
# Disable all filtering (keep raw results)
atdork -q "test" --no-validate

# Strict filtering (require non‑empty snippet)
atdork -q "test" --strict-filter

# Granular control
atdork -q "test" --validate-url only --validate-title 10 --validate-desc 50 --validate-spam true
```

### Database & History
```bash
# Resume interrupted batch
atdork --resume

# View search history
atdork --history

# Export database to JSON/CSV
atdork --export-db all_results.json

# Disable duplicate URL detection
atdork -q "test" --no-dedup
```

### IP Leak Detection (NEW)
```bash
# Halt immediately if your real IP is exposed while using proxies
atdork --batch-file dorks.txt --proxy-file proxies.txt --strict --ip-guard
```

### Post‑Processing (NEW)
```bash
# Run a command for every discovered URL
atdork -q "inurl:admin" -r 10 --exec "curl -I {} | grep Server"

# Run a command only on URLs flagged as vulnerable
atdork -q "inurl:wp-content" -r 30 --filter-vuln wordpress --exec-on-vuln "wpscan --url {}"
```

### Cache Results (NEW)
```bash
# Cache search results for 24 hours (default)
atdork -q "site:gov filetype:pdf" -r 20 --cache

# Use cached results only (offline mode)
atdork -q "site:gov filetype:pdf" -r 20 --cache-only

# Clear all cached data
atdork --clear-cache
```

---

## Complete Flag Reference

| Flag | Description | Default |
|------|-------------|---------|
| `-q`, `--query` | Search dork query | |
| `-r`, `--max-results` | Maximum results (1‑100) | 20 |
| `--batch-file` | File with one query per line | |
| `--batch-separator` | Separator for inline queries | `;` |
| `-o`, `--output` | Save results to file | |
| `--output-dir` | Save each query to separate file | |
| `--format` | Output format: `txt`, `json`, `csv` | `txt` |
| `-v`, `--verbose` | Show results in batch mode | |
| `--no-snippet` | Hide snippets in terminal | |
| `--template` | Load dork template(s) | |
| `--target` | Domain for template substitution | |
| `--select` | Select specific dorks from template | |
| `--list-templates` | List available templates | |
| `--template-path` | Custom template directory | |
| `--preview` | Preview template dorks | |
| `--region` | Search region | `us-en` |
| `--safesearch` | `on`, `moderate`, `off` | `moderate` |
| `--timelimit` | `d`, `w`, `m`, `y` | |
| `--backend` | Search engine(s) | `auto` |
| `--user-agent` | Custom User‑Agent | auto‑rotate |
| `--timeout` | Request timeout (seconds) | 10 |
| `--retries` | Retry attempts on failure | 2 |
| `--delay` | Delay between requests (seconds) | 0 |
| `--proxy` | Comma‑separated proxy URLs | |
| `--proxy-file` | File with proxy URLs | |
| `--tor` | Use Tor SOCKS5 proxy | |
| `--strict` | Fail if all proxies down | |
| `--proxy-cooldown` | Cooldown after proxy failure (seconds) | 60 |
| `--max-failures` | Remove proxy after N failures | 3 |
| `--concurrency` | Parallel threads for batch | 1 |
| `--resilient` | Enable circuit breaker & fallback | |
| `--adaptive-delay` | Enable adaptive rate limiting | |
| `--ip-guard` | Enable IP leak detection | |
| `--exec` | Execute command on each result URL | |
| `--exec-on-vuln` | Execute command on vulnerable results | |
| `--exec-parallel` | Parallel `--exec` processes | 1 |
| `--exec-timeout` | Timeout per `--exec` command (seconds) | 30 |
| `--cache` | Enable result caching | |
| `--cache-db` | Cache database path | `atdork_cache.db` |
| `--cache-ttl` | Cache TTL in hours | 24 |
| `--cache-only` | Use cache only, no network requests | |
| `--clear-cache` | Delete all cache before starting | |
| `--no-validate` | Disable spam filtering | |
| `--strict-filter` | Strict validation | |
| `--validate-url` | URL validation mode | `all` |
| `--validate-title` | Minimum title length | 5 |
| `--validate-desc` | Minimum description length | 10 |
| `--validate-spam` | Enable spam detection | `true` |
| `--filter-vuln` | Vulnerability platform filter | |
| `--no-fallback-backends` | Disable backend fallback | |
| `--no-verify` | Disable SSL verification | |
| `--log-file` | Log file path | `atdork.log` |
| `--db-path` | Database path | `atdork.db` |
| `--resume` | Resume pending queries | |
| `--history` | Show search history | |
| `--no-dedup` | Disable URL deduplication | |
| `--export-db` | Export database to file | |
| `--config` | YAML config file path | |
| `--interactive` | Interactive mode | |
| `--debug` | Enable debug logging | |
| `--version` | Show version and exit | |

---

## Real‑World Use Cases

### Bug Bounty Reconnaissance with Full Protection
```bash
atdork --template sqli,xss,lfi --target target.com \
  --proxy-file proxies.txt --strict --resilient --ip-guard \
  --format json -o recon.json
```

### Exposed Database Credentials
```bash
atdork -q 'filetype:env "DB_PASSWORD"' -r 50 --no-validate -v
```

### Finding Admin Panels
```bash
atdork -q 'intitle:"admin panel" inurl:login' -r 30 --backend google --region uk-en
```

### WordPress Vulnerability Scanning with Post‑Processing
```bash
atdork -q "inurl:wp-content site:example.com" -r 40 \
  --filter-vuln wordpress \
  --exec-on-vuln "wpscan --url {} --enumerate p" \
  --exec-parallel 2 --exec-timeout 60
```

### Automated Weekly Monitoring
```bash
# Add to crontab (Linux/macOS)
0 6 * * 1 cd /path/to/atdork && atdork --batch-file weekly_dorks.txt --format csv --output-dir /reports/$(date +\%Y-\%W)/
```

---

## Configuration File

Create `atdork.yaml` for persistent settings:
```yaml
max_results: 30
region: "uk-en"
safesearch: "off"
delay: 1.0
format: "json"
output_dir: "./results"
proxy_file: "proxies.txt"
```

AtDork automatically loads this file from the current directory. CLI flags override YAML values.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| **Rate limited (429)** | Add `--delay 3`, use `--proxy-file`, or enable `--adaptive-delay` |
| **No results** | Try different `--backend` (e.g., `startpage`, `yandex`) or `--region` |
| **Proxy fails** | Check format: `scheme://user:pass@host:port` |
| **Batch stuck** | Reduce `--concurrency`, add `--timeout 15`, enable `--resilient` |
| **Install error** | Use `pip install -e .` for development mode |
| **IP leak with --strict** | Enable `--ip-guard` to detect leaks early; use SOCKS5h proxies |
| **All backends exhausted** | Enable `--resilient` to activate backend fallback chain |
| **CSV opens with formulas** | Update to v1.3.8+ (CSV injection fixed) |
| **Proxy credentials in logs** | Update to v1.3.8+ (credentials are now redacted) |

---

## Project Structure

```
atdork/
├── atdork.py                    # CLI entry point
├── core/
│   ├── scanner.py               # Search engine integration
│   ├── batch_runner.py          # Batch execution (seq/parallel, resilience)
│   ├── proxy_manager.py         # Proxy pool management
│   ├── filter_vuln.py           # Vulnerability signature filtering
│   ├── template_dork.py         # YAML template loader
│   ├── post_processor.py        # External command execution on results
│   ├── manage_cache.py          # SQLite-based result caching
│   ├── database.py              # SQLite storage & export
│   ├── config.py                # YAML configuration loader
│   ├── logger.py                # Rotating file logger
│   └── case/
│       ├── circuit_breaker.py   # Prevent hammering dead backends
│       ├── ip_guard.py          # Real IP leak detection
│       ├── error_classifier.py  # Categorize exceptions
│       ├── fallback_manager.py  # Intelligent backend/proxy switching
│       ├── retry_handler.py     # Exponential backoff with jitter
│       ├── adaptive_delay.py    # Per‑backend dynamic delay
│       ├── recovery_strategy.py # Map errors to recovery actions
│       └── stats.py             # Runtime statistics collector
├── lib/
│   ├── display.py               # Terminal output formatting
│   ├── storage.py               # File export (TXT/JSON/CSV)
│   ├── validator.py             # Spam/invalid result filtering
│   └── redactor.py              # Proxy credential redaction
├── wordlists/                   # Vulnerability signatures & templates
├── tests/                       # Unit tests (pytest)
├── pyproject.toml               # Package configuration
└── README.md
```

---

## Ethical Use & Disclaimer

AtDork is intended for **legal, authorized security testing only**.
You must have explicit written permission from the target owner before scanning.

**Prohibited uses:**
- Unauthorized access to systems or data
- Harvesting information in violation of laws
- Any activity that infringes on privacy or intellectual property rights

The developer assumes no liability for misuse of this software.

---

## Licensei

Distributed under the MIT License. See `LICENSE` for details.

---

## Acknowledgements

- **tg12** – for responsibly disclosing critical security vulnerabilities (CSV injection and proxy credential leakage) and helping make AtDork safer for everyone.
- **Peter7896** – for the excellent pull request that fixed packaged wordlist resources, ensuring seamless functionality for `pip install` users.

---

## Contact & Support

- **GitHub:** [github.com/amnottdevv/atdork](https://github.com/amnottdevv/atdork)
- **Issues:** [github.com/amnottdevv/atdork/issues](https://github.com/amnottdevv/atdork/issues)
- **PyPI:** [pypi.org/project/atdork](https://pypi.org/project/atdork/)

If you find this tool useful, consider leaving a ⭐ on GitHub!
```

---

## Configuration File

Create `atdork.yaml` for persistent settings:
```yaml
max_results: 30
region: "uk-en"
safesearch: "off"
delay: 1.0
format: "json"
output_dir: "./results"
proxy_file: "proxies.txt"
```

AtDork automatically loads this file from the current directory. CLI flags override YAML values.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| **Rate limited (429)** | Add `--delay 3`, use `--proxy-file`, or enable `--adaptive-delay` |
| **No results** | Try different `--backend` (e.g., `startpage`, `yandex`) or `--region` |
| **Proxy fails** | Check format: `scheme://user:pass@host:port` |
| **Batch stuck** | Reduce `--concurrency`, add `--timeout 15`, enable `--resilient` |
| **Install error** | Use `pip install -e .` for development mode |
| **IP leak with --strict** | Enable `--ip-guard` to detect leaks early; use SOCKS5h proxies |
| **All backends exhausted** | Enable `--resilient` to activate backend fallback chain |
| **CSV opens with formulas** | Update to v1.3.8+ (CSV injection fixed) |
| **Proxy credentials in logs** | Update to v1.3.8+ (credentials are now redacted) |

---

## Project Structure

```
atdork/
├── atdork.py                    # CLI entry point
├── core/
│   ├── scanner.py               # Search engine integration
│   ├── batch_runner.py          # Batch execution (seq/parallel, resilience)
│   ├── proxy_manager.py         # Proxy pool management
│   ├── filter_vuln.py           # Vulnerability signature filtering
│   ├── template_dork.py         # YAML template loader
│   ├── post_processor.py        # External command execution on results
│   ├── manage_cache.py          # SQLite-based result caching
│   ├── database.py              # SQLite storage & export
│   ├── config.py                # YAML configuration loader
│   ├── logger.py                # Rotating file logger
│   └── case/
│       ├── circuit_breaker.py   # Prevent hammering dead backends
│       ├── ip_guard.py          # Real IP leak detection
│       ├── error_classifier.py  # Categorize exceptions
│       ├── fallback_manager.py  # Intelligent backend/proxy switching
│       ├── retry_handler.py     # Exponential backoff with jitter
│       ├── adaptive_delay.py    # Per‑backend dynamic delay
│       ├── recovery_strategy.py # Map errors to recovery actions
│       └── stats.py             # Runtime statistics collector
├── lib/
│   ├── display.py               # Terminal output formatting
│   ├── storage.py               # File export (TXT/JSON/CSV)
│   ├── validator.py             # Spam/invalid result filtering
│   └── redactor.py              # Proxy credential redaction
├── wordlists/                   # Vulnerability signatures & templates
├── tests/                       # Unit tests (pytest)
├── pyproject.toml               # Package configuration
└── README.md
```

---

## Ethical Use & Disclaimer

AtDork is intended for **legal, authorized security testing only**.
You must have explicit written permission from the target owner before scanning.

**Prohibited uses:**
- Unauthorized access to systems or data
- Harvesting information in violation of laws
- Any activity that infringes on privacy or intellectual property rights

The developer assumes no liability for misuse of this software.

---

## License

Distributed under the MIT License. See `LICENSE` for details.

---

## Acknowledgements

- **tg12** – for responsibly disclosing critical security vulnerabilities (CSV injection and proxy credential leakage) and helping make AtDork safer for everyone.
- **Peter7896** – for the excellent pull request that fixed packaged wordlist resources, ensuring seamless functionality for `pip install` users.

---

## Contact & Support

- **GitHub:** [github.com/amnottdevv/atdork](https://github.com/amnottdevv/atdork)
- **Issues:** [github.com/amnottdevv/atdork/issues](https://github.com/amnottdevv/atdork/issues)
- **PyPI:** [pypi.org/project/atdork](https://pypi.org/project/atdork/)

If you find this tool useful, consider leaving a ⭐ on GitHub!

