9.3 Filing Good Bug Reports

9.3 Filing Good Bug Reports

Kali is built by a small team, and high-quality bug reports are one of the most valuable contributions a user can make. But a report only helps if it lands in the right tracker and contains enough detail to reproduce the problem. The KLCP exam tests both halves: choosing the venue and writing the report.

Three Venues: Kali, Upstream, Debian

Because Kali is based on Debian Testing, every package on your system has one of three origins, and each origin has its own tracker:

1. Kali-specific packages and modifications — the kali-menu, metapackages like kali-linux-default, Kali's custom kernel patches, installer issues, and Kali-applied patches to tools. These go to bugs.kali.org, the Kali bug tracker.
2. The tool's own functionality — when the defect is in the software itself (a scanner crashes on valid input, a feature behaves wrongly) and would affect any distribution, report it to the upstream project, usually its GitHub or GitLab issue tracker. kali.org/tools links to each tool's upstream source.
3. Packages inherited unmodified from Debian — much of the base system (coreutils, openssh, most libraries) flows straight from Debian. Bugs in these belong in the Debian Bug Tracking System (BTS) at bugs.debian.org.

Telling Them Apart

Misrouting is the most common beginner failure, so learn the forensic steps:

• Check the version string with apt policy <package> or apt show <package>. A suffix like 0kali1 (for example 2.3-0kali1) means Kali modified or rebuilt the package — report to Kali. A plain Debian revision (like 2.3-1) with no kali marker usually means the package came through unmodified.
• Check the maintainer field in apt show <package>: Kali-maintained packages list the Kali team; Debian-maintained ones list a Debian maintainer.
• Check kali.org/tools to see whether Kali packages the tool, then follow its Package Tracker link to pkg.kali.org, which shows how the packaged version compares with upstream.
• Test whether the bug is in the software or the packaging. If the tool fails because a file is missing from the .deb, a dependency is wrong, or a Kali patch broke something, that is packaging (Kali's tracker). If the upstream source itself is defective — verifiable by testing the same version from the developer's own repository — report upstream.

Why does the exam care? Because filing in the wrong place hurts everyone: a Debian bug posted on bugs.kali.org will be closed by Kali's team (they cannot fix Debian's package), an upstream bug posted to Kali sits until the developer who never sees it fixes it, and the reporter waits weeks for nothing. Fifteen minutes of provenance checking gets the report in front of someone who can actually act on it.

Using bugs.kali.org

The Kali bug tracker runs MantisBT, a web-based tracker. The workflow:

1. Create an account and — before anything else — search existing reports. Duplicates dilute maintainer attention; if your bug exists, add your details as a note instead.
2. Choose the right category — the tracker's fixed set is General Bug, Kali Package Bug, Kali Package Improvement, Feature Requests, Tool Upgrade Request, New Tool Requests, Kali Websites & Docs, and Queued Tool Addition (the last is reserved for the Kali tool team). Anything attributable to a package belongs under Kali Package Bug or Kali Package Improvement.
3. Fill the fields honestly: a summary that names the tool and the failure ('aircrack-ng 1.7-0kali1 segfaults on WPA handshake capture'), the reproducibility (always, sometimes, random), and an accurate product version value — but leave severity, priority, assign to, target version and tags unmodified, because the book states those fields are for the developers.
4. Attach evidence: log files, screenshots, core dumps where relevant.
5. Monitor the issue and respond when a developer asks for more information; reports whose reporters vanish get closed as unactionable.

The reportbug Tool

For bugs that belong to Debian, the standard client is reportbug, available as a package and run from the command line:

sudo apt install reportbug
reportbug openssh-server

reportbug walks you through the process: it queries the BTS for existing reports on the package (so you can spot duplicates), prompts for a subject and description, automatically attaches system information such as package versions and configuration status, and submits the report by email to the BTS. The exam expects you to recognize reportbug as Debian's dedicated reporting tool — not apt, not dpkg, which have no bug-reporting function.

Anatomy of a Good Bug Report

Whatever the tracker, an actionable report contains the same elements. Think of it as giving a stranger everything needed to see the failure on their own machine:

• Environment: Kali version (cat /etc/os-release), kernel (uname -a), and the exact package version (apt policy <package>).
• Minimal, numbered reproduction steps starting from a clean state: '1. Install X. 2. Run this exact command. 3. Observe the crash.' Remove every step that is not required to trigger the bug.
• Expected versus actual behavior, stated explicitly: 'Expected: a pcap file is written. Actual: segmentation fault after banner.'
• Complete, verbatim error output — full messages, not paraphrases — plus relevant logs from journalctl, dmesg, or the tool's own log files.
• One bug per report. Bundling three issues into one ticket makes it impossible to close and easy to ignore.
• Proof the bug still exists in the current version. Run sudo apt update && sudo apt full-upgrade and retry before filing — developers run the latest version and will close reports for bugs they have already fixed. If Kali does not yet ship the newest upstream release, test it in a throw-away VM or check the upstream changelog, and say so in the report.
• What you already tried, including workarounds, so developers can skip dead ends.

Bug Tracker Etiquette

Close the loop on the chapter's theme: the tracker is a work queue, not a help desk. Do not file questions ('how do I install...'), do not bump tickets with 'any update?' comments days after filing, and be courteous — the person reading your report is the person who will fix it. A precise, reproducible, correctly routed report is often fixed within days; a vague 'it's broken, please investigate' note — a real pattern on bugs.kali.org — is closed with a pointer to the forums and the submission guidelines at kali.org/docs/community.