Sonar MCP security and profiles

Understand the fail-closed profiles and independent authorization boundaries that secure Sonar MCP.

Sonar MCP uses a fail-closed profile to construct the tools and prompts visible to one server process. That surface limits what a client can ask MCP to do; Sonar's API policies independently decide what the process's service identity may do.

Two authorization boundaries

MCP client
    │ client bearer token (HTTP only)
    ▼
Sonar MCP
    │ profile tier ∩ explicit tool allow-list
    │ profile-specific Sonar service token
    ▼
Sonar API
    │ endpoint authorization policy
    ▼
Inventory · workflows · scans · administration

For HTTP, the client bearer token protects the MCP endpoint. It is not sent to Sonar. Sonar MCP uses a separately configured service token for backend calls, and tool callers cannot override that Authorization header.

Hiding a tool is defense in depth, not the final permission boundary. The backend service identity must still satisfy the policy on every API endpoint.

Tiers

Every registered tool declares one tier:

Tier	Capability
`asset-read`	Read programs, scopes, and discovered assets.
`read`	Read workflow, scan, worker, and resolution state.
`author`	Structurally validate a complete workflow document.
`recon-execute`	Start a scan through the simple scan-creation boundary.
`write`	Read ingest schemas and upsert approved asset records.
`admin`	Consequential workflow, scan, worker, and resolution operations.

Profiles

The process must set BBM_MCP_PROFILE. Missing or unknown values stop startup.

Profile	Tiers	Effective purpose
`asset-read`	`asset-read`	Inventory-only coordinator surface.
`readonly`	`asset-read`, `read`	Inventory plus the allow-listed workflow and scan reads.
`pentest`	`asset-read`, `read`, `recon-execute`	Public pentest surface: Inventory, workflow/scan reads, and simple `create_scan`.
`astrix-author`	`asset-read`, `read`, `author`	Inspect Sonar and structurally validate a workflow; no persistence or execution.
`recon-executor`	`asset-read`, `read`, `author`, `recon-execute`	Narrow control-plane surface for create, per-scan status, and frozen result reads.
`sync`	`asset-read`, `write`	Inventory reads plus approved asset synchronization.
`admin`	all tiers	Explicit internal administration across all registered tools.

For every non-admin profile, the effective tool set is:

tools whose tier is enabled ∩ tools explicitly allowed for the profile

The allow-list is material. For example, recon-executor has read and author tiers but exposes only Inventory reads, create_scan, get_scan, and list_scan_results. It does not inherit every tool in those tiers.

Prompts use a separate per-profile allow-list. Connecting to one profile does not reveal every skill installed in the server package.

Deployment boundaries

The public pentest Streamable-HTTP endpoint is bearer-gated and reverse-proxied through Caddy.
The asset-read and astrix-author HTTP services are private loopback-bound identities with independent bearer gates and backend service tokens. Do not publish them through Caddy.
The backend recon control plane uses its service identity directly; no public recon-executor MCP listener is deployed.
Local stdio is a process boundary rather than an HTTP bearer boundary. Its profile and matching backend service token are still mandatory. Use admin only when the local client should have explicit administrative authority.

Public pentest policy

The public pentest profile exposes Inventory reads, seven workflow/scan reads, and create_scan. Its operating instructions require the agent to:

inspect Inventory first;
select and confirm a workflow whose category is exactly AI;
bind one program UUID in parameters;
call create_scan exactly once; and
avoid retrying an uncertain launch.

Policy limit

The category-AI and bounded-program rules are agent policy, not backend enforcement on the simple scan endpoint. The MCP tool shape prevents extra arguments and the profile hides other mutations, but a trusted client must still follow those launch rules.