liwasc

List, wake and scan nodes in a network.

Overview

liwasc is a high-performance network and port scanner. It can quickly give you a overview of the nodes in your network, the services that run on them and manage their power status.

It can ...

• Scan a network: Using an ARP scan and the mac2vendor database, liwasc can list the nodes in a network, their power status, manufacturer information, IP & MAC addresses and more metadata
• Scan a node: Using a high-performance custom TCP and UDP port scanner, liwasc can list the ports and services of a node and provide metadata (service names, registration dates etc.) using the Service Name and Transport Protocol Port Number Registry
• Power on a node: By sending Wake-on-LAN packets, liwasc can turn on nodes in a network
• Periodically scan a network: Using the integrated periodic scans feature, liwasc can periodically (based on a CRON syntax) scan a network and persist the results in a database
• Give remote insight into a network: Because liwasc is based on open web technologies, has a gRPC API and supports OpenID Connect authentication, liwasc can be securely exposed to the public internet and serve as a remote controller for a network

Installation

Containerized

You can get the Docker container like so:

$ docker pull pojntfx/liwasc-backend

Natively

If you prefer a native installation, static binaries are also available on GitHub releases.

You can install them like so:

$ curl -L -o /tmp/liwasc-backend https://github.com/pojntfx/liwasc/releases/latest/download/liwasc-backend.linux-$(uname -m)
$ sudo install /tmp/liwasc-backend /usr/local/bin
$ sudo setcap cap_net_raw+ep /usr/local/bin/liwasc-backend # This allows rootless execution

About the Frontend

The frontend is also available on GitHub releases in the form of a static .tar.gz archive; to deploy it, simply upload it to a CDN or copy it to a web server. For most users, this shouldn't be necessary though; thanks to @maxence-charriere's go-app package, liwasc is a progressive web app. By simply visiting the public deployment once, it will be available for offline use whenever you need it.

Usage

1. Setting up Authentication

liwasc uses OpenID Connect for authentication, which means you can use almost any authentication provider, both self-hosted and as a service, that you want to. We've created a short tutorial video which shows how to set up Auth0 for this purpose, but feel free to use something like Ory if you prefer a self-hosted solution:

2. (Option 1): Starting the Backend (Containerized)

Using Docker (or an alternative like Podman), you can easily start & configure the backend; see the Reference for more configuration parameters:

$ docker run \
    --name liwasc-backend \
    -d \
    --restart always \
    --net host \
    --cap-add NET_RAW \
    --ulimit nofile=16384:16384 \
    -v ${HOME}/.local/share/liwasc:/root/.local/share/liwasc:z \
    -e LIWASC_BACKEND_OIDCISSUER=https://pojntfx.eu.auth0.com/ \
    -e LIWASC_BACKEND_OIDCCLIENTID=myoidcclientid \
    -e LIWASC_BACKEND_DEVICENAME=eth0 \
    pojntfx/liwasc-backend

You can get the logs like so:

$ docker logs liwasc-backend

2. (Option 2): Starting the Backend (Natively)

If you prefer a native setup, you can also do a more traditional setup.

First, set up a config file at ~/.local/share/liwasc/etc/liwasc/liwasc-backend-config.yaml; see the Reference for more configuration parameters:

$ mkdir -p ~/.local/share/liwasc/etc/liwasc/
$ cat <<EOT >~/.local/share/liwasc/etc/liwasc/liwasc-backend-config.yaml
oidcIssuer: https://pojntfx.eu.auth0.com/
oidcClientID: myoidcclientid
deviceName: eth0
EOT

Now, create a systemd service for it:

$ mkdir -p ~/.config/systemd/user/
$ cat <<EOT >~/.config/systemd/user/liwasc-backend.service
[Unit]
Description=liwasc

[Service]
ExecStart=/usr/local/bin/liwasc-backend -c \${HOME}/.local/share/liwasc/etc/liwasc/liwasc-backend-config.yaml
LimitNOFILE=16384:16384

[Install]
WantedBy=multi-user.target
EOT

Finally, reload systemd and enable the service:

$ systemctl --user daemon-reload
$ systemctl --user enable --now liwasc-backend

You can get the logs like so:

$ journalctl --user -u liwasc-backend

3. Connecting the Frontend

Now that the backend is running, head over to https://pojntfx.github.io/liwasc/:

Alternatively, as described in About the Frontend, you can also choose to self-host. Once you're on the page, you should be presented with the following setup page:

You'll have to enter your own information here; the Backend URL is the URL on which the backend runs, the OIDC Issuer, Client ID and Redirect URL are the same values that you've set the backend up with above.

Finally, click on Login, and if everything worked out fine you should be presented with the initial launch screen:

🚀 That's it! We hope you enjoy using liwasc.

Reference

Command Line Arguments

$ liwasc-backend --help
liwasc is a high-performance network and port scanner. It can quickly give you a overview of the nodes in your network, the services that run on them and manage their power status.

