ContextQMD
Back to Beads

Antivirus False Positives

docs/ANTIVIRUS.md

1.0.37.6 KB
Original Source

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.

Beads release installers now verify downloaded archives against release checksums.txt before installation. For users who manually install binaries, checksum verification should be the first trust step before running bd or creating antivirus exclusions.

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: Verify File Integrity (Recommended First)

Before running a downloaded binary or adding antivirus exclusions, verify the 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. If a release includes code signing, verify that signature too

Verify checksum (Windows PowerShell):

powershell
Get-FileHash bd.exe -Algorithm SHA256

Verify checksum (macOS/Linux):

bash
shasum -a 256 bd

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

Option 2: Add Exclusion (After Verification)

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 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/gastownhall/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 multiple optimizations to reduce false positives:

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

Windows PE version info: Release builds embed legitimate PE resource metadata (company name, product name, file description, version, copyright, and an application manifest) into the Windows binary using go-winres. This is one of the most effective measures against AV false positives — legitimate software almost always has PE metadata, and AV heuristics use its absence as a suspicion signal.

These optimizations are applied automatically in official release builds.

Code Signing

Windows releases are signed with an Authenticode certificate when available. Code signing:

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

Verify a signed binary (Windows PowerShell):

powershell
# Check if the binary is signed
Get-AuthenticodeSignature .\bd.exe

# Expected output for signed binary:
# SignerCertificate: [Certificate details]
# Status: Valid

Verify a signed binary (Linux/macOS with osslsigncode):

bash
# Install osslsigncode if not available
# Ubuntu/Debian: apt-get install osslsigncode
# macOS: brew install osslsigncode

osslsigncode verify -in bd.exe

Note: Code signing requires an EV (Extended Validation) certificate, which involves a verification process. If a release is not signed, it means the certificate was not available at build time. Follow the checksum verification steps above to verify authenticity.

Alternative Build Methods

Some users report success with:

bash
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)
  • 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've implemented:

  • Windows PE version info embedded in binaries (company name, product name, version, manifest)
  • Code signing infrastructure for Windows releases (requires EV certificate)
  • Build optimizations to reduce heuristic triggers (-s -w ldflags)
  • Documentation for users to add exclusions and report false positives

Still in progress:

  • Acquiring an EV code signing certificate
  • Submitting beads to antivirus vendor whitelists

False positives may still occur with new releases until the certificate builds reputation with antivirus vendors. This typically takes several months of consistent signed releases.

Should I disable my antivirus?

No. Instead:

  1. Verify release checksums before first run
  2. Keep your antivirus enabled for other threats
  3. Add beads to your antivirus exclusions only after verification if detections persist

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