diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dc70a3d..edb0c9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/.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).