Skip to content

Latest commit

 

History

History
174 lines (134 loc) · 4.59 KB

README.md

File metadata and controls

174 lines (134 loc) · 4.59 KB

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"
)
  1. 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:

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.