years-old API keys are still live with nobody owning them

"""Report Twilio API keys that are old, unnamed, or otherwise unaccounted for.

Read only. GET requests and nothing else: give this an API Key with read access
rather than the account auth token. The repair is printed, never performed,
because deleting a key revokes REST access immediately and invalidates every
Access Token that key's secret ever signed.
"""
import argparse
import datetime
import logging
import os
import sys
from email.utils import parsedate_to_datetime

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("twilio_api_key_audit")

HOST = "https://api.twilio.com"
BASE = HOST + "/2010-04-01"

# Names that identify nothing. A key wearing one of these cannot be traced to an
# owner, which is worse than a key that is merely old.
PLACEHOLDER_NAMES = {"", "untitled", "untitled key", "default", "key", "my key",
                     "test", "temp", "tmp", "quickstart", "new key", "api key"}


def parse_date(value):
    """Parse a Twilio timestamp into an aware UTC datetime.

    The 2010-04-01 API returns RFC 2822 ("Tue, 18 Apr 2023 09:12:00 +0000") while
    the newer Twilio domains return ISO 8601. Branch on the first characters
    rather than letting one parser guess at the other's format: a parser that
    returns nothing produces a report with no findings, which reads exactly like
    a clean account.
    """
    text = str(value or "").strip()
    if not text:
        return None
    if text[:4].isdigit():
        try:
            parsed = datetime.datetime.fromisoformat(text.replace("Z", "+00:00"))
        except ValueError:
            return None
    else:
        try:
            parsed = parsedate_to_datetime(text)
        except (TypeError, ValueError):
            return None
    if parsed is None:
        return None
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=datetime.timezone.utc)
    return parsed.astimezone(datetime.timezone.utc)


def age_days(key, now):
    """Days since the key was created, or None when the date will not parse."""
    created = parse_date(key.get("date_created"))
    if created is None:
        return None
    return (now - created).days


def verdict(key, now, max_age_days=365):
    """Classify one API key. Pure, so the rules can be tested without a network.

    There is no last-used timestamp on a Twilio key, on any Twilio resource. So
    this cannot ask whether a key is in use; it asks whether a human can account
    for it, which makes the name the control and an empty name the finding.

    Returns (state, detail).
    """
    name = str(key.get("friendly_name") or "").strip()
    sid = str(key.get("sid") or "").strip()

    if name.lower() in PLACEHOLDER_NAMES or (sid and name == sid):
        return ("unowned",
                "friendly_name is %s: nothing on the account records what this "
                "key authenticates, and a key nobody can account for is a key "
                "nobody will ever be willing to delete." % (name or "empty"))

    age = age_days(key, now)
    if age is None:
        return ("undated",
                "date_created did not parse (%s): this API returns RFC 2822, not "
                "ISO 8601. Treat the key as the oldest on the account until "
                "somebody establishes otherwise." % (key.get("date_created") or "empty"))

    if age > max_age_days:
        created = parse_date(key.get("date_created"))
        renamed = parse_date(key.get("date_updated"))
        untouched = (renamed is not None and created is not None and renamed <= created)
        return ("stale",
                "%s, created %d days ago, past the %d day rotation window%s."
                % (name, age, max_age_days,
                   "; date_updated has never moved, so nobody has even renamed it"
                   if untouched else ""))

    return ("current", "%s, created %d days ago." % (name, age))


def get(session, url, **params):
    r = session.get(url, params=params, timeout=30)
    if r.status_code in (401, 403):
        raise SystemExit("%d from Twilio: check TWILIO_ACCOUNT_SID and that the "
                         "API key belongs to that account with read access"
                         % r.status_code)
    r.raise_for_status()
    return r.json()


