How to Use the `--debug` Flag to Diagnose and Resolve Module Failures in Patator

Enabling --debug in Patator sets the internal logger to DEBUG level, emitting timestamped messages that trace argument parsing, payload generation, and module execution to pinpoint exactly why a specific module fails.

When a Patator module such as ssh_login or ftp_login crashes or returns unexpected errors, the --debug flag provides the visibility needed to trace the failure from argument parsing through network execution. This diagnostic tool is implemented in the core controller of the lanjelot/patator repository and activates granular logging across all protocol modules.

What the --debug Flag Does Internally

Logger Configuration at Startup

In src/patator/patator.py, the flag is defined at line 840 within the Debugging option group as -d, --debug with action='store_true'. After argument parsing, lines 905-907 check opts.debug and call logger.setLevel(logging.DEBUG), switching the global logger from INFO to DEBUG.

Interactive Toggle During Runtime

While Patator runs, you can dynamically adjust verbosity without restarting. Lines 1556-1558 implement an interactive handler where pressing d sets the logger to DEBUG and D reverts it to INFO, allowing you to isolate specific failure windows during long scans.

Diagnosing Module Failures with Debug Output

Step 1: Enable Debug Logging

Start your command with the --debug flag to capture the full execution trace.

patator ssh_login host=TARGET user=FILE0 password=FILE1 0=users.txt 1=passwords.txt --debug

Step 2: Identify the Failure Stage

Scan the output for critical markers:

• payload: (around line 1404 in patator.py) shows the exact credential set and retry count being processed when the error occurred.
• caught: (line 1415) reveals the exception type and message when a module crashes.

Step 3: Inspect Raw Network Traces

Protocol-specific modules emit debug lines containing raw:, banner:, or recv: (e.g., FTP at line 1834, SMTP at line 2132). These entries display the exact bytes transmitted and received, helping you distinguish between server-side rejection, premature connection closure, and protocol mismatches.

Step 4: Correlate with Module Source

Each module's execute() method contains specific logger.debug() calls. Compare the trace output against the source file (e.g., src/patator/modules/ssh.py) to determine which conditional branch failed or which exception handler triggered.

Step 5: Resolve and Verify

Use the granular data to fix:

• Payload formatting errors: Adjust placeholders or COMBO files based on the payload: output.
• Timeout issues: Look for rate_limit or alarm-related debug messages to adjust --timeout values.
• Server restrictions: Interpret raw error strings (e.g., FTP_Error, SMTPResponseException) to determine if you need --allow-ignore-failures.

Re-run with --debug to confirm the error disappears and hit messages appear as expected.

Common Debug Messages Reference

Message	Meaning
payload: … [try X/Y]	Current credential combination and retry attempt.
caught: …	Exception type and details captured during module execution.
raw: … / banner: …	Raw network data exchanged with the target.
No error: …	Successful execution branch confirmation.
connect	TCP connection opened or reused from cache.
skip / free	Action rules applied to the current payload.

Practical Usage Examples

Basic Debugging Session

patator ftp_login host=192.168.1.1 user=FILE0 password=FILE1 0=users.txt 1=pass.txt --debug

Interactive Toggle During Scan

Press d to enable debug output mid-scan when you notice failures, or press D to suppress it and reduce console noise.

Filtering for Specific Modules

Pipe the output to isolate a specific module's debug lines:

patator ssh_login host=TARGET user=admin password=FILE0 0=passwords.txt --debug 2>&1 | grep "ssh_"

Summary

• The --debug flag activates logger.setLevel(logging.DEBUG) in patator.py (lines 905-907), enabling verbose internal tracing.
• Debug output includes payload: lines showing exact inputs, caught: lines for exceptions, and raw: lines for network traffic.
• Use the interactive d/D keys (lines 1556-1558) to toggle verbosity without restarting the scan.
• Correlate debug messages with module-specific logger.debug() calls in src/patator/modules/*.py to pinpoint logic errors or network issues.
• Resolve failures by adjusting payloads, timeouts, or retry limits based on the granular execution data.

Frequently Asked Questions

Where is the --debug flag defined in the Patator source code?

The flag is defined in src/patator/patator.py at line 840 within the Debugging option group, implemented as -d, --debug with action='store_true'.

Can I enable debug logging after Patator has already started?

Yes. While Patator is running, press the d key to raise the logger level to DEBUG, or press D to lower it back to INFO. This interactive toggle is handled at lines 1556-1558 in patator.py.

What debug message indicates which credentials caused a module failure?

Look for lines containing payload: followed by the dictionary of current values and the retry count (e.g., [try 1/5]). This appears around line 1404 in the core controller and shows the exact state when the error occurred.

How do I distinguish between network timeouts and authentication failures using debug output?

Check for caught: messages that reveal exception types (e.g., socket timeouts vs. authentication errors) and examine raw: or banner: lines to see if the server responded before disconnecting. Timeout-related debug messages reference enable_alarm or rate_limit indicators.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}