a conversation webhook with no URL fails every event: 50369

"""Report Twilio conversation webhooks with no URL behind them (error 50369).

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 this script holds a credential to an account that can send messages and
spend money.
"""
import argparse
import datetime as dt
import logging
import os
import re
import sys

import requests

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

MONITOR = "https://monitor.twilio.com/v1"
CONVERSATIONS = "https://conversations.twilio.com/v1"

NO_URL = 50369
CH_SID = re.compile(r"CH[0-9a-fA-F]{32}")


def conversation_sids(alerts, code=NO_URL):
    """Distinct conversation SIDs from the alerts carrying one error code. Pure.

    error_code arrives as a number on the Alert resource and as a string in some
    exports, so it is coerced rather than compared raw: that comparison is why a
    sweep reports nothing on an account full of findings. resource_sid is the
    affected resource; alert_text is the fallback when it is not a CH SID.

    Deduplicated, because one broken webhook on a busy conversation raises the
    error on every event and the finding is the conversation, not the alert.
    """
    found = []
    for a in alerts or []:
        raw = a.get("error_code")
        try:
            if raw is None or int(raw) != int(code):
                continue
        except (TypeError, ValueError):
            continue
        sid = str(a.get("resource_sid") or "")
        if not CH_SID.fullmatch(sid):
            match = CH_SID.search(str(a.get("alert_text") or ""))
            sid = match.group(0) if match else ""
        if sid and sid not in found:
            found.append(sid)
    return found


def verdict(webhook):
    """Classify one conversation-scoped webhook. Pure.

    target decides whether a URL is even required: `webhook` and `trigger`
    deliver to configuration.url, while `studio` hands the conversation to the
    Flow named by configuration.flow_sid and correctly has no URL at all.

    Returns (state, detail).
    """
    target = str(webhook.get("target") or "").lower()
    cfg = webhook.get("configuration") or {}
    url = str(cfg.get("url") or "").strip()

    if target == "studio":
        flow = str(cfg.get("flow_sid") or "").strip()
        if flow:
            return ("studio", "routes to Studio Flow %s; no URL is required." % flow)
        return ("studio-no-flow",
                "target is studio but configuration.flow_sid is empty, so there "
                "is no Flow to route to and no URL either.")

    if target not in ("webhook", "trigger"):
        return ("unknown-target",
                "target %r is not one this check understands; read the webhook "
                "resource by hand." % (target or "empty"))

    if not url:
        return ("missing-url",
                "target is %s and configuration.url is empty. Every event on this "
                "conversation raises 50369 and reaches nothing." % target)

    if url.startswith("http://"):
        return ("insecure",
                "delivers conversation content over plain http to %s. Not 50369, "
                "but message bodies in the clear." % url)

    if not url.startswith("https://"):
        return ("invalid-url",
                "configuration.url is %r, which is not an absolute http(s) URL." % url)

    return ("ok", "target %s delivering to %s." % (target, url))


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 paged(session, url, key, limit, **first):
    params = dict(first)
    params.setdefault("PageSize", 100)
    out = []
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get(key, []))
        url = (page.get("meta") or {}).get("next_page_url")
        params = {}
    return out[:limit]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=7,
                    help="how far back to sweep the alerts (30 day retention)")
    ap.add_argument("--max-alerts", type=int, default=10000,
                    help="stop paging after this many alerts")
    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

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

    start = (dt.date.today() - dt.timedelta(days=args.days)).isoformat()
    alerts = paged(session, "%s/Alerts" % MONITOR, "alerts", args.max_alerts,
                   LogLevel="error", StartDate=start)
    sids = conversation_sids(alerts)
    if not sids:
        log.info("0 conversation(s) raising 50369 in the last %d day(s)", args.days)
        return 0

    bad = 0
    for sid in sids:
        webhooks = paged(session, "%s/Conversations/%s/Webhooks"
                         % (CONVERSATIONS, sid), "webhooks", 50)
        if not webhooks:
            log.warning("%-15s %s  50369 in the alerts but the conversation has no "
                        "webhooks now: it was deleted, or the conversation was.",
                        "gone", sid)
            bad += 1
            continue
        for hook in webhooks:
            state, detail = verdict(hook)
            line = "%-15s %s/%s  %s" % (state, sid, hook.get("sid"), detail)
            if state in ("ok", "studio"):
                log.info(line)
                continue
            bad += 1
            log.warning(line)
            log.warning("  repair: update %s/Conversations/%s/Webhooks/%s with "
                        "Configuration.Url=https://... and Configuration.Method="
                        "POST, then fix the code path that created it without one.",
                        CONVERSATIONS, sid, hook.get("sid"))

    log.info("%d conversation(s) raising 50369 in the last %d day(s), %d webhook "
             "finding(s)", len(sids), args.days, bad)
    return 1 if bad else 0


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

