{"id":16856678,"url":"https://github.com/mhils/r8","last_synced_at":"2025-03-17T05:32:21.845Z","repository":{"id":53134557,"uuid":"148813285","full_name":"mhils/r8","owner":"mhils","description":"r8 – a simple ctf system","archived":false,"fork":false,"pushed_at":"2025-01-12T11:34:19.000Z","size":1544,"stargazers_count":24,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-16T08:41:13.533Z","etag":null,"topics":["ctf","ctf-framework","python3","teaching"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mhils.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":"2018-09-14T16:13:03.000Z","updated_at":"2025-03-16T03:36:34.000Z","dependencies_parsed_at":"2023-10-03T16:08:24.506Z","dependency_job_id":"be98c172-cc04-4c6e-8f02-6ff994266310","html_url":"https://github.com/mhils/r8","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/mhils%2Fr8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhils%2Fr8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhils%2Fr8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhils%2Fr8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhils","download_url":"https://codeload.github.com/mhils/r8/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243981390,"owners_count":20378569,"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":["ctf","ctf-framework","python3","teaching"],"created_at":"2024-10-13T14:05:03.729Z","updated_at":"2025-03-17T05:32:21.839Z","avatar_url":"https://github.com/mhils.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"misc/logo.svg\" width=200 /\u003e\n\u003cbr\u003e\n\u003cstrong\u003er8 - /ɹeɪt/\u003c/strong\u003e\n\u003c/p\u003e\n\nr8 is a simple [jeopardy-style](https://ctftime.org/ctf-wtf/) CTF ([Capture the Flag](https://en.wikipedia.org/wiki/Capture_the_flag_(cybersecurity))) system. What sets it apart from other platforms?\n\n1. r8 is intentionally simple. It won't support multi-server deployments or provide an LDAP integration.\n3. r8 is designed to support CTF events, but also entire university courses. \n   It can be deployed for an entire semester and includes challenge scheduling functionality and logging capabilities to detect cheating.\n3. r8 is written in modern Python 3. This generally makes it easy to spawn additional network services or interface with other tools and languages.\n\nr8 is successfully being used for teaching at the University of California, Berkeley, the University of Innsbruck,\nas well as some other places for hiring assessments.\n\n# Quick Start\n\nIn short, install r8 as a Python package using your preferred way. We recommend the following:\n\nMake sure you have Python 3.9 or above. Clone the repository, create a Python virtual environment \ninto which we install all dependencies, and finally install r8:\n\n```shell\npython3 -m venv venv\ngit clone https://github.com/mhils/r8.git\nvenv/bin/pip install -e ./r8\n```\n\nActivate the virtual environment. This always needs to be done to make the `r8` command available:\n\n```shell\nsource venv/bin/activate\n```\n\nCreate r8's SQLite database in the current directory. \n\n```shell\nr8 sql init\n```\n\nr8 is typically configured with a plain SQL file. Let's add some demo challenges and users:\n\n```shell\nr8 sql file r8/config.sql\n```\n\nWe can now start r8:\n\n```shell\nr8 run\n```\n\nYou can now browse to \u003chttp://localhost:8000/\u003e and log in as `user1` with password `test`.\n\n## Next Steps\n\n 1. `r8` has a comprehensive command line interface. Check out `r8 --help`, `r8 users --help`, etc.\n 2. Take a look at `config.sql` to learn how r8 can be configured.\n 3. Install additional challenges and create new ones (see next section).\n\n## Installing additional challenges\n\nWe likely want to install additional challenges, for example from the [r8-example](https://github.com/mhils/r8-example) \nrepository. To make challenges available to r8, we need to install the corresponding Python package into our Python \nenvironment. Let's get the example repository and add it:\n\n```shell\ngit clone https://github.com/mhils/r8-example.git\nvenv/bin/pip install -e r8-example\n```\n\nWe can now verify that r8 has picked up the new challenges:\n\n```shell\nr8 challenges list-available\n# Output:\n#   r8.builtin_challenges:\n#    [...]\n#   r8_example:\n#    - HelloWorld\n```\n\nTo make the challenge available to users, we also need to instantiate it by adding it to the database. \nGo back to the SQL configuration file (`config.sql` in the example above) and add the following:\n```sql\nINSERT INTO challenges (cid, team, t_start, t_stop) VALUES\n  ('HelloWorld', 0, datetime('now'), datetime('now','+1 month'));\n```\n\nFinally, we can apply our configuration changes and run r8 again:\n```shell\nr8 sql file config.sql\nr8 run\n```\n\nThe *Hello World* challenge is now visible to users! 🎉\n\n## Creating new challenges\n\nThe API Documentation for challenge development can be found at https://mhils.github.io/r8/.\n\nIt is recommended to use [r8-example](https://github.com/mhils/r8-example) as a template\nand place challenges in a new separate repository. See `r8.builtin_challenges` and `r8_example` \nfor challenge examples.\n\n## Customizing the HTML template\n\nr8 provides some simple means to modify the default HTML template, for example to add a custom logo.\nAn example can be found in the [`misc/custom-template`](misc/custom-template) directory.\n\n## Architecture\n\nr8 consists of the following parts:\n  1. The core **`r8` application** written in Python, which manages the currently active challenges. \n     It provides a command-line API for administration (`r8.cli`), a REST API for users (`r8.server`), \n     and a Python API for challenges (`r8.Challenge`).\n  2. **CTF challenges** implemented in Python. All challenges need to inherit from `r8.Challenge` \n     and must be registered using entrypoints so that they are imported on start. \n     See `r8.builtin_challenges` and `r8_example` for challenge examples and each repo's `setup.py` for entrypoint declaration.\n  3. An SQLite **database** that contains information on users, groups, challenge scheduling, and flags.\n     There also is an event log that can be used to help students or detect indicators of plagiarism.\n  4. A **web interface** that allows users to view challenges and enter flags, implemented using React and Bootstrap.\n     To simplify development, there is no compilation step.\n\nTo speed up development, the server can be automatically reloaded on changes using [modd](https://github.com/cortesi/modd).\n\n## User Provisioning\n\nr8 can be set up to allow users to register themselves (by enabling the `register` setting, see `config.sql`), \nbut you may also use it with a fixed set of users.\nThe following workflow works well to provision accounts for a class:\n\n1. Create a text file with one username per line. Those should be email addresses or the local part of an email address.\n   For example, add `john.doe` and `jane.doe` if their email addresses are `john.doe@example.com` and `jane.doe@example.com`.\n   If they are on different domains, use complete email addresses, e.g. `john@example.com` and `jane@other.example.org`.\n2. Run `r8 users make-sql usernames.txt` (optionally with `--teams r8/misc/teamnames.txt`).  \n   Put the output into your `config.sql` file.\n3. Run `r8 sql file config.sql` to apply the changes to the database.\n4. Run `r8 users send-credentials` to send out emails with login details.\n\n## Deployment\n\nFor production use, it is recommended to run r8 on a throwaway VM behind a TLS-terminating reverse \nproxy such as Caddy or nginx. A couple of auxiliary configuration examples are provided in the [./misc](./misc) folder:\n\n - `Caddyfile`: Caddyfile configuration example for an HTTPS-only deployment.\n - `r8.service`: systemd service file example.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhils%2Fr8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhils%2Fr8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhils%2Fr8/lists"}