zhongwei/gh-agentsecops-secopsagentkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-agentsecops-secopsagentkit/skills/incident-response/forensics-osquery/references/osqueryd-deployment.md
Zhongwei Li ff1f4bd119 Initial commit
2025-11-29 17:51:02 +08:00

12 KiB
Raw Permalink Blame History

osqueryd Deployment Guide

Deploy osqueryd for continuous endpoint monitoring, detection, and forensic evidence collection at scale.

Table of Contents

Overview

osqueryd is the daemon component of osquery that enables:

  • Scheduled query execution across endpoint fleet
  • Real-time event monitoring with event tables
  • Centralized log collection and aggregation
  • Detection-as-code with versioned query packs

Installation

Linux (Ubuntu/Debian)

# Add osquery repository
export OSQUERY_KEY=1484120AC4E9F8A1A577AEEE97A80C63C9D8B80B
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys $OSQUERY_KEY

# Add repository
sudo add-apt-repository 'deb [arch=amd64] https://pkg.osquery.io/deb deb main'

# Install
sudo apt update
sudo apt install osquery

Linux (RHEL/CentOS)

# Add osquery repository
curl -L https://pkg.osquery.io/rpm/GPG | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-osquery

# Add repository
sudo yum-config-manager --add-repo https://pkg.osquery.io/rpm/osquery-s3-rpm.repo

# Install
sudo yum install osquery

macOS

# Using Homebrew
brew install osquery

# Or download official PKG installer
# https://pkg.osquery.io/darwin/osquery-<version>.pkg

Windows

# Download MSI installer
# https://pkg.osquery.io/windows/osquery-<version>.msi

# Install via PowerShell
msiexec /i osquery-<version>.msi /quiet

Configuration

Configuration File Location

  • Linux: /etc/osquery/osquery.conf
  • macOS: /var/osquery/osquery.conf
  • Windows: C:\Program Files\osquery\osquery.conf

Basic Configuration

{
  "options": {
    "config_plugin": "filesystem",
    "logger_plugin": "filesystem",
    "logger_path": "/var/log/osquery",
    "disable_logging": false,
    "log_result_events": true,
    "schedule_splay_percent": 10,
    "pidfile": "/var/osquery/osquery.pidfile",
    "events_expiry": 3600,
    "database_path": "/var/osquery/osquery.db",
    "verbose": false,
    "worker_threads": 2,
    "enable_monitor": true,
    "disable_events": false,
    "disable_audit": false,
    "audit_allow_config": true,
    "audit_allow_sockets": true,
    "host_identifier": "hostname",
    "enable_syslog": false,
    "syslog_pipe_path": "/var/osquery/syslog_pipe"
  },

  "schedule": {
    "system_info": {
      "query": "SELECT * FROM system_info;",
      "interval": 3600,
      "description": "Collect system information hourly"
    },
    "running_processes": {
      "query": "SELECT pid, name, path, cmdline, uid FROM processes;",
      "interval": 300,
      "description": "Monitor running processes every 5 minutes"
    },
    "network_connections": {
      "query": "SELECT p.name, p.cmdline, ps.remote_address, ps.remote_port FROM processes p JOIN process_open_sockets ps ON p.pid = ps.pid WHERE ps.remote_address NOT IN ('127.0.0.1', '::1');",
      "interval": 600,
      "description": "Monitor network connections every 10 minutes"
    }
  },

  "packs": {
    "incident-response": "/etc/osquery/packs/ir-triage.conf",
    "ossec-rootkit": "/usr/share/osquery/packs/ossec-rootkit.conf"
  }
}

Security-Focused Configuration