def list_keys(session, account, limit=500):
    """Page Keys.json. next_page_uri is a path, not an absolute URL."""
    url = "%s/Accounts/%s/Keys.json" % (BASE, account)
    params = {"PageSize": 50}
    out = []
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get("keys", []))
        nxt = page.get("next_page_uri")
        url, params = (HOST + nxt) if nxt else None, {}
    return out[:limit]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-age-days", type=int, default=365,
                    help="keys older than this are reported for rotation")
    ap.add_argument("--as-of", default=None,
                    help="ISO date to age keys against, for a reproducible run")
    args = ap.parse_args()

    account = os.environ.get("TWILIO_ACCOUNT_SID")
    key = os.environ.get("TWILIO_API_KEY")
    secret = os.environ.get("TWILIO_API_SECRET")
    if not (account and key and secret):
        log.error("set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET "
                  "(an API Key with read access, not the auth token)")
        return 2

    now = parse_date(args.as_of) if args.as_of else None
    if now is None:
        now = datetime.datetime.now(datetime.timezone.utc)

    session = requests.Session()
    session.auth = (key, secret)

    keys = list_keys(session, account)
    if not keys:
        log.info("no API keys on this account: see the note on the auth token")
        return 0

    unowned = stale = 0
    for entry in keys:
        state, detail = verdict(entry, now, args.max_age_days)
        line = "%-8s %s  %s" % (state, entry.get("sid", "?"), detail)
        if state == "current":
            log.info(line)
            continue
        if state == "unowned":
            unowned += 1
        else:
            stale += 1
        log.warning(line)
        log.warning("  repair: rename it first, POST %s/Accounts/%s/Keys/%s.json "
                    "FriendlyName={owner}-{service}; once a cycle has passed with "
                    "nobody claiming it, remove it with DELETE on the same resource",
                    BASE, account, entry.get("sid", "?"))
        log.warning("  deleting also invalidates every Access Token signed with "
                    "this key's secret, so client SDK sessions drop with it")

    log.info("%d key(s), %d unowned, %d past the rotation window",
             len(keys), unowned, stale)
    return 1 if (unowned or stale) else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report Twilio API keys that are old, unnamed, or otherwise unaccounted for.
 *
 * Read only. GET requests and nothing else: give this an API Key with read
 * access rather than the account auth token. The repair is printed, never
 * performed, because removing a key revokes REST access immediately and
 * invalidates every Access Token that key's secret ever signed.
 */
const HOST = 'https://api.twilio.com';
const BASE = `${HOST}/2010-04-01`;

// Names that identify nothing. A key wearing one of these cannot be traced to an
// owner, which is worse than a key that is merely old.
const PLACEHOLDER_NAMES = new Set(['', 'untitled', 'untitled key', 'default', 'key',
  'my key', 'test', 'temp', 'tmp', 'quickstart', 'new key', 'api key']);

/**
 * Parse a Twilio timestamp. The 2010-04-01 API returns RFC 2822 while the newer
 * domains return ISO 8601; Date.parse reads both, and Twilio always sends an
 * explicit offset, so there is no local-time ambiguity to guard against.
 */
export function parseDate(value) {
  const text = String(value ?? '').trim();
  if (!text) return null;
  const ms = Date.parse(text);
  return Number.isNaN(ms) ? null : new Date(ms);
}

/** Days since the key was created, or null when the date will not parse. */
export function ageDays(key, now) {
  const created = parseDate(key.date_created);
  if (created === null) return null;
  return Math.floor((now.getTime() - created.getTime()) / 86400000);
}

/**
 * Classify one API key. Pure, so the rules can be tested without a network.
 *
 * There is no last-used timestamp on a Twilio key, so this cannot ask whether a
 * key is in use. It asks whether a human can account for it, which makes the
 * name the control and an empty name the finding. Returns [state, detail].
 */
export function verdict(key, now, maxAgeDays = 365) {
  const name = String(key.friendly_name ?? '').trim();
  const sid = String(key.sid ?? '').trim();

  if (PLACEHOLDER_NAMES.has(name.toLowerCase()) || (sid && name === sid)) {
    return ['unowned',
      `friendly_name is ${name || 'empty'}: nothing on the account records what ` +
      'this key authenticates, and a key nobody can account for is a key nobody ' +
      'will ever be willing to delete.'];
  }

  const age = ageDays(key, now);
  if (age === null) {
    return ['undated',
      `date_created did not parse (${key.date_created || 'empty'}): this API ` +
      'returns RFC 2822, not ISO 8601. Treat the key as the oldest on the account ' +
      'until somebody establishes otherwise.'];
  }

  if (age > maxAgeDays) {
    const created = parseDate(key.date_created);
    const renamed = parseDate(key.date_updated);
    const untouched = renamed !== null && created !== null
      && renamed.getTime() <= created.getTime();
    return ['stale',
      `${name}, created ${age} days ago, past the ${maxAgeDays} day rotation ` +
      `window${untouched ? '; date_updated has never moved, so nobody has even renamed it' : ''}.`];
  }

  return ['current', `${name}, created ${age} days ago.`];
}

