eblume/kingfisher
1
0
Fork 0
forked from mirrors/kingfisher
Code Pull requests Activity Actions
kingfisher/CONTRIBUTING.md

4.4 KiB
Raw Blame History

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. We welcome bug reports, feature requests, documentation improvements, rule additions, validation improvements, and code contributions.

Before You Start

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:

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:

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.
  • 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:

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:
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.