List, wake and scan nodes in a network.
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
You can get the Docker container like so:
$ docker pull pojntfx/liwasc-backendIf 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 executionThe 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.
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:
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-backendYou can get the logs like so:
$ docker logs liwasc-backendIf 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
EOTNow, 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
EOTFinally, reload systemd and enable the service:
$ systemctl --user daemon-reload
$ systemctl --user enable --now liwasc-backendYou can get the logs like so:
$ journalctl --user -u liwasc-backendNow 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.
$ 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")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.
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.
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.
- 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!
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 devThe 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!
If you want to have a modern network boot server to provision the nodes managed by liwasc, check out bofied!
liwasc (c) 2021 Felicitas Pojtinger and contributors
SPDX-License-Identifier: AGPL-3.0