Agent Configuration

This guide provides a comprehensive reference for configuring the Tamandua EDR agent, including all available settings, performance tuning options, and best practices.

Configuration File Location

The agent configuration file location varies by platform:

The configuration uses TOML format and supports hot-reloading for most settings.

Basic Configuration

Minimal Configuration Example

# Tamandua Agent Configuration
# Minimal required settings

# Agent identity (auto-generated during enrollment)
agent_id = "550e8400-e29b-41d4-a716-446655440001"

# Backend server URL
server_url = "wss://agents.tamandua.treantlab.org:8443/socket/agent"

# Authentication (set during enrollment)
auth_token = "your-jwt-token"

Server URL Configuration

Default (Tamandua Cloud)

# Official Tamandua cloud endpoint
server_url = "wss://agents.tamandua.treantlab.org:8443/socket/agent"

Self-Hosted Deployment

# Self-hosted server
server_url = "wss://your-tamandua-server.example.com:8443/socket/agent"

Connection Settings

# Heartbeat interval (seconds)
heartbeat_interval_seconds = 30

# Connection timeout (seconds)
connection_timeout_seconds = 30

# Reconnection settings
reconnect_delay_seconds = 5
max_reconnect_attempts = 0  # 0 = infinite retry

# Telemetry batching
batch_size = 100
batch_timeout_seconds = 5

Transport Failover

[transport]
# Backup servers for failover (tried in order)
backup_servers = [
    "wss://backup1.tamandua.treantlab.org:8443/socket/agent",
    "wss://backup2.tamandua.treantlab.org:8443/socket/agent"
]

# Certificate pinning (optional - for additional security)
cert_pins = [
    "sha256//AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
]

Enrollment Token

The enrollment token is obtained from the admin console and used during initial setup.

# Authentication token (JWT, set during enrollment)
auth_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Note: The token is automatically configured during the enrollment process. Do not manually edit unless re-enrolling the agent.

Collection Settings

Core Collectors

[collectors]
# Core collectors (cross-platform)
process_enabled = true      # Process creation/termination
file_enabled = true         # File operations
network_enabled = true      # Network connections
dns_enabled = true          # DNS queries

# Advanced detection collectors
injection_enabled = true            # Process injection detection
named_pipes_enabled = true          # Named pipe monitoring
usb_enabled = true                  # USB device monitoring
ransomware_canary_enabled = true    # Honeyfile monitoring
driver_blocklist_enabled = true     # Malicious driver detection
memory_enabled = true               # Memory-only malware signals
network_dpi_enabled = false         # Roadmap/preview: deep packet inspection requires validated packet sensor support
network_anomaly_enabled = true      # Network behavior anomalies from available endpoint telemetry
cloud_enabled = false               # Roadmap/preview: CSPM/cloud monitoring is not a current production claim
exploit_mitigation_enabled = true   # Exploit detection
defense_evasion_enabled = true      # EDR bypass detection
persistence_enabled = true          # Persistence mechanisms
script_inspector_enabled = true     # Script analysis
credential_theft_enabled = true     # Credential access
lateral_movement_enabled = true     # Lateral movement
container_enabled = true            # Container monitoring (Linux)
process_hollowing_enabled = true    # Process hollowing
scheduled_tasks_enabled = true      # Scheduled tasks
firmware_enabled = true             # Firmware integrity
clipboard_enabled = true            # Clipboard monitoring
browser_protection_enabled = true   # Browser security
input_capture_enabled = true        # Keylogging detection
office_email_enabled = true         # Office/email monitoring
ad_monitor_enabled = true           # AD monitoring (Windows)
health_enabled = true               # Agent health metrics
syscall_evasion_enabled = true      # Syscall hooking detection

Windows-Specific Collectors

[collectors]
# Windows-only collectors (ignored on other platforms)
registry_enabled = true     # Registry changes
etw_enabled = true          # Event Tracing for Windows
amsi_enabled = true         # Antimalware Scan Interface
lsass_enabled = true        # LSASS access monitoring
wmi_enabled = true          # WMI event subscriptions
clr_enabled = true          # .NET runtime monitoring

Linux-Specific Collectors

[collectors]
# Linux-only collectors
ebpf_enabled = true         # eBPF telemetry (kernel 5.4+)

ETW Configuration (Windows)

[collectors.etw]
enabled = true
session_name = "TamanduaEDR"
ring_buffer_size = 100000   # Number of events in buffer
tamper_detection = true     # Detect ETW tampering
health_check_interval_secs = 30
provider_rate_limit = 10000 # Events/sec per provider

# Per-provider toggles
[collectors.etw.providers]
kernel_process = true
kernel_file = true
kernel_network = true
kernel_registry = true
dns_client = true
powershell = true
amsi = true
security_auditing = true
sysmon = true
threat_intelligence = true
kernel_audit_api = true
wmi_activity = true
task_scheduler = true
services = true
code_integrity = true       # Unsigned driver detection
ldap_client = true          # LDAP reconnaissance

Performance Tuning

Performance Profiles

