Update Dockerfile, main.go, and tests to enhance functionality and validation. Added output file support with -o flag, DNS retry mechanism with -retries flag, and graceful shutdown on SIGINT/SIGTERM. Implemented domain and DNS server validation. Updated tests for new features and improved error handling.

Author: TMHSDigital

Dockerfile

@@ -35,8 +35,8 @@ CMD ["-version"]
 
 LABEL org.opencontainers.image.title="subenum"
 LABEL org.opencontainers.image.description="A Go-based CLI tool for subdomain enumeration"
-LABEL org.opencontainers.image.source="https://github.com/yourusername/subenum"
+LABEL org.opencontainers.image.source="https://github.com/TMHSDigital/subenum"
 LABEL org.opencontainers.image.licenses="MIT"
-LABEL org.opencontainers.image.documentation="https://github.com/yourusername/subenum/blob/main/README.md"
+LABEL org.opencontainers.image.documentation="https://github.com/TMHSDigital/subenum/blob/main/README.md"
 LABEL org.opencontainers.image.vendor="Educational Use Only"
 LABEL org.opencontainers.image.usage="For educational and legitimate security testing purposes only" 

README.md

@@ -96,6 +96,8 @@ go build
 -   `-dns-server <ip:port>`: DNS server to use for lookups (default: 8.8.8.8:53).
 -   `-v`: Enable verbose output with detailed information about each lookup.
 -   `-progress`: Show scan progress (default: true, use `-progress=false` to disable).
+-   `-o <file>`: Write discovered subdomains to file (in addition to stdout).
+-   `-retries <number>`: Number of DNS retry attempts per subdomain (default: 1).
 -   `-version`: Show version information and exit.
 
 ### Output:
