Contributing

Contributing

Contributions are welcome! This guide covers the development workflow for Aguara.

Development Setup

git clone https://github.com/garagon/aguara.git
cd aguara
make build
make test

Requirements: Go 1.25+

Makefile Targets

Target	Description
make build	Production binary
make test	Tests with race detector
make lint	golangci-lint
make fmt	gofmt
make vet	go vet
make clean	Remove binary

Project Structure

See Architecture for the full breakdown.

Adding Rules

Rules are YAML files in internal/rules/builtin/. See Custom Rules for the full schema.

Checklist for new rules

1. Choose a unique ID following the convention: CATEGORY_NNN
2. Write the YAML with all required fields
3. Include realistic true_positive and false_positive examples
4. Run make test to validate self-tests
5. If the rule targets JSON configs, account for optional quotes: ["']?key["']?
6. Remember: Go regexp does NOT support lookaheads/lookbehinds

Adding a new category

1. Create a new YAML file in internal/rules/builtin/
2. Add the category to categoryDescriptions in the dashboard (if applicable)
3. Update the rule count in README.md

Running Tests

# Full suite with race detector
make test

# Single package
go test -race -count=1 ./internal/rules/...

# Verbose
go test -race -count=1 -v ./internal/engine/pattern/...

# Integration tests (requires testdata/ directory)
go test -race -count=1 ./internal/scanner/...

Pull Request Process

1. Open an issue first to discuss the change
2. Fork and branch from main
3. Write tests for new functionality
4. Ensure all checks pass:

   make build && make test && make vet

5. Update CHANGELOG.md under the [Unreleased] section
6. Submit a PR with a clear description

PR Checklist

• Tests pass (make test)
• No lint issues (make lint)
• CHANGELOG updated
• No breaking changes (or clearly documented)

Reporting Issues

• Bugs: Bug report template
• Features: Feature request template
• Security: See SECURITY.md — report via GitHub Security Advisories, not public issues