Skip to content

Commit 525fd42

Browse files
Ap6packAp6pack
authored
Create README.md for DomainTool with detailed documentation
Added comprehensive README for DomainTool, detailing features, installation, usage, and troubleshooting.
1 parent f7b7835 commit 525fd42

1 file changed

Lines changed: 362 additions & 0 deletions

File tree

‎DomainTool/README.md‎

Lines changed: 362 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,362 @@
1+
# DomainTool
2+
3+
A comprehensive Python-based domain analysis tool for performing various network lookups and gathering domain information. Perfect for auditing domain portfolios, security assessments, and network reconnaissance.
4+
5+
## Features
6+
7+
### Network Lookups
8+
- **WHOIS Lookup** - Extract registrar, name servers, and registration details
9+
- **NSLookup** - Query name server records
10+
- **DNS Lookup** - Resolve domain DNS records
11+
- **Reverse DNS Lookup** - Find hostnames from IP addresses
12+
- **SSL Certificate Lookup** - Check SSL certificate details and expiration
13+
- **HTTP Headers Lookup** - Examine HTTP response headers
14+
15+
### Data Management
16+
- **Multiple Input Formats** - Excel (.xlsx), XML, Text (.txt), or manual terminal entry
17+
- **Multiple Output Formats** - Save results as Excel, XML, Text, or print to terminal
18+
- **Batch Processing** - Process multiple domains in one operation
19+
- **Interactive Menu System** - User-friendly command-line interface
20+
21+
## Installation
22+
23+
### Prerequisites
24+
- Python 3.x
25+
- pip (Python package manager)
26+
27+
### Required Dependencies
28+
29+
```bash
30+
pip install openpyxl python-whois dnspython pyOpenSSL requests
31+
```
32+
33+
Or install from requirements file:
34+
35+
```bash
36+
pip install -r requirements.txt
37+
```
38+
39+
### Dependencies List
40+
- `openpyxl` - Excel file operations
41+
- `python-whois` - WHOIS lookups
42+
- `dnspython` - DNS operations
43+
- `pyOpenSSL` - SSL certificate handling
44+
- `requests` - HTTP operations
45+
- `tkinter` - File dialog (usually comes with Python)
46+
47+
## Usage
48+
49+
### Starting the Application
50+
51+
```bash
52+
python domainTool.py
53+
```
54+
55+
### Main Menu Options
56+
57+
```
58+
1. Load data from Excel
59+
2. Load data from XML
60+
3. Load data from Text
61+
4. Load data from Terminal
62+
5. Exit
63+
```
64+
65+
### Input File Formats
66+
67+
#### Excel (.xlsx)
68+
Domains should be in the first column:
69+
```
70+
domain.com
71+
example.org
72+
website.net
73+
```
74+
75+
#### XML
76+
```xml
77+
<?xml version="1.0"?>
78+
<root>
79+
<domain>domain.com</domain>
80+
<domain>example.org</domain>
81+
<domain>website.net</domain>
82+
</root>
83+
```
84+
85+
#### Text (.txt)
86+
One domain per line:
87+
```
88+
domain.com
89+
example.org
90+
website.net
91+
```
92+
93+
#### Terminal Input
94+
Enter domains directly when prompted, one per line. Press Enter twice when done.
95+
96+
### Function Menu
97+
98+
After loading data, select lookup operations:
99+
100+
```
101+
1. Perform WHOIS lookup
102+
2. Perform NSLookup
103+
3. Perform DNS lookup
104+
4. Perform reverse DNS lookup
105+
5. Perform SSL certificate lookup
106+
6. Perform HTTP headers lookup
107+
7. Return to Main Menu
108+
8. Exit
109+
```
110+
111+
**Pro Tip:** You can select multiple operations by entering comma-separated numbers (e.g., `1,2,3`)
112+
113+
### WHOIS Lookup Output
114+
115+
The WHOIS lookup extracts:
116+
- **Domain name**
117+
- **Registrar** (e.g., GoDaddy, Namecheap, MarkMonitor)
118+
- **Creation Date**
119+
- **Expiration Date**
120+
- **Name Servers**
121+
- **Status** (success/error)
122+
- **Error Message** (if lookup failed)
123+
124+
**Excel Output Format:**
125+
| Domain | Registrar | Creation Date | Expiration Date | Name Servers | Status | Error Message |
126+
|--------|-----------|---------------|-----------------|--------------|---------|---------------|
127+
| example.com | GoDaddy.com, LLC | 2015-03-15 | 2026-03-15 | ns1.godaddy.com, ns2.godaddy.com | success | |
128+
| google.com | MarkMonitor Inc. | 1997-09-15 | 2028-09-14 | ns1.google.com, ns2.google.com | success | |
129+
130+
**Text/Terminal Output Format:**
131+
```
132+
[1] Domain: example.com
133+
Registrar: GoDaddy.com, LLC
134+
Creation Date: 2015-03-15
135+
Expiration Date: 2026-03-15
136+
Name Servers: ns1.godaddy.com, ns2.godaddy.com
137+
------------------------------------------------------------
138+
```
139+
140+
### Save Menu
141+
142+
After running lookups, choose how to save results:
143+
144+
```
145+
1. Save output as Excel
146+
2. Save output as XML
147+
3. Save output as Text
148+
4. Print output to Terminal
149+
5. Return to Main Menu
150+
6. Exit
151+
```
152+
153+
## Output Formats
154+
155+
### Excel Format (Recommended for Analysis)
156+
157+
All lookups save as **structured columns** for easy sorting, filtering, and analysis:
158+
159+
**Features:**
160+
- One row per domain/IP
161+
- Separate columns for each data field
162+
- Colored headers (blue background, white text)
163+
- Auto-adjusted column widths
164+
- Status column to identify failed lookups
165+
- Error messages for troubleshooting
166+
167+
**Example - WHOIS Results:**
168+
- Columns: Domain | Registrar | Creation Date | Expiration Date | Name Servers | Status | Error Message
169+
170+
**Why use Excel format:**
171+
- Sort by registrar to group domains
172+
- Filter by expiration date to find domains expiring soon
173+
- Count domains per registrar with pivot tables
174+
- Import into other tools (Tableau, Power BI)
175+
176+
### Text Format (Readable Output)
177+
178+
Saves as human-readable text with numbered entries:
179+
```
180+
[1] Domain: example.com
181+
Registrar: GoDaddy.com, LLC
182+
Creation Date: 2015-03-15
183+
Expiration Date: 2026-03-15
184+
Name Servers: ns1.godaddy.com, ns2.godaddy.com
185+
------------------------------------------------------------
186+
[2] Domain: google.com
187+
...
188+
```
189+
190+
### XML Format (Machine-Readable)
191+
192+
Structured XML with nested elements:
193+
```xml
194+
<?xml version="1.0" encoding="UTF-8"?>
195+
<results>
196+
<result>
197+
<domain>example.com</domain>
198+
<registrar>GoDaddy.com, LLC</registrar>
199+
<creation_date>2015-03-15</creation_date>
200+
...
201+
</result>
202+
</results>
203+
```
204+
205+
### Terminal Output
206+
207+
Same as text format but displayed in the console with separators for easy reading.
208+
209+
## Workflow Examples
210+
211+
### Example 1: Audit Domain Registrars from Excel
212+
213+
1. Run `python domainTool.py`
214+
2. Select `1` (Load data from Excel)
215+
3. Choose your .xlsx file with domains
216+
4. Select `1` (Perform WHOIS lookup)
217+
5. Select `1` (Save output as Excel)
218+
6. Choose save location
219+
220+
### Example 2: Quick DNS Check from Terminal
221+
222+
1. Run `python domainTool.py`
223+
2. Select `4` (Load data from Terminal)
224+
3. Enter domains, press Enter twice when done
225+
4. Select `3` (Perform DNS lookup)
226+
5. Select `4` (Print output to Terminal)
227+
228+
### Example 3: Multiple Lookups on Same Data
229+
230+
1. Load data (any method)
231+
2. Select `1,2,3` to perform WHOIS, NS, and DNS lookups simultaneously
232+
3. Save results in preferred format
233+
234+
## Project Structure
235+
236+
```
237+
DomainTool/
238+
├── domainTool.py # Main entry point
239+
├── data_processor.py # Core data processing logic
240+
├── menu.py # Menu initialization
241+
├── menu_logic.py # Menu flow and user interaction
242+
├── file_operations.py # File I/O operations
243+
├── network_operations.py # Network lookup implementations
244+
├── README.md # This file
245+
└── .gitignore # Git ignore rules
246+
```
247+
248+
## Module Descriptions
249+
250+
### `domainTool.py`
251+
Main application entry point that initializes the DataProcessor and starts the menu system.
252+
253+
### `data_processor.py`
254+
Core class that manages data lifecycle:
255+
- Loading data from various sources
256+
- Storing lookup results
257+
- Coordinating between file operations and network operations
258+
259+
### `menu_logic.py`
260+
Handles all menu interactions:
261+
- Main menu for data loading
262+
- Function menu for selecting lookups
263+
- Save menu for output options
264+
265+
### `file_operations.py`
266+
Manages all file I/O:
267+
- Loading from Excel, XML, Text
268+
- Saving to Excel, XML, Text
269+
- Terminal input/output
270+
- File dialog interactions
271+
272+
### `network_operations.py`
273+
Implements all network lookup functions:
274+
- WHOIS queries
275+
- DNS operations
276+
- SSL certificate checks
277+
- HTTP header inspection
278+
279+
## Common Use Cases
280+
281+
### Domain Portfolio Audit
282+
Use WHOIS lookup to map all domains to their registrars for inventory purposes. The structured Excel output makes it easy to:
283+
- Group domains by registrar
284+
- Count how many domains are with each registrar
285+
- Identify consolidation opportunities
286+
287+
### Expiration Tracking
288+
1. Run WHOIS lookup on your domain portfolio
289+
2. Save as Excel
290+
3. Sort by "Expiration Date" column
291+
4. Filter to show domains expiring in the next 90 days
292+
5. Create renewal reminders
293+
294+
### Registrar Cost Analysis
295+
1. Export WHOIS data to Excel
296+
2. Add a "Cost" column for each registrar's pricing
297+
3. Use pivot tables to calculate total costs per registrar
298+
4. Identify opportunities to consolidate and save money
299+
300+
### Security Assessment
301+
Combine SSL certificate lookup with HTTP headers to assess security configurations. Excel format allows you to:
302+
- Sort by SSL expiration date
303+
- Filter domains missing security headers
304+
- Track certificate renewal schedules
305+
306+
### DNS Troubleshooting
307+
Use NSLookup and DNS lookup to verify proper DNS configuration. The structured output helps you:
308+
- Quickly identify misconfigured domains
309+
- Compare name servers across your portfolio
310+
- Spot DNS propagation issues
311+
312+
## Tips and Best Practices
313+
314+
### For Large Domain Lists (100+ domains)
315+
316+
1. **Be mindful of rate limits** - WHOIS servers may throttle or block excessive queries
317+
2. **Run during off-peak hours** - Better success rates
318+
3. **Save intermediate results** - Save after each batch
319+
4. **Handle errors gracefully** - Review failed lookups and retry manually if needed
320+
321+
### WHOIS Lookup Limitations
322+
323+
- Some registrars limit query frequency
324+
- Different TLDs may return different data formats
325+
- Privacy protection services may hide registrar details
326+
- Temporary network issues can cause failures
327+
328+
### Input Data Tips
329+
330+
- Remove duplicates before processing
331+
- Ensure proper domain format (no http://, no paths)
332+
- For SSL lookups, ensure domains are accessible on port 443
333+
- For HTTP headers, domains should be web-accessible
334+
335+
## Troubleshooting
336+
337+
### "Failed to load data from Excel file"
338+
- Verify file is .xlsx format
339+
- Check that domains are in the first column
340+
- Ensure file isn't corrupted or password-protected
341+
342+
### "WHOIS lookup failed"
343+
- Domain may not exist or is improperly formatted
344+
- WHOIS server may be temporarily unavailable
345+
- Rate limiting may be in effect - try again later
346+
347+
### "SSL certificate lookup failed"
348+
- Domain may not have SSL certificate
349+
- Port 443 may be blocked
350+
- Certificate may be expired or invalid
351+
352+
### "No file selected"
353+
- File dialog was canceled
354+
- Permission issues with file location
355+
- Try running with appropriate permissions
356+
357+
## Security Considerations
358+
359+
- WHOIS queries are logged by registrars
360+
- Be respectful of rate limits to avoid IP blocking
361+
- Some lookups may trigger security monitoring
362+
- Use responsibly and only on domains you own or have permission to query

0 commit comments

Comments
 (0)