.env.example

# ==============================================================================
#  OPNsense Live Attack Map - configuration
#  Copy to .env and edit. .env is gitignored; never commit real credentials.
# ==============================================================================

# --- OPNsense connection ------------------------------------------------------
OPNSENSE_URL=https://192.168.1.1

# Create at: System > Access > Users > <user> > API keys > "+"
# An API key is REQUIRED for the IDS alert feed: that endpoint is POST-only and
# a plain session is rejected by CSRF. Consider a dedicated read-only user.
OPNSENSE_KEY=
OPNSENSE_SECRET=

# Fallback only, used when no API key is set. Scrapes the login form and holds a
# session. Firewall logs will work; IDS alerts will not.
OPNSENSE_USER=
OPNSENSE_PASS=

# Most OPNsense boxes present a certificate that will not match the address you
# reach them on. Set 0 if yours does.
TLS_INSECURE=1


# --- Branding -----------------------------------------------------------------
# All display text is configurable so you can publish screenshots or a public
# instance without it announcing whose network it is.
SITE_TITLE=ATTACK MAP
SITE_SUBTITLE=
SITE_DESCRIPTION=Live firewall and IDS activity
PAGE_TITLE=


# --- Privacy ------------------------------------------------------------------
# Redaction happens SERVER-SIDE, before anything reaches the browser. Hidden
# fields are never sent, so they cannot be recovered from devtools or a capture.
#
#   public  (default) - safe to screenshot, stream or expose. WAN address and
#                       LAN addresses become stable pseudonyms (lan-3f9a21),
#                       firewall rule labels and DNS/SNI names are dropped,
#                       interfaces are reduced to wan/lan/opt, and the home
#                       marker is displaced by up to HOME_FUZZ_KM.
#   private           - full detail. For your own screen only.
#
# Outbound destination addresses are never redacted - those are other people's
# servers, not yours.
PRIVACY=public

# Individual overrides. Leave blank to inherit from the preset above.
SHOW_WAN_IP=
MASK_LOCAL_IPS=
SHOW_RULE_LABELS=
SHOW_DNS_SNI=
SHOW_INTERFACES=

# Kilometres the home marker is displaced by. The offset is deterministic, so it
# lands in the same wrong place every restart - a per-frame jitter could be
# averaged back to the true position. 0 disables.
HOME_FUZZ_KM=

# Salt for the pseudonyms local addresses are replaced with. RFC1918 space is
# small enough to brute-force an unsalted hash. Defaults to a random value per
# boot; set it only if you want labels stable across restarts, and treat it as
# a secret.
PRIVACY_SALT=

# Addresses in the feed and the attacker rankings link to a lookup service.
# "{ip}" is substituted. Only real addresses are linked - redacted pseudonyms
# never are. Leave empty to disable the links entirely.
#
# Following a link tells that service which addresses you are investigating.
# Alternatives: https://www.abuseipdb.com/check/{ip}
#               https://www.shodan.io/host/{ip}
#               https://www.virustotal.com/gui/ip-address/{ip}
#               https://ipinfo.io/{ip}
IP_LOOKUP_URL=https://radar.cloudflare.com/ip/{ip}


# --- Attribution --------------------------------------------------------------
# Resolve attacker addresses to hostnames, shown under the address in the
# rankings. "o336.scanner.modat.io" identifies a scanner at a glance in a way
# that 85.217.140.37 does not.
#
# Turning this off is reasonable when publishing: PTR queries tell your resolver
# chain which addresses you are inspecting, the same class of disclosure
# IP_LOOKUP_URL carries. Local and RFC1918 addresses are NEVER resolved
# regardless of this setting - a LAN PTR would publish your host inventory.
RDNS=1

# How much of an alert counts as a threat, on the 1-4 scale derived from the
# Emerging Threats class token. At 3 the signature panel keeps SCAN, EXPLOIT,
# TROJAN, MALWARE, CNC and DOS, and hides the ET INFO / POLICY / DNS telemetry
# your own hosts generate - which is typically ~90% of all alerts and otherwise
# outranks real attacks on volume alone. The "all" toggle in the panel shows
# everything without changing this. Set 1 to rank every alert by default.
IDS_MIN_SEVERITY=3

# Individual rule SIDs to keep out of the threats panel, comma separated.
#
# Some rules are real signal in general but constant noise on a given network,
# because you legitimately run the service they watch for. The ET HUNTING class
# is the clearest case: it is where malware hiding inside legitimate services
# (Telegram, Discord, tunnelling providers) shows up, so it counts as a threat -
# but if you actually use Telegram, one rule will drown the panel.
#
# Mute that rule rather than lowering IDS_MIN_SEVERITY, which would discard the
# whole class. Muted alerts stay visible under the panel's "all" toggle, so
# nothing is hidden - and muting is absolute, so a muted rule stays out even if
# your IPS policy drops it.
#
# Example: IDS_MUTE_SIDS=2033966
IDS_MUTE_SIDS=


