/cb-analytics-security

name: cb-analytics-security
description: |
  Use this skill when the user wants to manage Couchbase users, groups,
  roles, or check permissions on the cluster — creating service accounts,
  rotating passwords, granting analytics privileges, or auditing who can do
  what. Trigger when they mention "user", "group", "role", "RBAC",
  "permission", "upsert_user", "check_permissions", "local domain",
  "external domain", or "analytics_reader" / "analytics_admin".
license: MIT

Couchbase RBAC via cb-analytics-mcp

You have 9 RBAC tools: list/get/upsert/delete user, list/upsert/delete group, list roles, and check permissions.

The two domains

Couchbase users live in one of two domains:

• **local** — created and managed inside Couchbase itself.
• **external** — authenticated via LDAP / SAML / PAM, mirrored locally with

role bindings.

Every user-related tool takes a `domain` argument. If you list users without a domain you get both.

Role-spec format

`roles` is a single comma-separated string, never a list. Each role can be unscoped or scoped:

analytics_reader[*]                       # all buckets
analytics_select[bucket1]                 # one bucket
analytics_select[bucket1:scope1]          # one scope
analytics_admin[*],query_select[bucket1]  # multiple roles

Use `list_roles()` first if you don't know what's available — it returns every role the cluster supports, with descriptions.

Creating a service account

For Claude itself, or any automation, create a least-privileged user:

upsert_user(
    domain="local",
    username="cb-mcp",
    roles="analytics_reader[*],analytics_select[*]",
    password="<generated>",
    full_name="cb-analytics-mcp service account"
)

**Never** use `analytics_admin` or `cluster_admin` for the MCP server's cluster credentials in production. Grant only what the workflow needs.

Password handling

The password is passed as a plain string into the tool and immediately wrapped in `SecretStr` inside the impl, then unwrapped only at the HTTP boundary. The audit log redacts it. That said:

• Generate strong passwords (`secrets.token_urlsafe(32)`).
• Rotate by calling `upsert_user` again with a new `password`.
• Never echo a password back to the user in chat.

Checking permissions

`check_permissions(permissions="cluster.analytics!read,cluster.admin!write")` returns a dict mapping each permission to `true`/`false` for the currently authenticated user (the one in `CB_ANALYTICS_USERNAME`). Use this when:

• A tool returns `AnalyticsAuthError` and you want to confirm whether RBAC

is the cause.

• You're auditing what the service account can actually do.

Groups

Groups bundle role assignments and apply them to multiple users. Workflow:

1. `upsert_group("analytics-readers", roles="analytics_reader[*]", description="Read-only analytics users")` 2. `upsert_user(..., roles="local:analytics-readers")` to assign by group reference (Couchbase 7.2+).

What to avoid

• Don't grant `cluster_admin` to "make things work" — find the specific role.
• Don't delete a user before deleting / reassigning what they own (libraries,

active requests).

• Don't store passwords in the cluster config file. Use environment vars or

a secrets manager instead.

• Don't echo a generated password back to the chat — show it once via a

side channel (1Password, vault, etc.) and ask the user to confirm it's stored.

Rate limits & safety

Security/RBAC tools split across two categories:

• **`read`** (60/sec): `list_users`, `get_user`, `list_groups`,

`list_roles`, `check_permissions`.

• **`write`** (1/sec, intentionally tight): `upsert_user`, `delete_user`,

`upsert_group`, `delete_group`.

The 1/sec write limit is deliberate — RBAC changes are durable cluster state and the typical error mode is "did something irreversible quickly". Bulk-provisioning users from a roster? Sequence them, accept the ~1 second per user.

If `RateLimitExceeded` comes back on an `upsert_user` or `delete_user`, honour `retry_after_sec`. Don't retry-storm.

Reads (`list_users`, `check_permissions`, etc.) share the global `read` bucket. If you're auditing a permissions matrix, batch — one `list_users` then targeted `check_permissions` calls is friendlier than calling `get_user` per user-per-role combination.

Worth noting: rate limits are per **API key**, not per cluster. If a single bearer token is doing both heavy RBAC bulk-load AND read-heavy inspection at the same time, they contend for separate buckets, but the bulk-load can starve other writes on the same key. Use distinct API keys per workload if this matters.

Related skills

• `cb-analytics-mcp-setup` — the MCP server's own credentials (`CB_ANALYTICS_USERNAME`, `MCP_API_KEY`) are configured here, not via RBAC tools
• `cb-analytics-cluster` — `who_am_i` to verify the effective role of the current MCP connection