- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
website docs, plugin/npm docs, examples, and doctor hints.
- Standardized on:
- CGO_ENABLED=0 go install ... for server-mode only
- CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
capable
- Added scripts/check-go-install-guidance.sh and wired it into CI.
- Updated default.nix to use gms_pure_go instead of ICU flags.
Validation passed locally:
- make test
- golangci-lint run --build-tags=gms_pure_go ./...
- ./scripts/check-go-install-guidance.sh
- ./scripts/check-build-tags.sh
- go test -tags gms_pure_go ./cmd/bd/doctor
- doc flag check
5.7 KiB
Security Policy
Reporting Security Issues
If you discover a security vulnerability in bd, please report it responsibly:
Email: security@steveyegge.com (or open a private security advisory on GitHub)
Please include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)
We will respond within 48 hours and work with you to address the issue.
Security Considerations
Database Security
bd stores issue data locally in a Dolt database (.beads/dolt/), which is gitignored.
Important:
- Do not store sensitive information (passwords, API keys, secrets) in issue descriptions or metadata
- Issue data is committed to git and will be visible to anyone with repository access
- bd does not encrypt data at rest (it's a local development tool)
- The
.beads/directory contains server state files (PID, port) and should have restrictive permissions (0700) to prevent other local users from tampering with process lifecycle
Git Workflow Security
- bd uses standard git operations (no custom protocols)
- Export/import operations read and write local files only
- No network communication except through git and the Dolt dependency (see Network & Privacy below)
- Git hooks (if used) run with your local user permissions
Network & Privacy
Beads is local-first — the beads codebase itself contains no telemetry, analytics, or outbound network calls.
However, the Dolt database engine (a beads dependency) collects usage
metrics by default, contacting doltremoteapi.dolthub.com even when no
remotes are configured.
To disable Dolt metrics collection, use either method:
# Method 1: Dolt config (persistent)
dolt config --global --add metrics.disabled true
# Method 2: Environment variable (per-session or export in shell profile)
export DOLT_DISABLE_EVENT_FLUSH=1
To verify, block doltremoteapi.dolthub.com in your firewall or DNS — beads
continues working normally with no degradation.
Tracker Integration Trust Model
When syncing with external trackers (GitHub Issues, Jira, Linear, GitLab, Azure DevOps), all data crossing the integration boundary is treated as untrusted input.
Trust boundaries:
- Issue titles and descriptions from external trackers may contain arbitrary content, including ANSI escape sequences, control characters, or prompt injection payloads targeting AI agents
- External content is sanitized before terminal display (ANSI stripping, control character removal)
- API responses are size-limited to prevent out-of-memory conditions from malformed responses
- External issue identifiers are validated before use in SQL queries
Credential handling:
- Tracker API tokens stored in beads config (
bd config set) are plaintext in the Dolt database - Prefer platform-native authentication when available (
gh auth,glab auth, Azure CLI) — these use the platform's secure credential store - Never store tokens in environment variables in shared environments
- Tokens are scoped to the permissions you grant — use minimal required scopes
Sync security model:
- Sync is always user-initiated — no background daemons, no inbound webhooks, no listening ports
- No data is sent to external trackers unless the user explicitly runs a sync command such as
bd dolt push - Conflict resolution strategies are deterministic and auditable via Dolt history
Content safety for AI agents:
- Issue descriptions imported from external trackers may contain prompt injection payloads
- Consuming agents should treat all issue content as untrusted input
- The
--jsonoutput flag provides structured data that separates metadata from free-text content - beads does not execute or interpret issue content — it is stored and displayed only
Command Injection Protection
bd uses parameterized SQL queries to prevent SQL injection. However:
- Do not pass untrusted input directly to
bdcommands - Issue IDs are validated against the pattern
^[a-z0-9-]+$ - File paths are validated before reading/writing
Dependency Security
bd has minimal dependencies:
- Go standard library
- Dolt (version-controlled SQL database)
- Cobra CLI framework
All dependencies are pinned via go.sum and verified with go mod verify. Renovate (or Dependabot) monitors for known vulnerabilities. Run go mod verify locally to check integrity.
Supported Versions
We provide security updates for:
| Version | Supported |
|---|---|
| main | ✅ |
| < 1.0 | ❌ |
Once version 1.0 is released, we will support the latest major version and one previous major version.
Best Practices
- Don't commit secrets - Never put API keys, passwords, or credentials in issue descriptions
- Review before sharing - Check issue content before sharing project details
- Use private repos - If your issues contain proprietary information, use private git repositories
- Validate git hooks - If using automated export/import hooks, review them for safety
- Regular updates - Keep bd updated with your package manager, or re-run the install script from docs/INSTALLING.md.
Known Limitations
- bd is designed for development/internal use, not production secret management
- Issue data is stored in plain text in the Dolt database
- No built-in encryption or access control (relies on filesystem permissions)
- No audit logging beyond git history
For sensitive workflows, consider using bd only for non-sensitive task tracking.
Security Updates
Security updates will be announced via:
- GitHub Security Advisories
- Release notes on GitHub
- Git commit messages (tagged with
[security])
Subscribe to the repository for notifications.