Skip to main content

​
Quick Start

This guide gets you from zero to a working CHAD installation in minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed
  • An OpenSearch cluster (existing or new)
  • Fluentd or another log shipper configured to send logs to OpenSearch
CHAD does not include OpenSearch. You need an existing cluster or can deploy one alongside CHAD.

​
Installation

​
1. Clone the Repository

git clone https://github.com/terrifiedbug/chad.git
cd chad

​
2. Create Environment File

cp .env.example .env
Edit .env and set secure values: 
# Required - generate secure random values
POSTGRES_PASSWORD=your-secure-password
JWT_SECRET_KEY=$(openssl rand -base64 32)
SESSION_SECRET_KEY=$(openssl rand -base64 32)
CHAD_ENCRYPTION_KEY=$(openssl rand -base64 32)

# Your public URL (for CSRF validation)
APP_URL=https://chad.example.com
Never use default secrets in production. Generate unique values for each deployment.

​
3. Start CHAD

docker compose up -d
This starts:
  • PostgreSQL database
  • CHAD Backend (FastAPI)
  • CHAD Frontend (React)

​
4. Access the UI

Open your browser to http://localhost:3000 You’ll see the setup wizard:
  1. Create Admin Account - Set up your first admin user
  2. Configure OpenSearch - Enter your OpenSearch connection details
  3. Create Index Pattern - Define your first log source

​
Setup Wizard

​
Step 1: Create Admin Account

Enter credentials for the initial administrator:
  • Username: Your admin username
  • Email: Admin email address
  • Password: Strong password (min 12 characters recommended)
This account has full admin privileges. Create additional analyst accounts after setup.

​
Step 2: Configure OpenSearch Connection

Enter your OpenSearch cluster details:
FieldDescriptionExample
HostOpenSearch hostnameopensearch.example.com
PortOpenSearch port9200
UsernameOpenSearch useradmin
PasswordOpenSearch password********
Use SSLEnable HTTPStrue (recommended)
Verify SSLValidate certificatestrue (production)
CHAD validates the connection before proceeding.

​
Step 3: Create First Index Pattern

Define a log source to monitor:
FieldDescriptionExample
NameFriendly nameWindows Security Logs
Index PatternOpenSearch index patternwinlogbeat-*
Timestamp FieldTime field name@timestamp

​
Configure Log Shipping

CHAD receives logs directly for real-time detection. Configure your log shipper to send data to both CHAD and OpenSearch.
Logs must be sent to both destinations:
  • CHAD (POST /api/logs/{index}) - for real-time detection
  • OpenSearch - for log storage and search

​
Get Auth Token

Each index pattern has an authentication token for log shipping:
  1. Go to Index Patterns
  2. Click your index pattern
  3. Copy the Auth Token

​
Fluentd Example

Configure Fluentd with two outputs using @type copy: 
<match winlogbeat.**>
  @type copy

  <!-- Send to CHAD for detection -->
  <store>
    @type http
    endpoint https://chad.example.com/api/logs/winlogbeat
    headers {"Authorization": "Bearer YOUR_INDEX_PATTERN_AUTH_TOKEN"}
    json_array true
    <buffer>
      @type memory
      flush_interval 1s
      chunk_limit_size 1m
    </buffer>
  </store>

  <!-- Send to OpenSearch for storage -->
  <store>
    @type opensearch
    host opensearch.example.com
    port 9200
    index_name winlogbeat-%Y.%m.%d
    user admin
    password ${OPENSEARCH_PASSWORD}
    ssl_verify true
  </store>
</match>

​
Logstash Example

output {
  # Send to CHAD for detection
  http {
    url => "https://chad.example.com/api/logs/winlogbeat"
    http_method => "post"
    format => "json_batch"
    headers => {
      "Authorization" => "Bearer YOUR_INDEX_PATTERN_AUTH_TOKEN"
    }
  }

  # Send to OpenSearch for storage
  opensearch {
    hosts => ["https://opensearch.example.com:9200"]
    index => "winlogbeat-%{+YYYY.MM.dd}"
    user => "logstash"
    password => "${OPENSEARCH_PASSWORD}"
    ssl => true
  }
}
The auth token is specific to each index pattern. Use the correct token for each log source.

​
Create Your First Rule

Now let’s create a detection rule:
  1. Navigate to Rules in the sidebar
  2. Click Create Rule
  3. Paste this example Sigma rule:
title: Failed Windows Login Attempt
status: test
logsource:
  product: windows
  service: security
detection:
  selection:
    EventID: 4625
  condition: selection
level: low
tags:
  - attack.credential_access
  - attack.t1110
  1. Click Validate to check the rule
  2. Click Deploy to activate detection

​
Verify Detection

To verify CHAD is working:
  1. Go to Dashboard - you should see system status
  2. Check Health - verify OpenSearch connection is healthy
  3. Generate a test event or wait for matching logs
  4. Check Alerts for new detections

​
Next Steps

Rule Management

Learn to write and manage Sigma rules

Alert Investigation

Investigate and triage alerts

SigmaHQ Import

Import rules from SigmaHQ

Notifications

Set up webhooks and Jira

​
Troubleshooting

​
Cannot connect to OpenSearch

  • Verify OpenSearch is running and accessible
  • Check firewall rules allow connections from CHAD
  • Ensure SSL settings match your cluster configuration
  • Test with curl: curl -u admin:password https://opensearch:9200

​
No alerts appearing

  • Verify logs are flowing into OpenSearch indices
  • Check index pattern matches your actual indices
  • Ensure at least one rule is deployed (not just saved)
  • Check rule field names match your log schema

​
Permission denied errors

  • Verify OpenSearch user has required permissions
  • CHAD needs: index management, document CRUD, percolator access