{"id":13832013,"url":"https://github.com/pojntfx/liwasc","last_synced_at":"2025-07-09T15:34:23.308Z","repository":{"id":45715345,"uuid":"294105748","full_name":"pojntfx/liwasc","owner":"pojntfx","description":"List, wake and scan nodes in a network.","archived":true,"fork":false,"pushed_at":"2023-02-26T04:46:38.000Z","size":154857,"stargazers_count":161,"open_issues_count":1,"forks_count":16,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-08-05T10:19:47.685Z","etag":null,"topics":["arp","arp-scanner","go","golang","iana","ip-scanner","liwasc","network","network-scanner","port-scanner","ports2packets","service-name","vendor2mac","wake-on-lan","wol"],"latest_commit_sha":null,"homepage":"http://pojntfx.github.io/liwasc/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pojntfx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-09-09T12:26:00.000Z","updated_at":"2024-06-29T12:42:30.000Z","dependencies_parsed_at":"2024-01-15T15:46:05.073Z","dependency_job_id":"357f464a-e2cc-44e0-bd28-7150c4bfd800","html_url":"https://github.com/pojntfx/liwasc","commit_stats":null,"previous_names":["pojntfx/wascan"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fliwasc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fliwasc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fliwasc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pojntfx%2Fliwasc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pojntfx","download_url":"https://codeload.github.com/pojntfx/liwasc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225565964,"owners_count":17489290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arp","arp-scanner","go","golang","iana","ip-scanner","liwasc","network","network-scanner","port-scanner","ports2packets","service-name","vendor2mac","wake-on-lan","wol"],"created_at":"2024-08-04T10:01:47.658Z","updated_at":"2024-11-20T13:32:22.058Z","avatar_url":"https://github.com/pojntfx.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# liwasc\n\n[![liwasc demo video](./assets/demo.webp)](https://pojntfx.github.io/liwasc/)\n\nList, wake and scan nodes in a network.\n\n[![hydrun CI](https://github.com/pojntfx/liwasc/actions/workflows/hydrun.yaml/badge.svg)](https://github.com/pojntfx/liwasc/actions/workflows/hydrun.yaml)\n[![Docker CI](https://github.com/pojntfx/liwasc/actions/workflows/docker.yaml/badge.svg)](https://github.com/pojntfx/liwasc/actions/workflows/docker.yaml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/pojntfx/liwasc.svg)](https://pkg.go.dev/github.com/pojntfx/liwasc)\n[![Matrix](https://img.shields.io/matrix/liwasc:matrix.org)](https://matrix.to/#/#liwasc:matrix.org?via=matrix.org)\n[![Docker Pulls](https://img.shields.io/docker/pulls/pojntfx/liwasc-backend?label=docker%20pulls)](https://hub.docker.com/r/pojntfx/liwasc-backend)\n[![Binary Downloads](https://img.shields.io/github/downloads/pojntfx/liwasc/total?label=binary%20downloads)](https://github.com/pojntfx/liwasc/releases)\n\n## Overview\n\nliwasc 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.\n\nIt can ...\n\n- **Scan a network**: Using an ARP scan and the [mac2vendor](https://mac2vendor.com/) database, liwasc can list the nodes in a network, their power status, manufacturer information, IP \u0026 MAC addresses and more metadata\n- **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](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml)\n- **Power on a node**: By sending [Wake-on-LAN packets](https://en.wikipedia.org/wiki/Wake-on-LAN), liwasc can turn on nodes in a network\n- **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\n- **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\n\n## Installation\n\n### Containerized\n\nYou can get the Docker container like so:\n\n```shell\n$ docker pull pojntfx/liwasc-backend\n```\n\n### Natively\n\nIf you prefer a native installation, static binaries are also available on [GitHub releases](https://github.com/pojntfx/liwasc/releases).\n\nYou can install them like so:\n\n```shell\n$ curl -L -o /tmp/liwasc-backend https://github.com/pojntfx/liwasc/releases/latest/download/liwasc-backend.linux-$(uname -m)\n$ sudo install /tmp/liwasc-backend /usr/local/bin\n$ sudo setcap cap_net_raw+ep /usr/local/bin/liwasc-backend # This allows rootless execution\n```\n\n### About the Frontend\n\nThe frontend is also available on [GitHub releases](https://github.com/pojntfx/liwasc/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](https://github.com/maxence-charriere)'s [go-app package](https://go-app.dev/), liwasc is a progressive web app. By simply visiting the [public deployment](https://pojntfx.github.io/liwasc/) once, it will be available for offline use whenever you need it.\n\n[\u003cimg src=\"https://github.com/alphahorizonio/webnetesctl/raw/main/img/launch.png\" width=\"240\"\u003e](https://pojntfx.github.io/liwasc/)\n\n## Usage\n\n### 1. Setting up Authentication\n\nliwasc uses [OpenID Connect](https://en.wikipedia.org/wiki/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](https://auth0.com/) for this purpose, but feel free to use something like [Ory](https://github.com/ory/hydra) if you prefer a self-hosted solution:\n\n[\u003cimg src=\"https://img.youtube.com/vi/N3cocCOsrGw/0.jpg\" width=\"256\" alt=\"Setting up OpenID Connect for Internal Apps YouTube Video\" title=\"Setting up OpenID Connect for Internal Apps YouTube Video\"\u003e](https://www.youtube.com/watch?v=N3cocCOsrGw)\n\n### 2. (Option 1): Starting the Backend (Containerized)\n\nUsing Docker (or an alternative like Podman), you can easily start \u0026 configure the backend; see the [Reference](#reference) for more configuration parameters:\n\n```shell\n$ docker run \\\n    --name liwasc-backend \\\n    -d \\\n    --restart always \\\n    --net host \\\n    --cap-add NET_RAW \\\n    --ulimit nofile=16384:16384 \\\n    -v ${HOME}/.local/share/liwasc:/root/.local/share/liwasc:z \\\n    -e LIWASC_BACKEND_OIDCISSUER=https://pojntfx.eu.auth0.com/ \\\n    -e LIWASC_BACKEND_OIDCCLIENTID=myoidcclientid \\\n    -e LIWASC_BACKEND_DEVICENAME=eth0 \\\n    pojntfx/liwasc-backend\n```\n\nYou can get the logs like so:\n\n```shell\n$ docker logs liwasc-backend\n```\n\n### 2. (Option 2): Starting the Backend (Natively)\n\nIf you prefer a native setup, you can also do a more traditional setup.\n\nFirst, set up a config file at `~/.local/share/liwasc/etc/liwasc/liwasc-backend-config.yaml`; see the [Reference](#reference) for more configuration parameters:\n\n```shell\n$ mkdir -p ~/.local/share/liwasc/etc/liwasc/\n$ cat \u003c\u003cEOT \u003e~/.local/share/liwasc/etc/liwasc/liwasc-backend-config.yaml\noidcIssuer: https://pojntfx.eu.auth0.com/\noidcClientID: myoidcclientid\ndeviceName: eth0\nEOT\n```\n\nNow, create a systemd service for it:\n\n```shell\n$ mkdir -p ~/.config/systemd/user/\n$ cat \u003c\u003cEOT \u003e~/.config/systemd/user/liwasc-backend.service\n[Unit]\nDescription=liwasc\n\n[Service]\nExecStart=/usr/local/bin/liwasc-backend -c \\${HOME}/.local/share/liwasc/etc/liwasc/liwasc-backend-config.yaml\nLimitNOFILE=16384:16384\n\n[Install]\nWantedBy=multi-user.target\nEOT\n```\n\nFinally, reload systemd and enable the service:\n\n```shell\n$ systemctl --user daemon-reload\n$ systemctl --user enable --now liwasc-backend\n```\n\nYou can get the logs like so:\n\n```shell\n$ journalctl --user -u liwasc-backend\n```\n\n### 3. Connecting the Frontend\n\nNow that the backend is running, head over to [https://pojntfx.github.io/liwasc/](https://pojntfx.github.io/liwasc/):\n\n[\u003cimg src=\"https://github.com/alphahorizonio/webnetesctl/raw/main/img/launch.png\" width=\"240\"\u003e](https://pojntfx.github.io/liwasc/)\n\nAlternatively, as described in [About the Frontend](#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:\n\n![Setup page](./assets/setup.png)\n\nYou'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.\n\nFinally, click on `Login`, and if everything worked out fine you should be presented with the initial launch screen:\n\n![Initial page](./assets/initial.png)\n\n🚀 **That's it**! We hope you enjoy using liwasc.\n\n## Reference\n\n### Command Line Arguments\n\n```shell\n$ liwasc-backend --help\nliwasc 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.\n\nFor more information, please visit https://github.com/pojntfx/liwasc.\n\nUsage:\n  liwasc-backend [flags]\n\nFlags:\n  -c, --configFile string                            Config file to use\n  -d, --deviceName string                            Network device name (default \"eth0\")\n  -h, --help                                         help for liwasc-backend\n  -l, --listenAddress string                         Listen address (default \"localhost:15123\")\n      --mac2vendorDatabasePath string                Path to the mac2vendor database (default \"/home/pojntfx/.local/share/liwasc/etc/liwasc/oui-database.sqlite\")\n      --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\")\n  -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)\n      --nodeAndPortScanDatabasePath string           Path to the node and port scan database (default \"/home/pojntfx/.local/share/liwasc/var/lib/liwasc/node_and_port_scan.sqlite\")\n      --nodeWakeDatabasePath string                  Path to the node wake database (default \"/home/pojntfx/.local/share/liwasc/var/lib/liwasc/node_wake.sqlite\")\n  -t, --oidcClientID string                          OIDC client ID (default \"myoidcclientid\")\n  -i, --oidcIssuer string                            OIDC issuer (default \"https://pojntfx.eu.auth0.com/\")\n  -n, --periodicNodeScanTimeout int                  Time in milliseconds to wait for all nodes in a network to respond in the periodic node scans (default 500)\n  -p, --periodicPortScanTimeout int                  Time in milliseconds to wait for a response per port in the periodic port scans (default 10)\n  -e, --periodicScanCronExpression string            Cron expression for the periodic network scans \u0026 node scans. The default value will run a network \u0026 node scan every ten minutes. See https://pkg.go.dev/github.com/robfig/cron for more information (default \"*/10 * * * *\")\n      --ports2PacketsDatabasePath string             Path to the ports2packets database (default \"/home/pojntfx/.local/share/liwasc/etc/liwasc/ports2packets.csv\")\n      --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\")\n  -o, --prepareOnly                                  Only download external databases \u0026 prepare them, then exit\n      --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\")\n      --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\")\n  -w, --webSocketListenAddress string                Listen address (for the WebSocket proxy) (default \"localhost:15124\")\n```\n\n### Environment Variables\n\nAll 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`.\n\n### Configuration File\n\nJust like with the environment variables, liwasc can also be configured using a configuration file; see [examples/liwasc-backend-config.yaml](./examples/liwasc-backend-config.yaml) for an example configuration file.\n\n### gRPC API\n\nliwasc 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](./api/proto/v1); send the OpenID Connect token with the `X-Liwasc-Authorization` metadata key.\n\n## Acknowledgements\n\n- This project would not have been possible were it not for [@maxence-charriere](https://github.com/maxence-charriere)'s [go-app package](https://go-app.dev/); if you enjoy using liwasc, please donate to him!\n- The open source [PatternFly design system](https://www.patternfly.org/v4/) provides a professional design and reduced the need for custom CSS to a minimium (less than 50 SLOC!).\n- The [mac2vendor database](https://mac2vendor.com/) is an awesome resource for OUI database lookups and is used to provide node metadata in liwasc.\n- UDP packets for status checks have been extracted from [nmap](https://nmap.org/) using [ports2packets](https://github.com/pojntfx/ports2packets), which allows liwasc to provide it's UDP port scans.\n- All the rest of the authors who worked on the dependencies used! Thanks a lot!\n\n## Contributing\n\nTo contribute, please use the [GitHub flow](https://guides.github.com/introduction/flow/) and follow our [Code of Conduct](./CODE_OF_CONDUCT.md).\n\nTo build and start a development version of liwasc locally, run the following:\n\n```shell\n$ git clone https://github.com/pojntfx/liwasc.git\n$ cd liwasc\n$ make depend\n$ LIWASC_BACKEND_OIDCISSUER=https://pojntfx.eu.auth0.com/ LIWASC_BACKEND_OIDCCLIENTID=myoidcclientid LIWASC_BACKEND_DEVICENAME=eth0 make dev\n```\n\nThe backend should now be started and the frontend be available on [http://localhost:15125/](http://localhost:15125/). Whenever you change a source file, the back- and frontend will automatically be re-compiled.\n\nHave any questions or need help? Chat with us [on Matrix](https://matrix.to/#/#liwasc:matrix.org?via=matrix.org)!\n\n## Related Projects\n\nIf you want to have a modern network boot server to provision the nodes managed by liwasc, check out [bofied](https://github.com/pojntfx/bofied)!\n\n## License\n\nliwasc (c) 2021 Felicitas Pojtinger and contributors\n\nSPDX-License-Identifier: AGPL-3.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpojntfx%2Fliwasc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpojntfx%2Fliwasc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpojntfx%2Fliwasc/lists"}