https://github.com/pojntfx/liwasc Skip to content Sign up Sign up * Why GitHub? Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Project management - + Integrations - + GitHub Sponsors - + Customer stories- * Team * Enterprise * Explore + Explore GitHub - Learn and contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing Plans - + Compare plans - + Contact Sales - + Education - [ ] [search-key] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up Sign up {{ message }} pojntfx / liwasc * Notifications * Star 11 * Fork 1 List, wake and scan nodes in a network. pojntfx.github.io/liwasc/ AGPL-3.0 License 11 stars 1 fork Star Notifications * Code * Issues 0 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights main Switch branches/tags [ ] Branches Tags Nothing to show {{ refName }} default View all branches Nothing to show {{ refName }} default View all tags 2 branches 1 tag Go to file Code Clone HTTPS GitHub CLI [https://github.com/p] Use Git or checkout with SVN using the web URL. [gh repo clone pojntf] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio If nothing happens, download the GitHub extension for Visual Studio and try again. Go back Latest commit @pojntfx pojntfx docs: Add contribution guide ... f765b00 Apr 12, 2021 docs: Add contribution guide f765b00 Git stats * 386 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github/workflows feat: Add Docker CI Apr 11, 2021 api/proto/v1 refactor: Version API and clarify role of migrations Apr 10, 2021 assets docs: Add notes on connecting the frontend Apr 12, 2021 cmd feat: Add native usage instructions Apr 12, 2021 configs refactor: Prefix configuration files for sql-migrate and sqlboiler Apr 11, 2021 db/sqlite/migrations refactor: Properly prefix generated db bindings Apr 11, 2021 examples feat: Add native usage instructions Apr 12, 2021 pkg refactor: Prefix generated database models to distinguish them from e... Apr 12, 2021 web feat: Start port inspector implementation Apr 2, 2021 .gitignore refactor: Prefix configuration files for sql-migrate and sqlboiler Apr 11, 2021 CODE_OF_CONDUCT.md docs: Add CoC Mar 13, 2021 Dockerfile feat: Add Docker CI Apr 11, 2021 Hydrunfile build: Handle GH pages release build in frontend hydrun target Mar 13, 2021 LICENSE docs: Add license Sep 9, 2020 Makefile refactor: Use bindata instead of packr for embedded migrations Apr 12, 2021 README.md docs: Add contribution guide Apr 12, 2021 go.mod refactor: Use bindata instead of packr for embedded migrations Apr 12, 2021 go.sum refactor: Prefix generated database models to distinguish them from e... Apr 12, 2021 View code liwasc Overview Installation Containerized Natively About the Frontend Usage Setting up Authentication Starting the Backend (Containerized) Starting the Backend (Natively) Connecting the Frontend Reference Command Line Arguments Environment Variables Configuration File gRPC API Acknowledgements Contributing License README.md liwasc liwasc demo video List, wake and scan nodes in a network. hydrun CI Docker CI Go Reference Matrix 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/download/latest/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 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: Setting up OpenID Connect for Internal Apps YouTube Video 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 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 <~/.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 <~/.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 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: 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: Initial page 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! License liwasc (c) 2021 Felix Pojtinger and contributors SPDX-License-Identifier: AGPL-3.0 About List, wake and scan nodes in a network. pojntfx.github.io/liwasc/ Topics go golang network iana arp port-scanner wake-on-lan network-scanner arp-scanner wol ip-scanner ports2packets liwasc vendor2mac service-name Resources Readme License AGPL-3.0 License Releases 1 latest Latest Apr 12, 2021 Packages 0 No packages published Languages * Go 97.5% * Makefile 1.5% * Other 1.0% * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.