SecureExam-Generator

Overview

SecureExam-Generator is a Python CLI tool that produces tamper-proof, cryptographically verifiable exam papers. Each output PDF is uniquely bound to a specific student via an embedded QR code and a per-institution filigree watermark pattern — making unauthorized duplication or content substitution immediately detectable without any server infrastructure.

The tool is fully offline-first. Verification requires no internet connection, no proprietary software, and no subscription. An examiner with the original question bank and the student's sheet can verify integrity in under three seconds.

How It Works

Each exam sheet is generated through a three-stage pipeline built on deterministic hashing — the same cryptographic primitives that underpin version control and blockchain consensus, applied to educational document integrity:

1. Shuffle and seed. Questions are drawn from the question bank and shuffled using a deterministic PRNG seeded with a hash of (student_id + exam_id + secret_salt). The same seed always produces the same ordering — shuffle is verifiable, not random noise.
2. Hash and encode.A SHA-256 digest is computed over the ordered question set and the student metadata. This hash is encoded into a QR code and embedded in the header of the PDF, alongside the student's name and exam ID.
3. Watermark and render. A custom filigree pattern — supplied per institution as an SVG or raster asset — is composited beneath the content layer at low opacity. The watermark encodes institutional identity without obscuring readability.

Verification works in reverse: recompute the hash from the question bank and student ID, compare against the QR code. Any modification to the printed content — a changed question, a reordered answer, a replaced image — produces a different hash and fails verification instantly.

Features

• Per-student deterministic question ordering (reproducible shuffle)
• SHA-256 content hash embedded as QR code in the document header
• Configurable filigree watermark per institution (SVG or PNG)
• Batch generation — an entire class cohort in a single CLI invocation
• Question bank defined in YAML — structured, version-controllable, diffable
• Offline verification — no server, no API, no dependency on external services
• Answer key generation with the same shuffle seed for fast grading

Tech Stack

The tool is built in Python 3 with a deliberately small dependency surface to keep it auditable and portable. The full source is on GitHub, and the development environment is documented in /uses.

• reportlab — programmatic PDF generation with precise layout control for headers, question blocks, and answer grids
• qrcode — QR encoding of the SHA-256 hash; version and error correction level are configurable
• Pillow — watermark compositing; handles both SVG-rasterized and native raster inputs with opacity control
• PyYAML — question bank parsing; supports multi-line questions, image references, and metadata tags
• argparse — CLI interface with subcommands for generate, verify, and batch
• hashlib (stdlib) — SHA-256 digest; no third-party cryptography dependency

Usage

Generating a single exam sheet:

python secureexam.py generate \
  --bank questions.yaml \
  --student-id A2024001 \
  --exam-id MATH101-FINAL \
  --watermark logo.png \
  --out exams/

Batch generation for an entire class roster:

python secureexam.py batch \
  --bank questions.yaml \
  --roster students.csv \
  --exam-id MATH101-FINAL \
  --watermark logo.png \
  --out exams/ \
  --jobs 4

Verifying a printed sheet (after scanning the QR code):

python secureexam.py verify \
  --bank questions.yaml \
  --student-id A2024001 \
  --exam-id MATH101-FINAL \
  --hash 3a7f9c2b...

Motivation

Exam fraud is a persistent problem in educational institutions. The existing tools that address it fall into two categories: expensive proprietary platforms with vendor lock-in, or ad-hoc solutions (coloured paper, sequential numbering) that provide no cryptographic guarantee.

The problem space was shaped by conversations within the Turkish Informatics Association, where educators consistently raised concerns about document integrity and the cost of existing solutions. SecureExam-Generator was built to be free, offline, and auditable — prioritizing trust through transparency rather than obscurity.

The deterministic shuffle algorithm uses the same principles documented in my garden note on SHA-256 deterministic shuffling — a technique where a cryptographic hash function produces a repeatable-yet-unpredictable ordering. The formal reasoning behind why this approach guarantees fairness connects directly to concepts from mechanism design.

For a complementary approach to document tooling focused on capture and collaboration rather than security, see NotePadIo.

Related Concepts

This project connects to several ideas explored elsewhere in this garden:

• SHA-256 Deterministic Shuffle — the core algorithm behind per-student question ordering
• Mechanism Design — formal frameworks for designing tamper-resistant systems
• Turkish Informatics Association — where the problem space was first identified