{"id":20275634,"url":"https://github.com/softsec-kaist/gitctf","last_synced_at":"2025-08-15T00:35:18.622Z","repository":{"id":89248935,"uuid":"137466932","full_name":"SoftSec-KAIST/GitCTF","owner":"SoftSec-KAIST","description":"Git-based CTF","archived":false,"fork":false,"pushed_at":"2018-12-05T14:34:10.000Z","size":1206,"stargazers_count":60,"open_issues_count":0,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-07-30T13:03:38.574Z","etag":null,"topics":["ctf"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/SoftSec-KAIST.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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-06-15T09:13:37.000Z","updated_at":"2025-06-27T16:04:34.000Z","dependencies_parsed_at":"2023-06-18T19:53:23.585Z","dependency_job_id":null,"html_url":"https://github.com/SoftSec-KAIST/GitCTF","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SoftSec-KAIST/GitCTF","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FGitCTF","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FGitCTF/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FGitCTF/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FGitCTF/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftSec-KAIST","download_url":"https://codeload.github.com/SoftSec-KAIST/GitCTF/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftSec-KAIST%2FGitCTF/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270505764,"owners_count":24596504,"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","status":"online","status_checked_at":"2025-08-14T02:00:10.309Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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"],"created_at":"2024-11-14T13:10:22.851Z","updated_at":"2025-08-15T00:35:18.586Z","avatar_url":"https://github.com/SoftSec-KAIST.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Git-based CTF\n\nGit-based CTF is a novel attack-and-defense CTF platform that can be easily\nhosted as an in-course activity proposed in our [paper](https://www.usenix.org/system/files/conference/ase18/ase18-paper_wi.pdf) at USENIX ASE. This\nrepository contains [scripts](scripts) for automating ```Git-based CTF```. To\nsee how to configure and play Git-based CTF, see the followings.\n\n**If you want to see the version covered in our\n[paper](https://www.usenix.org/system/files/conference/ase18/ase18-paper_wi.pdf)\nat USENIX ASE, please refer to [ase](../../tree/ase) branch.**\n\n# Setup\n## Requirement\n\n1. Instructors should modify the [`config.json`](scripts/config.json) file to\n   start with.\n\n1. Students need to obtain the [`config.json`](scripts/config.json) file\n   prepared by the instructors in Step 1.\n\n1. Each team should prepare for a PGP public \u0026 private key pair in their own\n   machine. The teams' public keys should be distributed before the game begins.\n\n1. Each student should install GPG and Docker on their own machine in\n   order to play CTF.\n\n## For Students\n\nGit-based CTF consists of three major steps: preparation, injection, and\nexercise. We provide a set of tools that help students play the CTF for each\nstep.\n\n#### 1. Preparation Step\n\nIn this step, you need to prepare a network service running in a Docker\ncontainer. The final outcome of this step is a Git repository that contains a\nDockerfile as well as source code for the service program. We provide several\nuseful tools and scripts that help create such a service container.\n\n- We provide a template [Dockerfile](service_template), which can be used to\n  prepare a service application.\n\n- You can check whether a service repository is valid or not by running:\n    ```bash\n    ./gitctf.py verify service --team [TEAMNAME] --branch [BRANCH]\n    ```\n  The above command checks whether the BRANCH branch of the repository follows\n  the Git-based CTF convention.\n\n#### 2. Injection Step\n\nYou should inject vulnerabilities into the service application prepared in the\nprevious step. You should also provide a working exploit for each injected\nvulnerability as a proof. An exploit in Git-based CTF is a program running in a\nDocker container, and it should follow a specific format, e.g., it should be\nproperly encrypted and signed. We provide several tools and scripts that help\ncreating and verifying injected vulnerabilities and exploits.\n\n- You should write an exploit program/script using the template\n  [Dockerfile](exploit_template) we provided.\n\n- You can verify your exploit against a service of a specific version (i.e.,\n  specific branch). Assume that you have a local copy of a target service at\n  SRVDIR, and your exploit at EXPDIR. You can then run the following command to\n  test whether your exploit works within a SEC seconds against the BRANCH branch version of the\n  service:\n    ```bash\n    ./gitctf.py verify exploit --exploit [EXPDIR] --service-dir [SRVDIR] --branch [BRANCH] --timeout [SEC]\n    ```\n  Also, if you add the ```--encrypt``` option, you can encrypt the exploit when\n  it gets verified. You should upload (i.e. commit and push) this encrypted\n  exploit, which will be named as ```exploit_bugN.zip.pgp``` in the root\n  directory of each branch. Here, ```bugN``` is the corresponding branch name.\n\n- After uploading all the exploits, you can verify your submitted exploits\n  against each branch of your service, with the following command.\n\n    ```bash\n    ./gitctf.py verify injection --team [TEAMNAME]\n    ```\n\n#### 3. Exercise Step\n\nIn this step, you finally play the actual CTF game. To attack other opponents,\nyou should create an issue that contains an encrypted attack described in the\nprevious step.\n\n- To prepare for an attack, you should create a zip file that has a directory\n  containing an exploit Dockerfile as well as an exploit script/program. You\n  then sign and encrypt the zipped directory, and submit it as an issue in the\n  target team's repository. Assuming that you have a local copy of a target\n  service at SRVDIR, and your exploit at EXPDIR, the following command will\n  perform these steps automatically.\n    ```bash\n    ./gitctf.py submit --exploit [EXPDIR] --service-dir [SRVDIR] --target [TEAMNAME]\n    ```\n\n- You can see issues in your own repository to check whether you are attacked by\n  other opponents. Since each issue is encrypted with your own key, you can\n  download the attack and replay it in your own local machine. Especially, you\n  may want to analyze how an unintended vulnerability is exploited. To verify\n  unintended exploit, you can use `gitctf.py verify exploit` command described\n  above.\n\n- You can also check your score with our tool. Assuming that the scoreboard\n  repository URL is properly given by `config.json` file, you can invoke the\n  following command to see the current score.\n    ```bash\n    ./gitctf.py score\n    ```\n  Note that the points you see from the above command may slightly differ from\n  the actual points computed at the instructor's machine, because this command\n  relies on the system time to compute the unintended points.\n  Also, This command automatically populates an HTML file `score.html` that\n  shows a graph representing score over time for each team or person.\n\n## For Instructors\n\nThere should be a machine that is dedicated to evaluating the attacks in\nGit-based CTF. The machine needs to be time-synchronized with an NTP server.\n\n- Create the repository of scoreboard. You can check out an example\n  [scoreboard](https://github.com/KAIST-IS521/2018s-gitctf-score).\n\n- Click the `Watch` button in each team's service repository.\n\n- After the injection phase, you need to create a\n  [`config.json`](scripts/config.json) file, which describes the [basic\n  settings](#configuration) for a CTF.\n\n- After the injection phase, you need to fill the commit hash of N-th injected\n  bug of each team, with the following command.\n    ```bash\n    ./gitctf.py hash\n    ```\n\n- During the exercise phase, the machine should run the following command\n  assuming that you have a proper set-up for the ssh-agent and the gpg-agent,\n  because this command will invoke a series of `ssh` and `gpg` commands, and\n  such commands require a user to enter a passphrase.\n    ```bash\n    ./gitctf.py eval --token API_TOKEN\n    ```\n  This command will run in an infinite loop, automatically fetch issues from\n  the repositories, and update the scoreboard. This process will be killed when\n  CTF is finished.\n\n\n## Configuration\n\n[This file](scripts/config.json) contains critical information for managing\nGit-based CTF. This script must be created by an instructor, and distributed to\nstudents before a CTF begins. You can check out an [example configuration file](https://github.com/KAIST-IS521/2018-Spring/blob/master/Activities/config.json)\n\n##### The [config.json](scripts/config.json) file requires the following fields:\n\n1. `player`: Your GitHub ID.\n1. `player_team`: Your team name.\n1. `score_board`: The URL for the scoreboard repository.\n1. `repo_owner`: The name of the owner of the CTF repositories.\n1. `intended_pts`: Points for exploiting an intended vulnerability.\n1. `unintended_pts`: Points for exploiting an unintended vulnerability.\n1. `round_frequency`: How often will our system change the round? (in sec.)\n1. `start_time`: When does the exercise phase start? You should put a string in the ISO8601\n   format, e.g., you can use `date -Iseconds`.\n1. `end_time`: When does this CTF finish? You should put a string in the ISO8601\n   format.\n1. `exploit_timeout`: Timeout for exploit. (in sec.)\n    1. `exercise_phase`: Timeout when verify exploit in exercise phase.\n    1. `injection_phase`: Timeout when verify exploit in injection phase.\n1. `teams`: Participating teams' information.\n    1. `repo_name`: The URL for each team's service repository.\n    1. `pub_key_id`: The public key ID of the team.\n    1. `bugN`: The commit hash of the N-th injected bug of this team.\n1. `individual`: Participating individuals' information. Each field is separated\n   by participants' GitHub IDs.\n    1. `pub_key_id`: The public key ID of the individual.\n    1. `team`: Which team does this individual belong to?\n\n# Authors\n\nThis research project has been conducted by [SoftSec Lab](https://softsec.kaist.ac.kr) at KAIST.\n\n* Seongil Wi\n* [Jaeseung Choi](https://softsec.kaist.ac.kr/~jschoi/)\n* [Sang Kil Cha](https://softsec.kaist.ac.kr/~sangkilc/)\n\n# Citing Git-based CTF\n\nTo cite our paper:\n```\n@INPROCEEDINGS{wi:usenixase:2018,\n    author = {SeongIl Wi and Jaeseung Choi and Sang Kil Cha},\n    title = {Git-based {CTF}: A Simple and Effective Approach to Organizing In-Course Attack-and-Defense Security Competition},\n    booktitle = {2018 {USENIX} Workshop on Advances in Security Education ({ASE} 18)},\n    year = {2018}\n}\n```\n\n# License\n\nThis project is licensed under the [Apache License](LICENSE.md)\n\n# Acknowledgement\n\nWe thank GitHub for providing unlimited free plan for organizing classes. We also thank HyungSeok Han and anonymous reviewers for their constructive feedback. This work was supported by Institute for Information \u0026 communications Technology Promotion (IITP) grant funded by the Korea government (MSIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Fgitctf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftsec-kaist%2Fgitctf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftsec-kaist%2Fgitctf/lists"}