kryptheon-night 0.1.0

package/bin/kryptheon-night.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+//
+// The front door.
+//
+//     npx kryptheon-night
+//
+// No arguments, no environment variable, no flags. It asks for what it needs,
+// says what it is about to do, waits to be told yes, and then runs.
+//
+// `scan.js` is the same program underneath and still takes its connection
+// string and schema on the command line - that is the door for scripts and
+// for the checks in this repo, and it has not changed. This file exists
+// because the person this product is for does not have a command line habit.
+// They have a Lovable app, a Supabase project somebody set up for them, and a
+// worry that anyone can read their customers table. Everything between them
+// and an answer is in this file.
+//
+// Exit codes are the same three as `scan.js`, because anything that automates
+// this reads those and not the words:
+//
+//     0   every attack that ran, lost
+//     1   something got through
+//     2   it could not run at all
+
+const path = require('path');
+const { Client } = require('pg');
+
+const scanner = require('../scan.js');
+const recheck = require('../recheck.js');
+const intro = require('../intro.js');
+const trouble = require('../trouble.js');
+const { howToConnect } = require('../connect.js');
+
+const line = (text) => process.stdout.write(text + '\n');
+const fail = (text) => process.stderr.write(text + '\n');
+
+function usage() {
+  return [
+    '',
+    '  kryptheon-night - attacks a copy of your database and tells you what got in.',
+    '',
+    '  Run it with nothing and it will ask you for what it needs:',
+    '',
+    '      npx kryptheon-night',
+    '',
+    '  Options, none of them necessary:',
+    '',
+    '      --recheck        run the same attacks again after a fix, and say',
+    '                       which problems are actually closed',
+    '      --schema NAME    the part of the database your app lives in.',
+    '                       Leave it out; it is "public" for almost everyone',
+    '      --yes            skip the "may I?" question. For scripts only',
+    '      --help           this',
+    '',
+    '  The connection string can be put in KN_DATABASE_URL instead of being',
+    '  typed in, which is how you would run this on a schedule.',
+    '',
+  ];
+}
+
+/** What was asked for, and what was left to the default. */
+function readArgs(argv) {
+  const asked = { schema: null, recheck: false, yes: false, help: false, unknown: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--recheck') asked.recheck = true;
+    else if (arg === '--yes' || arg === '-y') asked.yes = true;
+    else if (arg === '--help' || arg === '-h') asked.help = true;
+    else if (arg === '--schema') asked.schema = argv[++i] || null;
+    else if (arg.startsWith('--schema=')) asked.schema = arg.slice('--schema='.length);
+    else if (arg.startsWith('-')) asked.unknown.push(arg);
+    // A bare word is the schema, so that somebody who has read the old
+    // instructions and types `kryptheon-night public` is not told off.
+    else if (!asked.schema) asked.schema = arg;
+    else asked.unknown.push(arg);
+  }
+  return asked;
+}
+
+/** Prints a block of plain lines with the indent the rest of the report uses. */
+function block(lines, write) {
+  (write || line)('');
+  for (const text of lines) (write || line)(text ? '  ' + text : '');
+  (write || line)('');
+}
+
+async function main() {
+  const asked = readArgs(process.argv.slice(2));
+
+  if (asked.help) {
+    usage().forEach(line);
+    return;
+  }
+  if (asked.unknown.length) {
+    fail('');
+    fail('  I do not know the option ' + asked.unknown[0] + '.');
+    usage().forEach(fail);
+    process.exit(2);
+  }
+
+  line('');
+  line('  Kryptheon Night Shift');
+  line('  I attack a copy of your database and tell you what got in.');
+
+  // Asking needs somewhere to ask. Piped into a script or run by a scheduler
+  // there is no keyboard, and a prompt written to nobody looks exactly like a
+  // program that has frozen.
+  const canAsk = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  let connection = process.env.KN_DATABASE_URL || '';
+  if (!connection) {
+    if (!canAsk) {
+      fail('');
+      fail('  I need a connection string and there is nobody here to ask.');
+      fail('');
+      fail('  Run me in a terminal window, or set KN_DATABASE_URL first.');
+      fail('');
+      process.exit(2);
+    }
+    connection = await intro.askForConnection(line);
+  }
+
+  // Everything that can be told from the string alone is told now, before a
+  // single packet goes anywhere. These are the mistakes a person makes on
+  // their first try, and Postgres describes every one of them badly.
+  const unusable = trouble.readConnectionString(connection);
+  if (unusable) {
+    block(unusable, fail);
+    process.exit(2);
+  }
+  connection = connection.trim().replace(/^["']|["']$/g, '');
+
+  const warning = trouble.poolerWarning(connection);
+  if (warning) block(warning);
+
+  const target = asked.schema || 'public';
+
+  // The password is not shown back, but the address is - it is the part a
+  // person can check, and seeing their own project name appear is the first
+  // sign that any of this is working.
+  line('');
+  line('  Database: ' + trouble.withoutSecret(connection));
+
+  if (!asked.yes) {
+    if (!canAsk) {
+      fail('');
+      fail('  I will not connect to your database without being told yes, and');
+      fail('  there is nobody here to ask.');
+      fail('');
+      fail('  Add --yes if you meant to run this unattended.');
+      fail('');
+      process.exit(2);
+    }
+    block(intro.consentLines(target));
+    const yes = await intro.askYesNo('  Go ahead? (y/n) ');
+    if (!yes) {
+      line('');
+      line('  Stopped. Nothing was connected to and nothing was changed.');
+      line('');
+      process.exit(0);
+    }
+  }
+
+  const file = path.resolve(scanner.LAST_RUN);
+  const before = asked.recheck ? scanner.loadLastRun(file) : null;
+  if (asked.recheck && !before) {
+    fail('');
+    fail('  There is no earlier run in this folder to compare against.');
+    fail('');
+    fail('  --recheck proves a fix worked by running the same attacks again and');
+    fail('  comparing. With nothing to compare against it would report every');
+    fail('  problem as new, which would look like an answer and would not be one.');
+    fail('');
+    fail('  Run it without --recheck first.');
+    fail('');
+    process.exit(2);
+  }
+
+  line('');
+  line('  Connecting ...');
+
+  let client;
+  try {
+    client = new Client(howToConnect(connection));
+    await client.connect();
+  } catch (err) {
+    block(trouble.explain(err, connection), fail);
+    process.exit(2);
+  }
+
+  line('  Connected.');
+  line('');
+
+  try {
+    const result = await scanner.scan(client, target, {
+      // Two requests arriving at the same instant cannot be faked down one
+      // connection, so the collision attack is handed a way to open its own.
+      // This is the one attack the nightly installer will never be able to
+      // run, and the report says so when it cannot.
+      openSession: async () => {
+        const extra = new Client(howToConnect(connection));
+        await extra.connect();
+        return extra;
+      },
+    });
+
+    if (!before) {
+      scanner.report(result);
+      scanner.saveRun(file, result);
+      process.exitCode = result.stopped ? 2 : result.findings.length ? 1 : 0;
+      return;
+    }
+
+    const verdict = recheck.compare(before, result);
+    recheck.describe(verdict).forEach(line);
+    recheck.badgeLines(verdict, result.attacksRun || 0).forEach(line);
+    if (result.findings.length) scanner.report(result);
+    scanner.saveRun(file, result);
+    process.exitCode = result.stopped ? 2 : verdict.allClear ? 0 : 1;
+  } catch (err) {
+    // Anything that went wrong mid-scan. The copy has already been dropped by
+    // the `finally` inside the scan itself, so there is nothing to clean up
+    // here - only something to say.
+    block(trouble.explain(err, connection), fail);
+    process.exitCode = 2;
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
+// Ctrl-C during the attack leaves a copy behind, because the process dies
+// before the `finally` that drops it runs. The next run sweeps it up, but the
+// person deserves to know it is there rather than finding it themselves.
+process.on('SIGINT', () => {
+  line('');
+  line('');
+  line('  Stopped.');
+  line('');
+  line('  If I had already made the temporary copy, it is still in your');
+  line('  database. Run me again and I will delete it before I start.');
+  line('');
+  process.exit(130);
+});
+
+main().catch((err) => {
+  block(trouble.explain(err, process.env.KN_DATABASE_URL || ''), fail);
+  process.exit(2);
+});

package/collision.js

@@ -0,0 +1,309 @@
+// The collision attack.
+//
+// Two requests arriving at the same moment, where only one of them should be
+// allowed to win. Impersonation asks "can the wrong person read this". This
+// asks "can the same thing exist twice", which is the bug nobody finds by
+// clicking through their own app, because one person clicking is never two
+// requests at once.
+//
+// It is run for real: two separate database sessions, both inside open
+// transactions, both inserting the same value while the other is still in
+// flight. Reading the catalogue and noticing a missing unique index would have
+// been easier and would have been a guess - the same shortcut that made the
+// copy look right while the grants were missing. So the value is inserted
+// twice and the rows are counted afterwards.
+//
+// WHAT THIS DELIBERATELY DOES NOT REPORT
+//
+// The lost update - two withdrawals of 100 from a balance of 100 that both
+// succeed. It is real, it is common, and it cannot honestly be reported from
+// here. Every Postgres database on default isolation behaves that way for a
+// read-then-write, so whether an app is actually vulnerable depends on code
+// this tool never sees: an atomic UPDATE or a SELECT ... FOR UPDATE makes it
+// safe, and nothing in the schema says which was used. Reporting it would mean
+// flagging every app that has a number in it. That is the definition of crying
+// wolf, and the re-check at the end of the loop is worth exactly as much as
+// the first report was believable.
+//
+// So only what was actually proven gets said: the same value went in twice,
+// here is the count.
+
+const { quote } = require('./schema.js');
+const attack = require('./attack.js');
+
+/**
+ * Columns where two rows holding one value is a security problem rather than
+ * an untidy spreadsheet.
+ *
+ * Anchored on the whole name on purpose. `token` is a credential; `token_id`,
+ * `token_expires_at` and `has_token` are not, and matching loosely would put
+ * three false alarms on screen for every real one.
+ */
+const MUST_BE_UNIQUE = [
+  {
+    // One secret matching two rows opens two different doors.
+    expectation: 'credential',
+    test: /^(token|auth_token|access_token|refresh_token|reset_token|session_token|session_id|api_key|apikey|access_key|secret_key)$/i,
+  },
+  {
+    // A one-time code that can exist twice can be redeemed twice.
+    expectation: 'code',
+    test: /^(invite_code|invitation_code|coupon_code|promo_code|promotion_code|referral_code|voucher_code|redemption_code|activation_code|license_key|serial_key)$/i,
+  },
+  {
+    // Two accounts answering to one login make "who is this" ambiguous, and
+    // password reset has to pick one of them.
+    expectation: 'identity',
+    test: /^(email|e_mail|username|user_name|handle|login)$/i,
+    accountTablesOnly: true,
+  },
+];
+
+/**
+ * Tables where a duplicate email really is a login problem.
+ *
+ * `customers` is deliberately absent. In half the apps it is the account
+ * table and in the other half it is a contact list, where two contacts sharing
+ * an office email is normal and correct. A finding that is wrong half the time
+ * is worse than no finding, so the ambiguous name is left alone.
+ */
+const ACCOUNT_TABLE = /^(users?|profiles?|accounts?|members?|auth_users|app_users|logins?)$/i;
+
+/** Everything on a table that already promises "only one of these". */
+function uniquenessTexts(table, indexes) {
+  const fromConstraints = (table.constraints || [])
+    .filter((c) => c.kind === 'u' || c.kind === 'p')
+    .map((c) => c.definition);
+  const fromIndexes = (indexes || [])
+    .filter((i) => i.table_name === table.name)
+    .map((i) => i.definition);
+  return fromConstraints.concat(fromIndexes);
+}
+
+/**
+ * Is this column already protected?
+ *
+ * Deliberately generous. A composite UNIQUE (org_id, email) counts, because
+ * the same email in two different organisations is how multi-tenant apps are
+ * supposed to work and calling that a bug would be wrong. A partial index
+ * counts, and so does an expression index on lower(email). The cost is that a
+ * column merely mentioned in some other index's WHERE clause also counts and
+ * gets skipped - an attack not run rather than a false alarm raised, which is
+ * the right way round.
+ */
+function coveredByUnique(table, columnName, indexes) {
+  const escaped = String(columnName).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const word = new RegExp('(^|[^A-Za-z0-9_])' + escaped + '([^A-Za-z0-9_]|$)');
+  return uniquenessTexts(table, indexes).some((text) => word.test(String(text)));
+}
+
+/**
+ * Every column worth racing, with whether it is already protected.
+ *
+ * Protected columns are raced too, and that is deliberate. The first version
+ * skipped them, which meant that the moment somebody added the unique
+ * constraint the attack stopped running - so the re-check could no longer see
+ * it happen, and reported the fix it had asked for as "could not confirm".
+ * A fix has to be provable, and the only proof is running the same attack
+ * again and watching it be refused.
+ *
+ * `covered` decides what is reported, never what is attempted. It has to stay,
+ * because UNIQUE (org_id, email) genuinely allows the same email twice and
+ * calling that a bug would be wrong.
+ */
+function candidates(tables, indexes) {
+  const found = [];
+  for (const table of tables || []) {
+    for (const column of table.columns || []) {
+      const rule = MUST_BE_UNIQUE.find((r) => r.test.test(column.name));
+      if (!rule) continue;
+      if (rule.accountTablesOnly && !ACCOUNT_TABLE.test(table.name)) continue;
+      found.push({
+        table: table.name,
+        column: column.name,
+        expectation: rule.expectation,
+        type: column.type,
+        covered: coveredByUnique(table, column.name, indexes),
+      });
+    }
+  }
+  return found;
+}
+
+/** Keeps the colliding value inside a declared width like varchar(12). */
+function fitToType(text, type) {
+  const match = /^[a-z ]*\((\d+)\)$/.exec(String(type || '').trim());
+  if (!match) return text;
+  const limit = Number(match[1]);
+  return text.length > limit ? text.slice(0, limit) : text;
+}
+
+/** The one value both sessions will fight over. */
+function collidingValue(target) {
+  const type = String(target.type || '').toLowerCase();
+  if (type === 'uuid') return '33333333-3333-4333-8333-333333333333';
+  if (/^(integer|bigint|smallint|numeric|decimal|real|double)/.test(type)) return 424242;
+  return fitToType('kryptheon-collision', target.type);
+}
+
+/**
+ * Two inserts of the same value, genuinely at the same time.
+ *
+ * The sequencing is the delicate part, and it was measured rather than assumed
+ * (probe-collision.js). When a unique index IS present the second insert
+ * blocks until the first transaction ends, so waiting on both before
+ * committing either simply hangs for ever. So: run the first, commit it, and
+ * only then wait on the second - which has been in flight, inside its own open
+ * transaction, the whole time.
+ */
+async function race(one, two, run) {
+  await one.query('BEGIN');
+  await two.query('BEGIN');
+  // A pathological lock must not hang the night's run.
+  await one.query("SET LOCAL statement_timeout = '15s'");
+  await two.query("SET LOCAL statement_timeout = '15s'");
+
+  const first = await run(one).then(
+    () => ({ ok: true }),
+    (err) => ({ ok: false, why: err.message }),
+  );
+
+  // Fired and deliberately not awaited: it has to be in flight while the first
+  // transaction is still open, or this is not a race at all.
+  const pending = run(two).then(
+    () => ({ ok: true }),
+    (err) => ({ ok: false, why: err.message }),
+  );
+
+  await one.query(first.ok ? 'COMMIT' : 'ROLLBACK');
+  const second = await pending;
+  await two.query(second.ok ? 'COMMIT' : 'ROLLBACK');
+
+  return { first: first, second: second };
+}
+
+/**
+ * Race every candidate, and say what got through.
+ *
+ * `notTried` is the half that keeps this honest. If the first insert fails -
+ * a constraint the seeding could not satisfy, a column that will not take the
+ * value - then nothing was learned about that column, and saying nothing at
+ * all would let it read as safe. A table nobody could test is not a table that
+ * held.
+ */
+async function collide(client, one, two, schema, tables, indexes) {
+  const findings = [];
+  const notTried = [];
+  const raced = [];
+  const byName = new Map((tables || []).map((t) => [t.name, t]));
+
+  for (const target of candidates(tables, indexes)) {
+    const table = byName.get(target.table);
+    const value = collidingValue(target);
+    const override = {};
+    override[target.column] = value;
+
+    let rows;
+    try {
+      // Two people the seeder never used, or on a table keyed by the person
+      // these rows clash with the seeded ones and the clash gets read as the
+      // app refusing a duplicate it never even saw.
+      // Numeric tags, so every other generated value differs between the two
+      // rows. They have to collide on the column under test and on nothing
+      // else, or a refusal elsewhere would be read as the app defending itself.
+      rows = [
+        await attack.rowFor(client, schema, table, attack.USER_C, 101, override),
+        await attack.rowFor(client, schema, table, attack.USER_D, 102, override),
+      ];
+    } catch (err) {
+      if (!target.covered) notTried.push({ table: target.table, column: target.column, why: err.message });
+      continue;
+    }
+
+    let outcome;
+    try {
+      let nth = 0;
+      outcome = await race(one, two, (session) => {
+        const row = rows[nth];
+        nth += 1;
+        return attack.insertRow(session, schema, target.table, row);
+      });
+    } catch (err) {
+      if (!target.covered) notTried.push({ table: target.table, column: target.column, why: err.message });
+      continue;
+    }
+
+    if (!outcome.first.ok) {
+      // Not a pass. The attack never got off the ground - unless the column
+      // is already protected, where the constraint itself is the answer and
+      // the race was only ever there to demonstrate it.
+      if (!target.covered) notTried.push({
+        table: target.table,
+        column: target.column,
+        why: 'I could not get even one test row in: ' + outcome.first.why,
+      });
+      continue;
+    }
+
+    // Counted rather than inferred from the two answers, because that is the
+    // thing a person can be told without hedging: there are now two.
+    let copies = 0;
+    try {
+      const { rows: counted } = await client.query(
+        'SELECT count(*)::int AS n FROM ' + quote(schema) + '.' + quote(target.table) +
+          ' WHERE ' + quote(target.column) + ' = $1',
+        [value],
+      );
+      copies = counted[0].n;
+    } catch (err) {
+      if (!target.covered) notTried.push({ table: target.table, column: target.column, why: 'could not count the rows: ' + err.message });
+      continue;
+    }
+
+    // The race happened and its result is known. Recorded whichever way it
+    // went: a refusal is an answer, and the re-check has to be able to tell
+    // "attacked and held" from "never attacked".
+    raced.push({ table: target.table, column: target.column });
+
+    // A duplicate that landed on a column carrying UNIQUE (org_id, email) is
+    // the multi-tenant design working, not a hole.
+    if (copies > 1 && !target.covered) {
+      findings.push({
+        kind: 'duplicated',
+        table: target.table,
+        column: target.column,
+        expectation: target.expectation,
+        copies: copies,
+        columns: (table.columns || []).map((c) => c.name),
+      });
+    }
+
+    // Put the copy back as it was found, so anything that runs after this
+    // reads the same database the earlier attacks did.
+    try {
+      await client.query(
+        'DELETE FROM ' + quote(schema) + '.' + quote(target.table) + ' WHERE ' + quote(target.column) + ' = $1',
+        [value],
+      );
+    } catch (err) {
+      if (!target.covered) notTried.push({
+        table: target.table,
+        column: target.column,
+        why: 'the test rows could not be cleaned up: ' + err.message,
+      });
+    }
+  }
+
+  return { findings: findings, notTried: notTried, raced: raced };
+}
+
+module.exports = {
+  MUST_BE_UNIQUE: MUST_BE_UNIQUE,
+  ACCOUNT_TABLE: ACCOUNT_TABLE,
+  uniquenessTexts: uniquenessTexts,
+  coveredByUnique: coveredByUnique,
+  candidates: candidates,
+  collidingValue: collidingValue,
+  race: race,
+  collide: collide,
+};

package/connect.js

@@ -0,0 +1,60 @@
+// How to open a connection, which is not the same as the string a person
+// pasted.
+//
+// In its own file because the decision is worth checking directly, and the
+// command it is used from runs the moment it is required.
+
+// Long enough for a Supabase project that has gone to sleep to wake up - free
+// projects pause after a week and take the better part of half a minute to
+// come back - and short enough that a blocked port does not look like a hang.
+// Without this the connection simply never returns and the person is left
+// watching a cursor with nothing to read.
+const CONNECT_TIMEOUT = 30000;
+
+// The two SSL modes the hosting companies put in the string themselves.
+// Nobody chose these; they came with the copy button.
+//
+// Measured: `pg` 8.23 reads both of them as full certificate verification,
+// and prints a nine-line upgrade notice to the screen while doing it. Neon
+// hands out a string ending `?sslmode=require`, so a person following the
+// instructions gets that notice in the middle of their security report - and
+// on Supabase's own certificate authority, verify-full fails outright.
+//
+// So these two are dropped and replaced with what `sslmode=require` means
+// everywhere else: encrypted, certificate not verified. Everything else -
+// verify-full, verify-ca, no-verify, disable - is somebody who went and typed
+// it, and is left exactly as they wrote it.
+const HANDED_OUT = /^(require|prefer)$/i;
+
+/** A database on this machine is not crossing a network. */
+function isLocal(host) {
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '';
+}
+
+function howToConnect(connectionString) {
+  let url;
+  try {
+    url = new URL(connectionString);
+  } catch (err) {
+    // Unparseable strings never get this far - readConnectionString stops
+    // them - but connecting and failing is better than throwing from here.
+    return { connectionString: connectionString, connectionTimeoutMillis: CONNECT_TIMEOUT };
+  }
+
+  const mode = url.searchParams.get('sslmode');
+  if (mode && !HANDED_OUT.test(mode)) {
+    return { connectionString: connectionString, connectionTimeoutMillis: CONNECT_TIMEOUT };
+  }
+  if (mode) url.searchParams.delete('sslmode');
+
+  const config = { connectionString: url.toString(), connectionTimeoutMillis: CONNECT_TIMEOUT };
+  if (isLocal(url.hostname)) return config;
+
+  config.ssl = { rejectUnauthorized: false };
+  return config;
+}
+
+module.exports = {
+  howToConnect: howToConnect,
+  CONNECT_TIMEOUT: CONNECT_TIMEOUT,
+};