Add .golangci.yml for linting configuration and update tests to use context in domain resolution

- Introduced a new .golangci.yml file to configure linting with various linters for code quality checks.
- Updated main.go and main_test.go to pass context as a parameter in domain resolution functions, enhancing error handling and timeout management.
- Added new tests for context cancellation and output file writing functionality, ensuring robust testing coverage.

Author: TMHSDigital

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "go"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"

.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    # Run every Monday at 06:00 UTC
+    - cron: '0 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze (Go)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: '1.22'
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: go
+        queries: security-extended
+
+    - name: Build
+      run: go build -buildvcs=false ./...
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:go"

.github/workflows/go.yml

@@ -6,12 +6,12 @@ on:
   pull_request:
     branches: [ "main" ]
 
-permissions:
-  contents: write
-
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
     steps:
     - uses: actions/checkout@v4
 
@@ -20,6 +20,16 @@ jobs:
       with:
         go-version: '1.22'
 
+    - name: Cache Go build artifacts
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cache/go-build
+          ~/go/pkg/mod
+        key: ${{ runner.os }}-go-${{ hashFiles('**/go.mod') }}
+        restore-keys: |
+          ${{ runner.os }}-go-
+
     - name: Verify dependencies
       run: go mod verify
 
@@ -37,6 +47,9 @@ jobs:
   release:
     needs: build
     if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
     strategy:
       matrix:
         include:
@@ -71,6 +84,16 @@ jobs:
       with:
         go-version: '1.22'
 
+    - name: Cache Go build artifacts
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cache/go-build
+          ~/go/pkg/mod
+        key: ${{ runner.os }}-go-${{ hashFiles('**/go.mod') }}
+        restore-keys: |
+          ${{ runner.os }}-go-
+
     - name: Build
       env:
         GOOS: ${{ matrix.goos }}

.golangci.yml

@@ -0,0 +1,35 @@
+run:
+  timeout: 5m
+  go: "1.22"
+
+linters:
+  enable:
+    - errcheck
+    - govet
+    - staticcheck
+    - gofmt
+    - unused
+    - gosec
+    - gocritic
+    - misspell
+    - unconvert
+
+linters-settings:
+  gosec:
+    excludes:
+      # G304: File path provided as taint input — expected for a wordlist tool
+      - G304
+  errcheck:
+    # These write to stdout/files in hot paths; errors are intentionally ignored
+    exclude-functions:
+      - fmt.Printf
+      - fmt.Fprintln
+      - fmt.Fprintf
+      - fmt.Println
+
+issues:
+  exclude-rules:
+    # Test files are allowed to use gosec-flagged patterns
+    - path: _test\.go
+      linters:
+        - gosec

README.md

@@ -98,6 +98,8 @@ go build
 -   `-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).
+-   `-simulate`: Run in simulation mode — no actual DNS queries are made.
+-   `-hit-rate <number>`: In simulation mode, percentage of subdomains that "resolve" (default: 15, range: 1-100).
 -   `-version`: Show version information and exit.
 
 ### Output:
@@ -110,11 +112,12 @@ Found: mail.example.com
 
 With verbose mode (`-v`), you'll see additional information:
 ```
-Starting subenum v0.2.0
+Starting subenum v0.3.0
 Target domain: example.com
 Wordlist: wordlist.txt
 Concurrency: 100 workers
 Timeout: 1000 ms
+Retries: 1
 DNS Server: 8.8.8.8:53
 ---
 Total wordlist entries: 50

docs/CONTRIBUTING.md

@@ -95,4 +95,46 @@ Please ensure that any contributions adhere to the ethical usage principles of t
 - Consider potential misuse and implement appropriate safeguards
 - Document proper usage scenarios and any necessary warnings
 
