Skip to main content

​
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 creates these indices:
  • chad-percolator-{pattern} - Detection queries
  • chad-alerts-{pattern} - Alert storage
  • chad-audit - Audit logs (optional)

​
Initial Setup

During the setup wizard:
  1. Enter connection details
  2. CHAD validates connectivity
  3. Creates required indices

​
Connection Settings

SettingDescriptionExample
HostOpenSearch hostnameopensearch.example.com
PortOpenSearch port9200
UsernameOpenSearch userchad_user
PasswordOpenSearch password********
Use SSLEnable HTTPStrue
Verify SSLValidate certificatestrue

​
SSL Options

SettingWhen to Use
SSL OffDevelopment only (insecure)
SSL On, Verify OnProduction with valid certificates
SSL On, Verify OffSelf-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:
  1. Navigate to Settings
  2. Click OpenSearch
  3. Update connection details
  4. Click Test Connection
  5. Save if successful
Changing OpenSearch settings requires admin privileges.

​
Connection Validation

CHAD validates:
  1. Connectivity - Can reach the cluster
  2. Authentication - Credentials are valid
  3. Permissions - Required actions are allowed
  4. Index access - Can read/write indices

​
Validation Errors

ErrorCauseSolution
Connection refusedWrong host/portVerify OpenSearch is running
Authentication failedInvalid credentialsCheck username/password
Permission deniedInsufficient privilegesGrant required permissions
SSL certificate errorCertificate validation failedCheck SSL settings

​
Performance Tuning

​
Percolator Performance

For large rule sets (1000+):
  1. Increase heap - OpenSearch needs memory for percolators
  2. Use dedicated nodes - Separate percolator workload
  3. 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

  1. Check OpenSearch is running: curl -u user:pass https://host:9200
  2. Verify firewall allows CHAD → OpenSearch
  3. Check DNS resolution from CHAD container

​
Permission errors

  1. Test with admin credentials (temporarily)
  2. Review required permissions above
  3. Check OpenSearch security audit logs

​
Slow queries

  1. Check OpenSearch cluster health
  2. Review percolator performance metrics
  3. Consider rule optimization

​
SSL errors

  1. Verify certificate validity
  2. Check certificate chain
  3. Try disabling verification (testing only)

​
Next Steps

Index Patterns

Configure log sources

Field Mappings

Map Sigma fields to your schema