Charon/docs/live-logs-guide.md

title, description

title	description
Live Logs & Notifications User Guide	Real-time security monitoring and notification configuration for Charon. Stream logs via WebSocket and configure webhooks.

Live Logs & Notifications User Guide

Quick links:

• Overview
• Accessing Live Logs
• Configuring Notifications
• Filtering Logs
• Webhook Integrations
• Troubleshooting

---

Overview

Charon's Live Logs & Notifications feature gives you real-time visibility into security events. See attacks as they happen, not hours later. Get notified immediately when critical threats are detected.

What you get:

• \u2705 Real-time security event streaming
• \u2705 Configurable notifications (webhooks, email)
• \u2705 Client-side and server-side filtering
• \u2705 Pause, resume, and clear controls
• \u2705 Auto-scroll with manual scroll override
• \u2705 WebSocket-based (no polling, instant updates)

---

Accessing Live Logs

Step 1: Enable Cerberus

Live logs are part of the Cerberus security suite. If you haven't enabled it yet:

1. Go to System Settings \u2192 Optional Features
2. Toggle Cerberus Security Suite to enabled
3. Wait for the system to initialize

Step 2: Open the Dashboard

1. Click Cerberus in the sidebar
2. Click Dashboard
3. Scroll to the Live Activity section (bottom of page)

You'll see a terminal-like interface showing real-time security events.

What You'll See

Each log entry shows:

• Timestamp \u2014 When the event occurred (ISO 8601 format)
• Level \u2014 Severity: debug, info, warn, error
• Source \u2014 Component that generated the event (waf, crowdsec, acl)
• Message \u2014 Human-readable description
• Details \u2014 Structured data (IP addresses, rule IDs, request URIs)

Example log entry:

[2025-12-09T10:30:45Z] ERROR [waf] WAF blocked SQL injection attempt
  IP: 203.0.113.42
  Rule: 942100
  URI: /api/users?id=1' OR '1'='1
  User-Agent: curl/7.68.0

---

Configuring Notifications

Step 1: Open Notification Settings

1. Go to Cerberus Dashboard
2. Click "Notification Settings" button (top-right corner)
3. A modal dialog will open

Step 2: Basic Configuration

Enable Notifications:

• Toggle the master switch to enable alerts

Set Minimum Log Level:

• Choose the minimum severity that triggers notifications
• Recommended: Start with error to avoid alert fatigue
• Options:
  • error \u2014 Only critical security events
  • warn \u2014 Important warnings and errors
  • info \u2014 Normal operations plus warnings/errors
  • debug \u2014 Everything (very noisy, not recommended)

Step 3: Choose Event Types

Select which types of security events trigger notifications:

• \u2611\ufe0f WAF Blocks \u2014 Firewall blocks (SQL injection, XSS, etc.)

  • Recommended: Enabled
  • Use case: Detect active attacks in real-time

• \u2611\ufe0f ACL Denials \u2014 Access control rule violations

  • Recommended: Enabled if you use geo-blocking or IP filtering
  • Use case: Detect unexpected access attempts or misconfigurations

• \u2610 Rate Limit Hits \u2014 Traffic threshold violations

  • Recommended: Disabled for most users (can be noisy)
  • Use case: Detect DDoS attempts or scraping bots

Step 4: Add Delivery Methods

Webhook URL (recommended):

• Paste your Discord/Slack webhook URL
• Must be HTTPS (HTTP not allowed for security)
• Format: https://hooks.slack.com/services/... or https://discord.com/api/webhooks/...

Email Recipients (future feature):

• Comma-separated list: admin@example.com, security@example.com
• Requires SMTP configuration (not yet implemented)

Step 5: Save Settings

Click "Save" to apply your configuration. Changes take effect immediately.

---

Filtering Logs

Client-Side Filtering

The Live Log Viewer includes built-in filtering:

1. Text Search:

   • Type in the filter box to search by any text
   • Searches message, IP addresses, URIs, and other fields
   • Case-insensitive
   • Updates in real-time

2. Level Filter:

   • Click level badges to filter by severity
   • Show only errors, warnings, etc.

3. Source Filter:

   • Filter by component (WAF, CrowdSec, ACL)

Example: To see only WAF errors from a specific IP:

• Type 203.0.113.42 in the search box
• Click the "ERROR" badge
• Results update instantly

Server-Side Filtering

For better performance with high-volume logs, use server-side filtering:

Via URL parameters:

• ?level=error \u2014 Only error-level logs
• ?source=waf \u2014 Only WAF-related events
• ?source=cerberus \u2014 All Cerberus security events

Example: To connect directly with filters:

const ws = new WebSocket('ws://localhost:8080/api/v1/logs/live?level=error&source=waf');

When to use server-side filtering:

• Reduces bandwidth usage
• Better performance under heavy load
• Useful for automated monitoring scripts

---

Webhook Integrations

Discord

