cipher-security 2.1.0 → 2.2.0

package/lib/benchmark/overthewire.js

@@ -0,0 +1,347 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * OverTheWire — Challenge loader for the OverTheWire wargames.
+ *
+ * OverTheWire hosts SSH-based wargames with progressive difficulty levels.
+ * Each level requires solving the current challenge to obtain the password
+ * for the next level.
+ *
+ * Supported wargames:
+ * - Bandit (34 levels) — Linux basics, SSH, file operations
+ * - Natas (34 levels) — Server-side web security
+ * - Leviathan (8 levels) — Binary exploitation basics
+ * - Krypton (7 levels) — Classical cryptography
+ * - Narnia (10 levels) — Basic exploitation
+ *
+ * @module benchmark/overthewire
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { BenchmarkConfig } from './models.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const OTW_DATA_DIR = join(homedir(), '.cipher', 'benchmarks', 'overthewire');
+export const OTW_PROGRESS_FILE = join(OTW_DATA_DIR, 'progress.json');
+
+export const OTW_HOST = 'bandit.labs.overthewire.org';
+export const OTW_BASE_DOMAIN = 'overthewire.org';
+
+/** OverTheWire wargame definitions. */
+export const OTW_WARGAMES = {
+  bandit: {
+    name: 'Bandit',
+    host: 'bandit.labs.overthewire.org',
+    port: 2220,
+    levels: 34,
+    category: 'general-skills',
+    description: 'Linux command line basics — files, permissions, SSH, networking',
+    startPassword: 'bandit0',
+    levelDescriptions: [
+      'Read the readme file in the home directory.',
+      'Find the password in a file with dashes in the name.',
+      'Find the password in a hidden file.',
+      'Find the human-readable file among several files.',
+      'Find the only human-readable, non-executable, 1033-byte file.',
+      'Find the file owned by a specific user and group.',
+      'Find the file somewhere on the server with specific properties.',
+      'Find the password in a file among lines of text.',
+      'Find the unique line that occurs only once in the file.',
+      'Find the base64-encoded password in data.txt.',
+      'Decode the ROT13 encoded password.',
+      'Decode the hexdump to extract the password.',
+      'Decompress a series of compressed files.',
+      'Use the SSH key to connect to the next level.',
+      'Retrieve the password using the setuid binary with a port argument.',
+      'Record the password by submitting the current password to a port.',
+      'Read the password from /etc/bandit_pass/ using the setuid binary.',
+      'Use the setuid binary with a correct command to read the password.',
+      'Find the cron job and trace it to the password.',
+      'Analyze the cron job script to find the password.',
+      'Analyze the cron job that generates a password based on date.',
+      'Use a shell escape in a setuid program.',
+      'Use the daemon listening on localhost to get the next password.',
+      'Brute-force or script the daemon with port and password.',
+      'Crack the encrypted key using SSH agent forwarding.',
+      'Use the git repository to find the password.',
+      'Navigate git history to find the password.',
+      'Explore git tags and branches for the password.',
+      'Exploit a setuid script that doesn\'t sanitize input properly.',
+      'Read the password with a race condition.',
+      'Write a shell script to exploit the setuid binary.',
+      'Network service exploitation.',
+      'Advanced git exploration.',
+      'Final bandit level.',
+    ],
+  },
+
+  natas: {
+    name: 'Natas',
+    host: 'natas0.natas.labs.overthewire.org',
+    port: 80,
+    levels: 34,
+    category: 'web-exploitation',
+    description: 'Server-side web security — source disclosure, injection, auth bypass',
+    startPassword: 'natas0',
+    levelDescriptions: [
+      'View page source to find the password.',
+      'Find the password in the page source.',
+      'Find the hidden page listed in robots.txt.',
+      'Find the password in the page source of a hidden page.',
+      'Bypass server-side access control.',
+      'Include a remote/local file to read the password.',
+      'Exploit an input validation flaw.',
+      'Use directory traversal to read files.',
+      'Exploit a weak session or authentication mechanism.',
+      'Find secret data in server source code.',
+    ],
+  },
+
+  leviathan: {
+    name: 'Leviathan',
+    host: 'leviathan.labs.overthewire.org',
+    port: 2223,
+    levels: 8,
+    category: 'binary-exploitation',
+    description: 'Basic exploitation — setuid, ltrace, simple buffer overflows',
+    startPassword: '',
+    levelDescriptions: [
+      'Find the hidden directory and decode the bookmarks file.',
+      'Use ltrace to find the password checked by the setuid binary.',
+      'Exploit the setuid binary to read the password file.',
+      'Trick the binary with a symlink.',
+      'Disassemble or trace the binary for the password.',
+      'Run the setuid binary correctly to get the password.',
+      'Use the binary with a specific trick.',
+      'Final leviathan level.',
+    ],
+  },
+
+  krypton: {
+    name: 'Krypton',
+    host: 'krypton.labs.overthewire.org',
+    port: 2231,
+    levels: 7,
+    category: 'cryptography',
+    description: 'Classical cryptography — Caesar, Vigenère, frequency analysis',
+    startPassword: 'KRYPTONISGREAT',
+    levelDescriptions: [
+      'Decode base64.',
+      'Decrypt ROT13 / Caesar cipher.',
+      'Break a Caesar cipher with known plaintext.',
+      'Break a Vigenère cipher.',
+      'Exploit a stream cipher.',
+      'Break a more complex cipher.',
+      'Final krypton level.',
+    ],
+  },
+
+  narnia: {
+    name: 'Narnia',
+    host: 'narnia.labs.overthewire.org',
+    port: 2226,
+    levels: 10,
+    category: 'binary-exploitation',
+    description: 'Basic exploitation — buffer overflows, format strings, shellcode',
+    startPassword: '',
+    levelDescriptions: [
+      'Set environment variable to the right value.',
+      'Buffer overflow to overwrite a variable.',
+      'Buffer overflow to redirect execution.',
+      'Buffer overflow with shellcode.',
+      'Format string vulnerability.',
+      'Stack-based exploitation.',
+      'Advanced buffer overflow.',
+      'Return-to-libc.',
+      'Advanced exploitation.',
+      'Final narnia level.',
+    ],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Level-to-difficulty mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a wargame level number to difficulty 1-5.
+ * Earlier levels are easier, later levels are harder.
+ *
+ * @param {number} level - Level number (0-indexed)
+ * @param {number} totalLevels - Total levels in the wargame
+ * @returns {number} Difficulty 1-5
+ */
+function levelToDifficulty(level, totalLevels) {
+  const pct = level / (totalLevels - 1 || 1);
+  if (pct <= 0.2) return 1;
+  if (pct <= 0.4) return 2;
+  if (pct <= 0.6) return 3;
+  if (pct <= 0.8) return 4;
+  return 5;
+}
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate BenchmarkConfig entries for a single wargame.
+ *
+ * @param {string} wargameId - Key in OTW_WARGAMES
+ * @returns {BenchmarkConfig[]}
+ */
+export function loadOtwWargame(wargameId) {
+  const wg = OTW_WARGAMES[wargameId];
+  if (!wg) throw new Error(`Unknown wargame: ${wargameId}. Available: ${Object.keys(OTW_WARGAMES).join(', ')}`);
+
+  const configs = [];
+  for (let i = 0; i < wg.levels; i++) {
+    const username = `${wargameId}${i}`;
+    const description = wg.levelDescriptions?.[i] || `Level ${i} of ${wg.name}`;
+
+    configs.push(new BenchmarkConfig({
+      name: `${wg.name} Level ${i}`,
+      description,
+      level: levelToDifficulty(i, wg.levels),
+      tags: [wg.category, 'overthewire', wargameId],
+      winCondition: 'flag', // The "flag" is the next level's password
+      files: [],
+      path: OTW_DATA_DIR,
+      category: wg.category,
+    }));
+  }
+
+  return configs;
+}
+
+/**
+ * Load all OverTheWire challenges across all wargames.
+ * @returns {BenchmarkConfig[]}
+ */
+export function enumerateOtwChallenges() {
+  const all = [];
+  for (const id of Object.keys(OTW_WARGAMES)) {
+    all.push(...loadOtwWargame(id));
+  }
+  return all;
+}
+
+/**
+ * Get SSH connection info for an OverTheWire level.
+ *
+ * @param {string} wargameId
+ * @param {number} level
+ * @returns {{ host: string, port: number, username: string, password: string|null }}
+ */
+export function getOtwConnectionInfo(wargameId, level) {
+  const wg = OTW_WARGAMES[wargameId];
+  if (!wg) throw new Error(`Unknown wargame: ${wargameId}`);
+
+  const username = `${wargameId}${level}`;
+  const progress = loadProgress();
+  const password = level === 0
+    ? wg.startPassword
+    : progress[wargameId]?.[level] ?? null;
+
+  // Natas uses per-level hostnames
+  let host = wg.host;
+  if (wargameId === 'natas') {
+    host = `natas${level}.natas.labs.overthewire.org`;
+  }
+
+  return { host, port: wg.port, username, password };
+}
+
+// ---------------------------------------------------------------------------
+// Progress tracking
+// ---------------------------------------------------------------------------
+
+/**
+ * Load saved progress (discovered passwords per level).
+ * @returns {object}
+ */
+export function loadProgress() {
+  if (!existsSync(OTW_PROGRESS_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(OTW_PROGRESS_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save a discovered password for a level.
+ *
+ * @param {string} wargameId
+ * @param {number} level
+ * @param {string} password
+ */
+export function saveProgress(wargameId, level, password) {
+  mkdirSync(OTW_DATA_DIR, { recursive: true });
+  const progress = loadProgress();
+  if (!progress[wargameId]) progress[wargameId] = {};
+  progress[wargameId][level] = password;
+  writeFileSync(OTW_PROGRESS_FILE, JSON.stringify(progress, null, 2));
+}
+
+/**
+ * Get progress stats across all wargames.
+ * @returns {object}
+ */
+export function getProgressStats() {
+  const progress = loadProgress();
+  const stats = {};
+
+  for (const [id, wg] of Object.entries(OTW_WARGAMES)) {
+    const solved = progress[id] ? Object.keys(progress[id]).length : 0;
+    stats[id] = {
+      name: wg.name,
+      total: wg.levels,
+      solved,
+      pct: wg.levels > 0 ? Math.round((solved / wg.levels) * 100) : 0,
+      category: wg.category,
+    };
+  }
+
+  return stats;
+}
+
+/**
+ * Initialize OverTheWire data directory.
+ * @returns {boolean}
+ */
+export function cloneOtw() {
+  mkdirSync(OTW_DATA_DIR, { recursive: true });
+  // Save initial progress file if it doesn't exist
+  if (!existsSync(OTW_PROGRESS_FILE)) {
+    writeFileSync(OTW_PROGRESS_FILE, '{}');
+  }
+  return true;
+}
+
+/**
+ * Get catalog stats for all OTW wargames.
+ * @returns {object}
+ */
+export function getOtwCatalogStats() {
+  const challenges = enumerateOtwChallenges();
+  const byCategory = {};
+  const byLevel = {};
+  const byWargame = {};
+
+  for (const c of challenges) {
+    byCategory[c.category] = (byCategory[c.category] || 0) + 1;
+    byLevel[c.level] = (byLevel[c.level] || 0) + 1;
+    const wg = c.tags.find(t => OTW_WARGAMES[t]);
+    if (wg) byWargame[wg] = (byWargame[wg] || 0) + 1;
+  }
+
+  return { total: challenges.length, byCategory, byLevel, byWargame };
+}

package/lib/benchmark/picoctf.js

@@ -0,0 +1,281 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * PicoCTF — Challenge loader for CMU's picoCTF benchmark suite.
+ *
+ * PicoCTF challenges are hosted remotely on picoctf.org / picoGym.
+ * This loader builds a challenge catalog from:
+ * 1. A bundled catalog of known challenges with metadata
+ * 2. Community writeup repos for solution verification
+ *
+ * Categories: Cryptography, Forensics, Binary Exploitation,
+ *             Web Exploitation, Reverse Engineering, General Skills
+ *
+ * Flag format: picoCTF{...}
+ *
+ * @module benchmark/picoctf
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+import { BenchmarkConfig, CompetitorBaseline } from './models.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const PICOCTF_DATA_DIR = join(homedir(), '.cipher', 'benchmarks', 'picoctf');
+export const PICOCTF_CATALOG_FILE = join(PICOCTF_DATA_DIR, 'catalog.json');
+
+/** PicoCTF categories mapped to our standard taxonomy. */
+export const PICO_CATEGORIES = [
+  'cryptography',
+  'forensics',
+  'binary-exploitation',
+  'web-exploitation',
+  'reverse-engineering',
+  'general-skills',
+];
+
+/** Category aliases (picoCTF uses various naming conventions). */
+const CATEGORY_ALIASES = {
+  'crypto':               'cryptography',
+  'cryptography':         'cryptography',
+  'forensics':            'forensics',
+  'pwn':                  'binary-exploitation',
+  'binary exploitation':  'binary-exploitation',
+  'binary_exploitation':  'binary-exploitation',
+  'binaryexploitation':   'binary-exploitation',
+  'web':                  'web-exploitation',
+  'web exploitation':     'web-exploitation',
+  'web_exploitation':     'web-exploitation',
+  'webexploitation':      'web-exploitation',
+  'rev':                  'reverse-engineering',
+  'reverse engineering':  'reverse-engineering',
+  'reverse_engineering':  'reverse-engineering',
+  'reverseengineering':   'reverse-engineering',
+  'general skills':       'general-skills',
+  'general_skills':       'general-skills',
+  'generalskills':        'general-skills',
+  'misc':                 'general-skills',
+};
+
+/**
+ * Difficulty mapping from point values to 1-5 scale.
+ * PicoCTF uses point values: 10-50 easy, 50-150 medium, 150-300 hard, 300-500 very hard.
+ */
+function pointsToLevel(points) {
+  if (points <= 50)  return 1;
+  if (points <= 150) return 2;
+  if (points <= 300) return 3;
+  if (points <= 500) return 4;
+  return 5;
+}
+
+/** Normalize a category string. */
+function normalizeCategory(raw) {
+  return CATEGORY_ALIASES[raw.toLowerCase().trim()] || 'general-skills';
+}
+
+// ---------------------------------------------------------------------------
+// PicoCTF challenge entry
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} PicoCTFChallenge
+ * @property {string} name        - Challenge name
+ * @property {string} category    - Normalized category
+ * @property {number} points      - Point value
+ * @property {string} event       - Event name (e.g. 'picoCTF 2024')
+ * @property {string} description - Challenge description
+ * @property {string} [host]      - Remote host (if network challenge)
+ * @property {number} [port]      - Remote port
+ * @property {string} targetType  - 'ssh' | 'netcat' | 'http' | 'static' | 'unknown'
+ * @property {string[]} hints     - Challenge hints
+ * @property {string[]} files     - Downloadable file URLs
+ * @property {string} [flag]      - Known flag (for validation)
+ */
+
+// ---------------------------------------------------------------------------
+// Bundled challenge catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Built-in catalog of PicoCTF challenges.
+ * This is a representative subset covering all categories and difficulty levels.
+ * The full picoGym has 400+ challenges; this catalog focuses on ones suitable
+ * for automated agent benchmarking.
+ *
+ * Organized by event year → challenges.
+ */
+export const PICOCTF_CATALOG = [
+  // --- General Skills (beginner) ---
+  { name: 'Obedient Cat', event: 'picoCTF 2021', category: 'general-skills', points: 5, targetType: 'static', description: 'Download and read a file to find the flag.' },
+  { name: 'Python Wrangling', event: 'picoCTF 2021', category: 'general-skills', points: 10, targetType: 'static', description: 'Use a Python script with a password to decrypt the flag.' },
+  { name: 'Wave a Flag', event: 'picoCTF 2021', category: 'general-skills', points: 10, targetType: 'static', description: 'Execute a program to get the flag.' },
+  { name: 'Nice Netcat', event: 'picoCTF 2021', category: 'general-skills', points: 15, targetType: 'netcat', description: 'Connect with netcat and decode ASCII values.' },
+  { name: 'Static aint always noise', event: 'picoCTF 2021', category: 'general-skills', points: 20, targetType: 'static', description: 'Use a disassembly script to find the flag in a binary.' },
+  { name: 'Tab, Tab, Attack', event: 'picoCTF 2021', category: 'general-skills', points: 20, targetType: 'static', description: 'Navigate deeply nested directories to find executable.' },
+  { name: 'Magikarp Ground Mission', event: 'picoCTF 2021', category: 'general-skills', points: 30, targetType: 'ssh', description: 'SSH into a machine and find flag pieces.' },
+  { name: 'Serpentine', event: 'picoCTF 2022', category: 'general-skills', points: 100, targetType: 'static', description: 'Modify Python source to bypass menu and call flag function.' },
+  { name: 'Based', event: 'picoCTF 2019', category: 'general-skills', points: 200, targetType: 'netcat', description: 'Convert between binary, octal, and hex encodings.' },
+  { name: 'First Find', event: 'picoCTF 2024', category: 'general-skills', points: 100, targetType: 'static', description: 'Unzip and find a specific file in a directory structure.' },
+
+  // --- Cryptography ---
+  { name: 'Mod 26', event: 'picoCTF 2021', category: 'cryptography', points: 10, targetType: 'static', description: 'Apply ROT13 to decode the flag.' },
+  { name: 'Mind your Ps and Qs', event: 'picoCTF 2021', category: 'cryptography', points: 20, targetType: 'static', description: 'Factor small RSA modulus and decrypt.' },
+  { name: 'Easy1', event: 'picoCTF 2019', category: 'cryptography', points: 100, targetType: 'static', description: 'Decrypt a one-time pad cipher with a given key table.' },
+  { name: 'New Caesar', event: 'picoCTF 2021', category: 'cryptography', points: 60, targetType: 'static', description: 'Reverse a custom Base16 + shift cipher.' },
+  { name: 'Mini RSA', event: 'picoCTF 2021', category: 'cryptography', points: 70, targetType: 'static', description: 'Small public exponent RSA attack.' },
+  { name: 'Substitution0', event: 'picoCTF 2022', category: 'cryptography', points: 100, targetType: 'static', description: 'Decode a simple substitution cipher.' },
+  { name: 'transposition-trial', event: 'picoCTF 2022', category: 'cryptography', points: 100, targetType: 'static', description: 'Reverse a transposition cipher.' },
+  { name: 'C3', event: 'picoCTF 2024', category: 'cryptography', points: 200, targetType: 'static', description: 'Custom cipher with Python encoder/decoder.' },
+  { name: 'rsa_oracle', event: 'picoCTF 2023', category: 'cryptography', points: 300, targetType: 'netcat', description: 'Use RSA oracle for chosen-ciphertext attack.' },
+
+  // --- Web Exploitation ---
+  { name: 'GET aHEAD', event: 'picoCTF 2021', category: 'web-exploitation', points: 20, targetType: 'http', description: 'Use HTTP HEAD request to find the flag.' },
+  { name: 'Cookies', event: 'picoCTF 2021', category: 'web-exploitation', points: 40, targetType: 'http', description: 'Manipulate cookie values to find the flag.' },
+  { name: 'Insp3ct0r', event: 'picoCTF 2019', category: 'web-exploitation', points: 50, targetType: 'http', description: 'Inspect page source, CSS, and JS for flag parts.' },
+  { name: 'Scavenger Hunt', event: 'picoCTF 2021', category: 'web-exploitation', points: 50, targetType: 'http', description: 'Find flag pieces in HTML, CSS, JS, robots.txt, .htaccess.' },
+  { name: 'SQL Direct', event: 'picoCTF 2022', category: 'web-exploitation', points: 200, targetType: 'netcat', description: 'Connect to PostgreSQL and query for the flag.' },
+  { name: 'Web Gauntlet', event: 'picoCTF 2020', category: 'web-exploitation', points: 170, targetType: 'http', description: 'SQL injection with increasing filter bypass rounds.' },
+  { name: 'JAuth', event: 'picoCTF 2022', category: 'web-exploitation', points: 300, targetType: 'http', description: 'JWT none algorithm bypass for privilege escalation.' },
+  { name: 'Java Code Analysis', event: 'picoCTF 2023', category: 'web-exploitation', points: 300, targetType: 'http', description: 'Analyze Java source to find JWT weak secret.' },
+  { name: 'Crack the Gate 1', event: 'picoCTF 2025', category: 'web-exploitation', points: 100, targetType: 'http', description: 'Find dev backdoor header in page source.' },
+
+  // --- Forensics ---
+  { name: 'information', event: 'picoCTF 2021', category: 'forensics', points: 10, targetType: 'static', description: 'Extract flag from image EXIF metadata.' },
+  { name: 'Matryoshka doll', event: 'picoCTF 2021', category: 'forensics', points: 30, targetType: 'static', description: 'Recursively extract hidden files from images.' },
+  { name: 'Wireshark doo dooo', event: 'picoCTF 2021', category: 'forensics', points: 50, targetType: 'static', description: 'Analyze a pcap file to find the flag.' },
+  { name: 'Trivial Flag Transfer Protocol', event: 'picoCTF 2021', category: 'forensics', points: 90, targetType: 'static', description: 'Extract files from TFTP pcap and decode.' },
+  { name: 'St3g0', event: 'picoCTF 2022', category: 'forensics', points: 200, targetType: 'static', description: 'Extract hidden data from PNG using steganography.' },
+  { name: 'Sleuthkit Intro', event: 'picoCTF 2022', category: 'forensics', points: 100, targetType: 'static', description: 'Use mmls and other Sleuthkit tools on a disk image.' },
+  { name: 'Disk, disk, sleuth!', event: 'picoCTF 2021', category: 'forensics', points: 110, targetType: 'static', description: 'Analyze a disk image with Sleuthkit.' },
+
+  // --- Reverse Engineering ---
+  { name: 'Transformation', event: 'picoCTF 2021', category: 'reverse-engineering', points: 20, targetType: 'static', description: 'Reverse a Unicode encoding transformation.' },
+  { name: 'vault-door-training', event: 'picoCTF 2019', category: 'reverse-engineering', points: 50, targetType: 'static', description: 'Read Java source to find hardcoded password.' },
+  { name: 'GDB baby step 1', event: 'picoCTF 2022', category: 'reverse-engineering', points: 100, targetType: 'static', description: 'Use GDB to find value in eax register.' },
+  { name: 'patchme.py', event: 'picoCTF 2022', category: 'reverse-engineering', points: 100, targetType: 'static', description: 'Read Python source to find the correct password.' },
+  { name: 'Safe Opener', event: 'picoCTF 2022', category: 'reverse-engineering', points: 100, targetType: 'static', description: 'Decode Base64 password from Java source.' },
+  { name: 'Reverse', event: 'picoCTF 2024', category: 'reverse-engineering', points: 100, targetType: 'static', description: 'Use strings or disassemble binary to find flag.' },
+  { name: 'asm1', event: 'picoCTF 2019', category: 'reverse-engineering', points: 200, targetType: 'static', description: 'Trace x86 assembly to compute return value.' },
+  { name: 'Keygenme', event: 'picoCTF 2022', category: 'reverse-engineering', points: 400, targetType: 'static', description: 'Reverse a key validation algorithm in a binary.' },
+
+  // --- Binary Exploitation ---
+  { name: 'Stonks', event: 'picoCTF 2021', category: 'binary-exploitation', points: 20, targetType: 'netcat', description: 'Format string vulnerability to leak flag from stack.' },
+  { name: 'buffer overflow 0', event: 'picoCTF 2022', category: 'binary-exploitation', points: 100, targetType: 'netcat', description: 'Basic stack buffer overflow to trigger win function.' },
+  { name: 'buffer overflow 1', event: 'picoCTF 2022', category: 'binary-exploitation', points: 200, targetType: 'netcat', description: 'Buffer overflow to overwrite return address.' },
+  { name: 'RPS', event: 'picoCTF 2022', category: 'binary-exploitation', points: 200, targetType: 'netcat', description: 'Win 5 consecutive games via binary analysis.' },
+  { name: 'x-sixty-what', event: 'picoCTF 2022', category: 'binary-exploitation', points: 200, targetType: 'netcat', description: '64-bit buffer overflow to call flag function.' },
+  { name: 'format string 0', event: 'picoCTF 2024', category: 'binary-exploitation', points: 50, targetType: 'netcat', description: 'Exploit a format string vulnerability.' },
+  { name: 'heap 0', event: 'picoCTF 2024', category: 'binary-exploitation', points: 50, targetType: 'netcat', description: 'Heap overflow to overwrite adjacent data.' },
+];
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Load a PicoCTF challenge entry into a BenchmarkConfig.
+ *
+ * @param {PicoCTFChallenge} entry
+ * @returns {BenchmarkConfig}
+ */
+export function loadPicoChallenge(entry) {
+  const category = normalizeCategory(entry.category);
+  const level = entry.level ?? pointsToLevel(entry.points ?? 100);
+  const tags = [category, 'picoctf'];
+  if (entry.event) tags.push(entry.event.toLowerCase().replace(/\s+/g, '-'));
+
+  return new BenchmarkConfig({
+    name: entry.name,
+    description: entry.description || '',
+    level: Math.min(5, Math.max(1, level)),
+    tags,
+    winCondition: 'flag',
+    files: (entry.files || []).map(f => typeof f === 'string' ? { name: f } : f),
+    path: entry.path || PICOCTF_DATA_DIR,
+    category,
+  });
+}
+
+/**
+ * Load all challenges from the bundled catalog.
+ * @returns {BenchmarkConfig[]}
+ */
+export function enumeratePicoChallenges() {
+  // First try loading from disk catalog (may have been enriched)
+  if (existsSync(PICOCTF_CATALOG_FILE)) {
+    try {
+      const catalog = JSON.parse(readFileSync(PICOCTF_CATALOG_FILE, 'utf8'));
+      return catalog.map(loadPicoChallenge);
+    } catch { /* fall through to bundled */ }
+  }
+
+  // Use bundled catalog
+  return PICOCTF_CATALOG.map(loadPicoChallenge);
+}
+
+/**
+ * Save an enriched catalog to disk.
+ * @param {PicoCTFChallenge[]} challenges
+ */
+export function savePicoCatalog(challenges) {
+  mkdirSync(PICOCTF_DATA_DIR, { recursive: true });
+  writeFileSync(PICOCTF_CATALOG_FILE, JSON.stringify(challenges, null, 2));
+}
+
+/**
+ * Initialize PicoCTF data directory and save bundled catalog.
+ * @returns {boolean}
+ */
+export function clonePicoCTF() {
+  mkdirSync(PICOCTF_DATA_DIR, { recursive: true });
+  savePicoCatalog(PICOCTF_CATALOG);
+  return true;
+}
+
+/**
+ * Get target connection info for a PicoCTF challenge.
+ *
+ * @param {PicoCTFChallenge} entry
+ * @returns {{ type: string, host: string, port: number }|null}
+ */
+export function getPicoTargetInfo(entry) {
+  if (entry.targetType === 'static') return null;
+  return {
+    type: entry.targetType || 'unknown',
+    host: entry.host || 'saturn.picoctf.net',
+    port: entry.port || 0, // Port assigned dynamically per-instance
+  };
+}
+
+/**
+ * Get challenge stats by category and difficulty.
+ * @returns {object}
+ */
+export function getPicoCatalogStats() {
+  const challenges = enumeratePicoChallenges();
+  const byCategory = {};
+  const byLevel = {};
+  const byTargetType = {};
+  const byEvent = {};
+
+  for (const c of challenges) {
+    byCategory[c.category] = (byCategory[c.category] || 0) + 1;
+    byLevel[c.level] = (byLevel[c.level] || 0) + 1;
+    // Count target types from original catalog entries
+    const entry = PICOCTF_CATALOG.find(e => e.name === c.name);
+    if (entry) {
+      byTargetType[entry.targetType] = (byTargetType[entry.targetType] || 0) + 1;
+      byEvent[entry.event] = (byEvent[entry.event] || 0) + 1;
+    }
+  }
+
+  return { total: challenges.length, byCategory, byLevel, byTargetType, byEvent };
+}