.env.example

# HomeNetSec environment configuration
# Copy to .env and customize for your environment.
#
# This file is sourced by scripts and read by docker-compose.
# Sections below include all supported operator-facing environment variables.

###############################################################################
# Core Paths (Required)
###############################################################################

# Root output/work directory used by HomeNetSec.
# If this path does NOT end with "/output", scripts automatically append "/output".
# Controls where state DBs, merged PCAPs, Zeek/Suricata/RITA output, and www files live.
# Example: /mnt/5TB/HomeNetSec/output
HOMENETSEC_WORKDIR=/path/to/HomeNetSec/output

# Directory where source PCAP chunks are ingested from.
# Controls what the ingest pipeline merges and later deletes (after delay).
# Example: /mnt/5TB/pcaps
PCAP_SOURCE_DIR=/path/to/pcap/source

# Optional explicit state directory override (dashboard API only).
# Default behavior: uses "$HOMENETSEC_WORKDIR/state".
#HOMENETSEC_STATE_DIR=/path/to/HomeNetSec/output/state

###############################################################################
# Dashboard Networking / Serving
###############################################################################

# LAN bind IP for dashboard nginx container (required when using dashboard compose).
#HOMENETSEC_LAN_BIND_IP=192.168.1.137

# Tailscale bind IP for dashboard nginx container (required when using dashboard compose).
#HOMENETSEC_TS_BIND_IP=100.x.y.z

# Dashboard HTTP port (default: 8088).
HOMENETSEC_DASHBOARD_PORT=8088

# Optional canonical dashboard URL for links/notifications.
# Example: http://100.x.y.z:8088
#HOMENETSEC_DASHBOARD_BASE_URL=http://TS_HOST_IP:8088

# Dashboard generation mode.
# Legacy mode was removed; keep this as "live".
HOMENETSEC_DASHBOARD_MODE=live

# Minimum alert confidence to include in dashboard/API alert listings.
# Uses COALESCE(triage_confidence, confidence) and accepts 0.0-1.0.
# Set to 0 to disable filtering.
HOMENETSEC_MIN_ALERT_CONFIDENCE=0

# Comma-separated severities to include in dashboard/API alert listings.
# Allowed values: critical,high,med,low,info
# Example: show only higher-priority alerts:
# HOMENETSEC_ALERT_SEVERITIES=critical,high,med
HOMENETSEC_ALERT_SEVERITIES=critical,high,med,low,info

###############################################################################
# Pipeline Runtime Controls
###############################################################################

# Orchestration flags used by run_ingest_and_analysis.sh.
# Set to 1 to skip that phase for a given run.
SKIP_INGEST=0
SKIP_ANALYSIS=0
SKIP_DASHBOARD=0

# Optional: expected ingest cadence in seconds for pipeline status UI.
# Set this to your cron interval (for example 300 for every 5 minutes).
#INGEST_EXPECT_NEXT_RUN_SECONDS=300

###############################################################################
# Detection / Triage Window Controls
###############################################################################

# Rolling historical lookback for continuous detection (hours, default: 720 = 30d).
CONTINUOUS_LOOKBACK_HOURS=720

# Recent comparison window for "newness" detection (hours, default: 2).
CONTINUOUS_RECENT_HOURS=2

# Optional explicit allowlist JSON path for detection.
# Default fallback order:
#   1) $HOMENETSEC_ALLOWLIST
#   2) $HOMENETSEC_WORKDIR/state/allowlist.local.json
#   3) assets/allowlist.example.json
#HOMENETSEC_ALLOWLIST=/path/to/allowlist.local.json

# Optional watch ports text file path for baseline/detection sensitivity.
# Default: $HOMENETSEC_WORKDIR/state/watch_ports.local.txt
#HOMENETSEC_WATCH_PORTS_FILE=/path/to/watch_ports.local.txt

# Used by allowlist_manage.sh helper script.
# Default: $HOMENETSEC_WORKDIR/state/allowlist.local.json
#HOMENETSEC_ALLOWLIST_PATH=/path/to/allowlist.local.json

