the token holds admin scopes the app has never called

"""Find Slack scopes on the deployed token that no call site justifies.

Read only, and unusually, nothing here is failing: the script proves a negative
rather than reading an error. One GET, and the answer is in a response header.
The prune and the reinstall are printed for a human to run.
"""
import argparse
import logging
import os
import sys

import requests

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

API = "https://slack.com/api/"

# Per method, the scopes that would each satisfy it: an OR list, not an AND list.
# Deliberately incomplete -- Slack has hundreds of methods, and a method missing
# from this table is reported rather than assumed harmless.
SCOPES_FOR_METHOD = {
    "auth.test": (),
    "team.info": ("team:read",),
    "conversations.list": ("channels:read", "groups:read", "im:read", "mpim:read"),
    "conversations.info": ("channels:read", "groups:read", "im:read", "mpim:read"),
    "conversations.members": ("channels:read", "groups:read"),
    "conversations.history": ("channels:history", "groups:history",
                              "im:history", "mpim:history"),
    "conversations.replies": ("channels:history", "groups:history",
                              "im:history", "mpim:history"),
    "users.list": ("users:read",),
    "users.info": ("users:read",),
    "users.lookupByEmail": ("users:read.email",),
    "users.conversations": ("channels:read", "groups:read", "im:read", "mpim:read"),
    "chat.postMessage": ("chat:write", "chat:write.public"),
    "chat.update": ("chat:write",),
    "files.list": ("files:read",),
    "files.info": ("files:read",),
    "emoji.list": ("emoji:read",),
    "usergroups.list": ("usergroups:read",),
    "reactions.get": ("reactions:read",),
    "pins.list": ("pins:read",),
    "bookmarks.list": ("bookmarks:read",),
    "search.messages": ("search:read",),
    "admin.teams.list": ("admin.teams:read",),
    "admin.users.list": ("admin.users:read",),
    "admin.conversations.search": ("admin.conversations:read",),
}

# Tier, and why it matters if the token is ever found somewhere it should not be.
TIERS = (
    ("admin", "acts across the organisation, not just this workspace"),
    ("write", "changes the workspace; a read-only integration should hold none"),
    ("pii", "enumerates staff identities and addresses"),
    ("archive", "opens the full message archive of every conversation it covers"),
    ("read", "ordinary read access; surplus is untidy rather than dangerous"),
)
SERIOUS = ("admin", "write", "pii", "archive")


def _tier(scope):
    if scope.startswith("admin."):
        return "admin"
    if ":write" in scope:
        return "write"
    if scope in ("users:read.email", "users.profile:read"):
        return "pii"
    if scope.endswith(":history"):
        return "archive"
    return "read"


def justify(granted, methods):
    """Split a granted scope list against the methods the app actually calls. Pure.

    Returns (justified, surplus, gaps, unknown). `justified` is every granted
    scope that satisfies at least one called method; `surplus` is the rest;
    `gaps` are called methods with none of their scopes granted; `unknown` are
    methods absent from the table, which make `surplus` a candidate list rather
    than a verdict.
    """
    granted = sorted(set(granted))
    justified, gaps, unknown = set(), [], []
    for method in sorted(set(methods)):
        options = SCOPES_FOR_METHOD.get(method)
        if options is None:
            unknown.append(method)
            continue
        if not options:
            continue
        hit = [s for s in options if s in granted]
        if hit:
            justified.update(hit)
        else:
            gaps.append((method, list(options)))
    surplus = [s for s in granted if s not in justified]
    return (sorted(justified), surplus, gaps, unknown)


def rank(scopes):
    """Order surplus scopes by what they would cost if the token leaked. Pure."""
    order = {name: i for i, (name, _why) in enumerate(TIERS)}
    why = dict(TIERS)
    out = [(s, _tier(s), why[_tier(s)]) for s in scopes]
    return sorted(out, key=lambda row: (order[row[1]], row[0]))


def granted_scopes(session, token):
    """The complete grant, from the header Slack puts on every response."""
    r = session.get(API + "auth.test", headers={"Authorization": "Bearer " + token},
                    timeout=30)
    header = r.headers.get("X-OAuth-Scopes")
    try:
        body = r.json()
    except ValueError:
        body = {"ok": False, "error": "unparseable_body"}
    scopes = [s.strip() for s in (header or "").split(",") if s.strip()]
    return (scopes, header is not None, body)


