How to Report a Bug in VulnClaw: A Step-by-Step Guide to GitHub Issues

Submit a structured bug report using the GitHub issue template at .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. 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.

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:

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, 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:

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. 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, which handles external toolchain registration.

Summary

• Use the official template at .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 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 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, 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, 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.

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