Skip to content

Latest commit

 

History

History
executable file
·
234 lines (177 loc) · 11.8 KB

README.md

File metadata and controls

executable file
·
234 lines (177 loc) · 11.8 KB
Raw

GitHub Committed Docker Size Docker Pulls GitHub Release GitHub Sponsors

NetAlertX 💻🔍 Network security scanner & notification framework

🐳 Docker hub 📑 Docker guide 🆕 Release notes 📚 All Docs

Note

There is also an experimental 🧪 bare-metal install method available.

📕 Basic Usage

Warning

You will have to run the container on the host network.

docker run -d --rm --network=host \
  -v local/path/config:/app/config \
  -v local/path/db:/app/db \
  -e TZ=Europe/Berlin \
  -e PORT=20211 \
  jokobsk/netalertx:latest
  • The initial scan can take up to 15min (with 50 devices and MQTT). Subsequent ones 3 and 5 minutes so wait that long for all of the scans to run.

Docker environment variables

Variable Description Default
PORT Port of the web interface 20211
LISTEN_ADDR Set the specific IP Address for the listener address for the nginx webserver (web interface). This could be useful when using multiple subnets to hide the web interface from all untrusted networks. 0.0.0.0
TZ Time zone to display stats correctly. Find your time zone here Europe/Berlin
ALWAYS_FRESH_INSTALL Setting ALWAYS_FRESH_INSTALL=true will delete the content of the /db & /config folders. For testing purposes. Can be coupled with watchtower to have an always freshly installed netalertx/-dev image. N/A

Docker paths

Note

See also Backup strategies.

Required Path Description
✅ :/app/config Folder which will contain the app.conf & devices.csv (read about devices.csv) files (see below for details).
✅ :/app/db Folder which will contain the app.db file
:/app/front/log Logs folder useful for debugging if you have issues setting up the container
:/etc/pihole/pihole-FTL.db PiHole's pihole-FTL.db database file. Required if you want to use PiHole DB mapping.
:/etc/pihole/dhcp.leases PiHole's dhcp.leases file. Required if you want to use PiHole dhcp.leases file. This has to be matched with a corresponding DHCPLSS_paths_to_check setting entry (the path in the container must contain pihole)
:/app/front/api A simple API endpoint containing static (but regularly updated) json and other files.
:/app/front/plugins/<plugin>/ignore_plugin Map a file ignore_plugin to ignore a plugin. Plugins can be soft-disabled via settings. More in the Plugin docs.
:/etc/resolv.conf Use a custom resolv.conf file for better name resolution.

Use separate db and config directories, don't nest them.

(If UI is not available) Modify the config (app.conf)

  • The preferred way is to manage the configuration via the Settings section in the UI.
  • You can modify app.conf directly, if needed.
  • If unavailable, the app generates a default app.conf and app.db file on the first run.

⚙ Important settings

These are the most important settings to get at least some output in your Devices screen. Usually, only one approach is used, but you can combine these approaches.

Scan method Setting Description
arp-scan, nmap-scan SCAN_SUBNETS See the documentation on how to setup SUBNETS, VLANs & limitations
PiHole PIHOLE_RUN There are 2 approaches how to get PiHole devices imported. Via the PiHole import (PIHOLE) plugin or DHCP leases (DHCPLSS) plugin. The PIHOLE plugin requires you to map the PiHole database, as mentioned above.
dhcp.leases DHCPLSS_RUN You need to map :/etc/myfiles/dhcp.leases in the docker-compose.yml file if you enable this setting. This path has to be matched with a corresponding DHCPLSS_paths_to_check setting entry (check the DHCPLSS plugin readme for details).

Note

It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.

🧭 Community guides

Use the official installation guides at first and use community content as suplementary material. Open an issue if you'd like to add your link to the list 🙏

Ordered by last update time.

Common issues

💡 Before creating a new issue, please check if a similar issue was already resolved.

⚠ Check also common issues and debugging tips.

Note

You can bulk-update devices via the CSV import method.

📄 docker-compose.yml Examples

Example 1

version: "3"
services:
  netalertx:
    container_name: netalertx
    # use the below line if you want to test the latest dev image
    # image: "jokobsk/netalertx-dev:latest" 
    image: "jokobsk/netalertx:latest"      
    network_mode: "host"        
    restart: unless-stopped
    volumes:
      - local/path/config:/app/config
      - local/path/db:/app/db      
      # (optional) useful for debugging if you have issues setting up the container
      - local/path/logs:/app/front/log
    environment:
      - TZ=Europe/Berlin      
      - PORT=20211

To run the container execute: sudo docker-compose up -d

Example 2

Example by SeimuS.

  netalertx:
    container_name: NetAlertX
    hostname: NetAlertX
    privileged: true
    # use the below line if you want to test the latest dev image
    # image: "jokobsk/netalertx-dev:latest" 
    image: jokobsk/netalertx:latest
    environment:
      - TZ=Europe/Bratislava
    restart: always
    volumes:
      - ./netalertx/db:/app/db
      - ./netalertx/config:/app/config
    network_mode: host

To run the container execute: sudo docker-compose up -d

Example 3

docker-compose.yml

version: "3"
services:
  netalertx:
    container_name: netalertx
    # use the below line if you want to test the latest dev image
    # image: "jokobsk/netalertx-dev:latest" 
    image: "jokobsk/netalertx:latest"      
    network_mode: "host"        
    restart: unless-stopped
    volumes:
      - ${APP_DATA_LOCATION}/netalertx/config:/app/config
      - ${APP_DATA_LOCATION}/netalertx/db/:/app/db/      
      # (optional) useful for debugging if you have issues setting up the container
      - ${LOGS_LOCATION}:/app/front/log
    environment:
      - TZ=${TZ}      
      - PORT=${PORT}

.env file

#GLOBAL PATH VARIABLES

APP_DATA_LOCATION=/path/to/docker_appdata
APP_CONFIG_LOCATION=/path/to/docker_config
LOGS_LOCATION=/path/to/docker_logs

#ENVIRONMENT VARIABLES

TZ=Europe/Paris
PORT=20211

#DEVELOPMENT VARIABLES

DEV_LOCATION=/path/to/local/source/code

To run the container execute: sudo docker-compose --env-file /path/to/.env up

Example 4

Courtesy of pbek. The volume netalertx_db is used by the db directory. The two config files are mounted directly from a local folder to their places in the config folder. You can backup the docker-compose.yaml folder and the docker volumes folder.

  netalertx:
    # use the below line if you want to test the latest dev image
    # image: "jokobsk/netalertx-dev:latest" 
    image: jokobsk/netalertx
    ports:
      - "80:20211/tcp"
    environment:
      - TZ=Europe/Vienna
    networks:
      local:
        ipv4_address: 192.168.1.2
    restart: unless-stopped
    volumes:
      - netalertx_db:/app/db
      - ./netalertx/:/app/config/

🏅 Recognitions

Big thanks to @Macleykun & for help and tips & tricks for Dockerfile(s) and @vladaurosh for Alpine re-base help.

❤ Support me

GitHub Buy Me A Coffee Patreon
  • Bitcoin: 1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM
  • Ethereum: 0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7

📧 Email me at jokob@duck.com if you want to get in touch or if I should add other sponsorship platforms.