-## *(Details on reporting bugs, suggesting features, pull requests.)* 
+## Reporting Bugs
+
+1. Search [existing issues](https://github.com/TMHSDigital/subenum/issues) first to avoid duplicates.
+2. Open a new issue using the **Bug Report** template.
+3. Include:
+   - The exact command you ran
+   - Your OS, Go version, and `subenum` version (`./subenum -version`)
+   - Full terminal output (redact any sensitive domain names)
+   - Expected vs. actual behaviour
+
+Do NOT include sensitive information, unauthorized scan results, or private domain details.
+
+## Suggesting Features
+
+1. Search [existing issues](https://github.com/TMHSDigital/subenum/issues) to avoid duplicates.
+2. Open a new issue using the **Feature Request** template.
+3. Describe:
+   - The problem the feature solves
+   - Your proposed solution
+   - Legitimate security testing use cases it enables
+
+Features that could primarily enable malicious use will be declined.
+
+## Simulation Mode for Development
+
+Use `-simulate` to develop and test without making real DNS queries:
+
+```bash
+./subenum -simulate -hit-rate 30 -w examples/sample_wordlist.txt example.com
+```
+
+This lets you iterate on output formatting, flag handling, and new features safely.
+
+## Testing Requirements
+
+All pull requests must pass the full test suite, including the race detector:
+
+```bash
+go test -v -race ./...
+```
+
+New features should include tests. New flags must be covered by at least one test case.
+Add network-dependent tests under `if testing.Short() { t.Skip(...) }` so they can be skipped in offline environments.

docs/_config.yml

@@ -5,4 +5,4 @@ show_downloads: true
 google_analytics:
 github:
   is_project_page: true
-  repository_url: https://github.com/yourusername/subenum 
+  repository_url: https://github.com/TMHSDigital/subenum 

docs/docker.md

@@ -18,7 +18,7 @@ This guide explains how to use `subenum` with Docker for a containerized subdoma
 
 ```bash
 # Clone the repository (if you haven't already)
-git clone https://github.com/yourusername/subenum.git
+git clone https://github.com/TMHSDigital/subenum.git
 cd subenum
 
 # Build the Docker image
@@ -73,6 +73,47 @@ docker run --rm -v /path/to/your/files:/data subenum -w /data/your-wordlist.txt
 - `/root/examples/`: Contains example files and wordlists from the repository
 - `/data/`: Mount point for your custom files
 
+### Saving Results to a File
+
+Use `-o` to write discovered subdomains to a file on the host via the `/data` volume:
+
+```bash
+docker run --rm -v $(pwd)/data:/data subenum \
+  -w /data/wordlist.txt \
+  -o /data/results.txt \
+  example.com
+```
+
+### Using Retries for Unreliable Networks
+
+The `-retries` flag re-attempts failed DNS lookups before marking a subdomain as unresolved:
+
+```bash
+docker run --rm -v $(pwd)/data:/data subenum \
+  -w /data/wordlist.txt \
+  -retries 3 \
+  -timeout 2000 \
+  example.com
+```
+
+### Safe Simulation Mode
+
+Test the tool without making any real DNS queries:
+
+```bash
+docker run --rm subenum \
+  -simulate \
+  -hit-rate 20 \
+  -w /root/examples/sample_wordlist.txt \
+  example.com
+```
+
+Or via Make:
+
+```bash
+make docker-simulate
+```
+
 ## Troubleshooting
 
 ### DNS Resolution Issues

examples/advanced_usage.md

@@ -101,11 +101,65 @@ cd examples
 ./multi_domain_scan.sh sample_domains.txt
 ```
 
+## Saving Results to a File
+
+Use `-o` to write discovered subdomains to a file while still printing them to stdout:
+
+```bash
+./subenum -w wordlist.txt -o results.txt example.com
+```
+
+Combine with other flags for a full scan that saves output:
+
+```bash
+./subenum -w wordlist.txt -v -t 150 -o scan_results.txt example.com
+```
+
+## Retries for Unreliable Networks
+
+Use `-retries` to re-attempt failed DNS lookups before giving up. Useful on flaky connections or rate-limited resolvers:
+
+```bash
+./subenum -w wordlist.txt -retries 3 example.com
+```
+
+Combine with a longer timeout for maximum resilience:
+
+```bash
+./subenum -w wordlist.txt -retries 3 -timeout 2000 -dns-server 1.1.1.1:53 example.com
+```
+
+## Simulation Mode
+
+Use `-simulate` to run without making any real DNS queries. Ideal for demonstrations, CI testing, or exploring the tool's output format:
+
+```bash
+./subenum -simulate -w examples/sample_wordlist.txt example.com
+```
+
+Adjust the simulated hit rate (percentage of subdomains that appear to resolve):
+
+```bash
+./subenum -simulate -hit-rate 30 -w examples/sample_wordlist.txt example.com
+```
+
+Simulation mode with verbose output shows fake IPs and timings:
+
+```bash
+./subenum -simulate -hit-rate 25 -v -w examples/sample_wordlist.txt example.com
+```
+
 ## Continuous Integration / Automated Testing
 
 For CI/CD environments, you can use the version flag to ensure the correct version is installed:
 
 ```bash
 ./subenum -version
-# Output: subenum v0.2.0
+# Output: subenum v0.3.0
+```
+
+Use simulation mode in CI pipelines to test the tool's behaviour without network access:
+
+```bash
+./subenum -simulate -hit-rate 20 -w examples/sample_wordlist.txt -o /tmp/results.txt example.com
 ```