Getting Help¶

This page is the entry point for when something is not working or you have a question the docs do not answer.

If any of the terms below (target, backend, sanitizer build, target.toml, work card) are unfamiliar, the Glossary has one-line definitions — read those first.

Where to file what¶

You want to…	Use
Report a bug in TokenFuzz itself	GitHub Issues on this repository.
Ask a usage question	GitHub Issues, labelled `question`.
Suggest a feature or investigation strategy	GitHub Issues, labelled `enhancement`. See Development before opening a PR.
Report a security issue in TokenFuzz	SECURITY.md. Do not open a public issue.
Report a security issue TokenFuzz found in another project	The upstream project's normal security-disclosure process, not this repository.
Share accepted impact from a TokenFuzz run	Open an issue with the public details, or use the private path in `SECURITY.md` if disclosure timing is sensitive.

Before filing a support issue¶

Run through this list first. It catches most setup and run problems quickly.

Did the test suite pass? Run bash tests/run-tests.sh from the repository root. The output names the failing test.
Did bin/audit … 1 complete startup? A one-iteration smoke test is the cheapest way to confirm that prerequisites, target.toml, and the backend CLI are wired up.
Have you checked Troubleshooting? Common failure modes — missing tools, sanitizer build mismatches, backend authentication, stalled agents — are covered there.
Have you read your logs? output/<target>/<backend>/logs/ contains the run timeline and per-agent logs. Start with the README.md inside that directory, then index.log.

What to include in a bug report¶

A good bug report gives a maintainer enough context to reproduce the failure without guessing.

Set this once while collecting evidence:

export LOGS="output/<target>/<backend>/logs"

Include:

TokenFuzz revision — git rev-parse HEAD (run from inside the repository).
Host details — OS name and version, Bash version, Python version, clang --version.
The exact command you ran — copy-paste, not paraphrased.
The smoke-test output — bin/audit --target <target> --backend <backend> 1 2>&1 | head -80.
Your target.toml — redact upstream URLs if private.
What you expected vs. what you got.
Relevant logs — paste the useful part of $LOGS/index.log. If it points at one agent session, include the matching $LOGS/session_<TS>_<role>-<n>-<mode>.log.summary.md or $LOGS/session_<TS>_<role>-<n>-<mode>.log. Use the raw transcript under $LOGS/.raw/ only as a last resort, and trim it to the failing section.

A minimal template:

TokenFuzz: <git rev-parse HEAD output>
OS: <uname -a>
Bash: <bash --version | head -1>
Python: <python3 --version>
Clang: <clang --version | head -1>

Command:
  bin/audit --target <target> --backend <backend> 1

Expected: run completes, results/ contains state/ and work-cards.jsonl.
Got:      `FATAL: …`

Relevant log:
  <paste from $LOGS/index.log,
   plus the session summary or session log it points at>

target.toml:
  <paste, redact private URLs if needed>

What not to include¶

Full raw backend transcripts. They are huge, expensive to read, and almost never the first thing needed. Start with index.log and a session summary.
Target source code. We do not need it; pointing at the upstream revision is enough.
API keys, tokens, or anything from ~/.config/<backend>/. The harness does not read them; the backend CLI does.

Reaching maintainers privately¶

For coordinated disclosure of a vulnerability found by a TokenFuzz run, or for a sensitive operational question, the contact path is in SECURITY.md.

Please do not use private channels for ordinary support questions — they do not scale and the answer cannot help the next person.

Helping the project¶

If TokenFuzz gave you a confirmed sanitizer crash or a security finding that an upstream maintainer accepted, that is the highest-leverage thing you can do for the project: tell us.

Saying "Found using TokenFuzz" in the upstream advisory, issue, or acknowledgement is enough.