{"id":19909000,"url":"https://github.com/dyne/dowse","last_synced_at":"2025-04-04T15:06:54.488Z","repository":{"id":9754479,"uuid":"11719971","full_name":"dyne/dowse","owner":"dyne","description":"The Awareness Hub for the Internet of Things","archived":false,"fork":false,"pushed_at":"2024-11-05T13:21:49.000Z","size":39033,"stargazers_count":165,"open_issues_count":8,"forks_count":18,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-03-28T14:06:36.123Z","etag":null,"topics":["dhcp","dns","dnscrypt","dyne","internet","lan","router"],"latest_commit_sha":null,"homepage":"http://dyne.org/dowse/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dyne.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["dyne"],"ko-fi":"dyneorg"}},"created_at":"2013-07-28T13:19:39.000Z","updated_at":"2025-03-13T12:53:56.000Z","dependencies_parsed_at":"2024-05-06T09:41:47.922Z","dependency_job_id":"b3169c65-c60f-43cf-8e92-6b0ab7ca1c05","html_url":"https://github.com/dyne/dowse","commit_stats":{"total_commits":1219,"total_committers":9,"mean_commits":"135.44444444444446","dds":0.5406070549630845,"last_synced_commit":"35c94a6dfef6e4b6d873a5532e07c725940cb1de"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dyne%2Fdowse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dyne%2Fdowse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dyne%2Fdowse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dyne%2Fdowse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dyne","download_url":"https://codeload.github.com/dyne/dowse/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198449,"owners_count":20900079,"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":["dhcp","dns","dnscrypt","dyne","internet","lan","router"],"created_at":"2024-11-12T21:14:08.476Z","updated_at":"2025-04-04T15:06:54.464Z","avatar_url":"https://github.com/dyne.png","language":"C","funding_links":["https://github.com/sponsors/dyne","dyneorg"],"categories":[],"sub_categories":[],"readme":"[![Dowse logo](http://dowse.equipment/dowse-logo.png)](http://dowse.eu)\n\nA digital rod for local area network rabdomancy\n\n[![software by Dyne.org](https://www.dyne.org/wp-content/uploads/2015/12/software_by_dyne.png)](https://www.dyne.org)\n\nUpdates: http://dowse.eu\n\nWhitepaper: https://files.dyne.org/dowse/dowse_whitepaper.pdf\n\n\n[![Build Status](https://api.travis-ci.org/dyne/dowse.svg)](https://travis-ci.org/dyne/dowse)\n\n[![Dowse project stats](https://www.openhub.net/p/dowse/widgets/project_thin_badge.gif)](https://www.openhub.net/p/dowse)\n\n# Introduction\n\nDowse is a **transparent proxy** facilitating the awareness of ingoing\nand outgoing connections, from, to, and within a local area network.\n\nDowse provides a **central point of soft control for all local\ntraffic**: from ARP traffic (layer 2) to TCP/IP (layers 3 and 4) as\nwell as application space, by chaining a firewall setup to a\ntrasparent proxy setup. A core feature for Dowse is that of **hiding\nall the complexity** of such a setup.\n\nDowse is also a **highly extensible platform**: interoperability\nbetween modules is available using Socks4/5, UNIX pipes, local TCP/IP\nsockets and port redirection, conforming to specific daemon\nimplementations. At the core of Dowse is a very portable shell script\ncodebase implementing a modular plugin architecture that isolates\nprocesses and supports any executable written in any language: Shell,\nC, Perl, Python etc.\n\nDowse is an ongoing development effort rapidly gaining momentum for\nits simplicity and usefulness. Here a recent backstage video:\n\n[![The making of Dowse](https://img.youtube.com/vi/wDLyYk_TQtI/0.jpg)](https://www.youtube.com/watch?v=wDLyYk_TQtI)\n\n# Features\n\n  Dowse takes control of a LAN by becoming its DHCP server and thereby\n  assigning itself as main gateway and DNS server for all clients. It\n  keeps tracks of assigned leases by MAC Address. ISC DHCP\n  and DNSCRYPT-PROXY are used as daemons.\n\n  All network traffic is passed through NAT rules for masquerading.\n  HTTP traffic (TCP port 80) can be filtered through a transparent\n  proxy using an application layer chain of Squid2 and Privoxy.\n\n  All IP traffic is filtered using configurable blocklists to keep out\n  malware, spyware and known bad peers, using Peerguardian2 and Iptables.\n\n  All DNS traffic (UDP port 53) is filtered through a DNSCRYPT-PROXY\n  plugin encrypting all traffic (AES/SHA256) and analysed using\n  domain-list to render a graphical representation of traffic.\n\n  Privilege escalation is managed using https://sup.dyne.org\n  \n# Installation\n\nInstallation and activation takes a few steps, only `make install` needs root:\n\n1. Download dowse on a GNU/Linux box (we use Devuan Ascii)\n\n```\ngit clone https://github.com/dyne/dowse dowse-src\ncd dowse-src \u0026\u0026 git submodule update --init --recursive\n```\n\n2. Install all requirements, here below the list of packages. To avoid installing\n   more than needed, consider using the `--no-install-recommends` flag in APT or\n   similar for other package managers.\n\n```\nzsh iptables build-essential autoconf automake libhiredis-dev libkmod-dev libjemalloc-dev pkg-config libtool libltdl-dev libsodium-dev libldns-dev libnetfilter-queue-dev uuid-dev zlib1g-dev cmake liblo-dev nmap python3-flask python3-redis xmlstarlet wget libcap2-bin\n```\n\n3. Choose which user should be running dowse: your own is fine, or\n   eventually create one just for that to separate filesystem\n   permissions.\n\n4. As the user of choice, run `make` inside the dowse source\n\n5. As root, run `make install`\n\n6. If necessary edit the files in the `/etc/dowse` folder, especially\n   `settings` where it should be indicated the address for the local\n   network you like to create.\n\n7. As the dowse user of choice and inside the source, fire up the\n   startup script `./start.sh`\n\nDowse is now running with a web interface on port 80.\n\nTo interact with dowse there is also a console with commands prefixed\nwith `dowse-` (tab completion available). To enter it run zsh without\nextensions and source the main script: first type `zsh -f` and press\nenter, then type `source /usr/local/dowse/zshrc` and press enter.\n\nIf you like the dowse user to have an interactive console every time\nit logs in, then do `ln -s /usr/local/dowse/zshrc $HOME/.zshrc`.\n\nIf all went well now one should be able to connect any device to the\ninternet as you did before, via Dowse.\n\n## Embedded ARM devices\n\nUsing https://www.devuan.org just compile and install Dowse following\nthe procedure above. Images are available for a several popular ARM\ndevices including RaspberryPI2 and 3, BananaPI, Cubieboard etc.\n\n# Starting Dowse\n\nHere below an example start script launching all services in\nDowse. Some can be commented / expunged ad-hoc depending from use\ncases, since the only vital functions are `redis-server`, `dhcpd` and\n`dnscrypt-proxy`.\n\n```zsh\n#/usr/bin/env zsh\n\nsource /etc/dowse/settings\nsource /usr/local/dowse/zshrc\n\n    notice \"Starting Dowse\"\n\n    # start the redis daemon (core k/v service)\n    start redis-server\n\n\tnotice \"Starting all daemons in Dowse\"\n\n    # launch the dhcp daemon\n    start dhcpd\n\n    # start the dns encrypted tunneling\n    start dnscrypt-proxy\n\n\t# start the mqtt/websocket hub\n\tstart mosquitto\n\n    # netdata dashboard for the technical status\n    start netdata\n\n\t# nodejs/node-red\n\tstart node-red\n\n\t# start the cronjob handler (with resolution to seconds)\n\tstart seccrond\n\n    notice \"Dowse succesfully started\"\n\n}\n```\n\nAdding the following line one can set up an open network, what we call it \"party\nmode\":\n\n```\necho \"set party-mode ON\" | redis-cli\n```\n\nAs a good practice, such a script can be launched from `/etc/rc.local` for user\ndowse using `setuidgid` from the `daemontools` package.\n\nThe next is an example on how to stop dowse, for instance from a stop.sh script:\n\n```zsh\n#/usr/bin/env zsh\n\nsource /usr/local/dowse/zshrc\n\n\tnotice \"Stopping all daemons in Dowse\"\n\n\tstop seccrond\n\n\tstop mosquitto\n\n\t# stop nodejs/node-red\n\tstop node-red\n\n    # stop the dashboard\n    stop netdata\n\n    # stop the dns crypto tunnel\n    stop dnscrypt-proxy\n\n    # stop the dhcp server\n    stop dhcpd\n\n    # remove the layer 3 firewall rules\n    iptables-snat-off\n    iptables-stop\n\n    # restore backup if present\n    # [[ -r /etc/resolv.conf.dowse-backup ]] \u0026\u0026  {\n    #     mv /etc/resolv.conf.dowse-backup /etc/resolv.conf\n    # }\n\n    stop redis-server\n\n    notice \"Dowse has stopped running.\"\n```\n\nThe scripts above are found in dowse source as `start.sh` and `stop.sh` and can\nbe customised and called from the system at boot. It is also possible to run an\ninteractive console with completion where dowse commands are available using the\n`console.sh` script. Once in the console all the above start/stop commands and\neven more internals will be available to be launched interactively.\n\n\n# Visualization\n\nThe DNS visualization is produced in a custom format which can be\neasily processed by `gource`. This is the best way to \"see dowse\nrunning\": if you are running it locally, then install `gource` and do:\n\n```\ndowse-to-gource | gource --log-format custom -\n```\n\nor from remote:\n\n```\nssh dowse@dowse.it -- dowse-to-gource | gource --log-format custom -\n```\n\nSidenote: dowse-to-gource must be in the user's `$PATH`. To achieve\nthis, as mentioned above, you can change the user's shell to zsh and do:\n`ln -sf /usr/local/dowse/zshrc $HOME/.zshrc`.\n\nThis will live render all the DNS activity occurring on your computer\nor local network, with the sort of animation that is also showcased on\nour website.\n\nOne can also experiment with gource arguments and render all the\noutput of dowse-to-gource into a video file.\n\n# Experimentation\n\nOpen Sound Control (OSC) messaging is implemented to interface\nlow-latency devices that are running on the same network. To start it\none must know the IP address of the device, then do:\n\n```\ndowse-to-osc osc.udp://10.0.0.2:999\n```\n\nThis will start sending OSC messages over UDP to IP 10.0.0.2 port 999\n\n# Development\n\nThe main development repository is on https://github.com/dyne/dowse\n\nInside the `ops` directory an Ansible recipe is found along a ready to\nuse Vagrant configuration to build two virtual machines (leader and\nclient) that simulate a LAN to do further testing of Dowse.\n\n```\ncd ops\nvagrant up\n```\n\nPlus the usual vagrant commands. The devops in Dowse is based on\nhttp://Devuan.org and will run two virtual machines connected to each\nother, one \"leader\" running Dowse and serving DHCP, one \"client\"\nconnected to it and to the Internet via the leader.\n\nHelp with development is welcome, manuals on how to write new modules\nand daemons are in the making and there is a sister project to\ncategorize all domains used by Internet's conglomerates which also\nwelcomes contributions: https://github.com/dyne/domain-list\n\n# Disclaimer\n\nDowse development is supported by: NLNET foundation (2015)\n                                   SIDNfonds   (2015-2016)\n\nDowse is Copyright (C) 2012-2017 by the Dyne.org Foundation\n\n\tThis source code is free software; you can redistribute it and/or\n\tmodify it under the terms of the GNU General Public License as\n\tpublished by the Free Software Foundation; either version 3 of\n\tthe License, or (at your option) any later version.\n\n\tThis source code is distributed in the hope that it will be\n\tuseful, but WITHOUT ANY WARRANTY; without even the implied\n\twarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\tPlease refer to the GNU General Public License for more details.\n\n\tYou should have received a copy of the GNU General Public License\n\talong with this source code; if not, write to: Free Software\n\tFoundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdyne%2Fdowse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdyne%2Fdowse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdyne%2Fdowse/lists"}