@@ -168,6 +170,16 @@ Disabling progress reporting (useful for scripting):
 ./subenum -w words.txt -progress=false example.com
 ```
 
+Saving results to a file:
+```bash
+./subenum -w words.txt -o results.txt example.com
+```
+
+Using retries for unreliable networks:
+```bash
+./subenum -w words.txt -retries 3 example.com
+```
+
 ### Simulation Mode for Safe Testing
 
 The tool includes a simulation mode for safely testing functionality without performing actual DNS queries:

SECURITY.md

@@ -5,7 +5,7 @@
 If you discover a security vulnerability in `subenum`, please follow these steps to report it responsibly:
 
 1. **Do NOT** disclose the vulnerability publicly until it has been addressed.
-2. Send details of the vulnerability to [your-email@example.com] or create a private report through GitHub's Security tab.
+2. Send details of the vulnerability to the repository maintainers via GitHub Issues or create a private report through GitHub's Security tab.
 3. Include the following information:
    - A description of the vulnerability
    - Steps to reproduce the issue

docs/ARCHITECTURE.md

@@ -16,8 +16,6 @@ This architecture is designed to be efficient by performing multiple DNS lookups
 
 ## 2. Key Components / Modules
 
-*(Details to be added regarding components, data flow, concurrency, etc.)*
-
 ### 2.1. Argument Parsing
 
 *   **Purpose**: This component is responsible for processing the command-line arguments provided by the user when `subenum` is executed. It extracts the target domain, the path to the wordlist file, the desired number of concurrent workers, and the DNS lookup timeout.
@@ -29,9 +27,11 @@ This architecture is designed to be efficient by performing multiple DNS lookups
     *   `flag.Bool("v", false, "Enable verbose output")`: Defines the verbose flag.
     *   `flag.Bool("progress", true, "Show progress during scanning")`: Defines the progress reporting flag.
     *   `flag.Bool("version", false, "Show version information")`: Defines the version flag.
+    *   `flag.String("o", "", "Write results to file")`: Defines the output file flag.
+    *   `flag.Int("retries", 1, "Number of DNS retry attempts")`: Defines the retry count flag.
     *   `flag.Parse()`: Parses the provided arguments.
     *   `flag.Arg(0)`: Retrieves the positional argument (the target domain).
-*   **Interactions**: The parsed values are used to configure the subsequent components, such as the Wordlist Processing and DNS Resolution Engine. Input validation is also performed to ensure valid values for critical parameters like concurrency and timeout.
+*   **Interactions**: The parsed values are used to configure the subsequent components, such as the Wordlist Processing and DNS Resolution Engine. Input validation is performed to ensure valid values for critical parameters like concurrency, timeout, DNS server format (validated via `validateDNSServer`), and domain syntax (validated via `validateDomain`).
 
 ### 2.2. Wordlist Processing
 
@@ -47,15 +47,16 @@ This architecture is designed to be efficient by performing multiple DNS lookups
 
 *   **Purpose**: This is the core component responsible for performing the actual DNS lookup for each constructed subdomain (e.g., `prefix.targetdomain.com`). It determines if a subdomain has a valid DNS record (typically A or CNAME, though the current implementation checks for any successful resolution).
 *   **Implementation**:
-    *   Function: `resolveDomain(domain string, timeout time.Duration) bool`
+    *   Function: `resolveDomain(domain string, timeout time.Duration, dnsServer string, verbose bool) bool`
+    *   Function: `resolveDomainWithRetry(domain string, timeout time.Duration, dnsServer string, verbose bool, maxRetries int) bool` — wraps `resolveDomain` with configurable retry logic and exponential backoff between attempts.
     *   `net.Resolver{}`: A custom DNS resolver is configured.
         *   `PreferGo: true`: Instructs the resolver to use the pure Go DNS client.
-        *   `Dial func(ctx context.Context, network, address string) (net.Conn, error)`: A custom dial function is provided to control the connection to the DNS server. This allows for setting a specific timeout for the dial operation and for specifying the DNS server to use (currently hardcoded to Google's public DNS `8.8.8.8:53`).
+        *   `Dial func(ctx context.Context, network, address string) (net.Conn, error)`: A custom dial function is provided to control the connection to the DNS server, using the user-specified `dnsServer` address.
             *   `net.Dialer{Timeout: timeout}`: A `Dialer` is created with the user-specified timeout.
-            *   `d.DialContext(ctx, "udp", "8.8.8.8:53")`: Establishes a UDP connection to the DNS server.
+            *   `d.DialContext(ctx, "udp", dnsServer)`: Establishes a UDP connection to the configured DNS server.
     *   `resolver.LookupHost(context.Background(), domain)`: Performs the DNS lookup for the given domain. It attempts to find A or AAAA records for the host.
     *   The function returns `true` if `LookupHost` returns no error (i.e., the domain resolved), and `false` otherwise.
-*   **Interactions**: This function is called by each worker goroutine. It takes a fully qualified domain name and the timeout duration as input. It outputs a boolean indicating whether the domain resolved successfully. The result is used to decide if the domain should be printed to the console.
+*   **Interactions**: Workers call `resolveDomainWithRetry`, which delegates to `resolveDomain` with retry logic. It takes a fully qualified domain name, timeout duration, DNS server address, verbose flag, and retry count as input. It outputs a boolean indicating whether the domain resolved successfully. The result is used to decide if the domain should be printed to the console and/or written to the output file.
 
 ### 2.4. Concurrency Management (Worker Pool)
 
@@ -144,8 +145,13 @@ Visually, this can be seen as:
 
 ### 4.1. User Input Errors
 
-*   **Missing Required Arguments**: When the user doesn't provide a wordlist file (`-w` flag) or a target domain, the tool prints a usage message (`fmt.Println("Usage: subenum -w <wordlist_file> <domain>")`) followed by the description of all flags, and then exits with a non-zero status code (`os.Exit(1)`).
-*   **Validation**: Currently, the tool performs minimal validation of the input arguments. The domain and wordlist file must be provided, but there is no validation of flag values (e.g., checking if the concurrency level or timeout is a positive number).
+*   **Missing Required Arguments**: When the user doesn't provide a wordlist file (`-w` flag) or a target domain, the tool prints a usage message followed by the description of all flags, and then exits with a non-zero status code (`os.Exit(1)`).
+*   **Validation**: The tool validates:
+    *   Concurrency level and timeout must be positive integers.
+    *   DNS server must be a valid `ip:port` format with proper IP address and port range (1-65535), validated by `validateDNSServer`.
+    *   Target domain must conform to DNS naming rules, validated by `validateDomain`.
+    *   Hit rate (simulation mode) must be 1-100.
+    *   Retry count must be at least 1.
 
 ### 4.2. File Operation Errors
 
@@ -162,12 +168,14 @@ Visually, this can be seen as:
 *   **Channel Operations**: The tool uses a channel (`subdomains`) to pass work between the wordlist reading goroutine and the worker goroutines. No explicit error handling is implemented for channel operations, as Go's channel semantics ensure that operations like closing an already closed channel would panic. This is avoided by design in the current implementation.
 *   **Worker Goroutine Errors**: Each worker goroutine processes DNS lookups independently. If an error occurs within a worker (outside of the expected DNS resolution failures), it can cause the entire goroutine to terminate. The current implementation doesn't have specific handling for such scenarios.
 
-### 4.5. Potential Improvements
+### 4.5. Graceful Shutdown
+
+The tool listens for `SIGINT` and `SIGTERM` signals. Upon receiving an interrupt, it cancels the work context, drains in-flight workers, and exits cleanly with a summary of results processed so far.
+
+### 4.6. Output File Support
+
+When the `-o` flag is provided, resolved subdomains are written to the specified file (one per line) in addition to stdout. A mutex protects concurrent writes to both stdout and the output file.
+
+### 4.7. Retry Mechanism
 
-*   **Input Validation**: Add more thorough validation of command-line arguments, including:
-    *   Checking that the concurrency level is positive.
-    *   Validating that the timeout value is reasonable.
-    *   Verifying that the domain adheres to DNS naming rules.
-*   **Verbose Mode**: Implement a verbose mode (e.g., `-v` flag) that would print more information, including errors during DNS lookups, to help with debugging.
-*   **Graceful Handling of DNS Server Issues**: Add better handling of DNS server problems, possibly including retry mechanisms or fall-back to alternative DNS servers.
-*   **Progress Reporting**: Provide information about the progress of the enumeration to give the user feedback on long-running scans. 
+The `-retries` flag (default: 1) controls how many times each subdomain is attempted before being marked as unresolved. A short backoff delay is applied between retries to handle transient DNS failures.

docs/CONTRIBUTING.md

@@ -18,12 +18,12 @@ We welcome contributions! Please read this guide to understand how you can contr
 1. **Fork the repository** on GitHub
 2. **Clone your fork**:
    ```bash
