Admin Guide: Installation Parameters

This page is the authoritative reference for every configuration parameter Logster exposes. It covers the contents of deploy/service-config.yaml, the environment variable overrides that take precedence, and the trade-offs behind the most commonly tuned values.

Read this end-to-end once; then use it as a lookup table.

How configuration is loaded

Logster services read configuration from two layers, applied in this order (later wins):

service-config.yaml — a single shared YAML file mounted read-only into every Python service container at /app/config.yaml. See the mount under each service's volumes: block in deploy/docker-compose.yml.
Environment variables — override host and connection details at the container level.

Python services load the YAML via their main.py entry points and construct typed config objects from libs/logster-common/logster_common/config.py.

[!NOTE] The dashboard is the only service that does not read service-config.yaml — its configuration comes entirely from the environment variables documented under Dashboard environment below.

`kafka`

Connection and topic names for the Kafka broker.

Key	Default	Meaning
`kafka.brokers`	`kafka:9092`	Comma-separated broker list. Overridden by the `KAFKA_BROKERS` environment variable.
`kafka.group_id`	`logster`	Base consumer group id; services append their own suffix.
`kafka.raw_sysmon_topic`	`sysmon-logs`	Raw topic the normalizer consumes for Windows events.
`kafka.raw_linux_topics`	4 topics	`linux-auditd-logs`, `linux-ebpf-file-logs`, `linux-ebpf-process-logs`, `linux-ebpf-network-logs`.
`kafka.normalized_topic`	`normalized-endpoint-events`	Normalizer output / inference input.
`kafka.inference_results_topic`	`logster-inference-results`	Inference output / alerts input.
`kafka.alerts_topic`	`logster-alerts`	Final alerts stream.

[!IMPORTANT] If you rename topics here, you must also update the kafka-init container in deploy/docker-compose.yml. Otherwise auto-created topics will have the wrong partition counts.

`model`

Points the inference service at the pre-trained GNN weights.

Key	Default	Meaning
`model.path`	`/app/models/balanced_run_20260114_143653/best_model.pt`	Windows model inside the container. Host path is `models/models/balanced_run_20260114_143653/best_model.pt`.
`model.linux_model_path`	`/app/models/balanced_run_20260222_142924/best_model.pt`	Linux model. Same mount.
`model.device`	`cpu`	PyTorch device. Set to `cuda` on a GPU host with the NVIDIA container runtime.

For the full model swap procedure, see Model Deployment.

`inference`

Controls how the inference service buckets events and runs the GNN.

Key	Default	Unit	Meaning
`inference.window`	`3.0`	minutes	Size of each per-endpoint event window. Every GNN run classifies the events from the last `window` minutes.
`inference.interval`	`30.0`	seconds	How often the inference service runs the GNN per endpoint.
`inference.threshold`	`0.7`	—	Minimum `attack_prob` from the model to label a window as `attack`.
`inference.use_idle_allowlist`	`true`	—	On Linux, skip the GNN when every process in the window is on the allow-list of known-idle daemons.

These four values are the main tuning surface for the detection pipeline. See Tuning recipes below.

`redis`

Per-endpoint inference state store.

Key	Default	Meaning
`redis.host`	`redis`	Hostname. Overridden by `REDIS_HOST`.
`redis.port`	`6379`	Port.

`elasticsearch`

Used by the Python services that write to or read from Elasticsearch.

Key	Default	Meaning
`elasticsearch.hosts`	`http://elasticsearch:9200`	Full URL to the ES cluster. Overridden by `ES_HOST`.
`elasticsearch.index_prefix`	`logster`	Prefix for the two indices: `logster-events` and `logster-inferences`.

`alerts`

The alert pipeline's dedup, correlation, and threshold behavior.

Key	Default	Unit	Meaning
`alerts.dedup_window_seconds`	`300`	seconds	If the same `(tenant, endpoint, platform)` fires again within this window, merge into the existing alert.
`alerts.correlation_window_seconds`	`60`	seconds	If multiple endpoints in the same tenant alert within this window, mark them as `related_endpoints`.
`alerts.min_threshold`	`0.7`	—	Inference results below this `attack_prob` never become alerts, even if `prediction == "attack"`.

