{"id":18329818,"url":"https://github.com/ctfd/koth-agent","last_synced_at":"2025-10-16T06:35:58.519Z","repository":{"id":46008684,"uuid":"422455006","full_name":"CTFd/koth-agent","owner":"CTFd","description":"KoTH Server Agent for use with CTFd Enterprise","archived":false,"fork":false,"pushed_at":"2024-01-17T18:06:54.000Z","size":47332,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-21T15:12:16.236Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CTFd.png","metadata":{"files":{"readme":"README.md","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":"2021-10-29T05:42:51.000Z","updated_at":"2024-10-15T23:07:45.000Z","dependencies_parsed_at":"2024-11-05T19:29:53.976Z","dependency_job_id":null,"html_url":"https://github.com/CTFd/koth-agent","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTFd%2Fkoth-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTFd%2Fkoth-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTFd%2Fkoth-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTFd%2Fkoth-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CTFd","download_url":"https://codeload.github.com/CTFd/koth-agent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423464,"owners_count":20936621,"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-11-05T19:18:49.017Z","updated_at":"2025-10-16T06:35:53.471Z","avatar_url":"https://github.com/CTFd.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KoTH Agent Server\n\nThe KoTH Agent Server is an open-source agent to use with CTFd Enterprise, King of the Hill (KoTH) challenges.\n\nIt is setup to run alongside the KoTH Challenge Type and its target server/application. \n\nThe agent monitors the target server/application for the current \"King of the Hill\" and simultaneously listens and responds to HTTP requests.\n\nTo learn more about King of The Hill challenges, [check out its documentation right here](https://docs.ctfd.io/docs/custom-challenges/king-of-the-hill).\n\n\n## File structure\n\nThis repository contains the KoTH Agent Server, source code, and binaries, as well as an example web application to show the interaction between the agent and a target server. \n\n- `dist` folder contains compiled agents for different operating systems\n- `/example` folder contains the files for an example web application used to demonstrate how the agent interacts with other applications, [as shown here](#example-application)\n- `src` folder contains the source code for the agent\n- `/tools/certify/` folder contains a Python script to [generate self-signed SSL certificates](#generating-self-signed-ssl-certificates)\n\n## How to use the agent\n\nYou can use the executables found in the `/dist` folder, or you can modify and recompile the agent's source code into an executable file using `go build`. \n\nYou can then run the agent using its available [options](#agent-cli-usage).\n\nFor example, running the command below, with the options indicated, tells the agent to:\n- monitor the content of the owner.txt file (assuming that the `owner.txt` file is present in the current working directory, and contains the text \"example\")\n- add an API key, to prevent unauthorized users from accessing the agent\n- add an SSL certificate, to encrypt the data\n- add the SSL key\n\n```\n./agent -file owner.txt -apikey 123 -certfile /tools/certify/example.com.crt -keyfile /tools/certify/example.com.key\n\nListening on 0.0.0.0:31337\nRunning with encryption certificates from filesystem\n```\n\nWe can then access the the `/status` or `/healthcheck` endpoint using cURL with a copy of the SSL certificate, `example.com.crt`.\n\n```\ncurl https://localhost:31337/status --cacert example.com.crt --header \"Authorization:123\"\n\n{\"success\":true,\"data\":{\"identifier\":\"example\"}}\n```\n\nFor more information about the agent's API, you can refer to this article: https://docs.ctfd.io/docs/custom-challenges/king-of-the-hill/redoc\n\n### Agent CLI Usage\n\n```\n❯ ./agent -h\nUsage of ./agent:\n  -apikey string\n        API Key to authenticate with\n  -certfile string\n        SSL certificate file\n  -certstring string\n        SSL cert as a string\n  -file string\n        text file to watch for server ownership changes (default \"owner.txt\")\n  -health-cmd string\n        Specify a command to run when asked for a healthcheck (default \"true\")\n  -help\n        print help text\n  -host string\n        host address to listen on (default \"0.0.0.0\")\n  -keyfile string\n        SSL key file\n  -keystring string\n        SSL key as a string\n  -origin string\n        CIDR ranges to allow connections from. IPv4 and IPv6 networks must be specified seperately (default \"0.0.0.0/0,::/0\")\n  -owner-cmd string\n        Specify a command to run when asked for an owner\n  -port string\n        port number to listen on (default \"31337\")\n```\n\n### Generating Self-signed SSL Certificates\n\nYou can further secure the connection via encryption when communicating with the KoTH Agent. The repository provides a Python script that will generate a self-signed SSL certificate using [OpenSSL](https://www.openssl.org/).\n\nIt is located in `/tools/certify/certify.py`.\n\nThe script creates and self-signs X.509 SSL/TLS certificates with the \"subjectAltName\" extension. Which allows for the specification of IP addresses as well as domain names.\n\nRunning the example script below will generate two files: `example.com.crt` and `example.com.key`.\n\n#### SSL Certificate Generator Usage\n```\n$ ./certify.py example.com IP:127.0.0.1 DNS:localhost [www.example.com] [mail.example.com] [...]\n```\n\n## Example Application\n\nTo get a sense of how the agent works, an example application is provided in the repository in the `/example` folder. It is a simple web application, built with [Flask](https://flask.palletsprojects.com/), that serves as the agent's target application for it to monitor. It takes in the user's identifier or any text, and writes it to a file called `owner.txt`.\n\nRun the web application together with the agent using `docker-compose up` in the root directory of the repository.\n\nOnce the Docker instance is running, you can interact with the agent and example web application.\n\nThe web application can be accessed in `http://[server]:5000/`. And the agent can be accessed from two endpoints: `/status` and `/healthcheck`. For example, `http://[server]:31337/status` and `http://[server]:31337/healthcheck`.\n\nTry entering text on the web application's input and submit it.\n\nThen, send a request to the agent via the `/status` endpoint. The agent responds in JSON format, where, the identifier key's value would be the text submitted from the web application.\n\nHere's a [full tutorial](https://docs.ctfd.io/tutorials/challenges/creating-koth-challenges) on how to setup King of the Hill challenges using the example application.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctfd%2Fkoth-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctfd%2Fkoth-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctfd%2Fkoth-agent/lists"}