BLT-Sammich is a feature-rich Slack bot built for the OWASP BLT (Bug Logging Tool) community. This bot helps teams interact with GitHub repositories, track contributors, manage projects, and discover OWASP resources directly from Slack.

Note: The core functionality of this bot has been merged into the main BLT repository. This repository serves as the standalone implementation and development base for the BLT Slack bot.

• Features
• Architecture
• Setup
• Slash Commands
• Comparison with Main BLT
• Development
• Contributing

Status: ✅ Standalone Feature (Not in main BLT)

Displays contributor activity for the OWASP-BLT/Lettuce repository over the last 7 days.

• Shows PRs merged, issues resolved, and comments made
• Formatted table view with user statistics
• Aggregates GitHub activity data

Usage:

/contributors

Status: ✅ Standalone Feature (Not in main BLT)

Creates a new GitHub issue directly from Slack.

• Creates issues in the configured repository (default: OWASP-BLT/BLT-Sammich)
• Returns a direct link to the created issue
• Requires GitHub token authentication

Usage:

/ghissue Fix login bug on mobile devices

Status: ✅ Standalone Feature (Not in main BLT)

Retrieves information about OWASP projects.

• Shows project details from curated projects.json database
• Interactive dropdown for project selection when no name specified
• Supports pagination for large project lists (100 projects per page)

Usage:

/project zap                    # Direct lookup
/project                        # Browse all projects

Status: ✅ Standalone Feature (Not in main BLT)

Finds repositories based on technology stack or programming language.

• Matches technologies from repos.json database
• Interactive button selection when no tech specified
• Returns curated list of relevant repositories

Usage:

/repo python                    # Direct tech search
/repo                          # Browse technologies

The following commands are available in the main BLT repository but NOT in BLT-Sammich:

Status: ⚠️ Main BLT Only

Searches and browses OWASP repositories.

• Searches all OWASP GitHub repositories
• Supports pagination for results
• Interactive repository selection to view issues
• Caches repository data for performance

Why not in BLT-Sammich? This feature was developed directly in the main BLT repository as part of the integration.

BLT-Sammich is built with a modular plugin system:

1. Contributors Plugin (src/sammich/plugins/contributors.py)

   • Fetches GitHub data via REST API
   • Formats contributor statistics
   • Displays activity in formatted tables

2. Project Plugin (src/sammich/plugins/project.py)

   • Manages OWASP project database
   • Handles pagination for large datasets
   • Interactive Slack components

3. Reminder Plugin (src/sammich/plugins/reminder.py)

   • Schedule messages to channels
   • Parse natural language time expressions
   • Supports recurring reminders (Note: Currently not integrated in app.py)

• data/projects.json: Database of 800+ OWASP projects with descriptions and links
• data/repos.json: Technology-to-repository mapping for development resources

• Framework: Slack Bolt for Python
• GitHub Integration: PyGithub library
• Environment Management: python-dotenv
• Build System: Poetry for dependency management

┌─────────────────────────────────────────────────────┐
│                   User in Slack                     │
└─────────────────┬───────────────────────────────────┘
                  │
                  ├─ Standalone Commands ──────────────┐
                  │  (/contributors, /ghissue,         │
                  │   /project, /repo)                 │
                  │                                    │
                  v                                    v
         ┌────────────────────┐            ┌──────────────────┐
         │   BLT-Sammich Bot  │            │   Main BLT Bot   │
         │  (This Repository) │            │  (/discover)     │
         └─────────┬──────────┘            └────────┬─────────┘
                   │                                │
                   v                                v
         ┌─────────────────────┐          ┌─────────────────┐
         │   GitHub API         │          │  OWASP GitHub   │
         │   OWASP-BLT/Lettuce │          │  Organization   │
         └─────────────────────┘          └─────────────────┘

Key Connections:

• Both bots interact with GitHub APIs independently
• BLT-Sammich focuses on BLT-specific workflows and project discovery
• Main BLT bot provides broader OWASP repository exploration
• No direct communication between the two bot implementations

• Python 3.10+
• Poetry (for dependency management)
• Slack workspace with admin access
• GitHub account and token

git clone https://github.com/OWASP-BLT/BLT-Sammich.git
cd BLT-Sammich

poetry install

