beads/docs/ANTIVIRUS.md

Antivirus False Positives

Overview

Some antivirus software may flag beads (bd or bd.exe) as malicious. This is a false positive - beads is a legitimate, open-source command-line tool for issue tracking.

Why This Happens

Go binaries (including beads) are sometimes flagged by antivirus software due to:

1. Heuristic detection: Some malware is written in Go, causing antivirus ML models to flag Go-specific binary patterns as suspicious
2. Behavioral analysis: CLI tools that modify files and interact with git may trigger behavioral detection
3. Unsigned binaries: Without code signing, new executables may be treated with suspicion

This is a known industry-wide problem affecting many legitimate Go projects. See the Go project issues for examples.

Known Issues

Kaspersky Antivirus

Detection: PDM:Trojan.Win32.Generic Affected versions: bd.exe v0.23.1 and potentially others Component: System Watcher (Proactive Defense Module)

Kaspersky's PDM (Proactive Defense Module) uses behavioral analysis that commonly triggers false positives on Go executables.

Solutions for Users

Option 1: Add Exclusion (Recommended)

Add beads to your antivirus exclusion list:

Kaspersky:

1. Open Kaspersky and go to Settings
2. Navigate to Threats and Exclusions → Manage Exclusions
3. Click Add → Add path to exclusion
4. Add the directory containing bd.exe (e.g., C:\Users\YourName\AppData\Local\bd\)
5. Select which components the exclusion applies to (scan, monitoring, etc.)

Windows Defender:

1. Open Windows Security
2. Go to Virus & threat protection → Manage settings
3. Scroll to Exclusions → Add or remove exclusions
4. Add the beads installation directory or the specific bd.exe file

Other antivirus software:

• Look for "Exclusions", "Whitelist", or "Trusted Applications" settings
• Add the beads installation directory or executable

Option 2: Verify File Integrity

Before adding an exclusion, verify the downloaded file is legitimate:

1. Download beads from the official GitHub releases
2. Verify the SHA256 checksum matches the checksums.txt file in the release
3. Check the file is signed (future releases will include code signing)

Verify checksum (Windows PowerShell):

Get-FileHash bd.exe -Algorithm SHA256

Verify checksum (macOS/Linux):

shasum -a 256 bd

Compare the output with the checksum in checksums.txt from the release page.

Option 3: Report False Positive

Help improve detection accuracy by reporting the false positive:

Kaspersky:

1. Visit Kaspersky Threat Intelligence Portal
2. Upload the bd.exe file for analysis
3. Mark it as a false positive
4. Reference: beads is open-source CLI tool (https://github.com/steveyegge/beads)

Windows Defender:

1. Go to Microsoft Security Intelligence
2. Submit the file as a false positive
3. Provide details about the legitimate software

Other vendors:

• Check their website for false positive submission forms
• Most major vendors have a process for reviewing flagged files

For Developers/Distributors

If you're building beads from source or distributing it:

Current Build Configuration

Beads releases are built with optimizations to reduce false positives:

ldflags:
  - -s -w  # Strip debug symbols and DWARF info

These flags are already applied in the official builds.

Code Signing (Future)

Future releases may include Windows code signing to improve trust scores with antivirus vendors. Code signing:

• Reduces false positive rates over time
• Builds reputation with SmartScreen/antivirus vendors
• Provides tamper verification

Alternative Build Methods

Some users report success with:

go build -ldflags "-s -w" -o bd ./cmd/bd

However, results vary by antivirus vendor and version.

Frequently Asked Questions

Is beads safe to use?

Yes. Beads is:

• Open source (all code is auditable on GitHub)
• Signed releases include checksums for verification
• Used by developers worldwide
• A simple CLI tool for issue tracking

Why don't you just fix the code to avoid detection?

The issue isn't specific to beads' code - it's a characteristic of Go binaries in general. Changing code won't reliably prevent heuristic/behavioral detection. The proper solutions are:

1. Code signing (builds trust over time)
2. Whitelist applications with antivirus vendors
3. User reports of false positives

Will this be fixed in future releases?

We're working on:

• Submitting beads to antivirus vendor whitelists
• Adding code signing for Windows releases
• Continuing to use build optimizations

However, false positives may still occur with new releases until reputation is established.

Should I disable my antivirus?

No. Instead:

1. Add beads to your antivirus exclusions (safe and recommended)
2. Keep your antivirus enabled for other threats
3. Verify checksums of downloaded files before adding exclusions

Reporting Issues

If you encounter a new antivirus false positive:

1. Open an issue on GitHub
2. Include:
   • Antivirus software name and version
   • Detection/threat name
   • Beads version (bd version)
   • Operating system

This helps us track and address false positives across different antivirus vendors.

References

• Kaspersky False Positive Guide
• Go Binary False Positives Discussion
• Go Project Issue Tracker
• Kaspersky Community Forum