{"id":17154486,"url":"https://github.com/aitjcize/overlord","last_synced_at":"2025-04-07T10:29:08.450Z","repository":{"id":49845421,"uuid":"52094302","full_name":"aitjcize/Overlord","owner":"aitjcize","description":"Overlord is a general purpose device monitoring and proxying framework","archived":false,"fork":false,"pushed_at":"2025-03-27T05:48:14.000Z","size":7630,"stargazers_count":70,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-31T09:06:17.750Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aitjcize.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-02-19T14:49:00.000Z","updated_at":"2025-03-27T05:48:18.000Z","dependencies_parsed_at":"2024-05-11T05:32:36.020Z","dependency_job_id":"cb5c272f-aa9d-4434-a664-e3c37a6711e1","html_url":"https://github.com/aitjcize/Overlord","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2FOverlord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2FOverlord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2FOverlord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aitjcize%2FOverlord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aitjcize","download_url":"https://codeload.github.com/aitjcize/Overlord/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247635131,"owners_count":20970676,"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":[],"created_at":"2024-10-14T21:49:20.526Z","updated_at":"2025-04-07T10:29:08.422Z","avatar_url":"https://github.com/aitjcize.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"Overlord\n========\nOverlord is a general purpose device monitoring and proxying framework.\n\n.. image:: https://goreportcard.com/badge/github.com/aitjcize/Overlord\n   :target: https://goreportcard.com/report/github.com/aitjcize/Overlord\n\nOverlord provides a web interface which allows you to access device you have control of directly on the web.  Features include:\n\n1. shell access\n2. file transfer\n3. port forwarding\n4. webcam streaming(directly from the web)\n5. VPN(to be implemented)\n\nand more.  A CLI tool is also provided for accesing the connected clients.  The Overlord server serve as a proxy, which means the devices are still accessible even if they are behind a NAT.\n\n**Opening terminals directly on the web-based dashboard**\n\n.. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/dashboard.gif\n\n**File upload via drag and drop**\n\n.. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/upload.gif\n\n**File download directly with HTTP download**\n\n.. image:: https://raw.github.com/aitjcize/Overlord/master/wiki/download.gif\n\nBuild\n-----\nRun ``make`` in the project root directory.  ``make`` builds the overlord daemon and the go version of the ghost (overlord client).  The resulting binary can be found in the ``bin`` directory.  Note that You need to have the `Go \u003chttps://golang.org/\u003e`_ compiler installed on your system.\n\nBasic Deployment\n----------------\n1. On a server with public IP (to be used as a proxy), initialize the database by running ``overlordd -init -db-path overlord.db``. You'll be prompted to create an admin username and password.\n2. Start the server with ``overlordd -port 9000 -db-path overlord.db`` (if ``-port`` is not specified, default port is 80 or 443 depends on whether TLS is enabled or not).\n3. On a client machine, run ``ghost SERVER_IP`` or ``ghost.py SERVER_IP``.  ``ghost`` and ``ghost.py`` are functional equivalent except one is written in Python, and the other is written in Go.\n4. Browse http://SERVER_IP:9000 and you will see the overlord web dashboard. Log in with the admin credentials you created during initialization.\n\nFor testing purpose, you can run both server and client on the same machine, then browse http://localhost:9000 instead.  Overlord server supports a lot of features such as TLS encryption, client auto upgrade.  For setting up these, please refer to the `Overlord advanced deployment guide \u003chttps://github.com/aitjcize/Overlord/blob/master/docs/deployment.rst\u003e`_.\n\nUser and Group Management\n------------------------\nOverlord uses a SQLite database for user and group management. The database is stored in the file specified by the ``-db-path`` parameter (default: ``overlord.db``).\n\nBefore starting the server for the first time, you must initialize the database with the ``-init`` flag:\n\n.. code-block:: bash\n\n   overlordd -init -db-path overlord.db\n\nThis command will:\n1. Create the database schema\n2. Generate a secure JWT secret for authentication\n3. Prompt you to create an admin user with a custom username and password\n4. Create the admin group\n\nYou can manage users and groups through the web interface by navigating to:\n- Users: ``/users``\n- Groups: ``/groups``\n\nOnly administrators can create, modify, and delete users and groups.\n\nAllowlist Format\n---------------\nOverlord supports access control through allowlists that specify which users can access which clients. The allowlist format has been enhanced to support both users and groups with the following prefixes:\n\n- ``u/username`` - Grants access to a specific user\n- ``g/groupname`` - Grants access to all members of a specific group\n- ``anyone`` - Grants access to all authenticated users\n\nWhen running a Ghost client, you can specify the allowlist using the ``--allowlist`` parameter:\n\n.. code-block:: bash\n\n   ghost --allowlist u/user1,u/user2,g/group1 SERVER_IP\n\nIf no prefix is provided for an entity, it's assumed to be a username and will be automatically prefixed with ``u/``.\n\nUsage\n-----\nOverlord provides a web interface for interacting with the devices connected to it.  The Overlord server provides a set of APIs that can be used for creating different apps(views) according to the need.  The default dashboard provides an app-switcher on the top right corner.\n\nBesides from the web interface, a command line interface is also provided.  The ``ovl`` command (located at ``scripts/ovl.py``) not only provides the same functionality to the web interface but also provide  command line only functions such as **port forwarding** and **VPN** (to be implemented).  The basic usage is as follows:\n\n1. Connect to the overlord server\n\n.. code-block:: bash\n\n   $ ovl connect SOME_SERVER_IP 9000\n   connect: Unauthorized: no authorization request\n   Username: user\n   Password: \n   connection to SOME_SERVER_IP:9000 established.\n\n2. List connected clients\n\n.. code-block:: bash\n\n   $ ovl ls\n   client1\n   client2\n   client3\n\n3. Select default target to operate on\n\n.. code-block:: bash\n\n   $ ovl select\n   Select from the following clients:\n       1. client1\n       2. client2\n       3. client3\n   \n   Selection: 1\n\n4. Open a shell\n\n.. code-block:: bash\n\n   $ ovl shell\n   localhost ~ # _\n\n5. File transfer\n\n.. code-block:: bash\n\n   % ovl push test_file /tmp\n   test_file                   9.9 KiB   38.1K/s 00:00 [#####################] 100%\n   % ovl pull /tmp/test_file test_file2\n   test_file                   9.9 KiB    1.1M/s 00:00 [#####################] 100%\n\n6. Port forwarding: forward the port on client to localhost (assuming we have a web server running on client1's  port 80)\n\n.. code-block:: bash\n\n   % ovl forward 80 9000\n   % ovl forward --list\n   Client   Remote    Local\n   client1  80        9000\n   % wget 'http://localhost:9000'\n   --2016-03-08 17:56:59--  http://localhost:9000/\n   Resolving localhost... ::1, 127.0.0.1\n   Connecting to localhost|::1|:9000... failed: Connection refused.\n   Connecting to localhost|127.0.0.1|:9000... connected.\n   HTTP request sent, awaiting response... 200 OK\n   Length: 419 [text/html]\n   Saving to: ‘index.html’\n   \n   index.html          100%[===================\u003e]     419  --.-KB/s    in 0s\n   \n   2016-03-08 17:57:00 (37.5 MB/s) - ‘index.html’ saved [419/419]\n\n7. User and group management with admin subcommand:\n\n.. code-block:: bash\n\n   # List all users\n   % ovl admin list-users\n   USERNAME             ADMIN      GROUPS\n   --------------------------------------------------\n   admin                Yes        admin\n   user1                No         testers\n\n   # Add a new user\n   % ovl admin add-user username password\n   User 'username' created successfully\n\n   # Add user to admin group\n   % ovl admin add-user-to-group username admin\n   User 'username' added to group 'admin' successfully\n\n   # List groups\n   % ovl admin list-groups\n   GROUP NAME           USER COUNT\n   ------------------------------\n   admin                2\n   testers              1\n\n   # View users in a group\n   % ovl admin list-group-users admin\n   Users in group 'admin':\n     - admin\n     - username\n\nREST API\n--------\nOverlord provides a REST API for managing users and groups:\n\n- GET /api/users - List all users\n- POST /api/users - Create a new user\n- DELETE /api/users/{username} - Delete a user\n- PUT /api/users/{username}/password - Update a user's password\n- GET /api/groups - List all groups\n- POST /api/groups - Create a new group\n- DELETE /api/groups/{groupname} - Delete a group\n- POST /api/groups/{groupname}/users - Add a user to a group\n- DELETE /api/groups/{groupname}/users/{username} - Remove a user from a group\n- GET /api/groups/{groupname}/users - List all users in a group\n\nDisclaimer\n----------\nThe Overlord project originates from the `Chromium OS factory repository \u003chttps://chromium.googlesource.com/chromiumos/platform/factory/\u003e`_, which is used for monitoring and deploying test fixtures in a factory.  The implementation of Overlord is general enough for non-factory use, thus, it's put into this GitHub mirror for greater visibility.  All source code in this repository belongs to the `Chromium OS \u003chttps://www.chromium.org/chromium-os\u003e`_ project and the source code is distributed under the same license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faitjcize%2Foverlord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faitjcize%2Foverlord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faitjcize%2Foverlord/lists"}