securenow 8.5.0 → 8.6.0

package/challenge.js

@@ -0,0 +1,273 @@
+'use strict';
+
+// SecureNow homegrown challenge protocol (v1 = invisible Proof-of-Work).
+//
+// This is the SDK-side half of a stateless, signed challenge handshake. The
+// API side (securenow-api/src/libs/challengeCrypto.js) implements the exact
+// same wire format so a challenge minted on one side can be verified on the
+// other. Nothing is stored server-side: a challenge token and a clearance
+// cookie are both self-describing, HMAC-signed envelopes.
+//
+// Flow:
+//   1. A request matches a challenge rule and carries no valid clearance.
+//   2. We mint a challenge token (signChallenge) and serve an interstitial that
+//      asks the browser to find a `nonce` such that SHA-256(token + '.' + nonce)
+//      has `diff` leading zero bits. That is the proof-of-work — invisible to a
+//      human (a sub-second JS loop) but a per-request CPU tax on a flood.
+//   3. The browser POSTs {token, nonce} back. We verify the work
+//      (verifyChallengeSolution) and, on success, issue a clearance cookie
+//      (issueClearance) bound to the IP + User-Agent for a short TTL.
+//   4. Subsequent requests present the cookie; verifyClearance lets them pass.
+//
+// `alg` is versioned so future challenge types (interactive, behavioural,
+// device-fingerprint) slot in behind the same token/cookie machinery without
+// touching the rule model, sync payload, or clearance handling.
+
+const crypto = require('crypto');
+
+const CHALLENGE_PREFIX = 'c1';
+const CLEARANCE_PREFIX = 'k1';
+const ALG_POW = 'pow-sha256';
+const CLEARANCE_COOKIE = '__sn_clearance';
+
+const DEFAULTS = {
+  difficulty: 14, // leading zero bits; ~2^14 hashes expected (sub-second in JS)
+  challengeTtl: 120, // seconds a minted challenge stays solvable
+  clearanceTtl: 1800, // seconds a solved clearance lasts (30 min)
+};
+
+// ── low-level helpers ──────────────────────────────────────────────────────
+
+function b64urlEncode(str) {
+  return Buffer.from(str, 'utf8').toString('base64url');
+}
+
+function b64urlDecode(str) {
+  return Buffer.from(String(str), 'base64url').toString('utf8');
+}
+
+function nowSec() {
+  return Math.floor(Date.now() / 1000);
+}
+
+function hmac(secret, data) {
+  return crypto.createHmac('sha256', String(secret || '')).update(data).digest('base64url');
+}
+
+function timingEqual(a, b) {
+  const ba = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ba.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+function normIp(ip) {
+  return String(ip || '').replace(/^::ffff:/i, '').trim();
+}
+
+function uaHash(ua) {
+  return crypto.createHash('sha256').update(String(ua || '')).digest('hex').slice(0, 16);
+}
+
+// Count leading zero BITS of a hash buffer. Bit-level granularity lets a single
+// `difficulty` knob scale work smoothly instead of in 16x jumps per hex nibble.
+function leadingZeroBits(buf) {
+  let bits = 0;
+  for (let i = 0; i < buf.length; i++) {
+    const byte = buf[i];
+    if (byte === 0) {
+      bits += 8;
+      continue;
+    }
+    bits += Math.clz32(byte) - 24; // clz32 of an 8-bit value, minus the 24 high zero bits
+    break;
+  }
+  return bits;
+}
+
+function meetsDifficulty(buf, diff) {
+  return leadingZeroBits(buf) >= Math.max(0, Number(diff) || 0);
+}
+
+function parseSigned(prefix, token) {
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length !== 3 || parts[0] !== prefix) return null;
+  let payload;
+  try {
+    payload = JSON.parse(b64urlDecode(parts[1]));
+  } catch (_) {
+    return null;
+  }
+  return { body: `${parts[0]}.${parts[1]}`, payload, sig: parts[2] };
+}
+
+// ── challenge token ────────────────────────────────────────────────────────
+
+function signChallenge(secret, opts = {}) {
+  const iat = nowSec();
+  const ttl = Number(opts.challengeTtl || DEFAULTS.challengeTtl);
+  const payload = {
+    ip: normIp(opts.ip),
+    alg: opts.alg || ALG_POW,
+    diff: Math.max(1, Number(opts.difficulty || DEFAULTS.difficulty)),
+    rid: opts.rid || '*',
+    iat,
+    exp: iat + ttl,
+  };
+  const body = `${CHALLENGE_PREFIX}.${b64urlEncode(JSON.stringify(payload))}`;
+  return `${body}.${hmac(secret, body)}`;
+}
+
+function verifyChallengeSolution(secret, { token, nonce, ip } = {}) {
+  const parsed = parseSigned(CHALLENGE_PREFIX, token);
+  if (!parsed) return { ok: false, reason: 'malformed' };
+  if (!timingEqual(parsed.sig, hmac(secret, parsed.body))) return { ok: false, reason: 'bad_signature' };
+  const p = parsed.payload;
+  if (p.exp && nowSec() > p.exp) return { ok: false, reason: 'expired' };
+  if (ip && normIp(ip) !== p.ip) return { ok: false, reason: 'ip_mismatch' };
+  if (p.alg !== ALG_POW) return { ok: false, reason: 'unsupported_alg' };
+  if (nonce === undefined || nonce === null || `${nonce}` === '') return { ok: false, reason: 'missing_nonce' };
+  const digest = crypto.createHash('sha256').update(`${token}.${nonce}`).digest();
+  if (!meetsDifficulty(digest, p.diff)) return { ok: false, reason: 'insufficient_work' };
+  return { ok: true, payload: p };
+}
+
+// ── clearance cookie ───────────────────────────────────────────────────────
+
+function issueClearance(secret, opts = {}) {
+  const iat = nowSec();
+  const ttl = Number(opts.clearanceTtl || DEFAULTS.clearanceTtl);
+  const payload = {
+    ip: normIp(opts.ip),
+    uah: uaHash(opts.ua),
+    rid: opts.rid || '*',
+    iat,
+    exp: iat + ttl,
+  };
+  const body = `${CLEARANCE_PREFIX}.${b64urlEncode(JSON.stringify(payload))}`;
+  return { value: `${body}.${hmac(secret, body)}`, maxAge: ttl, exp: payload.exp };
+}
+
+function verifyClearance(secret, { cookie, ip, ua } = {}) {
+  const parsed = parseSigned(CLEARANCE_PREFIX, cookie);
+  if (!parsed) return { ok: false, reason: 'malformed' };
+  if (!timingEqual(parsed.sig, hmac(secret, parsed.body))) return { ok: false, reason: 'bad_signature' };
+  const p = parsed.payload;
+  if (p.exp && nowSec() > p.exp) return { ok: false, reason: 'expired' };
+  if (ip && normIp(ip) !== p.ip) return { ok: false, reason: 'ip_mismatch' };
+  if (ua && uaHash(ua) !== p.uah) return { ok: false, reason: 'ua_mismatch' };
+  return { ok: true, payload: p };
+}
+
+function readClearanceCookie(req) {
+  const header = req && req.headers && req.headers['cookie'];
+  if (!header) return null;
+  for (const part of String(header).split(';')) {
+    const idx = part.indexOf('=');
+    if (idx === -1) continue;
+    if (part.slice(0, idx).trim() === CLEARANCE_COOKIE) {
+      return part.slice(idx + 1).trim();
+    }
+  }
+  return null;
+}
+
+// ── interstitial page ──────────────────────────────────────────────────────
+// Invisible PoW solver. Uses SubtleCrypto (available in every modern browser);
+// the leading-zero-bits check mirrors leadingZeroBits() above exactly so a
+// solution accepted by the browser verifies on the server.
+
+function challengeHtml({ token, difficulty, submitPath, returnPath, ip }) {
+  const cfg = JSON.stringify({
+    token: String(token),
+    diff: Math.max(1, Number(difficulty) || DEFAULTS.difficulty),
+    submit: String(submitPath || '/__securenow/challenge'),
+    ret: String(returnPath || '/'),
+  });
+  const safeIp = String(ip || 'unknown').replace(/[<>&"]/g, '');
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Verifying your browser - SecureNow</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{min-height:100vh;display:flex;align-items:center;justify-content:center;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;background:#0a0a0a;color:#e5e5e5}
+.wrap{text-align:center;max-width:540px;padding:2.5rem 2rem}
+.icon{width:64px;height:64px;margin:0 auto 1.5rem;border-radius:50%;background:rgba(59,130,246,.12);display:flex;align-items:center;justify-content:center}
+.icon svg{width:32px;height:32px;fill:none;stroke:#3b82f6;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}
+.badge{display:inline-block;padding:.25rem .75rem;border-radius:999px;background:rgba(59,130,246,.15);color:#93c5fd;font-size:.7rem;font-weight:700;letter-spacing:.08em;text-transform:uppercase;margin-bottom:1.25rem}
+h1{font-size:1.5rem;font-weight:700;margin-bottom:.6rem;color:#fff}
+p{font-size:.9rem;line-height:1.7;color:#a1a1aa;margin-bottom:.5rem}
+.spinner{width:34px;height:34px;margin:1.5rem auto .5rem;border:3px solid rgba(255,255,255,.12);border-top-color:#3b82f6;border-radius:50%;animation:spin .8s linear infinite}
+@keyframes spin{to{transform:rotate(360deg)}}
+.status{font-size:.82rem;color:#71717a;margin-top:.75rem;min-height:1.2em}
+.ip-box{display:inline-block;margin:1rem 0 .25rem;padding:.5rem 1.25rem;border-radius:8px;background:rgba(255,255,255,.04);border:1px solid rgba(59,130,246,.25);font-family:"SF Mono",SFMono-Regular,Consolas,Menlo,monospace;font-size:.85rem;color:#93c5fd}
+.footer{margin-top:2rem;font-size:.7rem;color:#3f3f46}
+.powered{margin-top:1.5rem;font-size:.75rem;color:#52525b}.powered a{color:#a1a1aa;text-decoration:none;font-weight:600}
+noscript{color:#f87171}
+</style>
+</head>
+<body>
+<div class="wrap">
+<div class="icon"><svg viewBox="0 0 24 24"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg></div>
+<span class="badge">Security Check</span>
+<h1>Verifying your browser</h1>
+<p>Automated traffic from your network triggered an extra verification step. This runs automatically &mdash; no action needed.</p>
+<div class="spinner" id="sp"></div>
+<p class="status" id="st">Starting verification&hellip;</p>
+<div class="ip-box">${safeIp}</div>
+<noscript><p>JavaScript is required to complete this verification.</p></noscript>
+<p class="footer">Protected by SecureNow &mdash; proof-of-work challenge</p>
+<p class="powered">Protected by <a href="https://securenow.ai" rel="dofollow" target="_blank">SecureNow</a></p>
+</div>
+<script>
+(function(){
+  var C=${cfg};
+  var st=document.getElementById('st');
+  function setStatus(t){ if(st) st.textContent=t; }
+  function lzbits(bytes){var bits=0;for(var i=0;i<bytes.length;i++){var b=bytes[i];if(b===0){bits+=8;continue;}bits+=Math.clz32(b)-24;break;}return bits;}
+  if(!(window.crypto&&window.crypto.subtle)){setStatus('Your browser does not support this verification.');return;}
+  var enc=new TextEncoder();
+  var nonce=0,started=Date.now();
+  function step(){
+    var batch=0;
+    (function loop(){
+      if(batch++>400){ setStatus('Verifying… ('+nonce+' attempts)'); setTimeout(step,0); return; }
+      var data=enc.encode(C.token+'.'+nonce);
+      window.crypto.subtle.digest('SHA-256',data).then(function(buf){
+        var bytes=new Uint8Array(buf);
+        if(lzbits(bytes)>=C.diff){ submit(nonce); return; }
+        nonce++; loop();
+      }).catch(function(){ setStatus('Verification error. Please refresh.'); });
+    })();
+  }
+  function submit(n){
+    setStatus('Solved. Finalizing…');
+    fetch(C.submit,{method:'POST',headers:{'Content-Type':'application/json'},credentials:'same-origin',body:JSON.stringify({token:C.token,nonce:String(n)})})
+      .then(function(r){ if(r.ok){ window.location.replace(C.ret); } else { return r.text().then(function(){ setStatus('Verification rejected. Refreshing…'); setTimeout(function(){window.location.reload();},1500); }); } })
+      .catch(function(){ setStatus('Network error. Refreshing…'); setTimeout(function(){window.location.reload();},1500); });
+  }
+  step();
+})();
+</script>
+</body>
+</html>`;
+}
+
+module.exports = {
+  CHALLENGE_PREFIX,
+  CLEARANCE_PREFIX,
+  CLEARANCE_COOKIE,
+  ALG_POW,
+  DEFAULTS,
+  signChallenge,
+  verifyChallengeSolution,
+  issueClearance,
+  verifyClearance,
+  readClearanceCookie,
+  challengeHtml,
+  meetsDifficulty,
+  leadingZeroBits,
+};

package/cli/challenges.js

@@ -0,0 +1,253 @@
+'use strict';
+
+const { api, requireAuth } = require('./client');
+const config = require('./config');
+const ui = require('./ui');
+
+function resolveApp(flags) {
+  return flags.app || config.getDefaultApp();
+}
+
+function resolveEnvironment(flags, fallback = null) {
+  return flags.env || flags.environment || fallback;
+}
+
+function parseTtl(value, fallback = 1800) {
+  if (value == null || value === '') return fallback;
+  if (/^\d+$/.test(String(value))) return Number(value);
+  const raw = String(value).trim().toLowerCase();
+  const match = raw.match(/^(\d+)\s*(s|sec|second|seconds|m|min|minute|minutes|h|hr|hour|hours)$/);
+  if (!match) {
+    ui.error('Clearance must be seconds or look like 30m, 1h, or 12h.');
+    process.exit(1);
+  }
+  const n = Number(match[1]);
+  const unit = match[2][0];
+  return unit === 'h' ? n * 3600 : unit === 'm' ? n * 60 : n;
+}
+
+function buildQuery(flags) {
+  const query = {};
+  if (flags.page) query.page = flags.page;
+  if (flags.limit) query.limit = flags.limit;
+  if (flags.status) query.status = flags.status;
+  if (flags.search) query.search = flags.search;
+  const appKey = resolveApp(flags);
+  if (appKey) query.appKey = appKey;
+  const environment = resolveEnvironment(flags, null);
+  if (environment) query.environment = environment;
+  return query;
+}
+
+function describeTarget(rule) {
+  const parts = [];
+  if (rule.ip) parts.push(rule.ip);
+  if (rule.method && rule.method !== 'ALL') parts.push(rule.method);
+  if (rule.pathPattern) parts.push(`${rule.pathMatchMode || 'prefix'}:${rule.pathPattern}`);
+  return parts.join(' ') || 'all traffic';
+}
+
+function describeClearance(rule) {
+  const ttl = rule.clearanceTtlSeconds || 1800;
+  return ttl % 3600 === 0 ? `${ttl / 3600}h` : ttl % 60 === 0 ? `${ttl / 60}m` : `${ttl}s`;
+}
+
+async function list(args, flags) {
+  requireAuth();
+  const s = ui.spinner('Fetching challenge rules');
+  try {
+    const data = await api.get('/challenges', { query: buildQuery(flags) });
+    const rules = data.challenges || [];
+    s.stop(`Found ${rules.length} challenge rule${rules.length !== 1 ? 's' : ''}${data.total ? ` (${data.total} total)` : ''}`);
+
+    if (flags.json) { ui.json(data); return; }
+
+    console.log('');
+    const rows = rules.map((r) => [
+      ui.c.dim(ui.truncate(r.id || r._id, 12)),
+      r.status === 'active' ? ui.statusBadge('active') : ui.statusBadge(r.status || 'unknown'),
+      describeTarget(r),
+      `pow:${r.difficulty}`,
+      describeClearance(r),
+      r.applicationKey || ui.c.dim('all apps'),
+      r.environment || ui.c.dim('all envs'),
+      r.expiresAt ? new Date(r.expiresAt).toLocaleString() : ui.c.dim('permanent'),
+    ]);
+    ui.table(['ID', 'Status', 'Target', 'Strength', 'Clears', 'App', 'Env', 'Expires'], rows);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to fetch challenge rules');
+    throw err;
+  }
+}
+
+async function show(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!id) {
+    ui.error('Usage: securenow challenge show <id>');
+    process.exit(1);
+  }
+  const s = ui.spinner('Fetching challenge rule');
+  try {
+    const data = await api.get(`/challenges/${id}`);
+    const r = data.challenge;
+    s.stop('Challenge rule loaded');
+    if (flags.json) { ui.json(r); return; }
+    console.log('');
+    ui.heading(r.name || 'Challenge rule');
+    console.log('');
+    ui.keyValue([
+      ['ID', r.id || r._id || id],
+      ['Status', r.status || '-'],
+      ['Target', describeTarget(r)],
+      ['Strength', `proof-of-work, ${r.difficulty} bits`],
+      ['Clearance', describeClearance(r)],
+      ['Escalate to block', r.escalation?.escalateToBlock ? `after ${r.escalation.failThreshold} fails (${r.escalation.blockTtlHours}h)` : 'no'],
+      ['App', r.applicationKey || 'all apps'],
+      ['Environment', r.environment || 'all envs'],
+      ['Reason', r.reason || '-'],
+      ['Expires', r.expiresAt || 'permanent'],
+    ]);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to fetch challenge rule');
+    throw err;
+  }
+}
+
+async function add(args, flags) {
+  requireAuth();
+  const ip = args[0] || flags.ip || '';
+  const pathPattern = flags.route || flags.path || flags.pattern || '';
+
+  if (!ip && !pathPattern) {
+    ui.error('Provide an IP/CIDR, --route, or both.');
+    ui.info('Example: securenow challenge add --route /login --difficulty 16 --clearance 30m');
+    process.exit(1);
+  }
+
+  const appKey = resolveApp(flags);
+  const environment = resolveEnvironment(flags, 'production');
+  const body = {
+    ip,
+    pathPattern,
+    pathMatchMode: flags.mode || flags['path-mode'] || 'prefix',
+    method: flags.method || 'ALL',
+    difficulty: flags.difficulty ? Number(flags.difficulty) : undefined,
+    clearanceTtlSeconds: parseTtl(flags.clearance || flags['clearance-ttl']),
+    reason: flags.reason || '',
+    name: flags.name || '',
+    duration: flags.duration || '',
+    expiresAt: flags.expiresAt || flags.expires || '',
+  };
+  if (flags['escalate-to-block'] || flags.escalate) {
+    body.escalation = {
+      escalateToBlock: true,
+      failThreshold: flags['fail-threshold'] ? Number(flags['fail-threshold']) : 10,
+      blockTtlHours: flags['block-ttl-hours'] ? Number(flags['block-ttl-hours']) : 24,
+    };
+  }
+  if (appKey) body.appKey = appKey;
+  if (environment) body.environment = environment;
+
+  const s = ui.spinner('Creating challenge rule');
+  try {
+    const data = await api.post('/challenges', body);
+    s.stop('Challenge rule created');
+    if (flags.json) { ui.json(data); return; }
+    const r = data.challenge;
+    console.log('');
+    console.log(`  ${ui.c.green('ACTIVE')} ${describeTarget(r)} - proof-of-work ${r.difficulty} bits, clears ${describeClearance(r)}`);
+    console.log(`  ${ui.c.dim('ID:')} ${r.id || r._id}`);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to create challenge rule');
+    throw err;
+  }
+}
+
+async function setStatus(args, flags, status) {
+  requireAuth();
+  const id = args[0];
+  if (!id) {
+    ui.error(`Usage: securenow challenge ${status === 'active' ? 'enable' : 'disable'} <id>`);
+    process.exit(1);
+  }
+  const s = ui.spinner(`${status === 'active' ? 'Enabling' : 'Disabling'} challenge rule`);
+  try {
+    const data = await api.put(`/challenges/${id}`, { status });
+    s.stop(status === 'active' ? 'Challenge rule enabled' : 'Challenge rule disabled');
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail('Failed to update challenge rule');
+    throw err;
+  }
+}
+
+async function enable(args, flags) { return setStatus(args, flags, 'active'); }
+async function disable(args, flags) { return setStatus(args, flags, 'disabled'); }
+
+async function remove(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!id) {
+    ui.error('Usage: securenow challenge remove <id> [--reason "..."]');
+    process.exit(1);
+  }
+  if (!flags.force && !flags.yes) {
+    const ok = await ui.confirm('Remove this challenge rule?');
+    if (!ok) { ui.info('Cancelled'); return; }
+  }
+  const s = ui.spinner('Removing challenge rule');
+  try {
+    const opts = flags.reason ? { query: { reason: flags.reason } } : undefined;
+    const data = await api.delete(`/challenges/${id}`, opts);
+    s.stop('Challenge rule removed');
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail('Failed to remove challenge rule');
+    throw err;
+  }
+}
+
+async function test(args, flags) {
+  requireAuth();
+  const ip = args[0] || flags.ip;
+  if (!ip) {
+    ui.error('Usage: securenow challenge test <ip> --path /login [--method GET]');
+    process.exit(1);
+  }
+  const query = {
+    ip,
+    path: flags.path || flags.route || '/',
+    method: flags.method || 'GET',
+  };
+  const appKey = resolveApp(flags);
+  if (appKey) query.appKey = appKey;
+  const environment = resolveEnvironment(flags, 'production');
+  if (environment) query.environment = environment;
+
+  const s = ui.spinner('Testing challenge match');
+  try {
+    const data = await api.get('/challenges/check', { query });
+    s.stop('Challenge check complete');
+    if (flags.json) { ui.json(data); return; }
+    console.log('');
+    if (data.challenged) {
+      console.log(`  ${ui.c.bold(ui.c.yellow('CHALLENGED'))} - ${data.matches.length} matching rule${data.matches.length !== 1 ? 's' : ''}`);
+      for (const r of data.matches.slice(0, 5)) {
+        console.log(`  ${ui.c.dim(r.id || r._id)}  ${describeTarget(r)}  pow:${r.difficulty}`);
+      }
+    } else {
+      console.log(`  ${ui.c.bold(ui.c.green('NOT CHALLENGED'))} - no matching challenge rules`);
+    }
+    console.log(`  ${ui.c.dim(`App scope: ${appKey || 'all apps'} - Environment: ${data.environment || environment}`)}`);
+    console.log('');
+  } catch (err) {
+    s.fail('Failed to test challenge');
+    throw err;
+  }
+}
+
+module.exports = { list, show, add, enable, disable, remove, test };

package/cli.js

@@ -389,6 +389,37 @@ const COMMANDS = {
     },
     defaultSub: 'list',
   },
+  challenge: {
+    desc: 'Manage CAPTCHA / proof-of-work challenge remediation rules',
+    usage: 'securenow challenge <list|add|show|test|enable|disable|remove> [options]',
+    flags: {
+      app: 'Scope to app key (defaults to logged-in app)',
+      env: 'Scope to environment (default for create/test: production)',
+      environment: 'Alias for --env',
+      json: 'Output as JSON',
+      difficulty: 'Proof-of-work strength in leading zero bits (4-28, default 14)',
+      clearance: 'How long a solve clears, e.g. 30m, 1h (default 30m)',
+      route: 'Path pattern such as /login',
+      path: 'Alias for --route',
+      mode: 'Path mode: exact, prefix, or regex',
+      method: 'HTTP method, or ALL',
+      duration: 'Rule expiry, e.g. 24h or 7d',
+      reason: 'Reason note',
+      'escalate-to-block': 'Promote to a hard block after repeated failures',
+      'fail-threshold': 'Failures before escalation (default 10)',
+      'block-ttl-hours': 'Block duration when escalating (default 24)',
+    },
+    sub: {
+      list: { desc: 'List challenge remediation rules', run: (a, f) => require('./cli/challenges').list(a, f) },
+      add: { desc: 'Create a challenge rule', usage: 'securenow challenge add [ip] --route /login --difficulty 16 --clearance 30m', run: (a, f) => require('./cli/challenges').add(a, f) },
+      show: { desc: 'Show one challenge rule', usage: 'securenow challenge show <id>', run: (a, f) => require('./cli/challenges').show(a, f) },
+      test: { desc: 'Check whether a request would be challenged', usage: 'securenow challenge test <ip> --path /login --method GET', run: (a, f) => require('./cli/challenges').test(a, f) },
+      enable: { desc: 'Enable a challenge rule', usage: 'securenow challenge enable <id>', run: (a, f) => require('./cli/challenges').enable(a, f) },
+      disable: { desc: 'Disable a challenge rule', usage: 'securenow challenge disable <id>', run: (a, f) => require('./cli/challenges').disable(a, f) },
+      remove: { desc: 'Remove a challenge rule', usage: 'securenow challenge remove <id> [--reason "..."]', run: (a, f) => require('./cli/challenges').remove(a, f) },
+    },
+    defaultSub: 'list',
+  },
   automation: {
     desc: 'Manage automation rules for blocklist actions',
     usage: 'securenow automation <list|defaults|show|create|update|dry-run|execute|delete> [rule-id] [options]',
@@ -724,7 +755,7 @@ function showHelp(commandName) {
     'Detect & Respond': ['human', 'notifications', 'alerts', 'fp'],
     'Investigate': ['ip', 'forensics'],
     'Firewall': ['firewall'],
-    'Remediation': ['automation', 'ratelimit', 'blocklist', 'revoke', 'allowlist', 'trusted'],
+    'Remediation': ['automation', 'ratelimit', 'challenge', 'blocklist', 'revoke', 'allowlist', 'trusted'],
     'Telemetry': ['log', 'event', 'test-span'],
     'Utilities': ['redact', 'cidr', 'doctor', 'env', 'mcp'],
     'Settings': ['instances', 'config', 'version'],