Contributing

Ferro Sentry is an open-source security project and contributions are welcome. This guide explains how to set up a local development environment, write custom rules, and submit a pull request.

Prerequisites

  • Rust (stable, edition 2024 or later)
  • Git
  • Linux or Windows development environment

Local setup

Getting started
# Clone the repo
git clone https://github.com/securyblack/ferro-sentry.git
cd ferro-sentry

# Build in debug mode
cargo build

# Run the agent locally (using local debug output)
FERROSENTRY_ENDPOINT=127.0.0.1:4317 FERROSENTRY_TOKEN=test cargo run

Project structure

Source tree
src/
├── main.rs          # Entry point, service loop
├── config.rs        # Config loading (env vars + TOML)
├── engine/          # Event engine, dedup, severity scoring
├── modules/         # Security modules (port_scanner, vuln_scanner)
├── output/          # Telemetry output layer (sb_agent, direct, file)
└── updater/         # Auto-update logic

Submitting a pull request

  1. Fork the repository on GitHub.
  2. Create a branch: git checkout -b feat/my-security-rule
  3. Make your changes and ensure cargo build passes.
  4. Run cargo clippy -- -D warnings and fix any lint errors.
  5. Open a pull request against the main branch with a clear description.
Keep dependencies Apache-2.0 or MIT only. No GPL or LGPL dependencies are accepted. This is a hard requirement to keep the project commercially usable.

Security issues

Please do not open public GitHub issues for security vulnerabilities. Instead, report them privately via security@securyblack.com.

Commit conventions

We use conventional commits for clean release notes:

Commit format examples
feat: add SUID binary auditor
fix: prevent false positive on port scan
docs: update configuration reference
chore: bump tonic to 0.12

Code of conduct

Be respectful. We follow the Contributor Covenant code of conduct.