# stypr/flagchecker architecture

> Architecture diagram of the GitHub repository stypr/flagchecker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stypr/flagchecker
- Repository: https://github.com/stypr/flagchecker

## Overview

##### Project Type and Purpose
- The project is an anti-cheating tool for CTFs that uses a Linux Kernel Module (LKM) to hook the read() syscall. When flagged data is detected, it modifies the flag’s content by generating a random value to thwart cheating. This modified flag is then recorded by a separate flag server.
- The README emphasizes its use in Docker-based CTF setups, meaning that the architecture should highlight how host-level kernel hooks influence containerized applications.

##### Analyzing the File Structure
- Top-level directories include:
- “flagchecker” – Contains the LKM source (flagchecker.c), build script (build.sh), flag-generation script (generate_flag.py), and test scripts.
- “flagserver” – Contains the flag management server, including a docker-compose file for deployment, and web interface files (index.php, database.sql, etc.).
- “docs” – Documentation and examples of usage.
- The structure indicates two almost independent components:
- The flagchecker (LKM) integrates deeply with the host kernel, intercepting syscalls and triggering flag updates.
- The flagserver (a Docker-based web service) receives, stores, and possibly displays the new flag values.

a. Main Components:
- Host Operating System: illustration of the underlying Linux kernel that will host the kernel module.
- Kernel Module (flagchecker): the LKM that hooks the read() syscall.
- Docker Containers: since the README describes how Docker containers are impacted by the host kernel-level modifications.
- Flag Server (flagserver): the component that manages the generation and registration of new flags, including its web interface and database.
- Utility Scripts & Test Tools: representing tools such as generate_flag.py and the test scripts that validate the LKM behavior.

b. Determining Relationships and Interactions:
- The flagchecker installs on the host system and intercepts read() calls. This component communicates with user-space scripts (via generate_flag.py) to log a flag change.
- On detection of a flagged syscall, an event is triggered that leads to the flagchecker executing the script to contact the flagserver.
- The flagserver, running likely in its own container (with docker-compose), receives these flag registration updates and possibly logs them as part of a scoreboard or detection mechanism.
- The Docker containers share the host kernel, thus even containerized applications are indirectly affected by flagchecker’s behavior.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The kernel module handles low-level syscall interception, while the flagserver manages application logic for logging and scorekeeping.
- Host-Container Interaction: Since the kernel module affects all containers on the host, include a layer that represents the impact on isolated Docker environments.
- Modularity: Keeping the LKM, user-space flag-generation script, and flagserver independent simplifies testing and future updates.

d. Relevant Technologies and Frameworks:
- LKM development using C (flagchecker.c).
- Python scripting for flag generation (generate_flag.py).
- PHP or similar (via index.php in flagserver/web) for the flag management web interface.
- Docker and docker-compose configuration reflecting container orchestration.
- A possible SQL database for flag records (as indicated by database.sql in flagserver/web).

##### Specific Elements
- Clear Labels: Each component (e.g., "Linux Kernel", "Flagchecker LKM", "generate_flag.py", "Docker Container", "Flagserver Web Service", "Database") should be clearly labeled.
- For example, circles for kernel components, rectangles for web services/components, and clouds for Docker infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Kernel/Host Layer"
        LK["Linux Kernel"]:::kernel
        FC["Flagchecker LKM"]:::kernel
        BS["Build Script"]:::script
        LK -->|"hosts"| FC
        BS -->|"builds"| FC
    end

    subgraph "Container Layer"
        DC["Docker Containers"]:::container
        RS["read()_syscall(in container)"]:::container
        DC -->|"utilizes"| LK
        RS -->|"intercepts"| FC
    end

    subgraph "User-Space Layer"
        GF["generate_flag.py"]:::script
        FS["Flagserver Web Service"]:::web
        DB["Database"]:::database
        TT["Test Tools(flag.php)"]:::test
        FC -->|"triggers"| GF
        GF -->|"updates"| FS
        FS -->|"logs_to"| DB
        TT -->|"validates"| FC
    end

    subgraph "Documentation"
        DOC["Usage Docs"]:::docs
    end

    classDef kernel fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef container fill:#ccffcc,stroke:#00cc00,stroke-width:2px;
    classDef script fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef web fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef database fill:#ccffff,stroke:#00cccc,stroke-width:2px;
    classDef test fill:#ffccff,stroke:#cc00cc,stroke-width:2px;
    classDef docs fill:#e0e0e0,stroke:#999999,stroke-width:2px;

    click FC "https://github.com/stypr/flagchecker/blob/main/flagchecker/flagchecker.c"
    click BS "https://github.com/stypr/flagchecker/blob/main/flagchecker/build.sh"
    click GF "https://github.com/stypr/flagchecker/blob/main/flagchecker/generate_flag.py"
    click TT "https://github.com/stypr/flagchecker/blob/main/flagchecker/test/flag.php"
    click FS "https://github.com/stypr/flagchecker/blob/main/flagserver/docker-compose.yml"
    click FS "https://github.com/stypr/flagchecker/tree/main/flagserver/web"
    click DOC "https://github.com/stypr/flagchecker/tree/main/docs"
```