For more information, please visit https://github.com/pojntfx/liwasc.

Usage:
  liwasc-backend [flags]

Flags:
  -c, --configFile string                            Config file to use
  -d, --deviceName string                            Network device name (default "eth0")
  -h, --help                                         help for liwasc-backend
  -l, --listenAddress string                         Listen address (default "localhost:15123")
      --mac2vendorDatabasePath string                Path to the mac2vendor database (default "/home/pojntfx/.local/share/liwasc/etc/liwasc/oui-database.sqlite")
      --mac2vendorDatabaseURL string                 URL to the mac2vendor database; will be downloaded on the first run if it doesn't exist (default "https://mac2vendor.com/download/oui-database.sqlite")
  -u, --maxConcurrentPortScans int                   Maximum concurrent port scans. Be sure to set this value to something lower than the systems ulimit or increase the latter (default 100)
      --nodeAndPortScanDatabasePath string           Path to the node and port scan database (default "/home/pojntfx/.local/share/liwasc/var/lib/liwasc/node_and_port_scan.sqlite")
      --nodeWakeDatabasePath string                  Path to the node wake database (default "/home/pojntfx/.local/share/liwasc/var/lib/liwasc/node_wake.sqlite")
  -t, --oidcClientID string                          OIDC client ID (default "myoidcclientid")
  -i, --oidcIssuer string                            OIDC issuer (default "https://pojntfx.eu.auth0.com/")
  -n, --periodicNodeScanTimeout int                  Time in milliseconds to wait for all nodes in a network to respond in the periodic node scans (default 500)
  -p, --periodicPortScanTimeout int                  Time in milliseconds to wait for a response per port in the periodic port scans (default 10)
  -e, --periodicScanCronExpression string            Cron expression for the periodic network scans & node scans. The default value will run a network & node scan every ten minutes. See https://pkg.go.dev/github.com/robfig/cron for more information (default "*/10 * * * *")
      --ports2PacketsDatabasePath string             Path to the ports2packets database (default "/home/pojntfx/.local/share/liwasc/etc/liwasc/ports2packets.csv")
      --ports2PacketsDatabaseURL string              URL to the ports2packets database; will be downloaded on the first run if it doesn't exist (default "https://github.com/pojntfx/ports2packets/releases/download/weekly-csv/ports2packets.csv")
  -o, --prepareOnly                                  Only download external databases & prepare them, then exit
      --serviceNamesPortNumbersDatabasePath string   Path to the CSV input file containing the registered services (default "/home/pojntfx/.local/share/liwasc/etc/liwasc/service-names-port-numbers.csv")
      --serviceNamesPortNumbersDatabaseURL string    URL to the CSV input file containing the registered services; will be downloaded on the first run if it doesn't exist (default "https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.csv")
  -w, --webSocketListenAddress string                Listen address (for the WebSocket proxy) (default "localhost:15124")

Environment Variables

All command line arguments described above can also be set using environment variables; for example, to set --deviceName to tap0 with an environment variable, use LIWASC_BACKEND_DEVICENAME=tap0.

Configuration File

Just like with the environment variables, liwasc can also be configured using a configuration file; see examples/liwasc-backend-config.yaml for an example configuration file.

gRPC API

liwasc exposes a full-featured streaming gRPC and gRPC-Web API, which is also used internally to connect the front- and backend. You can find the relevant .proto files in api/proto/v1; send the OpenID Connect token with the X-Liwasc-Authorization metadata key.

Acknowledgements

• This project would not have been possible were it not for @maxence-charriere's go-app package; if you enjoy using liwasc, please donate to him!
• The open source PatternFly design system provides a professional design and reduced the need for custom CSS to a minimium (less than 50 SLOC!).
• The mac2vendor database is an awesome resource for OUI database lookups and is used to provide node metadata in liwasc.
• UDP packets for status checks have been extracted from nmap using ports2packets, which allows liwasc to provide it's UDP port scans.
• All the rest of the authors who worked on the dependencies used! Thanks a lot!

Contributing

To contribute, please use the GitHub flow and follow our Code of Conduct.

To build and start a development version of liwasc locally, run the following:

$ git clone https://github.com/pojntfx/liwasc.git
$ cd liwasc
$ make depend
$ LIWASC_BACKEND_OIDCISSUER=https://pojntfx.eu.auth0.com/ LIWASC_BACKEND_OIDCCLIENTID=myoidcclientid LIWASC_BACKEND_DEVICENAME=eth0 make dev

The backend should now be started and the frontend be available on http://localhost:15125/. Whenever you change a source file, the back- and frontend will automatically be re-compiled.

Have any questions or need help? Chat with us on Matrix!

Related Projects

If you want to have a modern network boot server to provision the nodes managed by liwasc, check out bofied!

License

liwasc (c) 2021 Felicitas Pojtinger and contributors

SPDX-License-Identifier: AGPL-3.0