ctf-collab - Collaborative programming environment inside GitHu

项目说明

Introduction

Create an ephemeral, collaborati en inside GitHub
Actions; con save data with git. Particularly useful for solving
Capture The Flag
(CTF)
problems.

Less technically: this is kind of like Google Docs for working on hacking
competitions collaboratively.

Quick start

Create a repo from the
template. Do the rest
of the steps from within your copy of the repository. The link to create a copy
of the repository will only work for users logged into GitHub.

In all cases, the username is runner and the password is ctf.

Connect With Tor

Connecting over Tor is the most secure way to use the server, and doesn't
require signing up for any service. It does, however, require downloading the
Tor Browser Bundle. It also runs with noticeably higher latency than using the
alternati connection method.

0. Create a repo from the
template. Many of
the following links will only work from within your copy of the repository.
Creating a copy only works for users logged into GitHub.
1. Download and run the Tor Browser
Bundle.
2. Na to the "Run Collaborative CTF En"
workflow.
3. Start the ser the button in the top right ("Run workflow").
4. View the output; wait for it to print the connection information.
5. SSH in or connect from the Web using the connection information printed
during the Action run. Note: whether connection to the .onion address
using the browser or SSH, Tor Browser must be running.
6. Tor browser has a default setting that causes text to be illegible in ttyd
and/or its dependency xterm.js. To fix this, go to about:config in the
address bar, and set privacy.resistFingerprinting to false.

Connect With ngrok (Without Tor)

Connecting o instead of Tor is a less secure, but lower-latency way to
connect to the ser on GitHub Actions. This method of connecting
doesn't require downloading Tor, but it does require signing up for ngrok.

0. Create a repo from the
template. Many of
the following links will only work from within your copy of the repository.
Creating a copy only works for users logged into GitHub.
1. Sign up for ngrok.
2. Copy your ngrok
Authtoken.
3. Na to the "Run Collaborative CTF En"
workflow.
4. Paste in your ngrok Authtoken when you start the ser the button in
the top right ("Run workflow").
- To avoid pasting the Authtoken every time, paste it into a secret called
NGROK_TOKEN under the Secrets settings
area. It will be saved here and used automatically.
5. View the output; wait for it to print the connection information.
6. SSH in or connect from the Web using the connection information printed
during the Action run.

Once Connected

By default, the collaborati uses tmux with <kbd>Ctrl</kbd> +

<kbd>A</kbd> as the "prefix," and a few other custom keys that can be
in .tmux.conf
- Read a good introduction to
tmux
- Press <kbd>Ctrl</kbd> + <kbd>A</kbd> and then <kbd>c</kbd> to open a new
window
- Press <kbd>Ctrl</kbd> + <kbd>A</kbd> and then <kbd>n</kbd> to go to the
next window and <kbd>Ctrl</kbd> + <kbd>A</kbd> and then <kbd>p</kbd> to go
to the previous window
- Press <kbd>Ctrl</kbd> + <kbd>A</kbd> and then <kbd>|</kbd> to split the
current pane (this is a bar "|" – not the letter "L" or
"i")
- Press <kbd>Ctrl</kbd> + <kbd>A</kbd> and then <kbd>S</kbd> to split the
current pane horizontally (this is a *capitalized* "S" – tmux cares about
capitalization)
- Press <kbd>Ctrl</kbd> + <kbd>A</kbd> and then one of the arrow keys to move
to the pane in that direction

By default, tmux adjusts the size of a window to accommodate the smallest

- Every window is the same size for all , at all times
- To make the window adjust to the largest client instead of the smallest,
press <kbd>Ctrl</kbd> + <kbd>A</kbd> and then <kbd>G</kbd> (must be capital
"G")
- Be careful! This will mean that some of the window is difficult or
impossible to see for the with the smaller client

Use the quit command to terminate the server for all connected users

- Alternatively, the workflow can be canceled from within the GitHub web
interface

Create folders in the repo (~/ctf) for each CTF to stay organized

- Save any changes by committing using git within the ~/ctf folder
- The default identity associated with commits is anonymous

Theoretically, unlimited users can connect at once via Tor, and up to 40 can

connect using ngrok for free
- Practically, the real upper-limit is probably far lower
- Every new user connects using the same link/connection information
- Additional users do not need GitHub accounts to connect or commit to the
repository from within the en
- Each user can create their own windows independently, or switch to windows
created by other users
- All connected users ha sudo capabilities

If you regularly install packages, add them to the GitHub Actions

