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

> Learn how to use the --debug flag to diagnose and resolve module failures in Patator. Trace module execution and pinpoint errors with detailed log messages.

- Repository: [lanjelot/patator](https://github.com/lanjelot/patator)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/lanjelot/patator/blob/main/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.

```bash
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`](https://github.com/lanjelot/patator/blob/main/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`](https://github.com/lanjelot/patator/blob/main/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

```bash
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:

```bash
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`](https://github.com/lanjelot/patator/blob/main/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`](https://github.com/lanjelot/patator/blob/main/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`](https://github.com/lanjelot/patator/blob/main/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.