How to Report a Bug in user-scanner: A Complete Guide

To report a bug in user-scanner, search existing GitHub issues first, then submit a detailed report including your version from user_scanner/version.json, environment details, the exact CLI command used, and a minimal reproducible example.

When you encounter unexpected behavior in user-scanner, the open-source username enumeration tool maintained in the kaifcodec/user-scanner repository, providing structured information helps maintainers reproduce and fix issues quickly. The project follows a standard GitHub workflow where detailed bug reports significantly reduce triage time and improve resolution speed.

Search Existing Issues Before Reporting

Before opening a new issue, browse the GitHub Issues page to check if your bug has already been reported. Duplicate reports fragment discussion and slow down the debugging process.

If you find an existing report that matches your issue, add additional context as a comment rather than opening a new ticket. Include any unique details about your environment or error output, and up-vote the existing issue to signal its impact.

Gather Essential Debugging Information

A high-quality bug report requires specific technical details extracted from your local environment. The maintainers need this data to trace execution paths in user_scanner/core/result.py and verify version-specific behavior.

Capture the Version String

Include the exact version number stored in user_scanner/version.json. This file contains the current release identifier (e.g., 1.5.1.1) that helps maintainers identify if the bug exists in a specific release.

cat user_scanner/version.json

When reporting, paste the full version string verbatim to eliminate ambiguity about which code revision you are running.

Document Your Environment

Specify your operating system, Python version, and installation method. Run python --version in your terminal and note whether you installed via PyPI, Nix, or a virtual environment.

Network configuration details also matter. Indicate whether you are using proxies, VPNs, or operating behind restricted network topology, as these factors affect how the scanner interacts with target platforms.

Record the CLI Invocation and Output

Provide the exact command you executed, including all flags. For example:

user-scanner -u johndoe --cross-scan -c social

If the program crashes, include the complete traceback. For logic errors where the program completes but returns incorrect results (such as Result.taken when the account does not exist), paste the relevant portion of the output. The Result object defined in user_scanner/core/result.py uses states like Result.available and Result.taken, so reference these specific return values in your description.

Create a Minimal Reproducible Example

Isolate the failure to the smallest possible input. A single-username scan that consistently triggers the bug is more valuable than a complex batch operation. For instance:

user-scanner -u nonexistent_user -c dev --cross-scan

This stripped-down command eliminates variables and gives maintainers a reliable test case.

Submitting the Bug Report

Once you have compiled the required information, submit your report through GitHub using either the web interface or the command-line tool.

Using the GitHub Web Interface

Navigate to the repository and click "New issue". Select the Bug report template if available, and fill in all sections with the data gathered above. Reference the documentation in CONTRIBUTING.md for specific formatting guidelines required by the project.

Structure your report with clear sections for version, OS/Python details, observed behavior versus expected behavior (e.g., expecting Result.available but receiving Result.taken), reproducible steps, and additional context.

Using the GitHub CLI (Alternative)

If you have the GitHub CLI (gh) installed, you can create the issue directly from your terminal. This method ensures consistent labeling and formatting:

gh issue create \
  --title "Bug: Email scan misclassifies valid address on example.com" \
  --body "$(cat <<'EOF'
**Version**: 1.5.1.1
**OS / Python**: Linux / Python 3.12.0
**Command**: user-scanner -e alice@example.com -c social
**Observed behavior**: `Result.taken` returned, but the email does not exist on the site.
**Expected behavior**: `Result.available`.
**Steps to reproduce**
1. Run the command above.
2. Observe the output.
**Additional info**
- No proxies enabled.
- Network connection is stable.
EOF
)" \
  --label "bug"

The --label "bug" tag automatically categorizes the issue for triage. For complex reports involving specific flag interactions, consult docs/FLAGS.md to ensure you describe the exact CLI options used.

Following Up and Next Steps

After submission, monitor the issue for maintainer responses. They may request additional logs, ask you to test against the tests/ directory to isolate regressions, or suggest workarounds such as disabling specific flags.

If the maintainers need deeper debugging, they might reference user_scanner/core/result.py or ask you to run the test suite locally. Keep your environment available for follow-up questions to expedite the fix.

Summary

• Search first: Check existing issues on the kaifcodec/user-scanner GitHub repository before creating duplicates.
• Version is critical: Always include the exact string from user_scanner/version.json.
• Be specific: Document your OS, Python version, exact CLI command, and network configuration.
• Show don't tell: Provide full tracebacks or output showing Result.taken vs Result.available states defined in user_scanner/core/result.py.
• Minimize reproduction: Create the smallest possible command that triggers the bug.
• Use templates: Submit via GitHub web UI or the gh CLI with the bug label as outlined in CONTRIBUTING.md.
• Stay engaged: Respond to maintainer requests for additional testing or logs.

Frequently Asked Questions

Where do I find the current version of user-scanner?

The current release version is stored in user_scanner/version.json in the repository root. Run cat user_scanner/version.json to display the version string (e.g., 1.5.1.1), which is essential for diagnosing version-specific bugs according to the kaifcodec/user-scanner source code.

What information is most important when reporting a bug?

The most critical details are the version from user_scanner/version.json, your exact CLI invocation (including all flags documented in docs/FLAGS.md), the complete error traceback or output showing Result object states, and a minimal reproducible example. This information allows maintainers to trace execution through user_scanner/core/result.py.

Can I report bugs using the command line?

Yes. If you have the GitHub CLI (gh) installed, you can use gh issue create with the --label "bug" flag to submit reports directly from the terminal. This method supports multi-line body text and automatically applies the bug label for faster triage.

What should I do if my bug report is ignored?

Wait at least one week for a response, as maintainers may be coordinating fixes against the tests/ directory or analyzing edge cases in the Result object logic. If the issue remains unattended, add a polite comment with additional context or logs rather than opening a duplicate issue.

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