workflow so they are installed every
time the en starts up
- The default packages that are installed in the en can be
here

<details>

<summary><b>Graphical Server</b></summary>

Don't use the graphical workflow unless absolutely necessary!

0. Create a repo from the
template. Many of
the following links will only work from within your copy of the repository.
Creating a copy only works for users logged into GitHub.
1. Sign up for ngrok.
2. Copy your ngrok
Authtoken.
3. Na to the "Run Graphical RDP CTF En (Ubuntu GNOME)"
workflow").
4. Paste in your ngrok Authtoken when you start the ser the button in
the top right ("Run workflow").
- To avoid pasting the Authtoken every time, paste it into a secret called
NGROK_TOKEN under the Secrets settings
area. It will be saved here and used automatically.
5. View the output; wait for it to print the connection information.
6. Connect to the HTTP link in your browser or paste the connection link into
your remote desktop (RDP)
client.
- On Windows, press the start button and search for "Remote Desktop
Connection" – the client should be installed by default.
- On Linux Remmina is a
well-regarded RDP client.

</details>

Who This Project is For

This project is for those with limited access to compute resources – students
in particular. By making it possible to connect from the web and over Tor, the
project is designed to be accessible to those who are behind a firewall and/or
are unable to install software on the computer they are using. For example,
someone who wants to participate in a CTF competition, but is using
shared computers in a library or a school computer lab.

Be a Good Citizen

This project uses generously-offered, free resources in a way that was likely
not intended by GitHub. Please do not abuse them.

I claim no responsibility for how you use this project. Based on my reading of
GitHub's:

Terms of

Service

Acceptable Use

Policy

and Actions Usage

Policy

I ha that using this Actions workflow to do productive work,
particularly if you don't have the ability to run a Linux computer of your own,
is probably permissible if done in good faith, and with an effort made to
reduce excessi consumption. For example, don't use the graphical
workflows unless absolutely necessary, because they are considerably more
resource intensive to set up and run, and don't leave the workflows running
when not using them.

That being said, I may be reading the policies wrong, and GitHub has the right
to change them at any time. In particular, if this use of GitHub Actions is
abused, it is likely that future ability to do things like this will be limited
by GitHub. If you like it, don't ruin it for others.

Note: typical users get 3,000 minutes of private Actions
time
per month per user. This project can quickly run up that time if you are not
careful. Check your own usage here to
see how close to the limit you are. Also note that actions stop automatically
after 6 hours.

Known Issues

Problem: Tor browser loads the hidden service indefinitely, never

connecting

Solution: Restart Tor browser

Problem: The web interface text is illegible when using Tor browser or

Firefox

Solution: Disable the privacy.resistFingerprinting setting in
about:config

Problem: The "Display connection info and sleep" workflow step fails when

trying to display ngrok connection information

Solution: The ngrok authtoken supplied either as input to the workflow,
or as a repository secret is invalid or corrupted

Problem: Connecting to the ser SSH over Tor fails

Solution: Make sure Tor browser is running while the command is run. If
it is still not working, try the command on port 9050 instead of 9150

Problem: Tor fails to bind to the port when running the workflow

Solution: Run the action again. If it continues to fail, open an
issue

Problem: The web interface does not work with tor2web sites like

tor2web.io or onion.sh

Solution: Use Tor browser and do not use tor2web sites

How to Read This Code

The vast majority of the code is contained in a single, primary GitHub

Actions workflow, which sets up the
en and displays connection details to the user. This file is fairly
well-commented, and most design decisions should ha justification.
For readability, I have
tried to use long command-line options where possible. There may be more
information in the commit history, for example this
commit
justifies switching from tmate.io to ngrok and Tor.

The dotfiles directory contains configuration files for many

programs running in the collaborati.
- install.sh copies dotfiles to the proper
locations
- .tmux.conf contains custom shortcuts for tmux
- .bashrc is pretty minimal, but contains a few
useful command aliases
- ttyd_run.sh is run every time a new user
connects via SSH or the Web interface and is responsible for opening a new
tmux session that uses one common set of windows for all clients

Acknowledgments

Thanks to my good friend Logan Snow ()
for testing, fixing bugs, and other contributions!

This project makes use of several great software packages that have made their
services a for free:

Tor

ngrok

ttyd

tmux

GitHub Actions

项目信息

开发语言：Shell

Star 数：73

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Collaborative programming environment inside GitHub Actions – like Google Docs for hacking展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。