From 10139c6a13fb0f6dd04f573287e99af4e5f421c7 Mon Sep 17 00:00:00 2001 From: Joshua Reed <11220408+jreed1701@users.noreply.github.com> Date: Thu, 14 Mar 2024 15:13:23 -0600 Subject: [PATCH 1/3] Update usage docs. --- docs/usage.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 84 insertions(+), 7 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 3263c46..4f4d6d0 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -9,9 +9,15 @@ Agent Smith is automatically built and packaged each time the main branch update 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. +recent release and download "agent-smith.exe" to your machine. -TODO - Add a checksum verification method. +Verify the checksum of the "agent-smith.exe" file by comparing the computed checksum with the +value stored in checksum.exe + +Easy way - Open powershell +``` +Get-FileHash -Algorithm [MD5|SHA1|SHA256] +``` ## How to launch the software. @@ -27,11 +33,18 @@ Right clicking the icon reveals the menu. ### A word about Windows. +## Security Warnings + 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. +a threat. At some point in the future, the goal is to do so due to lack of options. + +Also - Pyinstaller, as great as it is for packaging legitimate python apps in an exe bundle is a fan +favorite of nefarious people. As a result, Windows Defender may at time flag this legitimate +software as malware. You will have to go back into windows defender and tell it to allow the +executable on your machine. ## Files and Folders Agent Smith Creates @@ -51,15 +64,49 @@ C:. └───games └───nginx └───nginx- + └───nginx-/nginx.exe + └───nginx-/logs └───ssl └───steam └───AgentSmith.db ``` -As of writing, Agent Smith does not have the ability to change this location or move it. +### Nginx Info + +As of writing, Agent Smith does not have the ability to change this location or move it. There are +useful files in the logs folder. + +There is access.log in the logs folder and it will report any and all HTTP requests that came to your +Agent Smith. + +There is error.log in the logs folder and it will show any error messagse coming from nginx.exe. + +There is a conf folder, if you mess with nginx.conf the app will not work. However, feel free to +view it if interested in how nginx is configured. + +### SQLite Database Info A word about the sqlite database. Deleting this file result in Agent Smith recieving a wipe. You'll -be back to a fresh installation. +be back to a fresh installation, essentially. Only modify or edit this file if you really know +what you're doing. + +## Windows Firewall + +Windows Firewall will always be something to deal with. Whenever a new game is installed and run +for the first time, windows will attempt to prompt the user to allow the app through the firewall. +However, sometimes this automation doesn't work. Therefore, it's important to know how to +get at least nginx.exe through the firewall. + +1. Open Start Menu +2. Search "Allow an App through the Windows firewall" and open. +3. Click "Change Settings" +4. If nginx.exe (or whatever app you're searching for is in the list) is present, skip on to + step 7. +5. Click "Allow another app" and give it "C:\AgentSmith\nginx\nginx-[nginx ver]\nginx.exe" + with the browse button. +6. Click Add +7. Check the box for both public and private. +8. Click OK to finish. ## Instructions to install a game server @@ -93,10 +140,40 @@ Manager windows. it will initiate startup. Conversley if the game server is green, clicking it will shutdown the game server. +## Instructions to modify a game server's inputs. + +The definition of an argument in the context of a game server is a mechanism to give the user control +over either the configuration of the server and/or the game settings itself. + +Agent Smith attempts to generalize some game servers ability to change things like a server port via +an Arguments Mechanism. No two game servers are different. + +There are roughtly a few categories: + +1. Servers that take no argument(s) and instead rely on a file being in a specific location. +2. Servers that take only or a combination of input arguments. +3. Servers have arguments that point to a specific configuration file. + +Each game is tailored to whatever method the game devs chose to feed user input into their dedicated +game server. However, not everything is exposed or perfectly provided via GUI. + +Examples: +* Vrising - The user game modify a subset of server settings via GUI but not global game settings. + Instead, the user would need to modify the files on the file system after installation. +* 7DTD - This game server simply points to a file on the file system that the user can manipulate + after installation. + +To modify server arguments expose via GUI that's done either at installation time, or via the +Game Manager window when the server is shutdown. + +WARNING: +* Some games servers, like PalWorld for example, require Agent Smith to use a file template that is + overwritten each time the server is started. So only through software modification can additional + inputs be exposed. + ## 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! - +Please don't confuse feature requests with a bug... Thanks in advance! Ask questions! From 6968af0e968133069a9d17529c6a1354b71e4593 Mon Sep 17 00:00:00 2001 From: Joshua Reed <11220408+jreed1701@users.noreply.github.com> Date: Wed, 20 Mar 2024 13:51:27 -0600 Subject: [PATCH 2/3] Move docs to oracle. --- README.md | 13 ++- docs/design.md | 114 ------------------- docs/developer-add-game-server.md | 3 - docs/developer.md | 135 ---------------------- docs/getting-started.md | 20 ---- docs/security.md | 73 ------------ docs/software-code-quality.md | 26 ----- docs/testing.md | 43 ------- docs/usage.md | 179 ------------------------------ 9 files changed, 7 insertions(+), 599 deletions(-) delete mode 100644 docs/design.md delete mode 100644 docs/developer-add-game-server.md delete mode 100644 docs/developer.md delete mode 100644 docs/getting-started.md delete mode 100644 docs/security.md delete mode 100644 docs/software-code-quality.md delete mode 100644 docs/testing.md delete mode 100644 docs/usage.md diff --git a/README.md b/README.md index 0e17cc7..abd64cb 100644 --- a/README.md +++ b/README.md @@ -17,20 +17,19 @@ 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!!! +# TODO - Add link # Getting Started +# TODO - Add link + I've written instructions for every day use of this software as well as what a developer might need [here](./docs/getting-started.md). # Security +# TODO - Add link + 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 @@ -38,6 +37,8 @@ possible. # Design +# TODO - Add link + 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. 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 4f4d6d0..0000000 --- a/docs/usage.md +++ /dev/null @@ -1,179 +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 your machine. - -Verify the checksum of the "agent-smith.exe" file by comparing the computed checksum with the -value stored in checksum.exe - -Easy way - Open powershell -``` -Get-FileHash -Algorithm [MD5|SHA1|SHA256] -``` - -## 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. - -## Security Warnings - -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. At some point in the future, the goal is to do so due to lack of options. - -Also - Pyinstaller, as great as it is for packaging legitimate python apps in an exe bundle is a fan -favorite of nefarious people. As a result, Windows Defender may at time flag this legitimate -software as malware. You will have to go back into windows defender and tell it to allow the -executable on your machine. - -## 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- - └───nginx-/nginx.exe - └───nginx-/logs - └───ssl - └───steam - └───AgentSmith.db -``` - -### Nginx Info - -As of writing, Agent Smith does not have the ability to change this location or move it. There are -useful files in the logs folder. - -There is access.log in the logs folder and it will report any and all HTTP requests that came to your -Agent Smith. - -There is error.log in the logs folder and it will show any error messagse coming from nginx.exe. - -There is a conf folder, if you mess with nginx.conf the app will not work. However, feel free to -view it if interested in how nginx is configured. - -### SQLite Database Info - -A word about the sqlite database. Deleting this file result in Agent Smith recieving a wipe. You'll -be back to a fresh installation, essentially. Only modify or edit this file if you really know -what you're doing. - -## Windows Firewall - -Windows Firewall will always be something to deal with. Whenever a new game is installed and run -for the first time, windows will attempt to prompt the user to allow the app through the firewall. -However, sometimes this automation doesn't work. Therefore, it's important to know how to -get at least nginx.exe through the firewall. - -1. Open Start Menu -2. Search "Allow an App through the Windows firewall" and open. -3. Click "Change Settings" -4. If nginx.exe (or whatever app you're searching for is in the list) is present, skip on to - step 7. -5. Click "Allow another app" and give it "C:\AgentSmith\nginx\nginx-[nginx ver]\nginx.exe" - with the browse button. -6. Click Add -7. Check the box for both public and private. -8. Click OK to finish. - -## 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. - -## Instructions to modify a game server's inputs. - -The definition of an argument in the context of a game server is a mechanism to give the user control -over either the configuration of the server and/or the game settings itself. - -Agent Smith attempts to generalize some game servers ability to change things like a server port via -an Arguments Mechanism. No two game servers are different. - -There are roughtly a few categories: - -1. Servers that take no argument(s) and instead rely on a file being in a specific location. -2. Servers that take only or a combination of input arguments. -3. Servers have arguments that point to a specific configuration file. - -Each game is tailored to whatever method the game devs chose to feed user input into their dedicated -game server. However, not everything is exposed or perfectly provided via GUI. - -Examples: -* Vrising - The user game modify a subset of server settings via GUI but not global game settings. - Instead, the user would need to modify the files on the file system after installation. -* 7DTD - This game server simply points to a file on the file system that the user can manipulate - after installation. - -To modify server arguments expose via GUI that's done either at installation time, or via the -Game Manager window when the server is shutdown. - -WARNING: -* Some games servers, like PalWorld for example, require Agent Smith to use a file template that is - overwritten each time the server is started. So only through software modification can additional - inputs be exposed. - -## 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! Ask questions! From f385e171649d3e4afb1eca443db6bedfe1570c5e Mon Sep 17 00:00:00 2001 From: Joshua Reed <11220408+jreed1701@users.noreply.github.com> Date: Thu, 21 Mar 2024 14:04:11 -0600 Subject: [PATCH 3/3] Update REAME.md --- README.md | 37 +++++-------------------------------- 1 file changed, 5 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index abd64cb..236de6f 100644 --- a/README.md +++ b/README.md @@ -17,43 +17,16 @@ Some of Agent Smith's core features are: ### Supported Games -# TODO - Add link +All supported games can be found [here](https://docs.agentsofthesystem.com/build/html/agent_smith/supported-game-servers.html). # Getting Started -# TODO - Add link - -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 -# TODO - Add link - -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 - -# TODO - Add link - -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 @@ -61,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).