# --- Statistics windows -------------------------------------------------------
# Ranking windows offered in the UI, shortest first; the first is the default.
# These are cheap: events are counted into per-minute buckets as they arrive, so
# cost scales with the number of DISTINCT attackers rather than with traffic
# volume - a day costs about the same as an hour (~0.3% of a core either way).
STATS_WINDOWS=1h,24h

# How much history to keep. Must cover your longest window above.
STATS_RETAIN_HOURS=26

# Keep history across restarts, so a redeploy does not reset the panels.
# Written every 5 minutes and on shutdown.
#
# NOTE: this file holds real, unredacted addresses from your network. It lives in
# data/, which is gitignored in full for that reason. Redaction still happens on
# the way out, so nothing about what is sent to browsers changes.
STATS_PERSIST=1
STATS_FILE=./data/rollup.json

# How much history to seed from the firewall log at startup, so a fresh deploy
# shows a full day immediately instead of minutes of data under a "24h" label.
# After a restart only the gap since the last save is filled. Set 0 to disable.
#
# This walks the PAGED log endpoint backwards, which is what makes a full day
# reachable: measured on OPNsense 26.7.1, 24h is ~27 pages and ~65s of
# background work, and the log itself retains about 72h. Seeded hostile events
# also populate the threat log, so an attack from last night is readable on a
# freshly deployed instance.
#
# Do not be tempted back to a single large request against the parsed endpoint:
# it has no cursor, and at 400k rows it exhausts PHP's 1 GB limit and dies on
# the firewall.
BACKFILL_HOURS=24

# Rows per page (server caps at 9999) and a hard stop on how far the walk may
# go, so a very busy network cannot turn startup into an unbounded crawl.
BACKFILL_PAGE_ROWS=10000
BACKFILL_MAX_PAGES=200


# --- Timezone -----------------------------------------------------------------
# The firewall log's timestamps carry no timezone. "auto" infers the offset at
# startup by comparing a log line against the current time; pin it (e.g.
# "+01:00", "-05:00", "Z") if you would rather be explicit.
FW_TZ_OFFSET=auto


# --- Where "home" sits on the map ---------------------------------------------
# Every arc has one end here. Defaults to the geolocation of your WAN address.
# Setting these explicitly is the most reliable way to avoid revealing where you
# actually are - point it at your nearest city centre.
HOME_LAT=
HOME_LON=
HOME_LABEL=home.lan

# Networks treated as "ours" rather than geolocated. Add any subnets you use.
# Your WAN address is added automatically.
HOME_NETS=192.168.0.0/16,10.0.0.0/8,172.16.0.0/12,100.64.0.0/10,169.254.0.0/16,fd00::/8,fe80::/10

# Longitude the map is centred on. 0 is the conventional world map. Use the
# literal "home" to centre on your own longitude instead - every arc then runs
# to the middle, at the cost of an unfamiliar layout.
MAP_CENTER_LON=0


# --- Polling ------------------------------------------------------------------
FW_POLL_MS=2000
IDS_POLL_MS=5000
FW_LIMIT=1000
IDS_ROWCOUNT=200


# --- GeoIP --------------------------------------------------------------------
# A local GeoLite2 database is the primary source, downloaded on first run
# (~62 MB City + ~12 MB ASN, about 15s) from FyraLabs' mirror of MaxMind's
# releases - no account, no licence key. Offline, instant, no rate limit, and it
# carries the ASN/org names that make an attacker line readable.
#
# ip-api.com is the fallback, used while the first download is in flight or if
# it fails. Free and keyless, but ~15 requests/minute, it sends every address to
# a third party, and Suricata alerts on the lookups themselves.
#
# /api/health reports which mode is currently active.
GEO_AUTO_DOWNLOAD=1
GEO_FALLBACK=1
GEO_CITY_DB=./data/GeoLite2-City.mmdb
GEO_ASN_DB=./data/GeoLite2-ASN.mmdb

# How old a database may get before it is re-fetched - and how often that check
# runs. Nothing is downloaded until the local copy is this stale, so the default
# is roughly 74 MB per week, not per day. Set GEO_AUTO_DOWNLOAD=0 to manage the
# files yourself.
GEO_REFRESH_DAYS=7

# Alerts triggered by this tool's own geo lookups ("ET POLICY External IP Lookup
# ip-api.com" and friends) are dropped, so the map reflects your network rather
# than itself - left in, they are usually the single most frequent signature.
# Only applies while a third-party provider is in use; a local GeoLite2 database
# makes no lookups to alert on. Set 0 to see them.
#
# Note this also hides genuine lookups to the same service by other devices on
# your network. /api/health reports how many alerts have been suppressed.
SUPPRESS_GEO_ALERTS=1


# --- Server -------------------------------------------------------------------
PORT=8474
HOST=0.0.0.0


# --- Rendering / volume control -----------------------------------------------
# Most events on a home connection are outbound passes. Repeats of the same
# src -> dst:port inside this window collapse into one arc with a hit count.
COLLAPSE_MS=10000
MAX_ARCS=300
BUFFER_SIZE=2000

# Replay recent firewall events at speed to exercise the renderer without
# waiting for real traffic. 0 for live operation.
REPLAY=0
REPLAY_SPEED=10