1. Go to https://api.slack.com/apps
2. Click "Create New App" → "From scratch"
3. Name your app (e.g., "BLT-Sammich Dev") and select your workspace

Navigate to OAuth & Permissions and add these Bot Token Scopes:

• commands - Create and handle slash commands
• chat:write - Send messages
• users:read - Read user information
• channels:read - View channels
• groups:read - View private channels
• im:read - View direct messages
• mpim:read - View group direct messages

1. Go to Socket Mode in your app settings
2. Enable Socket Mode
3. Generate an App-Level Token with connections:write scope
4. Save the token (starts with xapp-)

Go to Slash Commands and create:

• /contributors - URL: https://your-server.com (or use Socket Mode)
• /ghissue - URL: https://your-server.com
• /project - URL: https://your-server.com
• /repo - URL: https://your-server.com

1. Go to Install App
2. Click "Install to Workspace"
3. Authorize the requested permissions
4. Save the Bot User OAuth Token (starts with xoxb-)

Create a .secrets file in the project root:

cp .secrets.sample .secrets

Edit .secrets with your credentials:

SLACK_APP_TOKEN=xapp-your-app-level-token
SLACK_BOT_TOKEN=xoxb-your-bot-user-oauth-token
GITHUB_TOKEN=ghp_your-github-personal-access-token

Getting a GitHub Token:

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token with repo and user scopes
3. Copy the token to your .secrets file

poetry run python app.py

You should see:

⚡️ Bolt app is running!

In your Slack workspace, try:

/contributors
/project
/repo python

✅ In BLT-Sammich Only:

• /contributors - GitHub activity tracking
• /ghissue - Issue creation from Slack
• /project - OWASP projects database
• /repo - Technology-based repository discovery
• Plugin architecture for extensibility
• Curated projects and repos JSON databases

⚠️ In Main BLT Only:

• /discover - Full OWASP repository search
• Slack integration with Django web app
• OAuth-based Slack workspace integration
• Daily timelog updates
• Welcome messages for new members
• Activity logging and monitoring
• Workspace-specific configurations

BLT-Sammich serves as:

1. Standalone Bot - Can run independently without the full BLT web application
2. Development Environment - Faster iteration for Slack-specific features
3. Specialized Commands - Focus on BLT project management workflows
4. Plugin Testbed - Experimental features before main BLT integration

Main BLT provides:

1. Full Integration - Deep integration with BLT's bug tracking system
2. Web Dashboard - Configure bot settings through web UI
3. Enterprise Features - Multi-workspace support, admin controls
4. Production Ready - Comprehensive logging and monitoring

BLT-Sammich/
├── app.py                    # Main bot application
├── src/
│   ├── settings.py          # Configuration
│   └── sammich/
│       └── plugins/         # Bot plugins
│           ├── contributors.py  # GitHub activity tracking
│           ├── project.py       # OWASP project lookup
│           └── reminder.py      # Message scheduling (WIP)
├── data/
│   ├── projects.json        # OWASP projects database
│   └── repos.json          # Technology repository mapping
├── tests/                   # Unit tests
└── pyproject.toml          # Poetry dependencies

poetry run pytest

# Run linter
poetry run ruff check .

# Format code
poetry run ruff format .

1. Create handler in app.py:

@app.command("/mycommand")
def my_command(ack, say, command):
    ack()
    # Your logic here
    say("Response message")

2. Register command in Slack App manifest
3. Test in your workspace
4. Add tests in tests/

We welcome contributions! Here's how:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
4. Run tests

   poetry run pytest

5. Commit with clear message

   git commit -m "Add amazing feature"

6. Push to your fork

   git push origin feature/amazing-feature

7. Open a Pull Request

• 🔧 Integrate the /setreminder command from reminder.py plugin
• 📊 Add analytics for command usage
• 🌐 Support for more OWASP data sources
• 🔍 Enhanced search capabilities
• 🧪 Improve test coverage
• 📝 Additional documentation

This project is part of OWASP BLT and follows the same license terms. See LICENSE.md for details.

• Main BLT Repository
• OWASP BLT Website
• Slack Bot Documentation
• Report Issues

Need help?

• 📖 Check the Main BLT Documentation
• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Join the OWASP BLT Slack workspace

Made with ❤️ by the OWASP BLT community