forked from mirrors/kingfisher
153 lines
4.4 KiB
Markdown
153 lines
4.4 KiB
Markdown
# Contributing to Kingfisher
|
|
|
|
Thank you for your interest in contributing to Kingfisher.
|
|
|
|
Kingfisher is an open-source project owned by MongoDB and licensed under the
|
|
[Apache License 2.0](LICENSE). We welcome bug reports, feature requests,
|
|
documentation improvements, rule additions, validation improvements, and code
|
|
contributions.
|
|
|
|
## Before You Start
|
|
|
|
- Be respectful and collaborative. Participation in this project is covered by
|
|
the [MongoDB Community Code of Conduct](https://www.mongodb.com/community-code-of-conduct).
|
|
- If you plan to submit a pull request, sign the
|
|
[MongoDB Contributor Agreement](https://www.mongodb.com/legal/contributor-agreement)
|
|
first.
|
|
- For security vulnerabilities, do not open a public issue. Follow
|
|
[SECURITY.md](SECURITY.md) instead.
|
|
|
|
## Ways to Contribute
|
|
|
|
- Report bugs with clear reproduction steps, environment details, and logs when
|
|
possible.
|
|
- Propose features or usability improvements through GitHub issues.
|
|
- Improve documentation in `README.md`, `docs/`, or `docs-site/`.
|
|
- Add or refine detection rules under
|
|
`crates/kingfisher-rules/data/rules/`.
|
|
- Improve validation, revocation, scanning performance, output formats, or
|
|
integrations.
|
|
|
|
## Reporting Bugs and Requesting Features
|
|
|
|
Before opening a new issue:
|
|
|
|
- Check whether an existing issue already covers the problem or request.
|
|
- Confirm the issue still reproduces on a recent `main` checkout or current
|
|
release when practical.
|
|
- Include the smallest reproducible example you can provide.
|
|
|
|
Use the repository issue templates when they fit your case.
|
|
|
|
## Development Setup
|
|
|
|
Kingfisher is a Rust workspace. The workspace minimum Rust version is `1.94`,
|
|
and CI currently uses Rust `1.94.1`.
|
|
|
|
Helpful commands:
|
|
|
|
```bash
|
|
cargo build
|
|
make tests
|
|
cargo test --workspace --all-targets
|
|
cargo fmt --all
|
|
cargo clippy --workspace --all-targets -- -D warnings
|
|
```
|
|
|
|
For repository layout and project-specific guidance, see:
|
|
|
|
- [README.md](README.md)
|
|
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
|
|
- [docs/USAGE.md](docs/USAGE.md)
|
|
- [docs/RULES.md](docs/RULES.md)
|
|
|
|
## Contribution Guidelines
|
|
|
|
### Keep changes focused
|
|
|
|
- Prefer small, reviewable pull requests over large mixed changes.
|
|
- Avoid unrelated refactors in the same PR unless they are necessary for the
|
|
fix.
|
|
- Update tests and docs when behavior changes.
|
|
|
|
### Do not commit real secrets
|
|
|
|
Kingfisher is a secret scanner. Never add live credentials, customer data, or
|
|
real tokens anywhere in the repository, including:
|
|
|
|
- tests
|
|
- fixtures
|
|
- examples
|
|
- docs
|
|
- screenshots
|
|
- benchmark artifacts
|
|
|
|
Use clearly fake placeholders or provider-documented example values only.
|
|
|
|
### Rule contributions
|
|
|
|
If you are adding or updating a rule:
|
|
|
|
- Follow the schema and authoring guidance in [docs/RULES.md](docs/RULES.md).
|
|
- Prefer YAML-defined validation and revocation when the provider API supports
|
|
it.
|
|
- Keep patterns specific and efficient.
|
|
- Add realistic examples and relevant tests.
|
|
- Set rule confidence to `medium`.
|
|
|
|
Useful validation commands:
|
|
|
|
```bash
|
|
cargo test -p kingfisher-rules
|
|
cargo test --workspace --all-targets
|
|
kingfisher scan ./testdata --rule <rule-family-or-id> --rule-stats
|
|
kingfisher validate --rule <rule-id> <token-or-secret>
|
|
```
|
|
|
|
## Testing Expectations
|
|
|
|
Run the narrowest relevant checks for your change before opening a PR, then run
|
|
broader checks when practical.
|
|
|
|
Examples:
|
|
|
|
- Rule-only changes: `cargo test -p kingfisher-rules`
|
|
- General Rust changes: `make tests`
|
|
- Formatting: `cargo fmt --all`
|
|
- Linting: `cargo clippy --workspace --all-targets -- -D warnings`
|
|
|
|
If you cannot run a relevant check locally, say so in the pull request and
|
|
explain why.
|
|
|
|
## Documentation Changes
|
|
|
|
- Keep examples consistent with current CLI behavior.
|
|
- Update related docs when flags, outputs, or workflows change.
|
|
- After changing `docs-site/` sources, rebuild the site when practical:
|
|
|
|
```bash
|
|
docs-site/.venv/bin/mkdocs build -f docs-site/mkdocs.yml
|
|
```
|
|
|
|
## Pull Request Checklist
|
|
|
|
Before opening a PR, make sure you have:
|
|
|
|
- signed the MongoDB Contributor Agreement
|
|
- kept the change focused
|
|
- added or updated tests where needed
|
|
- updated docs where needed
|
|
- run the relevant local checks
|
|
- avoided adding any real secrets or sensitive data
|
|
|
|
In the PR description, include:
|
|
|
|
- what changed
|
|
- why it changed
|
|
- how you tested it
|
|
- any follow-up work or known limitations
|
|
|
|
## Questions
|
|
|
|
If you are unsure whether a change is in scope, open an issue first so the
|
|
approach can be discussed before you spend time on implementation.
|