# How to Report a Bug in VulnClaw: A Step-by-Step Guide to GitHub Issues > Learn how to report a bug in VulnClaw with our step by step guide. Submit clear GitHub issues with diagnostic output and trace logs for quick issue resolution. - Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw) - Tags: how-to-guide - Published: 2026-07-03 --- **Submit a structured bug report using the GitHub issue template at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml), include diagnostic output from `vulnclaw doctor`, and attach trace logs generated with `--trace` to help maintainers reproduce the issue quickly.** VulnClaw is an open-source security testing framework that streamlines vulnerability detection through LLM-powered analysis. When you encounter unexpected behavior or crashes, providing a detailed bug report ensures the core developers can diagnose and patch the issue efficiently. This guide walks you through the official reporting workflow defined in the Unclecheng-li/VulnClaw repository. ## Using the GitHub Issue Template The repository provides a standardized YAML template that enforces consistent formatting for all bug reports. ### Accessing the Bug Report Template Navigate to the repository's Issues tab and click **"New issue"**. Select the **"Bug report"** option to load the template located at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml). This template automatically structures your submission with mandatory fields for reproduction steps and environment details. ### Required Fields and Formatting Fill out each section to minimize triage delays: - **Title** – Prefix with `[Bug]:` followed by a concise summary (e.g., `[Bug]: Crash when loading Chrome-DevTools MCP`). - **Bug Description** – Explain the observed behavior and why it deviates from expected functionality. - **Reproduction Steps** – List exact CLI commands or configuration changes that trigger the issue, such as `vulnclaw config provider openai` followed by `vulnclaw run http://demo.test`. - **Logs** – Paste relevant console output from the Python `logging` module, which is configured in [`vulnclaw/config/token_provider.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/token_provider.py). ## Gathering Diagnostic Information Comprehensive diagnostics reduce the back-and-forth required to isolate defects. ### Running the Environment Check Execute the built-in validation command to capture system state: ```bash vulnclaw doctor ``` This command aggregates Python version, Node.js version, and installed MCP service status into a single snapshot. The implementation resides in [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py), which serves as the CLI entry point. Copy the complete output into your issue's "Logs" section. ### Capturing Verbose Trace Logs For runtime errors during scanning or exploitation, enable detailed tracing: ```bash vulnclaw run http://target.example.com --trace ``` The `--trace` flag activates maximum verbosity in the logger initialized via `logging.getLogger(__name__)` across modules like [`vulnclaw/config/token_provider.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/token_provider.py). This output reveals LLM provider configurations and MCP service interactions without exposing sensitive environment variables. ## Submitting and Following Up After completing the template, click **"Submit new issue"**. The repository automation automatically labels your submission with `bug` and `triage`, routing it to the maintainers. If contributors request additional context, attach minimal reproducible examples or session JSON files directly to the issue thread. Monitor the GitHub notification stream for follow-up questions regarding your specific environment configuration or the contents of [`vulnclaw/mcp/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/registry.py), which handles external toolchain registration. ## Summary - **Use the official template** at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) to ensure consistent formatting. - **Prefix titles** with `[Bug]:` for automatic categorization and triage. - **Run `vulnclaw doctor`** to generate comprehensive environment diagnostics. - **Capture trace logs** with `--trace` when reporting runtime failures. - **Reference specific modules** like [`vulnclaw/config/token_provider.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/token_provider.py) when discussing logging behavior. ## Frequently Asked Questions ### Where is the VulnClaw bug report template located? The template is stored at [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/Unclecheng-li/VulnClaw/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) in the repository root. It provides structured fields for title, description, and reproduction steps, ensuring all reports follow the same format required by the maintainers. ### How do I capture diagnostic information for a VulnClaw bug report? Run the `vulnclaw doctor` command from your terminal. This aggregates Python version, Node.js version, and MCP service status into a single output. The functionality is implemented in [`vulnclaw/cli/main.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py), which serves as the primary entry point for the CLI. ### What log level should I use when reporting bugs? Use the `--trace` flag when running commands that trigger the bug, such as `vulnclaw run http://target.example.com --trace`. This activates maximum verbosity through the Python `logging` module configured in [`vulnclaw/config/token_provider.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/token_provider.py), capturing full runtime context without exposing secrets. ### What happens after I submit a bug report to VulnClaw? Once submitted, GitHub Actions automatically applies the `bug` and `triage` labels to your issue. Maintainers will review the diagnostic data from `vulnclaw doctor` and any trace logs provided, then respond with reproduction confirmation or requests for additional files like session JSON exports.