{
  "options": {
    "config_plugin": "filesystem",
    "logger_plugin": "filesystem",
    "logger_path": "/var/log/osquery",
    "disable_logging": false,
    "log_result_events": true,
    "schedule_splay_percent": 10,
    "worker_threads": 4,
    "enable_monitor": true,
    "watchdog_level": 1,
    "watchdog_memory_limit": 250,
    "watchdog_utilization_limit": 20
  },

  "schedule": {
    "suspicious_processes": {
      "query": "SELECT * FROM processes WHERE on_disk = 0 OR path LIKE '%tmp%' OR path LIKE '%Temp%';",
      "interval": 300,
      "description": "Detect suspicious processes"
    },
    "unauthorized_suid": {
      "query": "SELECT path, mode, uid FROM file WHERE (mode LIKE '%4%' OR mode LIKE '%2%') AND path NOT IN (SELECT path FROM file WHERE path LIKE '/usr/%' OR path LIKE '/bin/%');",
      "interval": 3600,
      "description": "Find unauthorized SUID binaries",
      "platform": "posix"
    },
    "registry_run_keys": {
      "query": "SELECT key, name, path FROM registry WHERE key LIKE '%Run%' OR key LIKE '%RunOnce%';",
      "interval": 3600,
      "description": "Monitor registry persistence",
      "platform": "windows"
    }
  }
}

Query Packs

Creating Query Packs

Query packs organize related queries for specific security scenarios.

Example: /etc/osquery/packs/ir-triage.conf

{
  "platform": "all",
  "version": "1.0.0",
  "queries": {
    "logged_in_users": {
      "query": "SELECT * FROM logged_in_users;",
      "interval": 600,
      "description": "Track logged-in users"
    },
    "listening_ports": {
      "query": "SELECT lp.port, lp.address, p.name, p.path FROM listening_ports lp LEFT JOIN processes p ON lp.pid = p.pid WHERE lp.address NOT IN ('127.0.0.1', '::1');",
      "interval": 300,
      "description": "Monitor listening network ports"
    },
    "kernel_modules": {
      "query": "SELECT name, used_by, status FROM kernel_modules;",
      "interval": 3600,
      "description": "Monitor loaded kernel modules",
      "platform": "linux"
    },
    "scheduled_tasks": {
      "query": "SELECT name, action, path, enabled FROM scheduled_tasks WHERE enabled = 1;",
      "interval": 3600,
      "description": "Monitor Windows scheduled tasks",
      "platform": "windows"
    },
    "launchd_services": {
      "query": "SELECT name, path, program, run_at_load FROM launchd WHERE run_at_load = 1;",
      "interval": 3600,
      "description": "Monitor macOS launch services",
      "platform": "darwin"
    }
  }
}

Platform-Specific Packs

Use "platform" field to limit queries:

  • "posix" - Linux and macOS
  • "linux" - Linux only
  • "darwin" - macOS only
  • "windows" - Windows only
  • "all" - All platforms

Log Management

Log Types

osqueryd generates several log types:

  1. Result logs: Query results from scheduled queries
  2. Status logs: osqueryd operational status and errors
  3. Snapshot logs: Full result sets (vs differential)

Log Formats

JSON (recommended):

{
  "name": "suspicious_processes",
  "hostIdentifier": "web-server-01",
  "calendarTime": "Mon Oct 02 12:34:56 2023 UTC",
  "unixTime": 1696251296,
  "epoch": 0,
  "counter": 1,
  "columns": {
    "pid": "1234",
    "name": "suspicious",
    "path": "/tmp/suspicious"
  },
  "action": "added"
}

Centralized Logging

Option 1: Syslog

{
  "options": {
    "logger_plugin": "syslog",
    "syslog_pipe_path": "/var/osquery/syslog_pipe"
  }
}

Option 2: AWS Kinesis/Firehose

{
  "options": {
    "logger_plugin": "aws_kinesis",
    "aws_kinesis_stream": "osquery-results",
    "aws_region": "us-east-1"
  }
}

Option 3: TLS Endpoint

{
  "options": {
    "logger_plugin": "tls",
    "logger_tls_endpoint": "/log",
    "logger_tls_period": 60
  }
}

Option 4: Kafka

{
  "options": {
    "logger_plugin": "kafka_producer",
    "kafka_topic": "osquery-logs",
    "kafka_brokers": "broker1:9092,broker2:9092"
  }
}

Fleet Management

Fleet Manager Options

  1. osquery Fleet Manager - Official fleet management tool
  2. Kolide Fleet - Open-source fleet management (now FleetDM)
  3. Doorman - Minimal fleet manager
  4. Zentral - macOS-focused fleet management

FleetDM Configuration