The agent supports three performance profiles that automatically configure collector intervals and resource usage:

# Options: "aggressive", "balanced", "lightweight"
performance_profile = "balanced"

CPU Limiting

# Maximum CPU percentage target
max_cpu_percent = 15.0

# Sub-loop interval multiplier (affects scanning frequency)
# Higher values = slower scanning = lower CPU
# Automatic based on profile, but can override:
sub_loop_interval_multiplier = 3.0

Collector Tuning

[collector_tuning]
# Scan intervals (seconds unless noted)
process_scan_interval_secs = 5
memory_scan_interval_secs = 30
dns_poll_interval_ms = 500
network_poll_interval_ms = 1000
registry_poll_interval_secs = 2

# Adaptive throttling
adaptive_throttling_enabled = true
cpu_throttle_threshold = 25.0

Resource Governor

[resource_governor]
enabled = true

# Hard limits
cpu_limit_percent = 25.0
memory_limit_mb = 512
disk_write_limit_mbps = 50

# Pressure thresholds
elevated_pressure_cpu = 15.0
critical_pressure_cpu = 20.0
emergency_pressure_cpu = 25.0

# Throttle escalation
throttle_backoff_secs = 5
max_throttle_level = 4

Proxy Configuration

HTTP Proxy

[transport]
# HTTP proxy for HTTPS connections (enrollment)
http_proxy = "http://proxy.example.com:8080"
https_proxy = "http://proxy.example.com:8080"

# Proxy authentication
proxy_username = "user"
proxy_password = "password"

# No proxy for specific hosts
no_proxy = "localhost,127.0.0.1,.internal.example.com"

WebSocket Proxy

For WebSocket connections through a proxy:

[transport]
# SOCKS5 proxy for WebSocket connections
socks_proxy = "socks5://proxy.example.com:1080"

# Or use HTTP CONNECT
ws_proxy = "http://proxy.example.com:8080"

TLS Configuration

[tls]
enabled = true              # TLS enabled (required in production)
skip_verify = false         # Never skip in production

# Client certificate (for mTLS)
# Usually auto-configured during enrollment
cert_file = "config/cert.pem"
key_file = "config/key.pem"
ca_bundle = "config/ca-bundle.pem"

# Minimum TLS version
min_version = "1.2"         # Options: "1.2", "1.3"

Exclusions

Path Exclusions

# Paths to exclude from monitoring
excluded_paths = [
    # Linux system paths
    "/proc",
    "/sys",
    "/dev",
    "/run",

    # Windows system paths
    "C:\\Windows\\WinSxS",
    "C:\\Windows\\Installer",
    "C:\\Windows\\SoftwareDistribution",

    # macOS system paths
    "/System",
    "/private/var/folders",

    # Application-specific exclusions
    "/var/log/tamandua",
    "C:\\ProgramData\\Tamandua\\logs"
]

Process Exclusions

# Processes to exclude from monitoring
excluded_processes = [
    # System processes
    "System Idle Process",
    "System",

    # Known good high-volume processes
    "MsMpEng.exe",           # Windows Defender
    "svchost.exe",           # Use with caution

    # Backup/indexing software
    "Spotlight",
    "mds",
    "mds_stores"
]

File Pattern Monitoring

# File extensions to actively monitor
monitored_file_patterns = [
    "*.exe",
    "*.dll",
    "*.sys",
    "*.ps1",
    "*.bat",
    "*.cmd",
    "*.vbs",
    "*.js",
    "*.hta",
    "*.scr",
    "*.msi",
    "*.jar",
    "*.py",
    "*.sh",
    "*.elf"
]

Advanced Exclusions

[exclusions]
# Regex-based path exclusions
path_patterns = [
    ".*\\.log$",
    ".*\\.tmp$",
    "/home/[^/]+/\\.cache/.*"
]

# Exclude by signer (Windows)
trusted_signers = [
    "Microsoft Corporation",
    "Microsoft Windows"
]

# Exclude by process hash (SHA-256)
trusted_hashes = [
    "abc123...",
    "def456..."
]

Detection Settings

YARA Scanning

# Enable YARA rule scanning
yara_enabled = true

# YARA rules directory (platform default if not set)
# yara_rules_dir = "/var/lib/tamandua/rules/yara"

Entropy Analysis

# Enable entropy-based packed/encrypted detection
entropy_check_enabled = true

# Entropy threshold (7.2 = highly compressed/encrypted)
entropy_threshold = 7.2

ML-Based Detection

# Enable ML-based pre-execution scanning
ml_scanning_enabled = true

# Confidence threshold (0.0-1.0)
ml_confidence_threshold = 0.7

# Model path (optional, uses default if not set)
# ml_model_path = "/var/lib/tamandua/models/malware_smell.onnx"

# Inference timeout (seconds)
ml_inference_timeout_secs = 30

Offline Detection

[offline_detection]
enabled = true

# Maximum queued verdicts when offline
verdict_queue_max = 10000

# Backend reachability check interval
backend_check_interval_secs = 30

# Local ML confidence threshold
ml_confidence_threshold = 0.7