def load_calls(path):
    """One Slack method name per line; comments and blanks ignored."""
    lines = open(path, encoding="utf-8").read().splitlines()
    return [l.strip() for l in lines if l.strip() and not l.strip().startswith("#")]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--calls", help="file of Slack method names this app actually calls")
    args = ap.parse_args()

    token = os.environ.get("SLACK_BOT_TOKEN")
    if not token:
        log.error("set SLACK_BOT_TOKEN (the token the app actually deploys with)")
        return 2
    if not args.calls:
        log.error("pass --calls with the methods this app calls. Build it with:")
        log.error("  grep -rhoE 'slack[./][a-z]+\\.[a-zA-Z]+' . | sort -u")
        log.error("A surplus scope is only surplus relative to a call inventory, so "
                  "this script will not guess one.")
        return 2

    s = requests.Session()
    scopes, had_header, body = granted_scopes(s, token)
    if body.get("ok") is not True:
        log.error("auth.test answered error=%s; fix the credential first",
                  body.get("error") or "?")
        return 2
    if not had_header:
        log.error("no X-OAuth-Scopes header on the response. Something between this "
                  "script and Slack is stripping it, and the audit cannot proceed")
        return 2

    methods = load_calls(args.calls)
    justified, surplus, gaps, unknown = justify(scopes, methods)

    log.info("granted %d, justified %d, surplus %d, gaps %d",
             len(scopes), len(justified), len(surplus), len(gaps))

    serious = 0
    for scope, tier, why in rank(surplus):
        line = "%-9s %-26s %s" % (tier, scope, why)
        if tier in SERIOUS:
            serious += 1
            log.warning(line)
        else:
            log.info(line)

    for method, options in gaps:
        log.warning("%-9s %-26s none of %s is granted; that is a missing scope, "
                    "not a surplus one", "gap", method, ", ".join(options))

    if unknown:
        log.warning("%-9s %d method(s) are not in this script's table: %s",
                    "unmapped", len(unknown), ", ".join(unknown))
        log.warning("  each one may justify a scope listed above, so treat the "
                    "surplus list as candidates until they are mapped")

    if serious:
        log.warning("repair: prune OAuth & Permissions to the justified set, then "
                    "reinstall -- removing a scope needs a reinstall too")
        log.warning("repair: where broad read access is genuinely needed, split it "
                    "into a second app so the wide token has its own blast radius")

    log.info("%d surplus scope(s) above the ordinary-read tier", serious)
    return 1 if serious else 0


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

/**
 * Find Slack scopes on the deployed token that no call site justifies.
 *
 * Read only, and unusually, nothing here is failing: the script proves a
 * negative rather than reading an error. One GET, and the answer is in a
 * response header. The prune and the reinstall are printed for a human to run.
 */
import { readFile } from 'node:fs/promises';

const API = 'https://slack.com/api/';

// Per method, the scopes that would each satisfy it: an OR list, not an AND
// list. Deliberately incomplete -- Slack has hundreds of methods, and a method
// missing from this table is reported rather than assumed harmless.
const SCOPES_FOR_METHOD = {
  'auth.test': [],
  'team.info': ['team:read'],
  'conversations.list': ['channels:read', 'groups:read', 'im:read', 'mpim:read'],
  'conversations.info': ['channels:read', 'groups:read', 'im:read', 'mpim:read'],
  'conversations.members': ['channels:read', 'groups:read'],
  'conversations.history': ['channels:history', 'groups:history', 'im:history', 'mpim:history'],
  'conversations.replies': ['channels:history', 'groups:history', 'im:history', 'mpim:history'],
  'users.list': ['users:read'],
  'users.info': ['users:read'],
  'users.lookupByEmail': ['users:read.email'],
  'users.conversations': ['channels:read', 'groups:read', 'im:read', 'mpim:read'],
  'chat.postMessage': ['chat:write', 'chat:write.public'],
  'chat.update': ['chat:write'],
  'files.list': ['files:read'],
  'files.info': ['files:read'],
  'emoji.list': ['emoji:read'],
  'usergroups.list': ['usergroups:read'],
  'reactions.get': ['reactions:read'],
  'pins.list': ['pins:read'],
  'bookmarks.list': ['bookmarks:read'],
  'search.messages': ['search:read'],
  'admin.teams.list': ['admin.teams:read'],
  'admin.users.list': ['admin.users:read'],
  'admin.conversations.search': ['admin.conversations:read'],
};

// Tier, and why it matters if the token is ever found somewhere it should not be.
const TIERS = [
  ['admin', 'acts across the organisation, not just this workspace'],
  ['write', 'changes the workspace; a read-only integration should hold none'],
  ['pii', 'enumerates staff identities and addresses'],
  ['archive', 'opens the full message archive of every conversation it covers'],
  ['read', 'ordinary read access; surplus is untidy rather than dangerous'],
];
const SERIOUS = new Set(['admin', 'write', 'pii', 'archive']);