-   git clone https://github.com/your-username/subenum.git
+   git clone https://github.com/TMHSDigital/subenum.git
    cd subenum
    ```
 3. **Set up the upstream remote**:
    ```bash
-   git remote add upstream https://github.com/original-owner/subenum.git
+   git remote add upstream https://github.com/TMHSDigital/subenum.git
    ```
 
 ## Development Workflow

docs/DEVELOPER_GUIDE.md

@@ -8,7 +8,7 @@ This guide provides information for developers looking to contribute to or build
 
 To work with `subenum`, you'll need:
 
-*   **Go Programming Language**: [Go 1.16+](https://golang.org/dl/) is recommended. The tool uses features from recent Go versions.
+*   **Go Programming Language**: [Go 1.22+](https://golang.org/dl/) is required.
 *   **Git**: For version control.
 *   **Text Editor or IDE**: VS Code, GoLand, or any editor with Go support is recommended.
 
@@ -17,7 +17,7 @@ To work with `subenum`, you'll need:
 1.  **Clone the Repository**
 
     ```bash
-    git clone https://github.com/yourusername/subenum.git
+    git clone https://github.com/TMHSDigital/subenum.git
     cd subenum
     ```
 
@@ -79,17 +79,14 @@ go test ./...
 When adding new features or modifying existing ones, please ensure you add appropriate tests. Here's a basic structure for tests:
 
 ```go