function authHeader(key, secret) {
  return `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
}

async function get(auth, url, params = {}) {
  const u = new URL(url);
  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
  const res = await fetch(u, { headers: { Authorization: auth } });
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from Twilio: check TWILIO_ACCOUNT_SID and ` +
                    'that the API key belongs to that account with read access');
  }
  if (!res.ok) throw new Error(`${res.status} from ${u.pathname}`);
  return res.json();
}

export async function listKeys(auth, account, limit = 500) {
  let url = `${BASE}/Accounts/${account}/Keys.json`;
  let params = { PageSize: 50 };
  const out = [];
  while (url && out.length < limit) {
    const page = await get(auth, url, params);
    out.push(...(page.keys ?? []));
    url = page.next_page_uri ? HOST + page.next_page_uri : null;
    params = {};
  }
  return out.slice(0, limit);
}

async function main() {
  const account = process.env.TWILIO_ACCOUNT_SID;
  const key = process.env.TWILIO_API_KEY;
  const secret = process.env.TWILIO_API_SECRET;
  if (!account || !key || !secret) {
    console.error('set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET ' +
                  '(an API Key with read access, not the auth token)');
    process.exitCode = 2;
    return;
  }

  const flag = process.argv.indexOf('--max-age-days');
  const maxAgeDays = flag === -1 ? 365 : Number.parseInt(process.argv[flag + 1], 10);
  const now = new Date();

  const auth = authHeader(key, secret);
  const keys = await listKeys(auth, account);
  if (keys.length === 0) {
    console.log('no API keys on this account: see the note on the auth token');
    return;
  }

  let unowned = 0;
  let stale = 0;
  for (const entry of keys) {
    const [state, detail] = verdict(entry, now, maxAgeDays);
    const line = `${state.padEnd(8)} ${entry.sid ?? '?'}  ${detail}`;
    if (state === 'current') { console.log(line); continue; }
    if (state === 'unowned') unowned += 1; else stale += 1;
    console.warn(line);
    console.warn(`  repair: rename it first, POST ${BASE}/Accounts/${account}/Keys/` +
                 `${entry.sid ?? '?'}.json FriendlyName={owner}-{service}; once a ` +
                 'cycle has passed with nobody claiming it, remove it with DELETE ' +
                 'on the same resource');
    console.warn('  deleting also invalidates every Access Token signed with this ' +
                 "key's secret, so client SDK sessions drop with it");
  }

  console.log(`${keys.length} key(s), ${unowned} unowned, ${stale} past the rotation window`);
  process.exitCode = (unowned || stale) ? 1 : 0;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing credentials and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

import datetime

from twilio_api_key_audit import age_days, parse_date, verdict

NOW = datetime.datetime(2026, 8, 30, tzinfo=datetime.timezone.utc)


def make(**kw):
    key = {"sid": "SK00000000000000000000000000000001",
           "friendly_name": "billing-worker-prod",
           "date_created": "Sat, 01 Aug 2026 09:12:00 +0000",
           "date_updated": "Sat, 01 Aug 2026 09:12:00 +0000"}
    key.update(kw)
    return key


def test_the_2010_api_returns_rfc_2822_and_it_has_to_parse():
    parsed = parse_date("Tue, 18 Apr 2023 09:12:00 +0000")
    assert parsed == datetime.datetime(2023, 4, 18, 9, 12,
                                       tzinfo=datetime.timezone.utc)


def test_iso_8601_from_the_newer_domains_parses_too():
    parsed = parse_date("2023-04-18T09:12:00Z")
    assert parsed == datetime.datetime(2023, 4, 18, 9, 12,
                                       tzinfo=datetime.timezone.utc)


def test_an_unparseable_date_is_none_rather_than_a_wrong_answer():
    assert parse_date("last tuesday") is None
    assert parse_date("") is None
    assert parse_date(None) is None


def test_age_is_measured_in_whole_days_from_the_created_date():
    assert age_days(make(date_created="Thu, 30 Jul 2026 00:00:00 +0000"), NOW) == 31


def test_a_recently_created_named_key_is_current():
    state, _ = verdict(make(), NOW)
    assert state == "current"


def test_an_empty_friendly_name_is_unowned_whatever_its_age():
    state, detail = verdict(make(friendly_name="",
                                 date_created="Sat, 01 Aug 2026 09:12:00 +0000"), NOW)
    assert state == "unowned"
    assert "nobody can account for" in detail


def test_a_placeholder_name_counts_as_no_name():
    assert verdict(make(friendly_name="Untitled"), NOW)[0] == "unowned"
    assert verdict(make(friendly_name="  test  "), NOW)[0] == "unowned"


def test_a_key_named_after_its_own_sid_records_nothing():
    sid = "SK00000000000000000000000000000009"
    assert verdict(make(sid=sid, friendly_name=sid), NOW)[0] == "unowned"


def test_a_named_key_past_the_window_is_stale():
    state, detail = verdict(make(date_created="Wed, 15 Mar 2023 09:12:00 +0000",
                                 date_updated="Wed, 15 Mar 2023 09:12:00 +0000"),
                            NOW, max_age_days=365)
    assert state == "stale"
    assert "never moved" in detail


def test_date_updated_after_creation_is_a_rename_not_activity():
    # It moved, so the report drops the "never renamed" clause. It still says
    # nothing about whether the key has ever been used.
    state, detail = verdict(make(date_created="Wed, 15 Mar 2023 09:12:00 +0000",
                                 date_updated="Mon, 06 Jan 2025 11:00:00 +0000"),
                            NOW, max_age_days=365)
    assert state == "stale"
    assert "never moved" not in detail


def test_a_key_whose_date_will_not_parse_is_reported_not_skipped():
    state, detail = verdict(make(date_created="18/04/2023"), NOW)
    assert state == "undated"
    assert "RFC 2822" in detail

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { ageDays, parseDate, verdict } from './twilio-api-key-audit.mjs';

const NOW = new Date('2026-08-30T00:00:00Z');

const make = (over = {}) => ({
  sid: 'SK00000000000000000000000000000001',
  friendly_name: 'billing-worker-prod',
  date_created: 'Sat, 01 Aug 2026 09:12:00 +0000',
  date_updated: 'Sat, 01 Aug 2026 09:12:00 +0000',
  ...over,
});

test('the 2010 api returns rfc 2822 and it has to parse', () => {
  assert.equal(parseDate('Tue, 18 Apr 2023 09:12:00 +0000').toISOString(),
               '2023-04-18T09:12:00.000Z');
});

test('iso 8601 from the newer domains parses too', () => {
  assert.equal(parseDate('2023-04-18T09:12:00Z').toISOString(),
               '2023-04-18T09:12:00.000Z');
});

test('an unparseable date is null rather than a wrong answer', () => {
  assert.equal(parseDate('last tuesday'), null);
  assert.equal(parseDate(''), null);
  assert.equal(parseDate(null), null);
});

test('age is measured in whole days from the created date', () => {
  assert.equal(ageDays(make({ date_created: 'Thu, 30 Jul 2026 00:00:00 +0000' }), NOW),
               31);
});

test('a recently created named key is current', () => {
  assert.equal(verdict(make(), NOW)[0], 'current');
});

test('an empty friendly name is unowned whatever its age', () => {
  const [state, detail] = verdict(make({ friendly_name: '' }), NOW);
  assert.equal(state, 'unowned');
  assert.match(detail, /nobody can account for/);
});

test('a placeholder name counts as no name', () => {
  assert.equal(verdict(make({ friendly_name: 'Untitled' }), NOW)[0], 'unowned');
  assert.equal(verdict(make({ friendly_name: '  test  ' }), NOW)[0], 'unowned');
});

test('a key named after its own sid records nothing', () => {
  const sid = 'SK00000000000000000000000000000009';
  assert.equal(verdict(make({ sid, friendly_name: sid }), NOW)[0], 'unowned');
});

test('a named key past the window is stale', () => {
  const [state, detail] = verdict(make({
    date_created: 'Wed, 15 Mar 2023 09:12:00 +0000',
    date_updated: 'Wed, 15 Mar 2023 09:12:00 +0000',
  }), NOW, 365);
  assert.equal(state, 'stale');
  assert.match(detail, /never moved/);
});

test('date_updated after creation is a rename not activity', () => {
  const [state, detail] = verdict(make({
    date_created: 'Wed, 15 Mar 2023 09:12:00 +0000',
    date_updated: 'Mon, 06 Jan 2025 11:00:00 +0000',
  }), NOW, 365);
  assert.equal(state, 'stale');
  assert.doesNotMatch(detail, /never moved/);
});

test('a key whose date will not parse is reported not skipped', () => {
  const [state, detail] = verdict(make({ date_created: 'not a date at all' }), NOW);
  assert.equal(state, 'undated');
  assert.match(detail, /RFC 2822/);
});