diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..a8e109d --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,60 @@ +# 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. + +```text +├── 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](file:///home/venus/code/ctf/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](file:///home/venus/code/ctf/src/ctf/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](file:///home/venus/code/ctf/src/ctf/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](file:///home/venus/code/ctf/src/ctf/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](file:///home/venus/code/ctf/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. diff --git a/README.md b/README.md index c44bb42..30c10dd 100644 --- a/README.md +++ b/README.md @@ -33,3 +33,6 @@ the end goal is to create a methodology solid enough to build out a full AI tool - Cyberchef like decoding and magic feature - regexing input text for flag - flag selection and filtering with remembered prev. flags +# Tools +- forensics + - forensics tool for basic file analysis diff --git a/pyproject.toml b/pyproject.toml index 3f27b19..5492940 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,6 +7,7 @@ requires-python = ">=3.14" dependencies = [ "platformdirs>=4.9.4", "toml>=0.10.2", + "click", ] [build-system] diff --git a/src/ctf/commands.py b/src/ctf/commands.py index 1460ac2..a7ee252 100644 --- a/src/ctf/commands.py +++ b/src/ctf/commands.py @@ -1,9 +1,12 @@ # functions for commands needed # src/commands.py -from pathlib import path +# from pathlib import path +import click +@click.command() def test(): print("hello from test") + def Set_Challenge(comp: str, chal: str, setDirectory: bool): # set the current challenge and competition from input if state.current_comp != comp: diff --git a/src/ctf/main.py b/src/ctf/main.py index 6446630..73a88c0 100644 --- a/src/ctf/main.py +++ b/src/ctf/main.py @@ -1,27 +1,11 @@ # src/main.py # Parses and calls commands -import argparse -from os import setregid -from pathlib import Path -from ctf.utils import * - -def set_arguments(): - parser = argparse.ArgumentParser( #type:ignore - prog="ctf", - description="A collection of cli tools to improve your ctf workflow", - epilog="") - parser.add_argument('action') # positional argument, action to be taken - parser.add_argument('-c', '--count') # option that takes a value - parser.add_argument('-v', '--verbose', action='store_true') # on/off flag - args = parser.parse_args() - return args - +import ctf.commands as commands def main(): - args = set_arguments() - print(args) + commands.test() diff --git a/uv.lock b/uv.lock index 942cc0e..635e861 100644 --- a/uv.lock +++ b/uv.lock @@ -2,6 +2,18 @@ version = 1 revision = 3 requires-python = ">=3.14" +[[package]] +name = "click" +version = "8.4.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama", marker = "sys_platform == 'win32'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/76/d4/81420972a676e8ffea40450d8c8c92943e7218a78fe9b64359836cc9876b/click-8.4.2.tar.gz", hash = "sha256:9a6cea6e60b17ebe0a44c5cc636d94f09bd66142c1cd7d8b4cd731c4917a15f6", size = 338000, upload-time = "2026-06-24T17:45:15.148Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fb/e2/79c688af8b210d232694e31e59da9f6ec747bae31c3f5946e4e9b98860d5/click-8.4.2-py3-none-any.whl", hash = "sha256:e6f9f66136c816745b9d65817da91d61d957fb16e02e4dcd0552553c5a197b76", size = 119243, upload-time = "2026-06-24T17:45:13.73Z" }, +] + [[package]] name = "colorama" version = "0.4.6" @@ -16,6 +28,7 @@ name = "ctf" version = "0.1.0" source = { editable = "." } dependencies = [ + { name = "click" }, { name = "platformdirs" }, { name = "toml" }, ] @@ -27,6 +40,7 @@ dev = [ [package.metadata] requires-dist = [ + { name = "click" }, { name = "platformdirs", specifier = ">=4.9.4" }, { name = "toml", specifier = ">=0.10.2" }, ]