function tierOf(scope) {
  if (scope.startsWith('admin.')) return 'admin';
  if (scope.includes(':write')) return 'write';
  if (scope === 'users:read.email' || scope === 'users.profile:read') return 'pii';
  if (scope.endsWith(':history')) return 'archive';
  return 'read';
}

/**
 * Split a granted scope list against the methods the app actually calls. Pure.
 * Returns [justified, surplus, gaps, unknown]. `unknown` are methods absent from
 * the table, which make `surplus` a candidate list rather than a verdict.
 */
export function justify(granted, methods) {
  const grantedSet = new Set(granted);
  const sortedGranted = [...grantedSet].sort();
  const justified = new Set();
  const gaps = [];
  const unknown = [];

  for (const method of [...new Set(methods)].sort()) {
    const options = SCOPES_FOR_METHOD[method];
    if (options === undefined) {
      unknown.push(method);
      continue;
    }
    if (options.length === 0) continue;
    const hit = options.filter((s) => grantedSet.has(s));
    if (hit.length) hit.forEach((s) => justified.add(s));
    else gaps.push([method, options]);
  }

  const surplus = sortedGranted.filter((s) => !justified.has(s));
  return [[...justified].sort(), surplus, gaps, unknown];
}

/** Order surplus scopes by what they would cost if the token leaked. Pure. */
export function rank(scopes) {
  const order = new Map(TIERS.map(([name], i) => [name, i]));
  const why = new Map(TIERS);
  return scopes
    .map((s) => [s, tierOf(s), why.get(tierOf(s))])
    .sort((a, b) => (order.get(a[1]) - order.get(b[1])) || a[0].localeCompare(b[0]));
}

async function grantedScopes(token) {
  const res = await fetch(API + 'auth.test', {
    headers: { Authorization: `Bearer ${token}` },
  });
  const header = res.headers.get('x-oauth-scopes');
  let body;
  try {
    body = await res.json();
  } catch {
    body = { ok: false, error: 'unparseable_body' };
  }
  const scopes = (header ?? '').split(',').map((s) => s.trim()).filter(Boolean);
  return [scopes, header !== null, body];
}

async function main() {
  const args = process.argv.slice(2);
  const i = args.indexOf('--calls');
  const callsPath = i === -1 ? null : args[i + 1];

  const token = process.env.SLACK_BOT_TOKEN;
  if (!token) {
    console.error('set SLACK_BOT_TOKEN (the token the app actually deploys with)');
    process.exitCode = 2;
    return;
  }
  if (!callsPath) {
    console.error('pass --calls with the methods this app calls. Build it with:');
    console.error("  grep -rhoE 'slack[./][a-z]+\\.[a-zA-Z]+' . | sort -u");
    console.error('A surplus scope is only surplus relative to a call inventory, ' +
                  'so this script will not guess one.');
    process.exitCode = 2;
    return;
  }

  const [scopes, hadHeader, body] = await grantedScopes(token);
  if (body?.ok !== true) {
    console.error(`auth.test answered error=${body?.error ?? '?'}; fix the credential first`);
    process.exitCode = 2;
    return;
  }
  if (!hadHeader) {
    console.error('no X-OAuth-Scopes header on the response. Something between this ' +
                  'script and Slack is stripping it, and the audit cannot proceed');
    process.exitCode = 2;
    return;
  }

  const methods = (await readFile(callsPath, 'utf8'))
    .split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
  const [justified, surplus, gaps, unknown] = justify(scopes, methods);

  console.log(`granted ${scopes.length}, justified ${justified.length}, surplus ` +
              `${surplus.length}, gaps ${gaps.length}`);

  let serious = 0;
  for (const [scope, tier, why] of rank(surplus)) {
    const line = `${tier.padEnd(9)} ${scope.padEnd(26)} ${why}`;
    if (SERIOUS.has(tier)) {
      serious += 1;
      console.warn(line);
    } else {
      console.log(line);
    }
  }

  for (const [method, options] of gaps) {
    console.warn(`${'gap'.padEnd(9)} ${method.padEnd(26)} none of ${options.join(', ')} ` +
                 'is granted; that is a missing scope, not a surplus one');
  }

  if (unknown.length) {
    console.warn(`${'unmapped'.padEnd(9)} ${unknown.length} method(s) are not in this ` +
                 `script's table: ${unknown.join(', ')}`);
    console.warn('  each one may justify a scope listed above, so treat the surplus ' +
                 'list as candidates until they are mapped');
  }

  if (serious) {
    console.warn('repair: prune OAuth & Permissions to the justified set, then ' +
                 'reinstall -- removing a scope needs a reinstall too');
    console.warn('repair: where broad read access is genuinely needed, split it into ' +
                 'a second app so the wide token has its own blast radius');
  }

  console.log(`${serious} surplus scope(s) above the ordinary-read tier`);
  process.exitCode = serious ? 1 : 0;
}