###############################################################################
# Ingest / Merge Behavior
###############################################################################

# Ignore source PCAPs newer than "now - SAFETY_LAG_SECONDS" (default: 120).
# Prevents ingesting still-growing files.
SAFETY_LAG_SECONDS=120

# Retry count for merge/verify logic on failure (default: 1).
MERGE_RETRIES=1

# If 1, verify merged packet count matches input packet count (default: 1).
#VERIFY_MERGE=1

# Delay before deleting source PCAPs after successful merge (hours, default: 48).
SOURCE_PCAP_DELETE_DELAY_HOURS=48

# Backfill window to reconstruct missing merge manifests from recent merged PCAPs
# (hours, default: 36).
RECENT_MERGE_INDEX_BACKFILL_HOURS=36

###############################################################################
# RITA Controls
###############################################################################

# Enable continuous RITA import/beacon extraction:
# - 1 = enabled
# - 0 = disabled (default in current scripts)
RUN_RITA=0

# Zeek flatten lookback window for RITA import (hours, default: 2).
RITA_RECENT_LOOKBACK_HOURS=2

# Host directory used for flattened recent Zeek logs consumed by continuous RITA.
# Keep this path writable by the user running pipeline scripts.
# Example: /mnt/5TB/HomeNetSec/output/state/zeek-flat-staging
#HOMENETSEC_RITA_STAGING_DIR=/path/to/HomeNetSec/output/state/zeek-flat-staging

# Optional compose file override for analysis pipeline containers.
# Default: assets/docker-compose.yml
#HOMENETSEC_COMPOSE_FILE=/home/user/HomeNetSec/assets/docker-compose.yml

# Optional compose project name override (default: homenetsec-pipeline).
HOMENETSEC_PIPELINE_COMPOSE_PROJECT=homenetsec-pipeline

# Optional RITA config file path override.
# Default: assets/rita-config.yaml.example
#HOMENETSEC_RITA_CONFIG=/home/user/HomeNetSec/assets/rita-config.yaml.example

###############################################################################
# Retention / Cleanup
###############################################################################

# If 1, retention cleanup runs at end of ingest pipeline (default: 1).
RUN_RETENTION_CLEANUP=1

# Retain merged PCAPs/manifests this many days (default: 3).
MERGED_PCAP_RETENTION_DAYS=3

# Retain ingest artifacts (Zeek dirs, Suricata eve logs) this many days (default: 30).
HOURLY_ARTIFACT_RETENTION_DAYS=30

# Retain resolved alerts this many days before pruning (default: 90).
RESOLVED_ALERT_RETENTION_DAYS=90

###############################################################################
# AdGuard Integration (Optional, recommended for better device naming/context)
###############################################################################

# AdGuard Home base URL (no trailing slash preferred).
#ADGUARD_URL=http://192.168.1.2:3000

# AdGuard API username.
#ADGUARD_USER=admin

# AdGuard API password.
#ADGUARD_PASS=change_me

# Max AdGuard querylog entries triage inspects when correlating alert source IPs
# to recently requested domains (default: 500).
HOMENETSEC_ADGUARD_QUERYLOG_LIMIT=500

###############################################################################
# Device Visibility Filters (Optional)
###############################################################################

# Comma-separated CIDRs considered valid device ranges for dashboard/report views.
#HOMENETSEC_VISIBLE_DEVICE_CIDRS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

# Comma-separated CIDRs hidden from device views as infrastructure ranges.
#HOMENETSEC_HIDDEN_DEVICE_CIDRS=127.0.0.0/8,169.254.0.0/16,172.17.0.0/16,172.18.0.0/16,172.19.0.0/16,172.30.0.0/16

###############################################################################
# Legacy Compatibility (Optional)
###############################################################################

# Legacy variable from older flows; currently not used by the active pipeline.
# Keep only if external tooling depends on it.
#OPNSENSE_HOST=192.168.1.1