Skip to main content
Get the most out of Blocklight with these recommendations:

​
Start Simple

Begin with basic rules. Keep rules simple and focused on what you need to detect.

​
Always Validate & Test

Use validate and dry-run before deploying rules.

​
Use Testing Directory for Development

Create new rules in rules/testing/ first, then test them with dry-run before moving to production:
  1. Create rule in testing directory: 
    # Create your rule
vim rules/testing/my_new_rule.yaml
  2. Test it safely: 
    # Test without affecting production (dry-run automatically includes testing rules)
blocklight dry-run --tx 0xabc123...
  3. Move to production when ready: 
    # Once validated, move to custom
mv rules/testing/my_new_rule.yaml rules/custom/
Important: Rules in rules/testing/ are NEVER loaded in production (when running blocklight start). The dry-run command automatically includes them for testing purposes, ensuring you can test rules safely without generating alerts or affecting your monitoring system.

​
Caching

Caching is always enabled in Blocklight for optimal performance. Configure appropriate TTL values in analysis config based on your use case.

​
Reuse Components

Use lists and macros to keep rules maintainable. Important: lists and macros are defined at the file level (not inside rules), allowing you to create reusable building blocks that multiple rules in the same file can share. File Organization: When grouping multiple rules in the same file, ensure they are related to each other (e.g., same category, threat type, or protocol). While lists and macros can be shared across rules in the same file, mixing unrelated rules can make maintenance complex. Organize rules by category, threat type, or protocol to keep your rule base maintainable. See Rule Structure for more details.

​
Secure Your Secrets

Use ${ENV_VARS} in alert configuration. Never commit secrets.