README.md

pwncore

A CTF platform backend written in FastAPI using Tortoise-ORM, Tox and Pydantic

Table of Contents

1. TODO
2. Prerequisites
3. Installation
4. Usage
5. Project Structure
6. Documenting
7. Contributing
8. License

TODO

• Remove round2 logic and paths
• feat: Power ups
• fix: Leaderboard caching error
• Issue identification and Bug fixes
• Setup tests using tox
• feat: Leaderboard graph

Prerequisites

Before you begin, ensure you have met the following requirements:

• Python 3.7+
• Docker (optional, for container functionality)

Installation

1. Clone the repository (or a fork of the repository):

   git clone https://github.com/lugvitc/pwncore.git
   cd pwncore

2. Set up a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate

3. Install Poetry and project dependencies:

   pip install poetry
   poetry install

4. Configure the project:

   • Open src/pwncore/config.py
   • Set db_url to a path for persistent storage or continue with in-memory database
   • Configure docker_url as needed (see Usage for details)

Usage

1. Start:

   cd src
   uvicorn pwncore:app --reload

2. Access the auto-generated documentation at http://localhost:8000/docs

3. Docker configuration:

   • Enable and start the Docker service on your system, or
   • Modify src/pwncore/config.py:62:

	docker_url="http://google.com",  # For testing without Docker

Project Structure

.
├── Dockerfile
├── LICENSE
├── OVERVIEW.md
├── poetry.lock
├── poetry.toml
├── pyproject.toml
├── README.md
├── src
│   └── pwncore
│       ├── config.py
│       ├── container.py
│       ├── docs.py
│       ├── __init__.py
│       ├── __main__.py
│       ├── models
│       │   ├── container.py
│       │   ├── ctf.py
│       │   ├── __init__.py
│       │   ├── pre_event.py
│       │   ├── round2.py
│       │   └── user.py
│       ├── py.typed
│       ├── routes
│       │   ├── admin.py
│       │   ├── auth.py
│       │   ├── ctf
│       │   │   ├── __init__.py
│       │   │   ├── pre_event.py
│       │   │   └── start.py
│       │   ├── __init__.py
│       │   ├── leaderboard.py
│       │   ├── round2.py
│       │   └── team.py
│       └── types.py
├── tests
│   ├── __init__.py
│   └── test_login.py
└── tox.ini

7 directories, 32 files

Documenting:

FastAPI generates documentation for the routes using OpenAPI. The documentation is available by default at /docs (Swagger UI) and /redoc (ReDoc).

There are 2 ways to add documentation for a route:

1. Explicitly mention the summary and description:

@router.get("/start/{ctf_id}",
    description="This description supports **Markdown**.",
    summary="Start the docker container"
)

2. Let it infer summary from function name and description from comments:

@router.get("/start/{ctf_id}")
async def start_the_docker_container(ctf_id: int):       # The function name is inferred for the summary
    # This is a regular single-line comment.
    # Will not be displayed in the documentation.
    '''
    This is a multi-line comment, and will be displayed
    in the documentation when the route is expanded.

    The cool thing is that Markdown works here!
    # See, Markdown works!
    _Pretty_ **cool** right?
    '''
    return {"status": "CTF started"}

Result:

Contributing

Follow the following steps while working on the platform

1. Fork the repository
2. Create your feature branch (git checkout -b feature/functionality)
3. Commit your changes (git commit -m 'Add some functionality'). Go through CONTRIBUTING for preferred commit messages
4. Push to the branch (git push origin feature/functionality)
5. Open a Pull Request

License

This project is licensed under the [GNU GENERAL PUBLIC LICENSE] - see the LICENSE file for details.