`api`

The FastAPI service configuration.

Key	Default	Meaning
`api.host`	`0.0.0.0`	Bind address.
`api.port`	`8080`	Port. Published to host port `8080` by the Compose file.
`api.cors_origins`	`["*"]`	CORS allow-list. Tighten this before exposing the API — see Security Guide: Configuration.

`ttp`

Optional MITRE ATT&CK TTP enrichment service.

Key	Default	Meaning
`ttp.service_url`	`null`	URL of a deployed TTP analyzer. When `null`, alerts have no `ttp_techniques` / `ttp_explanation` populated — everything else still works.

Environment variable overrides

These are set per-service in deploy/docker-compose.yml and override the corresponding YAML keys where they conflict.

Variable	Used by	Overrides	Purpose
`KAFKA_BROKERS`	normalizer, inference, alerts	`kafka.brokers`	Point services at a different Kafka cluster without editing YAML.
`REDIS_HOST`	inference	`redis.host`	Point inference at a different Redis.
`ES_HOST`	dashboard	—	Dashboard's ES URL.
`DISABLE_AUTH`	dashboard	—	`"true"` disables the dashboard's auth layer. Leave enabled only for local development.
`NODE_ENV`	dashboard	—	Standard Node.js env (`production` / `development`).
`OTEL_EXPORTER_OTLP_ENDPOINT`	all services	—	OTLP endpoint for traces/metrics export. Defaults to the in-stack `otel-collector`.
`OTEL_SERVICE_NAME`	all services	—	Service name reported in traces.

Dashboard environment

The dashboard is the only service that does not read service-config.yaml. Its configuration lives entirely in environment variables:

environment:
    ES_HOST: http://elasticsearch:9200
    DISABLE_AUTH: "true"
    NODE_ENV: production

To point the dashboard at a different Elasticsearch cluster, override ES_HOST.

Tuning recipes

These are the questions operators ask most often. Each answer points you at the exact keys to change and names the trade-off.

"I want fewer false positives"

Raise the decision threshold and the alert floor:

inference:
  threshold: 0.85          # was 0.7
alerts:
  min_threshold: 0.85      # was 0.7

[!CAUTION] Higher thresholds also miss low-confidence real attacks. Tune against a labeled dataset if you have one, and review the Dashboard User Guide: Distribution panel to confirm the change had the intended effect.

"I want faster detection"

Shorten the window and the interval:

inference:
  window: 1.0              # was 3.0 (minutes)
  interval: 10.0           # was 30.0 (seconds)

Trade-offs:

Shorter windows contain fewer events, so graphs are smaller and the model has less context — expect more error predictions and worse accuracy on multi-step attacks.
Shorter intervals mean more GNN runs per endpoint per minute — plan for more CPU (or GPU) load.

"My inference service is overloaded on a big fleet"

Two levers:

Leave the Linux idle allow-list enabled (it is on by default):

inference:
  use_idle_allowlist: true

Increase the interval — less frequent, cheaper runs:

inference:
  interval: 60.0

For real scale-out, run multiple inference replicas. Kafka keys events by tenant_id:endpoint_id, so per-endpoint ordering is preserved across replicas. See Daily Operations: Scaling.

"I want to merge alerts more aggressively"

Widen the dedup window:

alerts:
  dedup_window_seconds: 900   # 15 min, was 5 min

[!TIP] An attacker running a long, low-and-slow campaign on a single host will show as one persistent alert rather than many individual events. This is usually what analysts want — just be aware of the effect on your "alerts created per hour" metric.

Applying a config change

After editing deploy/service-config.yaml:

cd deploy/
docker compose --profile services restart inference alerts api

The normalizer does not need a restart for most config keys (it only consumes kafka.*). The dashboard does not read service-config.yaml at all.

Confirm the services came back healthy:

curl http://localhost:8080/health
docker compose logs --tail=50 inference

You should see the service log its loaded configuration at startup.

Next steps

Daily Operations — run Logster day-to-day.
Important Considerations — production hardening checklist.
Model Deployment — swap in retrained model weights.