# fleet-config.yml
mysql:
  address: 127.0.0.1:3306
  database: fleet
  username: fleet
  password: fleet_password

redis:
  address: 127.0.0.1:6379

server:
  address: 0.0.0.0:8080
  tls: true
  cert: /path/to/cert.pem
  key: /path/to/key.pem

logging:
  json: true
  debug: false

Enrolling Endpoints

TLS Enrollment

{
  "options": {
    "enroll_secret_path": "/etc/osquery/enroll_secret.txt",
    "tls_server_certs": "/etc/osquery/certs/server.pem",
    "tls_hostname": "fleet.example.com",
    "host_identifier": "uuid",
    "enroll_tls_endpoint": "/api/v1/osquery/enroll",
    "config_plugin": "tls",
    "config_tls_endpoint": "/api/v1/osquery/config",
    "config_refresh": 60,
    "logger_plugin": "tls",
    "logger_tls_endpoint": "/api/v1/osquery/log",
    "logger_tls_period": 10,
    "distributed_plugin": "tls",
    "distributed_interval": 60,
    "distributed_tls_read_endpoint": "/api/v1/osquery/distributed/read",
    "distributed_tls_write_endpoint": "/api/v1/osquery/distributed/write"
  }
}

Performance Tuning

Resource Limits

{
  "options": {
    "watchdog_level": 1,
    "watchdog_memory_limit": 250,
    "watchdog_utilization_limit": 20,
    "worker_threads": 4,
    "schedule_timeout": 60,
    "schedule_max_drift": 60
  }
}

Query Optimization

  1. Use appropriate intervals: Balance freshness vs performance

    • Critical queries: 60-300 seconds
    • Standard monitoring: 300-900 seconds
    • Inventory queries: 3600+ seconds

  2. Add WHERE clauses: Reduce result set size

    -- Bad: SELECT * FROM file;
-- Good: SELECT * FROM file WHERE path LIKE '/etc/%';

  3. Limit result sets: Use LIMIT clause

    SELECT * FROM processes ORDER BY start_time DESC LIMIT 100;

  4. Differential logging: Only log changes

    {
  "options": {
    "log_result_events": true
  }
}

Schedule Splay

Prevent query storms by adding jitter:

{
  "options": {
    "schedule_splay_percent": 10
  }
}

Service Management

Linux (systemd)

# Start osqueryd
sudo systemctl start osqueryd

# Enable on boot
sudo systemctl enable osqueryd

# Check status
sudo systemctl status osqueryd

# View logs
sudo journalctl -u osqueryd -f

macOS (launchd)

# Start osqueryd
sudo launchctl load /Library/LaunchDaemons/com.facebook.osqueryd.plist

# Stop osqueryd
sudo launchctl unload /Library/LaunchDaemons/com.facebook.osqueryd.plist

# Check status
sudo launchctl list | grep osquery

Windows (Service)

# Start service
Start-Service osqueryd

# Stop service
Stop-Service osqueryd

# Check status
Get-Service osqueryd

# View logs
Get-Content "C:\ProgramData\osquery\log\osqueryd.results.log" -Wait

Security Best Practices

  1. Limit configuration access: Restrict /etc/osquery/ to root only
  2. Use TLS: Encrypt fleet management communications
  3. Rotate secrets: Change enrollment secrets regularly
  4. Monitor osqueryd: Alert on service failures
  5. Version control configs: Track configuration changes in Git
  6. Test before deploy: Validate queries in lab first
  7. Implement RBAC: Use fleet manager role-based access
  8. Audit queries: Review all scheduled queries for performance impact

Troubleshooting

High CPU Usage

Check query performance:

# Enable verbose logging
sudo osqueryd --verbose --config_path=/etc/osquery/osquery.conf

# Check query times
tail -f /var/log/osquery/osqueryd.INFO | grep "query="

Missing Results

Verify query syntax:

# Test query interactively
osqueryi "SELECT * FROM processes LIMIT 5;"

# Check for errors
tail -f /var/log/osquery/osqueryd.results.log

Service Crashes

Review watchdog settings:

{
  "options": {
    "watchdog_level": 0,  # Disable for debugging
    "verbose": true
  }
}

Reference

Reference in New Issue View Git Blame Copy Permalink