OpenSearch Configuration
CHAD uses OpenSearch as its detection engine. This guide covers connection setup and requirements.
Requirements
OpenSearch Version
- Minimum: OpenSearch 2.0+
- Recommended: OpenSearch 2.11+
Required Permissions
The CHAD user needs these OpenSearch permissions:
{
"cluster_permissions": [
"cluster:monitor/health",
"cluster:monitor/state"
],
"index_permissions": [
{
"index_patterns": ["chad-*"],
"allowed_actions": [
"indices:admin/create",
"indices:admin/delete",
"indices:admin/mapping/put",
"indices:data/read/*",
"indices:data/write/*"
]
},
{
"index_patterns": ["your-log-indices-*"],
"allowed_actions": [
"indices:admin/mappings/get",
"indices:data/read/*"
]
}
]
}
chad-percolator-{pattern} - Detection querieschad-alerts-{pattern} - Alert storagechad-audit - Audit logs (optional)
Initial Setup
During the setup wizard:
- Enter connection details
- CHAD validates connectivity
- Creates required indices
Connection Settings
| Setting | Description | Example |
|---|
| Host | OpenSearch hostname | opensearch.example.com |
| Port | OpenSearch port | 9200 |
| Username | OpenSearch user | chad_user |
| Password | OpenSearch password | ******** |
| Use SSL | Enable HTTPS | true |
| Verify SSL | Validate certificates | true |
SSL Options
| Setting | When to Use |
|---|
| SSL Off | Development only (insecure) |
| SSL On, Verify On | Production with valid certificates |
| SSL On, Verify Off | Self-signed certificates (less secure) |
Disabling SSL verification exposes credentials in transit. Use only with self-signed certs in trusted networks.
Modifying Connection
After initial setup, change settings in Settings > OpenSearch:
- Navigate to Settings
- Click OpenSearch
- Update connection details
- Click Test Connection
- Save if successful
Changing OpenSearch settings requires admin privileges.
Connection Validation
CHAD validates:
- Connectivity - Can reach the cluster
- Authentication - Credentials are valid
- Permissions - Required actions are allowed
- Index access - Can read/write indices
Validation Errors
| Error | Cause | Solution |
|---|
| Connection refused | Wrong host/port | Verify OpenSearch is running |
| Authentication failed | Invalid credentials | Check username/password |
| Permission denied | Insufficient privileges | Grant required permissions |
| SSL certificate error | Certificate validation failed | Check SSL settings |
- Increase heap - OpenSearch needs memory for percolators
- Use dedicated nodes - Separate percolator workload
- Optimize rules - Simplify complex detection logic
Alert Storage
Configure retention in Settings > OpenSearch:
- Alert retention days - How long to keep alerts
- Audit retention days - How long to keep audit logs
Use Index Lifecycle Management (ILM) for automatic rollover and deletion.
High Availability
For production deployments:
OpenSearch Cluster
- Minimum 3 nodes for HA
- Dedicated master nodes
- Cross-zone deployment
CHAD Considerations
- CHAD connects to a single OpenSearch endpoint
- Use a load balancer for multi-node clusters
- Configure appropriate timeouts for network latency
Troubleshooting
Cannot connect
- Check OpenSearch is running:
curl -u user:pass https://host:9200
- Verify firewall allows CHAD → OpenSearch
- Check DNS resolution from CHAD container
Permission errors
- Test with admin credentials (temporarily)
- Review required permissions above
- Check OpenSearch security audit logs
Slow queries
- Check OpenSearch cluster health
- Review percolator performance metrics
- Consider rule optimization
SSL errors
- Verify certificate validity
- Check certificate chain
- Try disabling verification (testing only)
Next Steps
