Contributing to the Hub
Parsers, Scenarios, Collections, and WAF rules allow the CrowdSec Security Engine to detect and block malevolent behavior. Supporting new services or improving detection capabilities is a great way to contribute to the CrowdSec ecosystem.
Sharing your parsers, scenarios, waf rules and collections on the hub allows other users to use them to protect themselves.
Communication
The main communication channels for hub contributions are:
- Discord: Best for live interactions and quick questions about hub development
- GitHub Issues: Use for bug reports and feature requests. Also great for discussing ideas, suggesting improvements, or asking detailed questions
Getting Started
Anyone can open an issue about parsers, scenarios, collections, or WAF rules, or contribute a change with a pull request (PR) to the crowdsecurity/hub GitHub repository. You need to be comfortable with git and GitHub to work effectively.
Find something to work on
Here are some things you can do today to start contributing:
- Help improve existing parsers, scenarios, collections, and WAF rules
- Add support for new services and applications
- Detect and block Web Application attacks via WAF rules
- Help triage issues and review pull requests
- Improve documentation and examples
Find a good first topic
The hub repository has beginner-friendly issues that are a great place to get started:
- Look for issues labeled
good first issue- these don't require high-level CrowdSec knowledge - Issues labeled
help wantedindicate that community help is particularly welcome
Prerequisites
Before contributing, make sure you have:
- Basic understanding of YAML syntax
- Familiarity with grok patterns (for parsers) and HTTP request basics (for WAF rules)
- Git and GitHub knowledge
- A local CrowdSec installation for testing
Contribution Workflow
The basic workflow for contributing:
- Have a look at open issues and pull requests
- Fork and clone the hub repository
- Create/Modify parsers/scenarios/collections/AppSec rules
- Create/Modify tests to ensure proper coverage
- Open a pull request
Parsers and scenarios
Use the dedicated creation guides for full walkthroughs and keep these must-haves in mind:
- Parsers: follow parsers creation; add cscli hubtest coverage and a short
.mddescribing purpose/setup. - Scenarios: follow scenarios creation; fill the required
labels, cover the scenario with cscli hubtest, and add a.mddoc.
AppSec rules
Follow AppSec rule creation for the detailed flow. Essentials:
- Tests: create a cscli hubtest with
--appsecand provide the nuclei template plus assertions as described in the guide. - Rule metadata: complete the required labels/fields so CI passes.
Collections
Use collections format; bundle tested parsers, scenarios, and WAF rules. Add a markdown page that states the collection goal plus the acquisition example to ingest the logs.
Testing
Before submitting, ensure proper testing with cscli hubtest. Follow the dedicated creation guides for step-by-step instructions instead of duplicating them here:
- Parser tests: parsers creation
- Scenario tests: scenarios creation
- AppSec tests (with nuclei templates): AppSec rule creation
- CLI reference and options: cscli hubtest
CI/CD Testing
The hub repository uses GitHub Actions for automated testing of parsers, scenarios, and AppSec rules when you open a PR. Make sure local tests pass before requesting review.
Git Workflow / Branch Management
We receive contributions on the master branch. To contribute:
- Fork the repository on GitHub
- Clone your fork locally:
SH
git clone https://github.com/yourusername/hub.git
cd hub - Create a dedicated branch for your contribution:
SH
git checkout -b feature/your-feature-name - Make your changes and commit them with descriptive messages
- Push to your fork:
SH
git push origin feature/your-feature-name - Open a Pull Request targeting the
masterbranch
Guidelines
YAML Best Practices
When creating parsers, scenarios, and collections, follow these YAML guidelines:
Avoid YAML Anchors
❌ Don't use YAML anchors - they make YAML files harder to maintain and understand:
AI-Assisted Generation
We do allow AI-assisted generation of parsers, scenarios, collections, and AppSec rules, but with important requirements:
- Follow all guidelines: AI-generated code must still follow all the guidelines in this document
- Include comprehensive tests: A pull request with AI-generated code but no tests will be immediately closed
- Proper documentation: Include complete documentation and examples as required
Disclosure Requirement
Important: When submitting AI-assisted contributions, you must check the "AI was used to generate any/all content of this PR" box in the PR template. You must understand and be able to explain yourself what was generated. AI-generated code will receive additional scrutiny to ensure quality and correctness.
What We Expect
- Test coverage using
cscli hubtest - Proper error handling and edge cases
- Clear documentation and examples
- Adherence to CrowdSec patterns and conventions
- Human review and validation of the AI output
Technical Documentation
The following explains how to create and test:
Collections
Collections group related parsers, scenarios, and postoverflows together. It often makes sense for a new parser or scenario to be added to an existing collection, or create a new one.
When to create a new collection:
- Your parsers and/or scenarios cover a new or specific service
- You're adding multiple related components that work together
- The existing collections don't fit your use case
When to add to existing collections:
- Adding a parser for a specific web server's access logs that would benefit from existing HTTP-related scenarios
- Your contribution enhances an existing service's detection capabilities
- Your scenario complements existing parsers in a collection
Collection structure:
Each collection should include:
- Descriptive name and description
- Proper labels and tags
- Documentation with setup instructions
- Example acquisition configuration
- Related parsers, scenarios, and postoverflows
Preparing your contribution
Before asking for a review of your PR, please ensure you have the following:
Tests
Test creation is covered in parsers creation, scenarios creation, and AppSec rule creation. Ensure that each component is properly tested:
- Parser tests: Include sample log files that cover various scenarios (success, failure, edge cases)
- Scenario tests: Test with different input data to ensure proper triggering and no false positives
- AppSec tests: Provide nuclei templates and expected outcomes for your rule
- Integration tests: Verify that your components work well with existing parsers/scenarios
Documentation
Please provide a .md file with the same name as each of your parsers, scenarios, collections, or WAF rules. The markdown is rendered in the hub.
Collection Documentation
State the collection goal and, if you're targeting a specific log file, provide an acquisition example:
filenames:
- /var/log/xxx/*.log
labels:
type: something
Code Quality
- Follow existing naming conventions
- Use consistent indentation and formatting
- Add comments for complex logic
- Ensure all required fields are properly filled
Opening your PR
Everything is all set, you can now open a PR that will be reviewed and merged!
PR Checklist
Before opening your PR, ensure you can check all items in the PR template. Additional requirements:
- Documentation is complete and accurate
- Code follows the project's style guidelines
- Commit messages are clear and descriptive
- PR description explains the changes and motivation
- Related issues are referenced (if applicable)
Review Process
- PRs are reviewed by maintainers and community members
- Feedback may be requested for improvements
- All CI checks must pass before merging
- Maintainers will merge approved PRs
Getting Help
If you encounter issues:
- Check existing GitHub Issues for similar problems
- Ask for help on Discord or Discourse
- Open a new issue with detailed information about your problem