Test/Upload Detections

When it’s time to upload detections, RunReveal’s CLI provides comprehensive testing and validation tools to ensure your detections are properly formatted and error-free before deployment. This guide walks you through the complete workflow from validation to deployment.

Validate your detection syntax with lint

Before uploading, validate your detection files for syntax errors and best practices using the lint command. This step catches common issues early and ensures your detections will deploy successfully.

Basic lint syntax

# Lint Sigma detections
runreveal lint sigma <file-or-directory>
 
# Lint SQL detections  
runreveal lint sql <file-or-directory>

Lint Sigma detections

Validate Sigma rule files for proper YAML syntax and Sigma specification compliance:

# Lint a single Sigma file
runreveal lint sigma ~/detection-as-code/1password/1password-unusual-client.yaml
 
# Lint all Sigma files in a directory
runreveal lint sigma ~/detection-as-code/sigma/
 
# Lint multiple directories
runreveal lint sigma ~/detection-as-code/1password/ ~/detection-as-code/cf-audit/

Lint SQL detections

Format and validate SQL detection files using ClickHouse standards:

# Lint a single SQL file
runreveal lint sql ~/detection-as-code/sql/privilege-escalation.sql
 
# Lint all SQL files in a directory
runreveal lint sql ~/detection-as-code/sql/
 
# Lint multiple directories
runreveal lint sql ~/detection-as-code/sql/ ~/detection-as-code/custom-sql/

Lint output examples

Successful lint (no errors):

$ runreveal lint sigma ~/detection-as-code/1password/1password-unusual-client.yaml
✅ All Sigma files passed validation

Failed lint (with errors):

$ runreveal lint sigma ~/detection-as-code/invalid-rule.yaml
❌ Validation failed for invalid-rule.yaml:
   - Missing required field: 'title'
   - Invalid YAML syntax at line 5

Test your upload

When you want to test to ensure that each detection is properly formatted and see which detections have been updated, deleted, or created, the dry run flag will show you exactly the information you want.

$ runreveal detections sync -d ~/detection-as-code --dry-run                                                            
processing '/Users/evan/detection-as-code/1password/1password-unusual-client.yaml'                                           
processing '/Users/evan/detection-as-code/cf-audit/anomalous-api-key-usage.yaml'                                             
processing '/Users/evan/detection-as-code/cf-audit/new-cloudflare-api-key.yaml'                                              
processing '/Users/evan/detection-as-code/cf-audit/user-added-removed-cloudflare.yaml
...
{                                                                                                                            
     "detections": {                                                                                                         
         "added": [                                                                                                                                                                                                                                       
             "1password-unusual-client",                                                                                                                                                                                                             
             "anomalous-api-key-usage",                                                                                                                                                                                                                 
             "new-cloudflare-api-key",                                                                                                                                                                                                                        
         ],
         "deleted": [],                                                                                                                                                                                                                                   
         "updated": [                                                                                                                                                                                                                                     
             "user-added-removed-cloudflare"                                                                                         
         ]                                                                                                                   
     },                                                                                                                      
     "dryRun": true                                                                                                          
 }

Uploading

The only difference between uploading and performing a dryrun is the --dry-run flag. Remove the --dry-run flag and your detections will be uploaded.

$ runreveal detections sync -d ~/detection-as-code

If you created a detection in the UI, and then attempt to upload your detection from the CLI you will see an error message the first time you attempt to overwrite your UI detection.

It will look a little something like this:

$ runreveal detections sync -d ~/detection-as-code --dry-run                                                            
processing '/Users/evan/detection-as-code/1password/1password-unusual-client.yaml'                                           
processing '/Users/evan/detection-as-code/cf-audit/anomalous-api-key-usage.yaml'                                             
processing '/Users/evan/detection-as-code/cf-audit/new-cloudflare-api-key.yaml'                                              
processing '/Users/evan/detection-as-code/cf-audit/user-added-removed-cloudflare.yaml
ERROR  This detection name is already in use, please choose a different name. If you're trying to upload your detections using detection as code, try the -o flag to overwrite existing detections created in the UI.

If you see this error, then adding the -o flag will overwrite the existing detection and convert the detection from being web managed to being cli managed.

Force uploading with overwrite

If you receive an error because the detections are managed with the web interface, you’ll need to run the following command to convert your detections to managed by the CLI:

runreveal detections sync -o -d ~/detection-as-code

Recommended workflow

Lint your detections - Validate syntax and format
Dry run - Preview changes without deployment
Upload - Deploy validated detections
Monitor - Check for any runtime issues

This workflow ensures your detections are properly validated before reaching production.

Export Detections Deployment