usage guide

# Usage Guide

This guide covers every operational mode and configuration option available in Atdork.  
After reading it, you'll be able to fine‑tune the tool for your specific OSINT or security testing workflow.

---

## Interactive Mode

Interactive mode is the easiest way to perform a single query.  
The tool asks you a series of questions and handles all the defaults.

### Starting interactive mode
```bash
python main.py --interactive

Or simply run python main.py without any arguments – if no query or output options are provided, it automatically launches the interactive wizard.

Prompts you'll see

1. Keyword/dork – your actual search string, e.g., site:gov filetype:pdf
2. Maximum results – number of results (1–100). Invalid input falls back to 20.
3. Save to file? – if you answer y, results are saved as a plain text file in the current directory.

All other parameters (region, safesearch, backend, etc.) use the default values (see Command Reference).

---

CLI Mode (Non‑Interactive)

CLI mode allows you to pass all options directly. It's suitable for scripting, automation, and when you need full control.

Basic single query

python main.py -q "intitle:index.of mp3" -r 30

With region and safesearch

python main.py -q "cyber attack" --region uk-en --safesearch off

Filter by time

python main.py -q "data leak" --timelimit m   # results from the last month

Choose a specific search backend

python main.py -q "admin login" --backend google

Available backends: auto, bing, brave, duckduckgo, google, grokipedia, mojeek, startpage, yandex, yahoo, wikipedia.

Add delay between requests

python main.py -q "company intranet" -r 50 --delay 2

Custom User‑Agent

python main.py -q "test" --user-agent "MyCustomBot/1.0"

If --user-agent is not set, Atdork automatically rotates through a pool of modern desktop and mobile User‑Agent strings.

Debug mode

python main.py -q "test" -r 5 --debug

This enables verbose logging, showing which User‑Agent is used, proxy attempts, retries, and more.

---

Batch Processing

Batch processing is essential for running multiple dorks in one session.
Atdork supports two input methods: file and inline string.

From a file

Create a plain text file (e.g., dorks.txt) with one query per line.
Empty lines and lines starting with # are ignored.

Example file:

# Admin panels
intitle:"admin panel" inurl:login
# Exposed logs
"index of" "/logs/"
# Sensitive documents
site:gov filetype:pdf confidential

Run the batch:

python main.py --batch-file dorks.txt -r 10 --delay 1 --format json -o batch_results.json

A progress bar will appear. After completion, the combined results are saved to batch_results.json.

From inline string

Use a separator (default ;) to split multiple queries:

python main.py -q "dork1;dork2;dork3" --batch-separator ";" -r 10 --output-dir batch_out --format csv

Each query's results will be saved as a separate CSV file inside the batch_out/ folder. File names are sanitised from the query text.

---

Proxy Configuration

Proxies are crucial for anonymity and avoiding rate limits. Atdork supports multiple proxy sources, automatic rotation, and smart fallback behaviour.

Single proxy or comma‑separated list

python main.py -q "target" --proxy "http://user:pass@10.0.0.1:8080,socks5://127.0.0.1:1080"

Proxy file

Create a file (e.g., proxies.txt) with one proxy URL per line:

http://proxy1:3128
socks5h://proxy2:1080

Then use:

python main.py -q "target" --proxy-file proxies.txt

Tor integration

Ensure Tor is running and listening on 127.0.0.1:9050. Then use:

python main.py -q "target" --tor

This automatically adds socks5h://127.0.0.1:9050 to the proxy pool.
Combine with --strict to avoid ever falling back to a direct connection.

Strict mode

When --strict is enabled, Atdork will not use your real IP if every proxy fails. Instead, it raises an error.

python main.py -q "sensitive" --proxy-file proxies.txt --strict

Proxy management parameters

• --proxy-cooldown 60 – number of seconds to wait before reusing a proxy that just failed.
• --max-failures 3 – automatically remove a proxy from the pool after it fails this many times in a row. Set to 0 to disable removal.

Example with full control:

python main.py -q "target" --proxy-file proxies.txt --proxy "http://fallback:8080" --tor --strict --proxy-cooldown 120 --max-failures 2

Checking proxy statistics

Run with --debug to see live proxy statistics after a search:

python main.py -q "test" --proxy "http://bad:8080,socks5://good:1080" --debug

At the end (or during batch processing) you'll see metrics like:

Proxy stats: {'active': 1, 'banned': 1, 'total_success': 3, 'total_failure': 2}

---

Output Options

Atdork can display results on screen and/or save them to files in various formats.

On‑screen display

By default, results are printed with title, URL, and a snippet (first 200 characters).
Use --no-snippet to show only titles and URLs.

Saving to a file

• -o results.txt saves results in TXT format.
• -o results.json (or --format json) saves as JSON.
• -o results.csv (or --format csv) saves as CSV.

The format is auto‑detected from the file extension unless --format is explicitly provided.

Saving without specifying file name

Use --output-dir folder/ to automatically generate a file name based on the current timestamp.

python main.py -q "test" --output-dir ./out --format json
# Creates: ./out/dork_20250215_143022.json

Batch output

• If you use -o, all batch results are saved in a single JSON file (the structure is {query: [results]}).
• If you use --output-dir, each query is saved as a separate file inside that folder.
• Both flags cannot be used at the same time (-o takes precedence).

---

Advanced: Combining Everything

A typical professional use case:
Run a batch of dorks with multiple proxies, strict anonymity, JSON output, and a short delay.

python main.py \
  --batch-file dorks.txt \
  --proxy-file proxies.txt \
  --tor \
  --strict \
  --delay 2 \
  --retries 3 \
  --timeout 15 \
  --max-results 30 \
  --backend google,bing \
  --output-dir batch_results \
  --format json \
  --debug

---

Next: Command Reference for a complete list of every flag.