Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,657 @@
|
||||
# Velociraptor Enterprise Deployment Guide
|
||||
|
||||
Comprehensive guide for deploying Velociraptor in enterprise environments.
|
||||
|
||||
## Table of Contents
|
||||
- [Architecture Overview](#architecture-overview)
|
||||
- [Server Deployment](#server-deployment)
|
||||
- [Client Deployment](#client-deployment)
|
||||
- [High Availability](#high-availability)
|
||||
- [Security Hardening](#security-hardening)
|
||||
- [Monitoring and Maintenance](#monitoring-and-maintenance)
|
||||
- [Scaling Considerations](#scaling-considerations)
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Components
|
||||
|
||||
**Frontend Server**:
|
||||
- Handles client communication (gRPC)
|
||||
- Serves web GUI
|
||||
- Manages TLS connections
|
||||
- Default port: TCP 8000 (clients), TCP 8889 (GUI)
|
||||
|
||||
**Datastore**:
|
||||
- Filesystem-based by default
|
||||
- Stores artifacts, collections, and configurations
|
||||
- Can use external storage (S3, GCS)
|
||||
|
||||
**Clients (Agents)**:
|
||||
- Lightweight endpoint agents
|
||||
- Execute VQL queries
|
||||
- Report results to server
|
||||
- Self-updating capability
|
||||
|
||||
### Deployment Models
|
||||
|
||||
**Single Server** (< 1000 endpoints):
|
||||
```
|
||||
[Clients] ──→ [Frontend + GUI + Datastore]
|
||||
```
|
||||
|
||||
**Multi-Frontend** (1000-10000 endpoints):
|
||||
```
|
||||
┌─→ [Frontend 1]
|
||||
[Clients] ──→ [LB]├─→ [Frontend 2] ──→ [Shared Datastore]
|
||||
└─→ [Frontend 3]
|
||||
```
|
||||
|
||||
**Distributed** (> 10000 endpoints):
|
||||
```
|
||||
┌─→ [Frontend Pool 1] ──→ [Datastore Region 1]
|
||||
[Clients by region]├─→ [Frontend Pool 2] ──→ [Datastore Region 2]
|
||||
└─→ [Frontend Pool 3] ──→ [Datastore Region 3]
|
||||
```
|
||||
|
||||
## Server Deployment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
**System Requirements**:
|
||||
- OS: Linux (Ubuntu 20.04+, RHEL 8+), Windows Server 2019+
|
||||
- RAM: 8GB minimum, 16GB+ recommended for large deployments
|
||||
- CPU: 4 cores minimum, 8+ for production
|
||||
- Storage: 100GB+ for datastore (grows with collections)
|
||||
- Network: Public IP or internal with client access
|
||||
|
||||
**Software Requirements**:
|
||||
- No external dependencies (single binary)
|
||||
- Optional: MySQL/PostgreSQL for metadata (future enhancement)
|
||||
|
||||
### Installation Steps
|
||||
|
||||
#### 1. Download Velociraptor
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
wget https://github.com/Velocidex/velociraptor/releases/download/v0.72/velociraptor-v0.72.3-linux-amd64
|
||||
|
||||
# Make executable
|
||||
chmod +x velociraptor-v0.72.3-linux-amd64
|
||||
sudo mv velociraptor-v0.72.3-linux-amd64 /usr/local/bin/velociraptor
|
||||
```
|
||||
|
||||
#### 2. Generate Server Configuration
|
||||
|
||||
```bash
|
||||
# Interactive configuration generation
|
||||
velociraptor config generate -i
|
||||
|
||||
# Or automated with defaults
|
||||
velociraptor config generate \
|
||||
--deployment linux \
|
||||
--frontend_hostname velociraptor.company.com \
|
||||
--frontend_port 8000 \
|
||||
--gui_port 8889 \
|
||||
--datastore /var/lib/velociraptor \
|
||||
> /etc/velociraptor/server.config.yaml
|
||||
```
|
||||
|
||||
**Key Configuration Options**:
|
||||
|
||||
```yaml
|
||||
# server.config.yaml
|
||||
version:
|
||||
name: velociraptor
|
||||
version: "0.72"
|
||||
|
||||
Client:
|
||||
server_urls:
|
||||
- https://velociraptor.company.com:8000/
|
||||
ca_certificate: |
|
||||
-----BEGIN CERTIFICATE-----
|
||||
[CA cert]
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
API:
|
||||
bind_address: 0.0.0.0
|
||||
bind_port: 8001
|
||||
bind_scheme: tcp
|
||||
|
||||
GUI:
|
||||
bind_address: 0.0.0.0
|
||||
bind_port: 8889
|
||||
use_plain_http: false
|
||||
internal_cidr:
|
||||
- 10.0.0.0/8
|
||||
- 172.16.0.0/12
|
||||
- 192.168.0.0/16
|
||||
|
||||
Frontend:
|
||||
hostname: velociraptor.company.com
|
||||
bind_address: 0.0.0.0
|
||||
bind_port: 8000
|
||||
|
||||
Datastore:
|
||||
implementation: FileBaseDataStore
|
||||
location: /var/lib/velociraptor
|
||||
filestore_directory: /var/lib/velociraptor
|
||||
```
|
||||
|
||||
#### 3. Setup Systemd Service (Linux)
|
||||
|
||||
```bash
|
||||
# Create service file
|
||||
sudo cat > /etc/systemd/system/velociraptor.service <<'EOF'
|
||||
[Unit]
|
||||
Description=Velociraptor DFIR Agent
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/server.config.yaml frontend -v
|
||||
Restart=on-failure
|
||||
RestartSec=10
|
||||
User=velociraptor
|
||||
Group=velociraptor
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
SyslogIdentifier=velociraptor
|
||||
|
||||
# Security hardening
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=full
|
||||
ProtectHome=true
|
||||
ReadWritePaths=/var/lib/velociraptor
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Create user
|
||||
sudo useradd -r -s /bin/false velociraptor
|
||||
|
||||
# Setup directories
|
||||
sudo mkdir -p /etc/velociraptor /var/lib/velociraptor
|
||||
sudo chown -R velociraptor:velociraptor /etc/velociraptor /var/lib/velociraptor
|
||||
|
||||
# Start service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable velociraptor
|
||||
sudo systemctl start velociraptor
|
||||
```
|
||||
|
||||
#### 4. Create Initial Admin User
|
||||
|
||||
```bash
|
||||
# Create admin user
|
||||
velociraptor --config /etc/velociraptor/server.config.yaml \
|
||||
user add admin --role administrator
|
||||
|
||||
# Verify
|
||||
velociraptor --config /etc/velociraptor/server.config.yaml \
|
||||
user show admin
|
||||
```
|
||||
|
||||
#### 5. Access Web Interface
|
||||
|
||||
```bash
|
||||
# Access GUI at: https://velociraptor.company.com:8889/
|
||||
# Login with admin credentials created above
|
||||
```
|
||||
|
||||
### TLS Certificate Configuration
|
||||
|
||||
**Option 1: Self-Signed (Testing)**:
|
||||
```bash
|
||||
# Already generated during config creation
|
||||
# Certificates in server.config.yaml
|
||||
```
|
||||
|
||||
**Option 2: Let's Encrypt**:
|
||||
```bash
|
||||
# Install certbot
|
||||
sudo apt install certbot
|
||||
|
||||
# Generate certificate
|
||||
sudo certbot certonly --standalone \
|
||||
-d velociraptor.company.com \
|
||||
--non-interactive --agree-tos \
|
||||
-m admin@company.com
|
||||
|
||||
# Update server.config.yaml with Let's Encrypt certs
|
||||
```
|
||||
|
||||
**Option 3: Corporate CA**:
|
||||
```yaml
|
||||
# Update server.config.yaml
|
||||
Frontend:
|
||||
certificate: /path/to/server-cert.pem
|
||||
private_key: /path/to/server-key.pem
|
||||
|
||||
GUI:
|
||||
use_plain_http: false
|
||||
certificate: /path/to/gui-cert.pem
|
||||
private_key: /path/to/gui-key.pem
|
||||
```
|
||||
|
||||
## Client Deployment
|
||||
|
||||
### Generate Client Configuration
|
||||
|
||||
```bash
|
||||
# Generate client config from server config
|
||||
velociraptor --config /etc/velociraptor/server.config.yaml \
|
||||
config client > /tmp/client.config.yaml
|
||||
```
|
||||
|
||||
### Deployment Methods
|
||||
|
||||
#### Method 1: MSI Installer (Windows)
|
||||
|
||||
```bash
|
||||
# Generate MSI installer
|
||||
velociraptor --config /etc/velociraptor/server.config.yaml \
|
||||
config msi --binary velociraptor.exe \
|
||||
--output VelociraptorClient.msi
|
||||
|
||||
# Deploy via GPO, SCCM, or Intune
|
||||
# Silent install: msiexec /i VelociraptorClient.msi /quiet
|
||||
```
|
||||
|
||||
#### Method 2: DEB/RPM Package (Linux)
|
||||
|
||||
```bash
|
||||
# Generate DEB package
|
||||
velociraptor --config /etc/velociraptor/server.config.yaml \
|
||||
debian client --binary velociraptor-linux-amd64 \
|
||||
--output velociraptor-client.deb
|
||||
|
||||
# Deploy via Ansible, Puppet, or package manager
|
||||
# Install: sudo dpkg -i velociraptor-client.deb
|
||||
```
|
||||
|
||||
#### Method 3: Manual Installation
|
||||
|
||||
**Windows**:
|
||||
```powershell
|
||||
# Copy binary and config
|
||||
Copy-Item velociraptor.exe C:\Program Files\Velociraptor\
|
||||
Copy-Item client.config.yaml C:\Program Files\Velociraptor\
|
||||
|
||||
# Install as service
|
||||
& "C:\Program Files\Velociraptor\velociraptor.exe" `
|
||||
--config "C:\Program Files\Velociraptor\client.config.yaml" `
|
||||
service install
|
||||
|
||||
# Start service
|
||||
Start-Service Velociraptor
|
||||
```
|
||||
|
||||
**Linux**:
|
||||
```bash
|
||||
# Copy binary and config
|
||||
sudo cp velociraptor /usr/local/bin/
|
||||
sudo cp client.config.yaml /etc/velociraptor/
|
||||
|
||||
# Create systemd service
|
||||
sudo cat > /etc/systemd/system/velociraptor-client.service <<'EOF'
|
||||
[Unit]
|
||||
Description=Velociraptor DFIR Client
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/local/bin/velociraptor --config /etc/velociraptor/client.config.yaml client -v
|
||||
Restart=on-failure
|
||||
User=root
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Start service
|
||||
sudo systemctl enable velociraptor-client
|
||||
sudo systemctl start velociraptor-client
|
||||
```
|
||||
|
||||
### Client Configuration Options
|
||||
|
||||
```yaml
|
||||
# client.config.yaml
|
||||
Client:
|
||||
server_urls:
|
||||
- https://velociraptor.company.com:8000/
|
||||
|
||||
# Connection tuning
|
||||
max_poll: 60 # Max seconds between polls
|
||||
max_poll_std: 10 # Jitter to prevent thundering herd
|
||||
|
||||
# Performance
|
||||
max_upload_size: 104857600 # 100MB
|
||||
cpu_limit: 80 # CPU usage percentage limit
|
||||
progress_timeout: 3600 # Query timeout
|
||||
|
||||
# Writeback file (client state)
|
||||
writeback_linux: /etc/velociraptor/writeback.yaml
|
||||
writeback_windows: C:\Program Files\Velociraptor\writeback.yaml
|
||||
```
|
||||
|
||||
## High Availability
|
||||
|
||||
### Load Balancer Configuration
|
||||
|
||||
**HAProxy Example**:
|
||||
```conf
|
||||
# /etc/haproxy/haproxy.cfg
|
||||
frontend velociraptor_frontend
|
||||
bind *:8000 ssl crt /etc/ssl/certs/velociraptor.pem
|
||||
mode tcp
|
||||
default_backend velociraptor_servers
|
||||
|
||||
backend velociraptor_servers
|
||||
mode tcp
|
||||
balance leastconn
|
||||
option tcp-check
|
||||
server velo1 10.0.1.10:8000 check
|
||||
server velo2 10.0.1.11:8000 check
|
||||
server velo3 10.0.1.12:8000 check
|
||||
|
||||
frontend velociraptor_gui
|
||||
bind *:8889 ssl crt /etc/ssl/certs/velociraptor.pem
|
||||
mode http
|
||||
default_backend velociraptor_gui_servers
|
||||
|
||||
backend velociraptor_gui_servers
|
||||
mode http
|
||||
balance roundrobin
|
||||
option httpchk GET /
|
||||
server velo1 10.0.1.10:8889 check
|
||||
server velo2 10.0.1.11:8889 check
|
||||
server velo3 10.0.1.12:8889 check
|
||||
```
|
||||
|
||||
### Shared Datastore
|
||||
|
||||
**NFS Configuration**:
|
||||
```bash
|
||||
# On NFS server
|
||||
sudo apt install nfs-kernel-server
|
||||
sudo mkdir -p /export/velociraptor
|
||||
sudo chown nobody:nogroup /export/velociraptor
|
||||
|
||||
# /etc/exports
|
||||
/export/velociraptor 10.0.1.0/24(rw,sync,no_subtree_check,no_root_squash)
|
||||
|
||||
# On Velociraptor servers
|
||||
sudo mount -t nfs nfs-server:/export/velociraptor /var/lib/velociraptor
|
||||
```
|
||||
|
||||
**S3 Datastore (Future)**:
|
||||
```yaml
|
||||
# server.config.yaml
|
||||
Datastore:
|
||||
implementation: S3DataStore
|
||||
s3_bucket: velociraptor-datastore
|
||||
s3_region: us-east-1
|
||||
credentials_file: /etc/velociraptor/aws-credentials
|
||||
```
|
||||
|
||||
## Security Hardening
|
||||
|
||||
### Network Security
|
||||
|
||||
**Firewall Rules** (iptables):
|
||||
```bash
|
||||
# Allow client connections
|
||||
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
|
||||
|
||||
# Allow GUI access from management network only
|
||||
sudo iptables -A INPUT -p tcp --dport 8889 -s 10.0.0.0/8 -j ACCEPT
|
||||
sudo iptables -A INPUT -p tcp --dport 8889 -j DROP
|
||||
|
||||
# Save rules
|
||||
sudo iptables-save > /etc/iptables/rules.v4
|
||||
```
|
||||
|
||||
**TLS Configuration**:
|
||||
```yaml
|
||||
# Enforce TLS 1.2+
|
||||
Frontend:
|
||||
min_tls_version: "1.2"
|
||||
|
||||
GUI:
|
||||
min_tls_version: "1.2"
|
||||
```
|
||||
|
||||
### Access Control
|
||||
|
||||
**Role-Based Access**:
|
||||
```bash
|
||||
# Create read-only analyst role
|
||||
velociraptor --config server.config.yaml \
|
||||
acl grant analyst --role reader
|
||||
|
||||
# Create hunt operator role
|
||||
velociraptor --config server.config.yaml \
|
||||
acl grant hunter --role analyst
|
||||
|
||||
# Create admin role
|
||||
velociraptor --config server.config.yaml \
|
||||
acl grant admin --role administrator
|
||||
```
|
||||
|
||||
**Permissions Matrix**:
|
||||
| Role | View Artifacts | Run Collections | Create Hunts | Manage Users | View All Clients |
|
||||
|------|---------------|-----------------|--------------|--------------|------------------|
|
||||
| Reader | ✓ | ✗ | ✗ | ✗ | ✗ |
|
||||
| Analyst | ✓ | ✓ | ✗ | ✗ | ✓ |
|
||||
| Investigator | ✓ | ✓ | ✓ | ✗ | ✓ |
|
||||
| Administrator | ✓ | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
### Audit Logging
|
||||
|
||||
**Enable Comprehensive Logging**:
|
||||
```yaml
|
||||
# server.config.yaml
|
||||
Logging:
|
||||
output_directory: /var/log/velociraptor
|
||||
separate_logs_per_component: true
|
||||
max_age: 365
|
||||
|
||||
# Log queries
|
||||
log_queries: true
|
||||
|
||||
# Log all API calls
|
||||
log_api_calls: true
|
||||
```
|
||||
|
||||
**Audit Log Monitoring**:
|
||||
```bash
|
||||
# Monitor authentication events
|
||||
tail -f /var/log/velociraptor/frontend.log | grep -i "auth"
|
||||
|
||||
# Monitor collection starts
|
||||
tail -f /var/log/velociraptor/frontend.log | grep -i "collection"
|
||||
|
||||
# Monitor hunt creation
|
||||
tail -f /var/log/velociraptor/frontend.log | grep -i "hunt"
|
||||
```
|
||||
|
||||
## Monitoring and Maintenance
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Server Health**:
|
||||
```bash
|
||||
# Check server status
|
||||
systemctl status velociraptor
|
||||
|
||||
# Check connected clients
|
||||
velociraptor --config server.config.yaml \
|
||||
query "SELECT client_id, os_info.hostname, last_seen_at FROM clients()"
|
||||
|
||||
# Check resource usage
|
||||
velociraptor --config server.config.yaml \
|
||||
query "SELECT * FROM monitoring()"
|
||||
```
|
||||
|
||||
**Client Health Monitoring**:
|
||||
```sql
|
||||
-- Find offline clients (>24 hours)
|
||||
SELECT client_id,
|
||||
os_info.hostname AS Hostname,
|
||||
timestamp(epoch=last_seen_at) AS LastSeen
|
||||
FROM clients()
|
||||
WHERE last_seen_at < now() - 86400
|
||||
ORDER BY last_seen_at
|
||||
```
|
||||
|
||||
### Backup and Recovery
|
||||
|
||||
**Backup Strategy**:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# velociraptor-backup.sh
|
||||
|
||||
BACKUP_DIR="/backup/velociraptor"
|
||||
DATASTORE="/var/lib/velociraptor"
|
||||
DATE=$(date +%Y%m%d-%H%M%S)
|
||||
|
||||
# Stop server (optional for consistency)
|
||||
# systemctl stop velociraptor
|
||||
|
||||
# Backup datastore
|
||||
tar -czf "$BACKUP_DIR/datastore-$DATE.tar.gz" "$DATASTORE"
|
||||
|
||||
# Backup configuration
|
||||
cp /etc/velociraptor/server.config.yaml "$BACKUP_DIR/server.config-$DATE.yaml"
|
||||
|
||||
# Restart server
|
||||
# systemctl start velociraptor
|
||||
|
||||
# Rotate old backups (keep 30 days)
|
||||
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete
|
||||
```
|
||||
|
||||
**Recovery**:
|
||||
```bash
|
||||
# Stop server
|
||||
systemctl stop velociraptor
|
||||
|
||||
# Restore datastore
|
||||
tar -xzf /backup/velociraptor/datastore-20240115.tar.gz -C /var/lib/
|
||||
|
||||
# Restore config
|
||||
cp /backup/velociraptor/server.config-20240115.yaml /etc/velociraptor/server.config.yaml
|
||||
|
||||
# Start server
|
||||
systemctl start velociraptor
|
||||
```
|
||||
|
||||
### Maintenance Tasks
|
||||
|
||||
**Database Cleanup**:
|
||||
```bash
|
||||
# Delete old collections
|
||||
velociraptor --config server.config.yaml \
|
||||
query "DELETE FROM collections WHERE timestamp < now() - 7776000" # 90 days
|
||||
|
||||
# Vacuum datastore (reclaim space)
|
||||
velociraptor --config server.config.yaml \
|
||||
datastore vacuum
|
||||
```
|
||||
|
||||
**Client Updates**:
|
||||
```bash
|
||||
# Update clients via server
|
||||
# 1. Upload new binary to server
|
||||
velociraptor --config server.config.yaml \
|
||||
tools upload --file velociraptor-v0.72.4.exe --name velociraptor
|
||||
|
||||
# 2. Create update hunt
|
||||
velociraptor --config server.config.yaml \
|
||||
query "SELECT * FROM hunt(artifact='Generic.Client.Update')"
|
||||
```
|
||||
|
||||
## Scaling Considerations
|
||||
|
||||
### Performance Tuning
|
||||
|
||||
**Server Configuration**:
|
||||
```yaml
|
||||
# server.config.yaml
|
||||
Frontend:
|
||||
# Increase concurrent connections
|
||||
max_connections: 10000
|
||||
|
||||
# Connection timeouts
|
||||
keep_alive_timeout: 300
|
||||
|
||||
Datastore:
|
||||
# Filesystem tuning
|
||||
max_dir_size: 10000 # Files per directory
|
||||
|
||||
Resources:
|
||||
# Increase worker pools
|
||||
expected_clients: 10000
|
||||
max_poll_threads: 100
|
||||
```
|
||||
|
||||
**System Tuning**:
|
||||
```bash
|
||||
# Increase file descriptors
|
||||
echo "velociraptor soft nofile 65536" >> /etc/security/limits.conf
|
||||
echo "velociraptor hard nofile 65536" >> /etc/security/limits.conf
|
||||
|
||||
# Kernel tuning
|
||||
cat >> /etc/sysctl.conf <<EOF
|
||||
net.core.somaxconn = 4096
|
||||
net.ipv4.tcp_max_syn_backlog = 4096
|
||||
net.ipv4.ip_local_port_range = 10000 65000
|
||||
EOF
|
||||
sysctl -p
|
||||
```
|
||||
|
||||
### Capacity Planning
|
||||
|
||||
**Client-to-Server Ratio**:
|
||||
- Single server: Up to 10,000 clients
|
||||
- Multi-frontend: Up to 100,000 clients
|
||||
- Distributed: 100,000+ clients
|
||||
|
||||
**Storage Requirements**:
|
||||
- Base install: ~200MB
|
||||
- Per-client metadata: ~100KB
|
||||
- Per-collection: Varies (typically 1-50MB)
|
||||
- Retention: Plan for 90-180 days of data
|
||||
|
||||
**Network Bandwidth**:
|
||||
- Baseline: ~1KB/client/minute (polling)
|
||||
- Collection: Depends on artifacts (10MB-1GB)
|
||||
- Hunt: Multiply collection size by client count
|
||||
|
||||
**Formula**:
|
||||
```
|
||||
Storage = (Clients × 100KB) + (Collections/day × AvgSize × RetentionDays)
|
||||
Bandwidth = (Clients × 1KB × 60 × 24) + (Hunts/day × Clients × AvgCollection)
|
||||
```
|
||||
|
||||
### Monitoring Metrics
|
||||
|
||||
**Key Performance Indicators**:
|
||||
- Client check-in rate (target: >99%)
|
||||
- Average query execution time
|
||||
- Collection success rate
|
||||
- Datastore growth rate
|
||||
- Server CPU/memory usage
|
||||
- Network throughput
|
||||
|
||||
**Prometheus Metrics** (if enabled):
|
||||
```yaml
|
||||
# server.config.yaml
|
||||
Monitoring:
|
||||
bind_address: localhost
|
||||
bind_port: 9090
|
||||
```
|
||||
Reference in New Issue
Block a user