diff --git a/README.md b/README.md index 0e17cc7..236de6f 100644 --- a/README.md +++ b/README.md @@ -17,42 +17,16 @@ Some of Agent Smith's core features are: ### Supported Games -Here's a short list of some games Agent Smith is currently programmed to manage. - -1. 7 Days To Die -2. V-Rising -3. Palworld -4. More to come!!! +All supported games can be found [here](https://docs.agentsofthesystem.com/build/html/agent_smith/supported-game-servers.html). # Getting Started -I've written instructions for every day use of this software as well as what a developer might need -[here](./docs/getting-started.md). +To learn how to use Agent Smith please read the [User Guide](https://docs.agentsofthesystem.com/build/html/agent_smith/usage.html) # Security -Opening a port to expose Agent Smith's API to the outside world can be a little scary, so I've -written a whole [section on it](./docs/security.md). The author takes security very seriously, and -wants you to be informed about the risks and what's been done to make this software as safe as -possible. - -# Design - -There is a dedicated section regarding the [design](./docs/design.md) of Agent Smith. For a detailed -account of system design, explanations for design choices, limitations, and more, please have a look -at that section. - -# Future Work - -I have identified work I intend to do for the future and could use help with. However, if you have -an idea yourself, please create an issue for that. - -There will always be room for improvements, but here are some high level goals the author has to -improve behavior and usability overall: - -1. Get functional & unit test framework to minimal code coverage; 20%. -2. Cross-platform support - I'd like to be able to support Linux Distributions as well. -3. Support steam game versions; eg install latest_experiemental or a specific release. +Security is a big deal, the author wrote a whole section about it. Have a look at the +[Security Docs](https://docs.agentsofthesystem.com/build/html/agent_smith/security.html). # References / Acknowledgements @@ -60,4 +34,4 @@ improve behavior and usability overall: 2. SteamCMD Documentation - https://developer.valvesoftware.com/wiki/SteamCMD 3. I found pythonsteamcmd here - https://github.com/f0rkz/pysteamcmd and it was helpful so I did not have to rebuild an interface to steamcmd. -4. All other dependencies, have a look at [requirements.txt](./requirements.txt). \ No newline at end of file +4. All other dependencies, have a look at [requirements.txt](./requirements.txt). diff --git a/docs/design.md b/docs/design.md deleted file mode 100644 index 851939b..0000000 --- a/docs/design.md +++ /dev/null @@ -1,114 +0,0 @@ -# Design - -This section of the documentation is intended to capture how Agent Smith works, explanations for -certain design choices, limitations, and - -## Architecture - -Explanations regarding architecture are contained in this section. - -### Generalized - -In short, Agent Smith is a web server with a PyQt front end for the user. The web server sports -an API that allows a client to make requests. There is a go-between piece of software called, -[Operator](https://github.com/agentsofthesystem/operator), and both the PyQt GUI uses it and anyone -wishing to write their own script. Everything is python based with the singular exception of Ningx. -For an explanation why, please see the explanations section. - -### API - -Application Programming Interface (API) - -The api is broken into versions in the [API](../application/api/) folder. The API itself is -versioned; v1, v2, etc... Flask itself uses a conecpt of a "Blueprint" to break them out so each -logical section of API is broken into its own Blueprint. For example, the games blueprint contains -the games API, and its responsible for manipulating Game Servers. - -### Security - -When running Agent Smith in production, the backend web server intenitally blocks outside connections -that do not come from localhost. Incoming web connections would go through Nginx, and then are reversed -proxied back to Agent Smith. Therefore, in production, from AgentSmith's perspective all web requests -are coming from localhost. - -In reality, web requests may also come from a different IP address, so the inner software also -enforces tokenized security based on the IP address. Nginx is configured to proxy pass the requestor's -IP address. Whenever AgentSmith see's a request that came from an origin IP address that is not -localhost, then it will expect a valid Bearer Token. But if the request did come from localhost, -specifically the PyQt GUI, then the backend web server will allow the connection without the token. - -More about tokens. The security tokens may be generated via the Operator client, or via GUI. Once -the token is generated the user gets a singular chance to copy it. The token itself is a Java Web -Token (JWT) based token. - -External web requests must use SSL through Nginx and have a valid token in the request header. The -Operator client makes this seamless to the user. - -Finally, a word about flask. Flask has a console made to run debug commands on. That console is -intentionally disabled. Running flask in debug mode should never be done by altering the code in -[config.py](../application/config/config.py) where "DEBUG=True". - -## Game Server Framework - -Game Servers are built into Agent Smith via a framework. One will notice the [games](../application/games/) -folder contains implementations of the supported Game Servers that are available. All of them inherit -from the [BaseGame](../application/common/game_base.py) class. - -To add a new supported dedicated game server one adds a new class which implements all the abstract -functions; startup, shutdown. The rest of the software dynamically imports the games module and -has the ability to generate the GUI on the fly. That way someone can add a new game and not have to -worry about updating the GUI. - -## Explanations - -* **Why are some things implemented with Threading?** - The author is proficient in what asynchronous - background task execution is and how that is implemented. In python, that's typically implemented - using a package called Celery, however, it's intentionally not being used for the purpose of keeping - the software used to being python only. The author wanted users to only have to download an EXE - file and not have to install pre-requisite softare, such as a message queue server. - -* **Why only supported games and not the ability to run scripts or generic executables?** - Firstly, - security. By not allowing scripts and generic executables to be run security is greatly enhanced. - Next, each and every single game is different. Some required specific arguments while others need - an input file. Also, some game servers don't just simply shutdown by killing the server executable, - and need extra steps to avoid corrupting files. Implementing a framework allows some semblance of - order to the disorder which is the dedicated game server landscape. - - -## Limitations - -The software has some limitations that users ought to be aware of. - -1. The steamcmd client that downloads a game server (based on its steam_id) does so as an anonymous user. If it - doesn't download publically, it's not supported very well. The package I used addresses this but I haven't paid - much attention to it. If your needs require authentication, be prepared for some issues. -2. Windows firewall: This software cannot click the button that says "Allow this app through the firewall". -3. Port Forwarding: This software cannot set up port forwarding rules on any network hardware -4. Linux: To start, the agent software is intended to operate on Windows. However, the client can run on windows or - linux. - -## Design - Dead Ends - -In this section, the author is attempting to describe both what the author personally has no interest -in working on, and "features" that Agent Smith should never adopt. All of these items would be -considered dead ends. - -### Authtor's own lack of interest - -1. I want to add the games that I want to manage into the software. I tried to go for an interface that is genearlized - so I didn't have to build customizations for each game server. Therefore, if you as a user want a game added that - the author isn't crazy about playingm, then be prepared to contribute! -2. The Graphical User Interface: To be honest, I'm not a GUI person. It's not a pretty GUI but it gets the job done. - I will help with bug-related issues, I'm not going to personally work issues to enhance the GUI unless I feel - strongly about it. I'm not opposed to making it better. If someone wants to make it better go for it! -3. Supporting new features so you can use this for personal gain. Again, if you do this, you must share the code back - for the community, but I'm not going to be helping. - -### Dead Ends - -* Building any support to upload and run generic executables via API. That is a **HUGE** security - risk I don't want this software to put on any user. -* Adding anything other than python & nginx to the tech stack. This software is intended to be - lean. -* By-passing security measures. No feature reducting the security posture of this tool should be - accepted. \ No newline at end of file diff --git a/docs/developer-add-game-server.md b/docs/developer-add-game-server.md deleted file mode 100644 index 3050ff9..0000000 --- a/docs/developer-add-game-server.md +++ /dev/null @@ -1,3 +0,0 @@ -# Adding a Game Server - -TODO - Add this section. \ No newline at end of file diff --git a/docs/developer.md b/docs/developer.md deleted file mode 100644 index c17e18c..0000000 --- a/docs/developer.md +++ /dev/null @@ -1,135 +0,0 @@ - -# Developer - -The following are instructions for developers. - -## The obvious... - -Why oh why did you pick windows!?!? - Well... the author wanted to target windows first because, in truth, -most people using this tool are likely to be gaming on a windows machine. The author has tons of linux -experience and recognizes that Linux/Dockerized platforms are entirely relevant and in the future. - -## Pre-requisites - -This software was developed on Windows 10. The chosen software language is Python 3, which can be installed -on any flavor of Linux or Windows. However, a python environment is a hard requirement. The author used VSCode to -develop software, although any IDE may be used which is the preference of the developer. - -1. Python 3 - (See section about python setup.) -2. VSCode + Python Extension (or other preferred IDE) -3. Steam - On Windows, you must have steam installed! -4. Git - -Finally - I'm assuming the reader has some software development experience. Please don't make an issue because you -don't know how to set something up or use an IDE. Please do make an issue if these instrutions need updating. Also, -feel free to figure out what's different and make a change yourself ;). - -## Development Workflow - -The [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) -is used and is enforced. - -All features get stacked up in the develop branch and then, after testing, released to the main branch. -GitHub Actions automate DevOps Continuous Integration checks along the way. On the main branch, however, -a packaged release of Agent Smith is generated and attached to the release section. - -## Development Environment Preparation - -### Ubuntu/Debian Based Linux - -Please note that development on linux is experimental for now. In the future, it will be supported -but not until a later release. And when that time comes, Ubuntu/Debian will likely be the first -distro supported. - -1. sudo apt update -2. sudo apt install python3 python3-venv python3-pip lib32gcc-s1 -3. sudo apt install libgl1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ - libxcb-shape0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-dev - -NOTE: - - The final step installs a number of required items for PyQt5 applications. - - You may develop on Linux but the software hasn't been built to do both Windows and Linux yet, so don't build - something that only works on Linux. - -## Windows - -1. Download python from here: https://www.python.org/downloads/ - Python 3.10+ will do. -2. install to windows. -3. Open a powershell and test that one can run the "python" command to verify python is installed. -4. install git for windows from here: https://git-scm.com/download/win - -## Docker - -The backend flask server could be containerized and the PyQT GUI could just simply communicate with -a container, but this has yet to be developed. - -# Development Environment - -## Stand Alone & Development - -One must create a python virtual environment. Therefore python3 must be present and configured on your machine. - -1. python3 -m venv venv/ -2. Activate the Python environment: - - linux: source venv/bin/activate - - windows: .\venv\bin\Activate.ps1 -3. pip install -U pip -4. pip install -r requirements.txt -5. pip install -r test-requirements.txt -6. Run the backend server: python .\server.py -7. Run the frontend GUI: python .\gui.py - -NOTE: - - There is another script (python .\agent-smith.py), and that can be used to run both the backend server and the front - end GUI simultaneously. Use this for final testing of features. - - The backend server operates on port 5000, and the frontend GUI is built to use that port by default. - That port should never change. Nginx is used to expose ports and that's where changes are made to - port numbers. - -**Warning**: If one is using a windows only environment, the second step where the python virtual environment is activated -may require a windows policy to be enabled which allows powershell scripts to be run. This is a windows security -mechanism. One need only enable the policy and repeat the step. [Here is more information](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-7.3) -to set this up properly. - -## Testing - -This software uses the coverage and pytest python packages for a testing framework. All tests are in the "tests" folder, -and are split up by unit tests and functional tests. Any unit test is a simple test of a singular function or independent -object. A functional or system test would be a test that covers and end-to-end function; eg installing a game server and -seeing that the game shows up in the quick action menu, for example. - -For more information about testing, [please read here](./testing.md) - -# Software Development Process - -## Documentation & Code Quality - -All that fun stuff is going to be [here](./software-code-quality.md). Really, have a read, PR's depend on it! - -Grumble? I tried to keep it simple... - -## Software Testing - -1. Before code submission run: coverage run -m pytest (All tests must pass) -2. Create a Pull Request -3. Wait for GitHub actions to run to completion. - -## Debugging - -This section will speak toward using VSCode for debugging. A launch configuration is a named JSON object that VSCode -uses to start up a debug session. There are two relevant to debugging: - -1. "Python: Server" - Run this to get a debug session for the backend Flask Server -2. "Python: GUI" - Run this to get a debug session for the frontend PyQt GUI. - -The user may use one or the other, or both at the same time. - -NOTES: - - **DO NOT** use print statements to write variables to the terminal in as opposed to proper debugging and expect - that to get merged! - - I'm not going to leave instrutions for which buttons to click on VSCode to use the debugger. - -## References: - -1. https://coverage.readthedocs.io/en/7.3.0/ -2. https://git-scm.com/download/win \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index e37eb99..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,20 +0,0 @@ -# Getting Started - -This document should contain everything a developer or user needs to know in order to utilzie this -software. - -## Usage - -TODO - Need to finish this section. - -The every day user of this software may find instructions [here](./usage.md). - -## Development - -## Setting up an environment - -Development Environment setup documentation can be found [here](./developer.md). - -## Adding a new supported game server - -A description of the software pattern used to add another supported game server can be found [here](./developer-add-game-server.md). diff --git a/docs/security.md b/docs/security.md deleted file mode 100644 index 20d0792..0000000 --- a/docs/security.md +++ /dev/null @@ -1,73 +0,0 @@ -# Security - -True story. While playing around with Agent Smith during development, I opened up a port and gave -it a hostname and left it running. In the couple of days which I left it running, a bot found it -and attacked it. My machine was compromised because I had the software running in debug mode. -After that I decided to double down on security posture. - -Security with Agent Smith is handled by Nginx and by some specific settings that I've made to secure -the software: - -1. First and foremost, I've disabled debug mode in the [configuration object](../application/config/config.py). -2. For the .\agent-smith.py inside of the GUI [launch.py](../application/gui/launch.py), debug mode - is also disabled. This script is the one that pyinstaller uses to pacakge AgentSmith for release. -3. Also, inside of [launch.py](../application/gui/launch.py), the Flask Server is set to only allow - connections from the localhost, or 127.0.0.1. -4. Nginx handles all incoming connections. Check out the "Security with Nginx" section below. -5. I've removed all software from AgentSmith that might be used to run any executable. That way, - if something was downloaded to your machine, AgentSmith won't be the mechanism that runs it. - -All of that in mind, there is no reason why exposing a home server to the open internet cannot be done -safely. Keep in mind that no matter what, your IP will be probed and tested no matter what is done. - -## Best Practices - -For those of us that like to tinker and change things, please watch out for the following: - -1. Never ever run agent smith in debug mode and expose it to the open internet. There is an attack - that takes advantage of Flask's /console endpoint to run any python code. -2. Always use HTTPS/SSL to communicate outside of your home network. If you alter the code to expose - the Flask Server then you're taking a risk. -3. A great place to get a dynamic dns address for your home WAN is noip.com -4. Agent Smith is designed to have the ability to change the port used with Nginx. Use one that isn't - a standard port. Pick a random 4-5 digit number! Try to avoid commonly used port numbers. Here - is a wiki article on common [port numbers to avoid](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers). - -I've written the code in such a way that a user must deliberately circumvent it to take the risks -I've described here. Do so at your own risk. - -### Home Network Configuration. - -Our home networks are deeply personal and equally unique. However, here are a couple of recommendations -that might help: - -1. If you have a managed switch, segregate the server running agent smith onto its own VLAN. That - way, if it ever becomes compromised the machine is isolated from the rest of your home network. -2. Port Forwarding. If you router supports it, specifically route the port forward to the machine - hosting Agent Smith instead of any and all on your network. -3. If you have the ability to run an "Intrusion Protection System" then do it. An extra set of eyes - never hurt! - -## Security with Nginx - -First and formost, Nginx is a piece of software that functions as a Reverse Proxy. That means it -takes incoming requests and routes valid request to an application secured behind itself. In essense, -Nginx is used as a "shield" to protect API requests coming to Agent Smith from anywhere. This section -will describe what Nginx is doing to protect you. - -The following are tactics used with Nginx to secure: - -1. SSL/TLS Encryption - Secures communciation so a users' token cannot be intercepted. It also - throws off any bots looking for a simple HTTP connetion. -2. HTTPS traffic only. Nginx actively blocks regular HTTP traffic. -3. Denies the /console route. This prevents access to the debug route if it was accidentally - exposed. -4. Limits the number of connetions per incoming IP address. -5. Expects the requestor to know the hostname of the server. If you don't then the request is denied. - This prevents bots scanning random IPs from getting through. - -To see how nginx is configured, have a look at the templated [configuration file](../application/config/nginx/nginx.conf.j2). - -The author is well aware that there are many more potential safeguards that Nginx might be able -to employee. If you, the reader, have a suggestion please create an Issue and help implement an -improvement! \ No newline at end of file diff --git a/docs/software-code-quality.md b/docs/software-code-quality.md deleted file mode 100644 index b2fd6d0..0000000 --- a/docs/software-code-quality.md +++ /dev/null @@ -1,26 +0,0 @@ -# Style Guide - -# Introduction - -This is a loose guide to how the python code should look at a minimum. The author of this software recognizes that -nothing is perfect, so all code should move toward better styling, documentation, typing (etc..) over time. Not away -from it and get worse. Therefore, not all code will immediately look this way, but will get better and better over time. - -## Documenation - -All files, classes and methods should have pydocstyle type comments. - -## Typing / Type Hints - -The PEP 484 standard for typing shall be followed and strived for; https://peps.python.org/pep-0484/. - -This applies to function signatures, class attributes, and where ever it makes sense. - -## Formatting - -In general, to take away people arguing this vs that for formatting of code, all formatting will be done by the "black" -python package. It's not perfect but it's consistent which is the goal. - -Before each commit simply tyep "black ." and all source code will be re-formatted. - -For more information, check out black's ReadTheDocs here; https://black.readthedocs.io/en/stable/index.html. diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index 06fc00f..0000000 --- a/docs/testing.md +++ /dev/null @@ -1,43 +0,0 @@ -# Testing - -Testing an application is imperative as it grows because as new features and fixes are introduced, -the potential for creating more issues than get solved increases. - -## Test Plan - -The goal is to first, implement unit testing and then system testing with the PyQt GUI. In the end, -all testing (or as much as possible) should become a part of CI/CD checks. - -A word about code coverage - In my experience people associate code coverage with an in-fallable -system. That is, if the code coverage is 95% then the system cannot have any bugs in it, certainly! -The author disagrees with this mentality. Instead, the author belives its best to use code coverage -metrics as a guidline and instead focus on test case coverage. In a perfect world, test driven -development would drive test case coverage, but in reality code gets written and tests are added -both as one can plan for and as issues are found. - -### Desired Unit Testing - -1. Testing API Endpoints. -2. Testing the Token authentication mechanisms. -3. Testing all isolated functions. - -### Desired System Testing - -1. Testing that the GUI can install a game server properly. -2. Testing that the GUI can startup, shutdown and restart an installed game server properly. -3. Testing that the GUI can update a game server properly. -4. Testing that the GUI can uninstall a game server. -5. Testing that installing a new game results in the quick action menu being updated. -6. Testing that uninstalling a game results in the quick action menu being updated. - -### Other testing. - -Other testing might consist of load testing, erroneous input testing, fault testing which is to mean -intentionally causing an error, and much more. - -Ideas: - -1. Try to break API endpoints with usupported HTTP request types and inputs. -2. Run game servers for days on end and then check basic functionality. -3. Try to do odd things like uninstall a game while its running or delete a database record and see - how the system reacts. \ No newline at end of file diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index 3263c46..0000000 --- a/docs/usage.md +++ /dev/null @@ -1,102 +0,0 @@ -# Usage - -The area of documention seeks to inform the end user the basics for using Agent Smith, and is not -intended for a developer. - -## Where to get the software. - -Agent Smith is automatically built and packaged each time the main branch updates. The GitHub -releases mechanism houses the executable binary. - -In a browser navigate to https://github.com/agentsofthesystem/agent-smith/releases, find the most -recent release and download "agent-smith.exe" to you machine. - -TODO - Add a checksum verification method. - -## How to launch the software. - -Once agent-smith.exe is downloaded, move the file to a location that best suits you. The author -recommends a place that won't change and is easily accessible, like your desktop. - -Onces a suitable location, to launch the software simply double-click it to run it. You'll be prompted -that the software is a potential threat, and you'll have to click "run anyway" to make windows run -it. - -After Agent Smith has launched, a green agent icon will appear in the bottom right of your screen. -Right clicking the icon reveals the menu. - -### A word about Windows. - -Developer creating applications are expected to "digitally sign" executable files so that Windows -won't flag it as a potential threat. However, to sign an executable one has to purchase an expensive -signing authority and until that expense can be covered, somehow, this warning will continue to happen. -The author's opinion is that it's sad that Windows forces you to pay or makes your software look like -a threat. - -## Files and Folders Agent Smith Creates - -Agent Smith creates the following directory structure: - -1. games - By default games get installed into this sub-directory. The user may optionally install - games elsewhere. -2. nginx - All things nginx go into this folder. -3. ssl - The SSL public certificate and private key are stored in this folder. -4. steam - The SteamCMD client is kept in this folder. -5. AgentSmith.db - This is an sqlite database that keeps track of everything that Agent Smith needs. - -Here is how the files look on the file system: -``` -C:. -├───AgentSmith - └───games - └───nginx - └───nginx- - └───ssl - └───steam - └───AgentSmith.db -``` - -As of writing, Agent Smith does not have the ability to change this location or move it. - -A word about the sqlite database. Deleting this file result in Agent Smith recieving a wipe. You'll -be back to a fresh installation. - -## Instructions to install a game server - -To install a supported game: - -1. Right click Agent Smith's icon in the system application tray. -2. Select New Game. -3. Chose the game server you wish to install in the dropdown. -4. There will be defaults, but alter any of the installation settings as desired. -5. Click the installation button at the bottom. - -## Instruction to start stop an installation. - -There are two methods to quickly startup a server and shut one down. - -### Using the Game Manager windows: - -1. Right click Agent Smith's icon in the system application tray. -2. Select New Game. -3. Chose the game server you wish to manage in the dropdown. -4. On the bottom you can click one of Startup/Shutdown/Restart as needed. - -### Using the Quick Action Menu: - -Agent Smith allows the user to quickly startup or shutdown a server without going through the Game -Manager windows. - -1. Right click Agent Smith's icon in the system application tray. -2. Hover your cursor over "Quck Action" -3. Click the game server you want to toggle. If the game server is red, that means its off and clicking - it will initiate startup. Conversley if the game server is green, clicking it will shutdown the - game server. - -## Reporting Bugs - -Things happen, don't work as expected, and many many more issues. If it happens to you, then fill -out the bug template in GitHub [here](https://github.com/agentsofthesystem/agent-smith/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBUG%5D+%5BGUI%2C+Backend%2C+Client%5D+-+Short+Subject). - -Please don't confuse feature requests with a bug... Thanks in advance! -