/**
 * Report Twilio conversation webhooks with no URL behind them (error 50369).
 *
 * 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.
 */
const MONITOR = 'https://monitor.twilio.com/v1';
const CONVERSATIONS = 'https://conversations.twilio.com/v1';

const NO_URL = 50369;
const CH_SID = /CH[0-9a-fA-F]{32}/;

/**
 * Distinct conversation SIDs from the alerts carrying one error code. Pure.
 *
 * error_code arrives as a number on the Alert resource and as a string in some
 * exports, so it is coerced rather than compared raw. resource_sid is the
 * affected resource; alert_text is the fallback. Deduplicated, because one
 * broken webhook on a busy conversation raises the error on every event.
 */
export function conversationSids(alerts, code = NO_URL) {
  const found = [];
  for (const a of alerts ?? []) {
    const raw = a.error_code;
    if (raw === null || raw === undefined || raw === '') continue;
    const n = Number(raw);
    if (!Number.isFinite(n) || n !== Number(code)) continue;
    let sid = String(a.resource_sid ?? '');
    if (!/^CH[0-9a-fA-F]{32}$/.test(sid)) {
      const match = CH_SID.exec(String(a.alert_text ?? ''));
      sid = match ? match[0] : '';
    }
    if (sid && !found.includes(sid)) found.push(sid);
  }
  return found;
}

/**
 * Classify one conversation-scoped webhook. Pure.
 *
 * target decides whether a URL is even required: `webhook` and `trigger`
 * deliver to configuration.url, while `studio` hands the conversation to the
 * Flow named by configuration.flow_sid and correctly has no URL at all.
 * Returns [state, detail].
 */
export function verdict(webhook) {
  const target = String(webhook.target ?? '').toLowerCase();
  const cfg = webhook.configuration ?? {};
  const url = String(cfg.url ?? '').trim();

  if (target === 'studio') {
    const flow = String(cfg.flow_sid ?? '').trim();
    if (flow) return ['studio', `routes to Studio Flow ${flow}; no URL is required.`];
    return ['studio-no-flow',
      'target is studio but configuration.flow_sid is empty, so there is no Flow ' +
      'to route to and no URL either.'];
  }

  if (target !== 'webhook' && target !== 'trigger') {
    return ['unknown-target',
      `target "${target || 'empty'}" is not one this check understands; read the ` +
      'webhook resource by hand.'];
  }

  if (!url) {
    return ['missing-url',
      `target is ${target} and configuration.url is empty. Every event on this ` +
      'conversation raises 50369 and reaches nothing.'];
  }

  if (url.startsWith('http://')) {
    return ['insecure',
      `delivers conversation content over plain http to ${url}. Not 50369, but ` +
      'message bodies in the clear.'];
  }

  if (!url.startsWith('https://')) {
    return ['invalid-url',
      `configuration.url is "${url}", which is not an absolute http(s) URL.`];
  }

  return ['ok', `target ${target} delivering to ${url}.`];
}

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 paged(auth, url, key, limit = 10000, first = {}) {
  let next = url;
  let params = { PageSize: 100, ...first };
  const out = [];
  while (next && out.length < limit) {
    const page = await get(auth, next, params);
    out.push(...(page[key] ?? []));
    next = page.meta?.next_page_url ?? 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 auth = authHeader(key, secret);

  const days = Number(process.argv.includes('--days')
    ? process.argv[process.argv.indexOf('--days') + 1] : 7) || 7;
  const start = new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);

  const alerts = await paged(auth, `${MONITOR}/Alerts`, 'alerts', 10000,
                             { LogLevel: 'error', StartDate: start });
  const sids = conversationSids(alerts);
  if (sids.length === 0) {
    console.log(`0 conversation(s) raising 50369 in the last ${days} day(s)`);
    return;
  }

  let bad = 0;
  for (const sid of sids) {
    const webhooks = await paged(auth, `${CONVERSATIONS}/Conversations/${sid}/Webhooks`,
                                 'webhooks', 50);
    if (webhooks.length === 0) {
      console.warn(`${'gone'.padEnd(15)} ${sid}  50369 in the alerts but the ` +
                   'conversation has no webhooks now: it was deleted, or the ' +
                   'conversation was.');
      bad += 1;
      continue;
    }
    for (const hook of webhooks) {
      const [state, detail] = verdict(hook);
      const line = `${state.padEnd(15)} ${sid}/${hook.sid}  ${detail}`;
      if (state === 'ok' || state === 'studio') { console.log(line); continue; }
      bad += 1;
      console.warn(line);
      console.warn(`  repair: update ${CONVERSATIONS}/Conversations/${sid}/Webhooks/` +
                   `${hook.sid} with Configuration.Url=https://... and ` +
                   'Configuration.Method=POST, then fix the code path that created ' +
                   'it without one.');
    }
  }

  console.log(`${sids.length} conversation(s) raising 50369 in the last ${days} ` +
              `day(s), ${bad} webhook finding(s)`);
  process.exitCode = bad ? 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; });
}

