Secure Exam Client (PeP.ExamApp) Architecture
Relevant source files
The following files were used as context for generating this wiki page:- PeP.ExamApp/MainWindow.xaml.cs
- PeP.ExamApp/ExamModeManager.cs
- PeP.ExamApp/ExamAppState.cs
- PeP.ExamApp/Pages/ExamRunnerPage.xaml.cs
- PeP.ExamApp/NativeMethods.cs
- PeP.ExamApp/ExamAppApiClient.cs
- Controllers/ExamAppController.cs
- PeP.ExamApp/Pages/AntiCheatPage.xaml.cs
- Models/ExamAppModels.cs
- PeP.ExamApp/Installer/README.md
The PeP.ExamApp is a secure desktop client built with WPF, designed to create a controlled and locked-down environment for students taking exams. Its primary purpose is to prevent cheating by restricting access to the local file system, other applications, and unauthorized web resources during an exam session. The application integrates with the main PeP web platform, rendering the exam content within a hardened WebView2 control while enforcing strict security policies through native Windows API calls.
This architecture ensures the integrity of the examination process by taking full control of the user's machine from the moment an exam is authorized until it is submitted. The application follows a multi-stage process including student login, exam code validation, teacher authorization, system security checks, and finally, the locked-down exam session.
Core Components
The client application is built around several key classes that manage its state, security, and communication with the backend.
This diagram shows the relationships between the main components of the PeP.ExamApp.
MainWindow: The main application window and entry point. It hosts theFramefor page navigation and orchestrates the application's lifecycle, including entering and exiting the secure exam mode.- Sources: PeP.ExamApp/MainWindow.xaml.cs
ExamAppState: A central class that holds the application's state throughout the user's session. This includes server details, authentication tokens, exam information, and API client instances. It acts as a shared context between different pages.- Sources: PeP.ExamApp/ExamAppState.cs
ExamModeManager: The core of the security system. This class is responsible for entering and exiting the locked-down exam mode. It uses low-level Windows hooks viaNativeMethodsto block system keys, prevent task switching, and enforce a fullscreen, topmost window state.- Sources: PeP.ExamApp/ExamModeManager.cs
ExamAppApiClient: A client for communicating with the backend PeP server's API. It handles login, fetching exam data, authorization, and starting the exam session.- Sources: PeP.ExamApp/ExamAppApiClient.cs
NativeMethods: A static class containing P/Invoke definitions for the Windows API functions required for system lockdown.- Sources: PeP.ExamApp/NativeMethods.cs
Application Flow and State Management
The application guides the user through a specific sequence of pages to ensure all prerequisites for a secure exam are met. The ExamAppState object persists state across these pages.
Page Navigation Flow
The diagram below illustrates the user's journey from launching the app to starting the exam.
- Connect/Login: The user provides the server URL and logs in.
- Exam Code: The user enters an exam code, which is validated against the server.
- Teacher Authorization: A teacher must enter their password to authorize the exam session for the student.
- Tutorial & Anti-Cheat: The user is shown instructions and the system undergoes a series of security checks.
- Exam Runner: If all checks pass, the
ExamRunnerPageis loaded,ExamModeManageris activated, and the exam content is displayed in aWebView2control.
Exam Authorization and Launch
The process of starting an exam involves a secure handshake between the client and the server to issue short-lived tokens.
This sequence diagram shows the API calls involved in authorizing and starting an exam.
Authorization Models
The authorization flow relies on several key data models stored in the database.
| Model | Purpose | Key Fields |
|---|---|---|
ExamAppAuthorization | Represents a teacher's approval for a student to take an exam. A hash of the generated token is stored. | StudentId, ExamCodeId, TokenHash, ExpiresAt, AuthorizedByTeacherId |
ExamAppLaunchSession | Represents a valid, started exam session. This is created after the AuthorizationToken is consumed. | ExamAttemptId, StudentId, TokenHash, ExpiresAt |
Sources: Models/ExamAppModels.cs
Secure Exam Mode (ExamModeManager)
The ExamModeManager is responsible for the core security lockdown of the client machine. It uses P/Invoke calls to the Windows API to enforce restrictions.
Sources: PeP.ExamApp/ExamModeManager.cs, PeP.ExamApp/NativeMethods.cs
Key Security Features
| Feature | Implementation | Native Method(s) Used |
|---|---|---|
| Keyboard Blocking | A low-level keyboard hook (WH_KEYBOARD_LL) intercepts and blocks prohibited key combinations system-wide. | SetWindowsHookEx, CallNextHookEx, UnhookWindowsHookEx |
| Focus Lock | A WinEventHook listens for EVENT_SYSTEM_FOREGROUND and forces the exam window back to the front if focus is lost. | SetWinEventHook, SetForegroundWindow, BringWindowToTop |
| Taskbar Hiding | Hides the main Windows taskbar and Start button. | FindWindow, ShowWindow |
| Fullscreen Enforcement | The window is made borderless and sized to cover the entire primary screen. | SetWindowPos |
| Anti-Screen Capture | Sets a display affinity on the window to prevent most screen recording and screenshot tools from capturing its content. | SetWindowDisplayAffinity (WDA_MONITOR) |
| Clipboard Control | A listener is attached to clear the clipboard whenever its content changes. | AddClipboardFormatListener, EmptyClipboard |
| Closing Prevention | The Window.Closing event is cancelled while exam mode is active, preventing the user from closing the app. | N/A (WPF event handling) |
Sources: PeP.ExamApp/ExamModeManager.cs, PeP.ExamApp/MainWindow.xaml.cs:214-224, PeP.ExamApp/NativeMethods.cs
Blocked Keyboard Shortcuts
The following key combinations are blocked by the low-level keyboard hook:
Alt + Tab(Task switching)Alt + F4(Close application)Ctrl + Esc(Open Start Menu)Left/Right Windows KeyPrint Screen / SnapshotCtrl + Shift + Esc(Task Manager)Ctrl + Alt + Del(Blocked by GPO, but hook is a fallback)- Various function keys like
F1,F11, etc.
Sources: PeP.ExamApp/ExamModeManager.cs:140-184, PeP.ExamApp/NativeMethods.cs:100-117
Anti-Cheat System
Before the exam can be launched, the AntiCheatPage performs a series of automated checks on the system's configuration.
This diagram outlines the security checks performed before an exam can be launched.
The checks are performed by the SecurityChecks.RunFullSecurityCheck() method, and the UI is updated to reflect the status of each check. If blacklisted processes are found, the user is given an option to try and close them automatically via SecurityChecks.KillBlacklistedProcesses().
Sources: PeP.ExamApp/Pages/AntiCheatPage.xaml.cs:72-149
Exam Execution and WebView2 Hardening
The actual exam is a web page loaded from the PeP server into a Microsoft.Web.WebView2.Wpf.WebView2 control on the ExamRunnerPage. To maintain the secure environment, this control is heavily restricted.
The HardenWebView2 method applies the following settings:
AreDevToolsEnabled = falseAreDefaultContextMenusEnabled = falseAreBrowserAcceleratorKeysEnabled = falseIsStatusBarEnabled = false- Downloads, popups, and new windows are blocked.
- Permissions for clipboard, camera, and microphone are denied.
- Navigation is restricted to the original server's domain only.
Sources: PeP.ExamApp/Pages/ExamRunnerPage.xaml.cs:161-210
Digital Watermark
To discourage photos or external recordings of the screen, a semi-transparent watermark is overlaid on top of the entire application. The watermark contains the student's email, the current attempt ID, the machine name, and a timestamp.
Sources: PeP.ExamApp/Pages/ExamRunnerPage.xaml.cs:212-251
Deployment and Auto-Updates
The PeP.ExamApp is deployed as a self-contained executable installer built using Inno Setup.
Installer Build Process
A PowerShell script, build-installer.ps1, automates the creation of the installer.
- Updates the version number in the
.csprojfile. - Publishes the WPF application using
dotnet publish. - Updates the version in the Inno Setup script (
.iss) file. - Compiles the installer using the Inno Setup command-line compiler (
ISCC.exe). - Generates a SHA256 checksum for the final installer executable.
Sources: PeP.ExamApp/Installer/build-installer.ps1
Auto-Update Mechanism
The application can update itself by checking an API endpoint on the server.
- Endpoint:
GET /api/exam-app/update - Function: The client sends its
currentVersionas a query parameter. The server responds with JSON containing the latest version information if an update is available. - Server Configuration: The update information is stored in the server's
appsettings.jsonfile under theExamAppUpdatesection.
Sources: Controllers/ExamAppController.cs:29-50, PeP.ExamApp/Installer/README.md
The response payload includes the new version number, a download URL for the installer, release notes, and a checksum for verification.
{
"version": "1.1.0",
"downloadUrl": "https://yourserver.com/downloads/PeP.ExamApp_Setup_1.1.0.exe",
"releaseNotes": "- Bug fixes\n- Performance improvements",
"releaseDate": "2025-12-22T00:00:00Z",
"isMandatory": false,
"minimumVersion": "1.0.0",
"checksum": "sha256hashhere"
}
Sources: PeP.ExamApp/Installer/README.md