A pre-contribution advisory system that helps contributors understand security expectations before opening pull requests.
BLT-Preflight provides security intent and risk guidance before contributors submit code, helping to:
- ✅ Prevent common security mistakes
- 📚 Educate contributors on security best practices
- ⚡ Reduce maintainer workload by catching issues early
- 🔗 Provide plain-language guidance with documentation links
- 📊 Learn and improve over time through feedback
Important: This is a purely advisory system, not enforcement. It aims to help contributors understand security considerations without blocking contributions.
The system evaluates:
- Issue Labels: Detects security-related labels and provides relevant guidance
- File Patterns: Identifies sensitive files (auth, database, encryption, etc.)
- Repository Metadata: Considers project context
- Past Patterns: Learns from historical contributions
Every advisory includes:
- Clear, actionable security recommendations
- Links to OWASP and security documentation
- Severity levels (Info, Warning, Critical)
- Context-specific best practices
Contributors can share their intent, helping the system provide more targeted guidance:
Intent: Adding OAuth2 support for third-party authentication
Track advisory effectiveness:
- Feedback statistics and patterns
- Advisory helpfulness rates
- Contributor intent analysis
- Recommendations for improvement
The system improves over time by:
- Collecting feedback on advisory helpfulness
- Analyzing contributor intent patterns
- Refining guidance based on effectiveness
- Adapting to project-specific patterns
Install the pf command once and run it before every commit:
# Install
git clone https://github.com/OWASP-BLT/BLT-Preflight.git
cd BLT-Preflight
./install.sh # sets up the 'pf' command
# Run before committing (checks your staged files)
pfWhen you open a PR, BLT-Preflight also runs automatically via GitHub Actions:
- Analyzes your changes and labels
- Generates relevant security guidance
- Posts an advisory comment on your PR
- Provides recommendations and documentation links
You can optionally:
- Include your intent in the PR description
- Provide feedback on advisory helpfulness
- Enable the GitHub Action (already configured in
.github/workflows/advisory.yml) - Review the configuration in
config/security_patterns.json - Check the dashboard periodically:
pf dashboard --output docs/MAINTAINER_DASHBOARD.md
Use the included installer to set up the pf command:
git clone https://github.com/OWASP-BLT/BLT-Preflight.git
cd BLT-Preflight
./install.shOptions:
./install.sh # install for the current user (default)
./install.sh --system # install system-wide (requires sudo)
./install.sh --uninstallOr install directly with pip:
pip install -e .The advisory system runs automatically via GitHub Actions. No installation required!
Just ensure the workflow file exists: .github/workflows/advisory.yml
# Check all staged files before committing
pf
# Check specific files
pf check --files "src/auth.py,src/login.py"pf exits with code 1 when critical security advisories are found (matching
git hook / CI pipeline conventions) and 0 otherwise.
echo '#!/bin/sh\npf' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commitpf advise \
--labels "security,authentication" \
--files "src/auth.py,src/login.py" \
--repo "OWASP-BLT/BLT" \
--output advisory.mdpf feedback \
--pattern "Security Advisory: Authentication" \
--helpful yes \
--comments "Very clear and actionable!"pf intent \
--intent "Adding two-factor authentication support" \
--labels "security,authentication" \
--files "src/auth/mfa.py"pf dashboard --output docs/MAINTAINER_DASHBOARD.mdThe action runs automatically on:
- Pull requests (opened, synchronized, reopened)
- Issues (opened, labeled)
Configure triggers in .github/workflows/advisory.yml
Edit config/security_patterns.json to customize:
{
"file_patterns": {
"authentication": {
"patterns": ["**/auth/**", "**/login/**"],
"severity": "critical",
"guidance": "Authentication changes require careful review"
}
},
"label_patterns": {
"security": {
"severity": "critical",
"guidance": "Security-related changes need thorough review"
}
}
}See Configuration Guide for detailed instructions.
- Security Guidance: Comprehensive security best practices
- Configuration Guide: How to customize the advisory system
- Maintainer Dashboard: View advisory statistics (generated)
BLT-Preflight/
├── src/
│ ├── advisory_engine/
│ │ ├── __init__.py
│ │ ├── core.py # Core advisory engine
│ │ ├── github_integration.py # GitHub API integration
│ │ └── dashboard.py # Maintainer dashboard
│ └── blt_preflight.py # CLI interface
├── config/
│ ├── security_patterns.json # Pattern definitions
│ └── learning_data.json # Learning loop data (generated)
├── docs/
│ ├── SECURITY_GUIDANCE.md # Security best practices
│ ├── CONFIGURATION.md # Configuration guide
│ └── MAINTAINER_DASHBOARD.md # Statistics (generated)
└── .github/
└── workflows/
└── advisory.yml # GitHub Action workflow
# 🛡️ BLT Preflight Security Advisory
## 🔴 Critical Security Considerations
### Security Advisory: Authentication
Authentication changes require careful review
**Recommendations:**
- Use multi-factor authentication where possible
- Implement proper session management
- Hash passwords with bcrypt or Argon2
- Add rate limiting to prevent brute force attacks
**Learn more:**
- https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
- https://owasp.org/www-project-top-ten/2017/A2_2017-Broken_Authentication- Total Advisory Feedback: 42
- Helpful Rate: 85.7%
- Total Intents Captured: 28
- Feedback (Last 7 Days): 8
We welcome contributions! To contribute:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
BLT-Preflight will automatically provide security guidance on your PR!
For security concerns or to report vulnerabilities:
- Email: security@owasp.org
- See our security policy
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- OWASP Bug Logging Tool (BLT) Project
- OWASP Security Cheat Sheet Series
- All contributors and security researchers
- Questions: Open an issue with the
questionlabel - Bug Reports: Open an issue with the
buglabel - Feature Requests: Open an issue with the
enhancementlabel
Part of the OWASP Bug Logging Tool (BLT) project