Step 1: Create Discord Webhook

1. Open your Discord server
2. Go to Server Settings \u2192 Integrations
3. Click Webhooks \u2192 New Webhook
4. Name it "Charon Security" (or similar)
5. Choose the channel (e.g., #security-alerts)
6. Click Copy Webhook URL

Step 2: Add to Charon

1. Open Charon Notification Settings
2. Paste the webhook URL in Webhook URL field
3. Save settings

Step 3: Test

Trigger a security event (e.g., try to access a blocked URL) and check your Discord channel.

Discord message format:

Charon sends formatted Discord embeds:

• \ud83d\udee1\ufe0f Icon and title based on event type
• Color-coded severity (red for errors, yellow for warnings)
• Structured fields (IP, Rule, URI)
• Timestamp

Slack

Step 1: Create Slack Incoming Webhook

1. Go to https://api.slack.com/apps
2. Click Create New App \u2192 From scratch
3. Name it "Charon Security" and select your workspace
4. Click Incoming Webhooks \u2192 Toggle Activate Incoming Webhooks
5. Click Add New Webhook to Workspace
6. Choose the channel (e.g., #security)
7. Click Copy Webhook URL

Step 2: Add to Charon

1. Open Charon Notification Settings
2. Paste the webhook URL in Webhook URL field
3. Save settings

Slack message format:

Charon sends JSON payloads compatible with Slack's message format:

{
  "text": "WAF Block: SQL injection attempt blocked",
  "attachments": [{
    "color": "danger",
    "fields": [
      { "title": "IP", "value": "203.0.113.42", "short": true },
      { "title": "Rule", "value": "942100", "short": true }
    ]
  }]
}

Custom Webhooks

Requirements:

• Must accept POST requests
• Must use HTTPS (HTTP not supported)
• Should return 2xx status code on success

Payload format:

Charon sends JSON POST requests:

{
  "event_type": "waf_block",
  "severity": "error",
  "timestamp": "2025-12-09T10:30:45Z",
  "message": "WAF blocked SQL injection attempt",
  "details": {
    "ip": "203.0.113.42",
    "rule_id": "942100",
    "request_uri": "/api/users?id=1' OR '1'='1",
    "user_agent": "curl/7.68.0"
  }
}

Headers:

Content-Type: application/json
User-Agent: Charon/1.0

Example custom webhook handler (Express.js):

app.post('/charon-webhook', (req, res) => {
  const event = req.body;

  console.log(`Security Event: ${event.event_type}`);
  console.log(`Severity: ${event.severity}`);
  console.log(`Message: ${event.message}`);
  console.log(`Details:`, event.details);

  // Process the event (store in DB, send to SIEM, etc.)

  res.status(200).json({ received: true });
});

---

Viewer Controls

Pause/Resume

Pause:

• Click the "Pause" button to stop streaming
• Useful for examining specific events
• New logs are buffered but not displayed

Resume:

• Click "Resume" to continue streaming
• Buffered logs appear instantly

Clear

• Click "Clear" to remove all current log entries
• Does NOT affect the log stream (new entries continue to appear)
• Useful for starting fresh after reviewing old events

Auto-Scroll

Enabled (default):

• Viewer automatically scrolls to show latest entries
• New logs always visible

Disabled:

• Scroll back to review older entries
• Auto-scroll pauses automatically when you scroll up
• Resumes when you scroll back to the bottom

---

Troubleshooting

No Logs Appearing

Check Cerberus status:

1. Go to Cerberus Dashboard
2. Verify Cerberus is enabled
3. Check that at least one security feature is active (WAF, CrowdSec, or ACL)

Check browser console:

1. Open Developer Tools (F12)
2. Look for WebSocket connection errors
3. Common issues:
   • WebSocket connection refused \u2192 Check Charon is running
   • 401 Unauthorized \u2192 Authentication issue (when auth is enabled)
   • CORS error \u2192 Check allowed origins configuration

Check filters:

• Clear all filters (search box and level/source badges)
• Server-side filters in URL parameters may be too restrictive

Generate test events:

• Try accessing a URL with SQL injection pattern: https://yoursite.com/api?id=1' OR '1'='1
• Enable WAF in "Block" mode to see blocks
• Check CrowdSec is running to see decision logs

WebSocket Disconnects

Symptoms:

• Logs stop appearing
• "Disconnected" message shows

Causes:

• Network interruption
• Server restart
• Idle timeout (rare\u2014ping keeps connection alive)

Solution:

• Live Log Viewer automatically reconnects
• If it doesn't, refresh the page
• Check network connectivity

Notifications Not Sending

Check notification settings:

1. Open Notification Settings
2. Verify Enable Notifications is toggled on
3. Check Minimum Log Level isn't too restrictive
4. Verify at least one event type is enabled

Check webhook URL:

• Must be HTTPS (HTTP not supported)

• Test the URL directly with curl:

  curl -X POST https://your-webhook-url \
    -H "Content-Type: application/json" \
    -d '{"test": "message"}'
  

• Check webhook provider's documentation for correct format

Check event severity:

• If minimum level is "error", only errors trigger notifications
• Lower to "warn" or "info" to see more notifications
• Generate a test error event to verify

Check logs:

• Look for webhook delivery errors in Charon logs
• Common errors:
  • Connection timeout \u2192 Webhook URL unreachable
  • 4xx status \u2192 Webhook authentication or format error
  • 5xx status \u2192 Webhook provider error

Too Many Notifications

Solution 1: Increase minimum log level

• Change from "info" to "warn" or "error"
• Reduces notification volume significantly

Solution 2: Disable noisy event types

• Disable "Rate Limit Hits" if you don't need them
• Keep only "WAF Blocks" and "ACL Denials"

Solution 3: Use server-side filtering

• Filter by source (e.g., only WAF blocks)
• Filter by level (e.g., only errors)

Solution 4: Rate limiting (future feature)

• Charon will support rate-limited notifications
• Example: Maximum 10 notifications per minute

Logs Missing Information

Incomplete log entries:

• Check that the source component is logging all necessary fields
• Update to latest Charon version (fields may have been added)

Timestamps in wrong timezone:

• All timestamps are UTC (ISO 8601 / RFC3339 format)
• Convert to your local timezone in your webhook handler if needed

IP addresses showing as localhost:

• Check reverse proxy configuration
• Ensure X-Forwarded-For or X-Real-IP headers are set

---

Best Practices

For Security Monitoring

1. Start with "error" level only

   • Avoid alert fatigue
   • Gradually lower to "warn" if needed

2. Enable all critical event types

   • WAF Blocks: Always enable
   • ACL Denials: Enable if using geo-blocking or IP filtering
   • Rate Limits: Enable only if actively monitoring for DDoS

3. Use Discord/Slack for team alerts

   • Create dedicated security channel
   • @mention security team on critical events

4. Review logs regularly

   • Check Live Log Viewer daily
   • Look for patterns (same IP, same rule)
   • Adjust ACL or WAF rules based on findings

5. Test your configuration

   • Trigger test events monthly
   • Verify notifications arrive
   • Update webhook URLs if they change

For Privacy & Compliance

1. Secure webhook endpoints

   • Always use HTTPS
   • Use webhook secrets/authentication when available
   • Don't log webhook URLs in plaintext

2. Respect data privacy

   • Log retention: Live logs are in-memory only (not persisted)
   • IP addresses: Consider personal data under GDPR
   • Request URIs: May contain sensitive data

3. Access control

   • Limit who can view live logs
   • Implement authentication (when available)
   • Use role-based access control

4. Third-party data sharing

   • Webhook notifications send data to Discord, Slack, etc.
   • Review their privacy policies
   • Consider self-hosted alternatives for sensitive data

---

Advanced Usage

API Integration

Connect to WebSocket programmatically:

const API_BASE = 'ws://localhost:8080/api/v1';
const ws = new WebSocket(`${API_BASE}/logs/live?source=waf&level=error`);

ws.onopen = () => {
  console.log('Connected to live logs');
};

ws.onmessage = (event) => {
  const log = JSON.parse(event.data);

  // Process log entry
  if (log.level === 'error') {
    console.error(`Security alert: ${log.message}`);
    // Send to your monitoring system
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected from live logs');
  // Implement reconnection logic
};

Custom Alerting Logic

Example: Alert only on repeated attacks from same IP:

const attackCounts = new Map();

ws.onmessage = (event) => {
  const log = JSON.parse(event.data);
  const ip = log.fields?.ip;

  if (!ip) return;

  const count = (attackCounts.get(ip) || 0) + 1;
  attackCounts.set(ip, count);

  // Alert if same IP attacks 5+ times in a row
  if (count >= 5) {
    sendCustomAlert(`IP ${ip} has attacked ${count} times!`);
    attackCounts.delete(ip); // Reset counter
  }
};

Integration with SIEM

Forward logs to Splunk, ELK, or other SIEM systems:

ws.onmessage = (event) => {
  const log = JSON.parse(event.data);

  // Forward to SIEM via HTTP
  fetch('https://your-siem.com/api/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: 'charon',
      timestamp: log.timestamp,
      severity: log.level,
      message: log.message,
      fields: log.fields
    })
  });
};

---

Next Steps

• Security Guide \u2014 Learn about Cerberus features
• API Documentation \u2014 Full API reference
• Features Overview \u2014 See all Charon capabilities
• WebSocket Troubleshooting — Fix WebSocket connection issues
• Troubleshooting \u2014 Common issues and solutions

---

Need Help?

• GitHub Issues: https://github.com/Wikid82/charon/issues
• Discussions: https://github.com/Wikid82/charon/discussions
• Documentation: https://wikid82.github.io/charon/