# ONNX model image size
onnx_image_size = 64

# Maximum file size to scan (bytes)
max_file_size = 104857600   # 100 MB

Syscall Evasion Detection

[syscall_evasion]
enabled = true

# IAT integrity check interval (seconds)
iat_check_interval_secs = 30

# Memory scan for syscall stubs (seconds)
memory_scan_interval_secs = 60

# Stack frame validation
stack_validation = true

# NTDLL integrity checks (seconds)
ntdll_check_interval_secs = 30

# ETW-based syscall profiling
etw_profiling = true

# Heaven's Gate detection
heavens_gate_detection = true

# High-risk processes (monitored more frequently)
high_risk_processes = [
    "powershell.exe",
    "pwsh.exe",
    "cmd.exe",
    "wscript.exe",
    "cscript.exe",
    "mshta.exe",
    "rundll32.exe",
    "regsvr32.exe"
]

# Behavioral anomaly threshold (0.0-1.0)
anomaly_threshold = 0.7

# Learning period before baselining (seconds)
learning_period_secs = 300

EDR Blinding Detection

[edr_blinding]
# ETW patching detection (T1562.006)
etw_patching_enabled = true
etw_check_interval_secs = 15

# AMSI bypass detection (T1562.001)
amsi_patching_enabled = true
amsi_check_interval_secs = 10
amsi_cross_process_enabled = true

# Event Log tampering detection (T1070.001)
event_log_integrity_enabled = true
event_log_check_interval_secs = 10
event_log_heartbeat_stale_secs = 300
event_log_thread_drop_threshold = 3

# Credential Guard bypass detection (T1003.001)
credential_guard_enabled = true
credential_guard_check_interval_secs = 10

Deception (Honeyfiles)

# Enable honeyfile monitoring
honeyfiles_enabled = true

# Custom honeyfile paths
honeyfile_paths = [
    "C:\\Users\\Public\\Documents\\passwords.xlsx",
    "C:\\Users\\Public\\Documents\\credentials.txt",
    "/home/shared/passwords.txt",
    "/var/secrets/api-keys.json"
]

Auto-Update Settings

[updater]
enabled = true

# Binary update check interval (hours)
check_interval_hours = 6

# Model/rule update interval (hours)
model_update_interval_hours = 1

# Enable model/rule updates
model_updates_enabled = true

# Custom update URL (leave empty for default)
update_url = ""

# Auto-restart after update
auto_restart = true

# Ed25519 public key for verification (empty = use compiled-in key)
signing_public_key = ""

File Journal (Ransomware Rollback)

[file_journal]
enabled = true

# Maximum journal size (MB)
max_size_mb = 500

# File size limit for snapshots (bytes)
max_file_size = 10485760    # 10 MB

# Monitored paths
monitored_paths = [
    "C:\\Users",
    "/home",
    "/var/www"
]

# Retention period (days)
retention_days = 7

DLP (Data Loss Prevention)

[dlp]
enabled = true

# Content scanning
scan_usb_writes = true
scan_cloud_sync = true
scan_network_shares = true
scan_clipboard = true

# Detection categories
detect_pii = true           # PII (SSN, credit cards)
detect_credentials = true   # Passwords, API keys
detect_source_code = true   # Code secrets
detect_regulated = true     # HIPAA, PCI-DSS data

# Maximum file size to scan (bytes)
max_scan_size = 52428800    # 50 MB

Configuration Hot-Reload

Most configuration changes are applied without restart:

# Send SIGHUP to reload config (Linux/macOS)
sudo kill -HUP $(pgrep tamandua-agent)

# Or via service (all platforms)
# Config is checked every 30 seconds by default

Changes Requiring Restart

• server_url changes
• TLS certificate changes
• Major collector enable/disable
• Resource governor limit changes

Configuration Signing

For high-security environments, configuration updates can be cryptographically signed:

# Configuration signing keys (Ed25519)
config_signing_keys = [
    { key_id = "production-2026-01", public_key = "BASE64_PUBLIC_KEY" }
]

# Enforcement mode
# false = log warnings (report-only)
# true = reject unsigned configs
config_signing_enforce = false

Best Practices

Production Deployment

1. Use balanced profile as default, aggressive only for high-value assets
2. Enable adaptive throttling to prevent performance issues
3. Configure exclusions for known-good high-volume applications
4. Enable TLS with certificate pinning
5. Configure backup servers for failover

Performance-Sensitive Systems

performance_profile = "lightweight"
max_cpu_percent = 5.0

[collectors]
memory_enabled = false
network_dpi_enabled = false
credential_theft_enabled = false
process_hollowing_enabled = false

High-Security Assets

performance_profile = "aggressive"

[collectors]
# Enable all collectors
syscall_evasion_enabled = true

[edr_blinding]
# Enable all tamper detection
etw_patching_enabled = true
amsi_patching_enabled = true
credential_guard_enabled = true

Next Steps

• Enrollment Guide - Manage agent enrollment
• Agent Overview - Return to agent overview
• Windows Installation - Platform-specific guides