If you believe you've found a security issue in Bitterbot, please report it privately.

Report vulnerabilities directly to the repository where the issue lives:

• Core CLI, gateway, and desktop app — bitterbot/bitterbot

For issues that don't fit a specific repo, or if you're unsure, email security@bitterbot.net and we'll route it.

1. Title
2. Severity Assessment
3. Impact
4. Affected Component
5. Technical Reproduction
6. Demonstrated Impact
7. Environment
8. Remediation Advice

Reports without reproduction steps, demonstrated impact, and remediation advice will be deprioritized. Given the volume of AI-generated scanner findings, we must ensure we're receiving vetted reports from researchers who understand the issues.

Bitterbot is a labor of love. There is no bug bounty program and no budget for paid reports. Please still disclose responsibly so we can fix issues quickly. The best way to help the project right now is by sending PRs.

When patching a GHSA via gh api, include X-GitHub-Api-Version: 2022-11-28 (or newer). Without it, some fields (notably CVSS) may not persist even if the request returns 200.

• Public Internet Exposure
• Using Bitterbot in ways that the docs recommend not to
• Prompt injection attacks

For threat model + hardening guidance (including bitterbot security audit --deep and --fix), see:

• docs/security/ in this repository

• tools.exec.applyPatch.workspaceOnly: true (recommended): keeps apply_patch writes/deletes within the configured workspace directory.
• tools.fs.workspaceOnly: true (optional): restricts read/write/edit/apply_patch paths to the workspace directory.
• Avoid setting tools.exec.applyPatch.workspaceOnly: false unless you fully trust who can trigger tool execution.

Bitterbot's web interface (Gateway Control UI + HTTP endpoints) is intended for local use only.

• Recommended: keep the Gateway loopback-only (127.0.0.1 / ::1).
  • Config: gateway.bind="loopback" (default).
  • CLI: bitterbot gateway run --bind loopback.
• Do not expose it to the public internet (no direct bind to 0.0.0.0, no public reverse proxy). It is not hardened for public exposure.
• If you need remote access, prefer an SSH tunnel or Tailscale serve/funnel (so the Gateway still binds to loopback), plus strong Gateway auth.
• The Gateway HTTP surface includes the canvas host (/__bitterbot__/canvas/, /__bitterbot__/a2ui/). Treat canvas content as sensitive/untrusted and avoid exposing it beyond loopback unless you understand the risk.

Bitterbot requires Node.js 22 or later (LTS).

node --version  # Should be v22.x or later

When running Bitterbot in Docker:

1. The official image runs as a non-root user (node) for reduced attack surface
2. Use --read-only flag when possible for additional filesystem protection
3. Limit container capabilities with --cap-drop=ALL

Example secure Docker run:

docker run --read-only --cap-drop=ALL \
  -v.bitterbot-data:/app/data \
  bitterbot/bitterbot:latest

This project uses detect-secrets for automated secret detection in CI/CD. See .detect-secrets.cfg for configuration and .secrets.baseline for the baseline.

Run locally:

pip install detect-secrets==1.5.0
detect-secrets scan --baseline .secrets.baseline