Improve CONTRIBUTING.md
This commit is contained in:
BlackSnufkin
+65
-22
@@ -1,36 +1,79 @@
|
||||
# Contributing to LitterBox
|
||||
|
||||
Contributions are welcome and encouraged. The following guidelines outline how to contribute effectively to this project.
|
||||
Thanks for considering a contribution. This file is the short version of how to land a useful change without a long review cycle.
|
||||
|
||||
## Acceptable Contributions
|
||||
## What we welcome
|
||||
|
||||
- Bug fixes
|
||||
- Improvements to existing code, analysis modules, or documentation
|
||||
- Addition of new features or enhancements (user interface, API, analysis modules, automation, etc.)
|
||||
- Tooling improvements for analysis or developer workflows
|
||||
- Bug fixes (with a clear repro)
|
||||
- New analyzers / scanners — see [New Scanner](../../wiki/New-Scanner) on the wiki
|
||||
- New / improved YARA rules — see [YARA Rules Management](../../wiki/YARA-Rules-Management)
|
||||
- Wiki improvements — corrections, missing detail, screenshots
|
||||
- New EDR profile examples (`Config/edr_profiles/<name>.yml.example`) for backends we haven't documented yet
|
||||
- Performance and code-quality improvements with measurable impact
|
||||
|
||||
---
|
||||
## What we won't merge
|
||||
|
||||
## Submitting Pull Requests
|
||||
- Style-only refactors that touch many files for no functional gain
|
||||
- Speculative abstractions ("this might be useful later") with no current consumer
|
||||
- Changes that introduce new third-party dependencies without a clear justification
|
||||
- "Add my tool to the stack" PRs without integration code, docs, and a sample run
|
||||
|
||||
- Open pull requests against the `main` branch.
|
||||
- Pull requests are reviewed for code quality, security, and alignment with project goals.
|
||||
- Pull requests must pass all automated tests, if applicable, before merging.
|
||||
- If changes are requested or continuous integration checks fail, add new commits to the same branch.
|
||||
- For guidance on submitting a pull request, refer to [GitHub’s documentation on forking and pull requests](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks).
|
||||
## Dev setup
|
||||
|
||||
---
|
||||
```bash
|
||||
git clone https://github.com/BlackSnufkin/LitterBox.git
|
||||
cd LitterBox
|
||||
python -m venv venv
|
||||
.\venv\Scripts\Activate.ps1 # Windows
|
||||
pip install -r requirements.txt
|
||||
python litterbox.py --debug # http://127.0.0.1:1337
|
||||
```
|
||||
|
||||
## Branching Model
|
||||
Architecture overview lives in the wiki: [Application Architecture](../../wiki/Application-Architecture).
|
||||
|
||||
This repository uses the `main` branch for all development. Long-lived feature or release branches are not maintained.
|
||||
## Branching + PR workflow
|
||||
|
||||
---
|
||||
- Work in a feature branch on a personal fork.
|
||||
- Open the PR against `main`. We don't maintain release branches.
|
||||
- PR description: what changed, why, and a one-line repro / sanity check.
|
||||
- Add new commits to fix review feedback — don't force-push the branch unless asked.
|
||||
|
||||
## Commit messages
|
||||
|
||||
Match the style in `git log --oneline`:
|
||||
|
||||
- One short imperative subject line, ~70 chars max
|
||||
- Optional body for the "why" — bullets, no padding
|
||||
- No `Co-Authored-By:` trailers
|
||||
- Don't enumerate every changed file in the message — the diff already does that
|
||||
|
||||
Example:
|
||||
```
|
||||
EDR — gate killed_by_edr on alert evidence
|
||||
|
||||
Otherwise a benign payload that crashes on its own gets a false-positive
|
||||
"killed by EDR" label.
|
||||
```
|
||||
|
||||
## Code expectations
|
||||
|
||||
- **Pyflakes clean** — no unused imports, no unused locals. We sweep these regularly.
|
||||
- **Follow existing patterns** before introducing new ones. New analyzers go through `BaseSubprocessAnalyzer`; new EDR profiles use the existing `EdrProfile` shape.
|
||||
- **No silent fallbacks for things that should fail loud.** If a config field is required, raise on missing — don't paper over it.
|
||||
- **No comments narrating what the code obviously does.** Comments belong where the *why* isn't obvious from the identifier names.
|
||||
|
||||
## Verifying changes
|
||||
|
||||
There is no automated test suite at the moment. Before opening a PR:
|
||||
|
||||
1. Boot LitterBox: `python litterbox.py --debug` — no errors at startup, dashboard renders.
|
||||
2. Exercise the path you changed end-to-end. For analyzer changes, upload a sample and watch the result page populate. For EDR changes, dispatch against a registered profile.
|
||||
3. If you touched anything user-visible, update the relevant wiki page in the same PR (or in a follow-up clearly linked from the PR).
|
||||
|
||||
## Security disclosures
|
||||
|
||||
If you find a vulnerability, **do not open a public issue.** Report it via [GitHub Security Advisories](https://github.com/BlackSnufkin/LitterBox/security/advisories) on this repo, or contact the maintainer privately. Public disclosure before a fix lands gets users compromised.
|
||||
|
||||
## License
|
||||
|
||||
By contributing to LitterBox, you agree your contributions will be licensed under the terms in the [LICENSE](LICENSE) file.
|
||||
|
||||
---
|
||||
|
||||
Thank you for helping make LitterBox better!
|
||||
By contributing to LitterBox, you agree your contributions will be licensed under the terms in [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user