from twilio_conversation_webhook_audit import conversation_sids, verdict

CH = "CH11111111111111111111111111111111"
CH2 = "CH22222222222222222222222222222222"


def alert(code=50369, resource=CH, text=""):
    return {"sid": "NO1", "error_code": code, "resource_sid": resource,
            "alert_text": text, "log_level": "error"}


def hook(target="webhook", **cfg):
    return {"sid": "WH1", "target": target, "configuration": cfg}


def test_error_code_as_a_string_still_matches():
    assert conversation_sids([alert(code="50369")]) == [CH]


def test_other_error_codes_are_ignored():
    assert conversation_sids([alert(code=50361), alert(code=None)]) == []


def test_one_chatty_conversation_is_one_finding():
    assert conversation_sids([alert(), alert(), alert(resource=CH2)]) == [CH, CH2]


def test_the_conversation_sid_is_recovered_from_the_alert_text():
    a = alert(resource="ACxxxxxxxx", text="Conversation webhook URL not provided "
                                          "for %s" % CH2)
    assert conversation_sids([a]) == [CH2]


def test_a_webhook_target_with_no_url_is_the_finding():
    state, detail = verdict(hook("webhook", url=None))
    assert state == "missing-url"
    assert "50369" in detail


def test_a_studio_target_with_no_url_is_correct():
    # This is the false positive that would make the report useless: a studio
    # webhook routes to a Flow and never has a URL.
    state, detail = verdict(hook("studio", flow_sid="FW1"))
    assert state == "studio"
    assert "FW1" in detail


def test_a_studio_target_with_no_flow_is_still_wrong():
    assert verdict(hook("studio"))[0] == "studio-no-flow"


def test_a_trigger_target_needs_a_url_too():
    assert verdict(hook("trigger", url=""))[0] == "missing-url"
    assert verdict(hook("trigger", url="https://app.example.com/hook"))[0] == "ok"


def test_plain_http_is_reported_separately_from_the_missing_url():
    state, detail = verdict(hook("webhook", url="http://app.example.com/hook"))
    assert state == "insecure"
    assert "Not 50369" in detail

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { conversationSids, verdict } from './twilio-conversation-webhook-audit.mjs';

const CH = 'CH11111111111111111111111111111111';
const CH2 = 'CH22222222222222222222222222222222';

const alert = ({ code = 50369, resource = CH, text = '' } = {}) => ({
  sid: 'NO1', error_code: code, resource_sid: resource, alert_text: text,
  log_level: 'error',
});

const hook = (target = 'webhook', configuration = {}) => ({
  sid: 'WH1', target, configuration,
});

test('error code as a string still matches', () => {
  assert.deepEqual(conversationSids([alert({ code: '50369' })]), [CH]);
});

test('other error codes are ignored', () => {
  assert.deepEqual(conversationSids([alert({ code: 50361 }), alert({ code: null })]), []);
});

test('one chatty conversation is one finding', () => {
  assert.deepEqual(conversationSids([alert(), alert(), alert({ resource: CH2 })]),
    [CH, CH2]);
});

test('the conversation sid is recovered from the alert text', () => {
  const a = alert({ resource: 'ACxxxxxxxx',
                    text: `Conversation webhook URL not provided for ${CH2}` });
  assert.deepEqual(conversationSids([a]), [CH2]);
});

test('a webhook target with no url is the finding', () => {
  const [state, detail] = verdict(hook('webhook', { url: null }));
  assert.equal(state, 'missing-url');
  assert.match(detail, /50369/);
});

test('a studio target with no url is correct', () => {
  const [state, detail] = verdict(hook('studio', { flow_sid: 'FW1' }));
  assert.equal(state, 'studio');
  assert.match(detail, /FW1/);
});

test('a studio target with no flow is still wrong', () => {
  assert.equal(verdict(hook('studio', {}))[0], 'studio-no-flow');
});

test('a trigger target needs a url too', () => {
  assert.equal(verdict(hook('trigger', { url: '' }))[0], 'missing-url');
  assert.equal(verdict(hook('trigger', { url: 'https://app.example.com/hook' }))[0], 'ok');
});

test('plain http is reported separately from the missing url', () => {
  const [state, detail] = verdict(hook('webhook', { url: 'http://app.example.com/hook' }));
  assert.equal(state, 'insecure');
  assert.match(detail, /Not 50369/);
});