// Only run when invoked directly, so importing this module in the tests does not
// execute main() and fail the file on a missing token.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from slack_scope_surplus import justify, rank


def test_a_scope_with_no_call_site_is_surplus():
    justified, surplus, gaps, unknown = justify(
        ["chat:write", "admin.users:read"], ["chat.postMessage"])
    assert justified == ["chat:write"]
    assert surplus == ["admin.users:read"]
    assert gaps == [] and unknown == []


def test_an_or_list_is_justified_by_whichever_option_was_granted():
    justified, surplus, _, _ = justify(["groups:history"], ["conversations.history"])
    assert justified == ["groups:history"]
    assert surplus == []


def test_a_method_the_table_does_not_know_is_reported_not_ignored():
    justified, surplus, gaps, unknown = justify(["pins:read"], ["pins.add"])
    assert unknown == ["pins.add"]
    assert surplus == ["pins:read"]
    assert gaps == []


def test_a_called_method_with_no_granted_scope_is_a_gap_not_a_surplus():
    _, surplus, gaps, _ = justify(["chat:write"], ["chat.postMessage", "users.list"])
    assert surplus == []
    assert gaps == [("users.list", ["users:read"])]


def test_a_method_that_needs_no_scope_justifies_nothing():
    justified, surplus, _, _ = justify(["team:read"], ["auth.test"])
    assert justified == []
    assert surplus == ["team:read"]


def test_ranking_puts_admin_scopes_first_and_plain_reads_last():
    ordered = [row[0] for row in rank(
        ["emoji:read", "channels:history", "admin.users:write", "files:write",
         "users:read.email"])]
    assert ordered == ["admin.users:write", "files:write", "users:read.email",
                       "channels:history", "emoji:read"]


def test_write_scopes_are_flagged_even_when_they_look_narrow():
    assert dict((s, t) for s, t, _ in rank(["chat:write.public"]))["chat:write.public"] == "write"


def test_history_is_ranked_as_an_archive_scope():
    assert rank(["im:history"])[0][1] == "archive"


def test_ordinary_reads_carry_a_gentler_explanation():
    _, _, why = rank(["emoji:read"])[0]
    assert "untidy" in why

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { justify, rank } from './slack-scope-surplus.mjs';

test('a scope with no call site is surplus', () => {
  const [justified, surplus, gaps, unknown] = justify(
    ['chat:write', 'admin.users:read'], ['chat.postMessage']);
  assert.deepEqual(justified, ['chat:write']);
  assert.deepEqual(surplus, ['admin.users:read']);
  assert.deepEqual(gaps, []);
  assert.deepEqual(unknown, []);
});

test('an or list is justified by whichever option was granted', () => {
  const [justified, surplus] = justify(['groups:history'], ['conversations.history']);
  assert.deepEqual(justified, ['groups:history']);
  assert.deepEqual(surplus, []);
});

test('a method the table does not know is reported not ignored', () => {
  const [, surplus, gaps, unknown] = justify(['pins:read'], ['pins.add']);
  assert.deepEqual(unknown, ['pins.add']);
  assert.deepEqual(surplus, ['pins:read']);
  assert.deepEqual(gaps, []);
});

test('a called method with no granted scope is a gap not a surplus', () => {
  const [, surplus, gaps] = justify(['chat:write'], ['chat.postMessage', 'users.list']);
  assert.deepEqual(surplus, []);
  assert.deepEqual(gaps, [['users.list', ['users:read']]]);
});

test('a method that needs no scope justifies nothing', () => {
  const [justified, surplus] = justify(['team:read'], ['auth.test']);
  assert.deepEqual(justified, []);
  assert.deepEqual(surplus, ['team:read']);
});

test('ranking puts admin scopes first and plain reads last', () => {
  const ordered = rank(['emoji:read', 'channels:history', 'admin.users:write',
    'files:write', 'users:read.email']).map((row) => row[0]);
  assert.deepEqual(ordered, ['admin.users:write', 'files:write', 'users:read.email',
    'channels:history', 'emoji:read']);
});

test('write scopes are flagged even when they look narrow', () => {
  assert.equal(rank(['chat:write.public'])[0][1], 'write');
});

test('history is ranked as an archive scope', () => {
  assert.equal(rank(['im:history'])[0][1], 'archive');
});

test('ordinary reads carry a gentler explanation', () => {
  assert.match(rank(['emoji:read'])[0][2], /untidy/);
});