tools.privilege_capsh module

Stargazer capability shell — capsh for the privilege bitmask system.

Star calls this to get a full decoded view of a user’s privilege state across all scopes: global, guild, channel, effective (resolved), and per-bit resolution mode annotations.

Equivalent to capsh --print on Linux capabilities.

async tools.privilege_capsh.run(target_user_id='', guild_id='', channel_id='', ctx=None)[source]

Produce a full decoded capability dump of a user’s privilege bitmask.

Entry point for the privilege_capsh tool — the capsh --print analogue for Stargazer’s 64-bit privilege system. It resolves the target user’s global, guild, and channel masks, computes the effective (resolved) mask under each bit’s resolution mode, annotates every set bit (NORMAL/INVERTED/DANGEROUS and whether a scope granted or revoked it), diffs global versus effective, and estimates a self-escalation ceiling (the maximum mask the user could reach if they went adversarial, given any admin bits they hold).

All privilege logic is imported lazily from tools.alter_privileges (PRIVILEGES, DANGEROUS_BITS, ALL_BITS, _bit_mode, _is_admin, _mask_to_names, _get_scoped_mask, get_user_privileges, resolve_privilege_bit); the mask reads ultimately consult Redis through ctx.redis. Guild/channel scopes default to ctx.guild_id / ctx.channel_id when not passed explicitly. Reading another user’s capabilities is gated: it requires the caller to hold ALTER_PRIVILEGES or be an admin, otherwise an error JSON is returned. This handler is read-only and mutates no state.

Registered via the single-tool module contract (TOOL_NAME / run) and dispatched by tool_loader.load_tools; the same decode is also surfaced to the !capsh chat command through message_processor.proxy_status_commands.capsh_text.

Parameters:

  • target_user_id (str) – User ID to inspect; empty means the calling user (ctx.user_id).

  • guild_id (str) – Guild scope to evaluate; empty falls back to ctx.guild_id.

  • channel_id (str) – Channel scope to evaluate; empty falls back to ctx.channel_id. Channel masks are only fetched when a guild is known.

  • ctx (ToolContext | None) – The tool context supplying redis, config, user_id, and the guild/channel context.

Returns:

A pretty-printed JSON dump with per-scope masks, the effective mask, per-bit details, scope diffs, resolution-mode legend, and the escalation ceiling; or a JSON {"error": ...} string when there is no context, Redis is unavailable, no target user can be determined, or the caller lacks ALTER_PRIVILEGES to read another user.

Return type:

str