beads/SECURITY.md
matt wilkie e2e4975044
Document supported go install modes (bd-o5a) (#3480)
- 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
2026-04-25 11:30:19 -07:00

136 lines
5.7 KiB
Markdown

# 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:
```sh
# 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 `--json` output 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 `bd` commands
- 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 | :white_check_mark: |
| < 1.0 | :x: |
Once version 1.0 is released, we will support the latest major version and one previous major version.
## Best Practices
1. **Don't commit secrets** - Never put API keys, passwords, or credentials in issue descriptions
2. **Review before sharing** - Check issue content before sharing project details
3. **Use private repos** - If your issues contain proprietary information, use private git repositories
4. **Validate git hooks** - If using automated export/import hooks, review them for safety
5. **Regular updates** - Keep bd updated with your package manager, or re-run the install script from [docs/INSTALLING.md](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.