CTF-tool/ARCHITECTURE.md

Project Architecture: AI-Enhanced CTF Toolchain

This document describes the architecture, directory layout, core modules, testing setup, and planned components 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  # 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 generic CLI context and active competition commands:

• 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.)

D. Forensics (forensics.py)

Implements specialized forensic inspection utilities registered as a nested subgroup under the CLI:

• info: Inspects target file sizes, reads magic bytes, and warns if extensions do not match detected signatures.
• flag-search: Extracts printable string sequences (equivalent to GNU strings) and matches them against regular expression patterns to find potential flags.

---

3. CLI Entry Point (main.py)

• Serves as the central CLI entry point via the main() function.
• Initializes the root Click cli group and registers nested sub-groups, such as forensics_group.

---

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) and mock files (e.g. valid PNGs, mismatching PDFs, text files with flag payloads) to safely test scanning, parsing, and CLI command execution without touching actual user data.

---

5. Planned Architectural Components

A. File Scraper & Extended Configuration

• A scraping module to fetch details/files for challenges or competitions.
• Integration with an expanded configuration schema in config.toml to store credentials, URLs, and directory preferences.

B. Download Organizer & Challenge Progress Documenter

• Monitoring or organizing downloaded challenge assets (e.g., from the browser's downloads folder) and sorting them into the correct competition/challenge subdirectories.
• An automated mechanism to log commands, notes, and milestones, providing clean progress documentation.

C. Forensics Metadata Expansion

• Extend forensics capabilities inside forensics.py to extract file-specific metadata (e.g., EXIF header extraction for JPG/PNG files, archive contents listing, and PE section analysis).

---

6. CLI Data Flow & Presentation Guidelines

A. Model-View Separation

All CLI command modules (such as forensics.py) must separate data extraction logic from command-line rendering.

• Data Models: Standard Python @dataclass objects should be defined to house parsed metadata (e.g., file size, magic bytes, detected types, warnings, and format-specific attributes).
• Decoupled Parsers: Extraction helper functions must return these dataclass instances instead of printing directly to standard output. This keeps the core parser functions purely functional and fully testable in unit tests.

B. Console Rendering with rich

To provide a clean, modern, and easily readable console output without building a full terminal user interface (TUI):

• Tables: Use rich.table.Table to align and structure multi-column metadata outputs.
• Formatting & Alerts: Utilize rich.console or rich.panel.Panel to highlight warnings (such as signature/extension mismatches) with distinct styling and colors.
• JSON Serialization: Dataclasses should be easily convertible to dictionaries to support raw JSON output options for scripting pipelines.