Project Architecture: AI-Enhanced CTF Toolchain

This document describes the current architecture, directory layout, core modules, and testing setup of the CTF Toolchain project.

1. Directory Structure

The project follows a standard modern Python layout (utilizing src/ directory layout) and is managed via the uv toolchain.

├── config.toml           # Mock/Default configuration for local testing
├── pyproject.toml        # Hatchling build configuration & project dependencies
├── uv.lock               # uv lockfile for exact dependency resolution
├── src/
│   └── ctf/
│       ├── __init__.py   # Module initializer
│       ├── main.py       # CLI Entry Point
│       ├── commands.py   # CLI Commands and action functions
│       ├── utils.py      # Core utility functions (file parsing, config, paths)
│       └── forensics.py  # Placeholder for future forensics analysis tools
└── tests/
    ├── env/              # Sandboxed, persistent test environment directories
    └── test_utils.py     # Unit/Integration tests for utility functions

2. Core Modules & Configuration

A. Configuration & State (config.toml)

The toolchain requires configuration of directories and active challenges:

Competition: Keeps track of the current producer, competition, category, and challenge.
Environment: Declares the base directory (ctf_dir) where all CTF files are stored.

B. Utilities (utils.py)

Provides helper functions for filesystem management and configuration parsing:

load_config(path): Loads and parses configuration data from a TOML file.
write_config(data, path): Serializes/updates a dictionary to a TOML file.
active_categories(path): Iterates over a competition path to return all active categories.
active_competitions(dir): Scans the base directory for active competitions, skipping designated helper directories (like tools).

C. Commands (commands.py)

Houses the logic for each CLI command action:

test(): A simple hello-world tester.
Set_Challenge(comp, chal, setDirectory): Sets the current active challenge/competition context. (Note: Currently has a NameError due to reference to an undefined state object.)

3. CLI Entry Point (main.py)

Currently acts as a simple entry point calling commands.test().
Uses click as the planned framework to build a sub-command CLI system (ctf test, ctf set-challenge, etc.).

4. Test Infrastructure

Framework: pytest (run via uv run pytest).
Sandbox: tests/env acts as a persistent mock directory tree containing temporary competition directories (like comp1, comp2) to safely test category scanning and config loading/saving without touching actual user data.

3.0 KiB Raw Blame History