-// In a file like main_test.go
 package main
 
 import (
-    "context"
     "testing"
     "time"
 )
 
 func TestResolveDomain(t *testing.T) {
-    // Test cases
     testCases := []struct {
         name     string
         domain   string
@@ -110,10 +107,9 @@ func TestResolveDomain(t *testing.T) {
         },
     }
 
-    // Run test cases
     for _, tc := range testCases {
         t.Run(tc.name, func(t *testing.T) {
-            result := resolveDomain(tc.domain, tc.timeout)
+            result := resolveDomain(tc.domain, tc.timeout, DefaultDNSServer, false)
             if result != tc.expected {
                 t.Errorf("Expected %v for domain %s, got %v", tc.expected, tc.domain, result)
             }
@@ -188,10 +184,10 @@ Please follow these style guidelines when contributing:
 
 Areas for potential enhancement include:
 
-*   **Custom DNS Server**: Adding a flag to specify a DNS server to use for lookups.
-*   **Output Formats**: Supporting different output formats (JSON, CSV).
-*   **Verbose Mode**: Adding a verbose flag for more detailed output, including errors and progress.
+*   **Output Formats**: Supporting different output formats (JSON, CSV) in addition to the current plain text output file (`-o`).
 *   **Result Filtering**: Allowing users to filter results based on DNS record types.
 *   **Recursive Enumeration**: Adding support for recursive subdomain enumeration (e.g., finding subdomains of discovered subdomains).
+*   **Wildcard Detection**: Detecting wildcard DNS records that resolve all subdomains.
+*   **Rate Limiting**: Adding configurable rate limiting for DNS queries to avoid triggering abuse detection.
 
 When working on new features, please update the documentation accordingly and add tests to cover the new functionality. 

docs/index.md

@@ -11,9 +11,14 @@ A Go-based CLI tool for subdomain enumeration designed for educational purposes
 
 - Fast, concurrent DNS lookup of subdomains using customizable wordlists
 - Configurable concurrency level and timeout settings
-- Support for custom DNS servers
+- Support for custom DNS servers with proper validation
 - Verbose mode for detailed output
 - Real-time progress tracking
+- Output to file with `-o` flag
+- DNS retry mechanism for transient failure resilience
+- Graceful shutdown on Ctrl+C (SIGINT/SIGTERM)
+- Simulation mode for safe testing without network access
+- Domain and DNS server input validation
 - Docker support for containerized usage
 - Extensive documentation and examples
 
@@ -23,7 +28,7 @@ A Go-based CLI tool for subdomain enumeration designed for educational purposes
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/subenum.git
+git clone https://github.com/TMHSDigital/subenum.git
 cd subenum
 
 # Build the tool
@@ -34,7 +39,7 @@ go build
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/subenum.git
+git clone https://github.com/TMHSDigital/subenum.git
 cd subenum
 
 # Build the Docker image
@@ -74,16 +79,16 @@ make docker-build docker-run
 
 ## Documentation
 
-- [Usage Guide](https://github.com/yourusername/subenum#usage)
-- [Advanced Usage Examples](https://github.com/yourusername/subenum/blob/main/examples/advanced_usage.md)
+- [Usage Guide](https://github.com/TMHSDigital/subenum#usage)
+- [Advanced Usage Examples](https://github.com/TMHSDigital/subenum/blob/main/examples/advanced_usage.md)
 - [Docker Usage](#using-docker)
 - [Architecture](ARCHITECTURE.html)
 - [Developer Guide](DEVELOPER_GUIDE.html)
 - [Contributing](CONTRIBUTING.html)
 
 ## Ethical Use
 
-This tool is provided for **educational and legitimate security testing purposes only**. Users must ensure they have proper authorization before conducting subdomain enumeration on any domains. See the [LICENSE](https://github.com/yourusername/subenum/blob/main/LICENSE) file for detailed terms of use.
+This tool is provided for **educational and legitimate security testing purposes only**. Users must ensure they have proper authorization before conducting subdomain enumeration on any domains. See the [LICENSE](https://github.com/TMHSDigital/subenum/blob/main/LICENSE) file for detailed terms of use.
 
 ## License
 

logs/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-02-22
+
+### Added
+- Output file support with the `-o` flag to save results to a file
+- DNS retry mechanism with configurable `-retries` flag for transient failure resilience
+- Graceful shutdown on SIGINT/SIGTERM — drains in-flight workers and prints partial results
+- Proper DNS server validation (IP format and port range 1-65535)
+- Domain format validation against DNS naming rules
+- Tests for `validateDNSServer`, `validateDomain`, `resolveDomainWithRetry`, and `simulateResolution`
+
+### Changed
+- Removed deprecated `rand.Seed` call (auto-seeded since Go 1.20)
+- Tests now use `t.Errorf` for real assertions instead of `t.Logf` warnings
+- Fixed test compilation — `resolveDomain` calls now pass all 4 required parameters
+- Updated all placeholder URLs/emails in documentation to actual repo values
+
+### Fixed
+- Progress goroutine `done` channel is now buffered to prevent potential deadlock
+- Mutex-protected stdout/file output to prevent interleaved writes from concurrent workers
+
 ## [0.2.0] - 2025-05-08
 
 ### Added