beads/SECURITY.md
Steve Yegge 19cd7d1887 Prepare for public launch: comprehensive examples, docs, and tooling
This commit adds everything needed for a successful public launch:

**New Documentation**
- SECURITY.md: Security policy and best practices
- CLAUDE.md: Complete agent instructions for contributing to beads
- Enhanced README with pain points, FAQ, troubleshooting sections
- Added Taskwarrior to comparison table with detailed explanation

**Installation**
- install.sh: One-liner installation script with platform detection
- Auto-detects OS/arch, tries go install, falls back to building from source
- Updated README with prominent installation instructions

**Examples** (2,268+ lines of working code)
- examples/python-agent/: Full Python implementation of agent workflow
- examples/bash-agent/: Shell script agent with colorized output
- examples/git-hooks/: Pre-commit, post-merge, post-checkout hooks with installer
- examples/claude-desktop-mcp/: Documentation for future MCP server integration
- examples/README.md: Overview of all examples

**Dogfooding**
- Initialized bd in beads project itself (.beads/beads.db)
- Created issues for roadmap (MCP server, migrations, demos, 1.0 milestone)
- Exported to .beads/issues.jsonl for git versioning

**Visual Assets**
- Added screenshot showing agent using beads to README intro
- Placed in .github/images/ following GitHub conventions

This addresses all launch readiness items:
✅ Security policy
✅ Working agent examples (Python, Bash)
✅ Git hooks for automation
✅ FAQ addressing skeptics
✅ Troubleshooting common issues
✅ Easy installation
✅ Dogfooding our own tool
✅ Pain points that create urgency

Ready to ship! 🚀

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-12 11:25:29 -07:00

3 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:

  • SQLite databases (.beads/*.db) - local only, gitignored
  • JSONL files (.beads/issues.jsonl) - committed to git

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)

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 itself
  • Git hooks (if used) run with your local user permissions

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
  • SQLite (via modernc.org/sqlite - pure Go implementation)
  • Cobra CLI framework

All dependencies are regularly updated. Run go mod verify 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

  1. Don't commit secrets - Never put API keys, passwords, or credentials in issue descriptions
  2. Review before export - Check .beads/issues.jsonl before committing sensitive 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 to the latest version: go install github.com/steveyegge/beads/cmd/bd@latest

Known Limitations

  • bd is designed for development/internal use, not production secret management
  • Issue data is stored in plain text (both SQLite and JSONL)
  • 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.