matijag/fortag repository overview

⁠Fortag Network Scanner 1.0.17

Fortag ((https://github.com/matijag/fortag-home-assistant/⁠)) is a lightweight network security scanner that discovers local devices, tracks open ports, and publishes its state and security alerts over MQTT for the Fortag Home Assistant integration.

⁠What’s new

• Tracks which devices were present during the latest completed scan.
• Supports Home Assistant’s current-host and all-known-host views.
• Publishes scanner version, MQTT API version, and SQLite schema version.
• Publishes existing database state immediately at startup, before beginning a potentially long scan.
• Adds transactional SQLite schema versioning using PRAGMA user_version.
• Safely upgrades existing unversioned databases to schema version 1.
• Preserves existing host, port, acknowledgement, and detection-history data.
• Rejects databases created by a newer unsupported scanner version.
• Improves scan-loop error handling and security-alert publication.
• Includes Go 1.26.5 tooling updates.

⁠Home Assistant compatibility

Scanner 1.0.17 is the recommended backend for Fortag Home Assistant integration 1.1.0.

The scanner and Home Assistant communicate through MQTT API version 1.

⁠Available tags

• matijag/fortag:1.0.17 — immutable stable release
• matijag/fortag:1.0 — latest stable 1.0 release
• matijag/fortag:latest — current stable release
• matijag/fortag:beta — opt-in beta channel

Supported platforms:

• linux/amd64
• linux/arm64

⁠Running the scanner

Fortag requires host networking for local Layer 2 discovery and a persistent directory for its SQLite database.

Create an environment file such as fortag.env:

MQTT_USER= MQTT_PASSWORD=

Protect it:

chmod 600 fortag.env

Run the container:

  docker run -d \
    --name fortag-scanner \
    --restart unless-stopped \
    --network host \
    --env-file fortag.env \
    -v /path/to/fortag/data:/app/data \
    matijag/fortag:1.0.17 \
    -db /app/data/scanner.db \
    -mqtt tcp://YOUR_MQTT_BROKER:1883

To specify the network explicitly:

  docker run -d \
    --name fortag-scanner \
    --restart unless-stopped \
    --network host \
    --env-file fortag.env \
    -v /path/to/fortag/data:/app/data \
    matijag/fortag:1.0.17 \
    -db /app/data/scanner.db \
    -mqtt tcp://YOUR_MQTT_BROKER:1883 \
    -range 192.168.1.0/24

⁠Upgrade from an earlier release

Pull the stable image:

  docker pull matijag/fortag:1.0.17

Stop and remove the old container, preserving its mounted data directory, then recreate it using the same database mount and MQTT configuration.

At startup, Fortag upgrades an existing unversioned database transactionally before publishing state or starting a scan. Back up the SQLite database before upgrading as a general precaution.

⁠MQTT topics

Published by the scanner:

fortag/scanner/state fortag/scanner/progress fortag/scanner/alert

Commands consumed by the scanner:

fortag/scanner/command/scan_now fortag/scanner/command/rename fortag/scanner/command/acknowledge fortag/scanner/command/set_range

The state topic is retained so Home Assistant receives the latest database state immediately after subscribing.