Roles & Permissions

Gibson's permission model has three layers:

1. Tenant roles define who in your organization can do what at the tenant level. Examples are invite users, configure secrets backends, enroll components, and run missions.
2. Per-component grants define which agents and tools can read, configure, or execute which other components.
3. Plugin invocation gates define which tools can call which plugins.

This page explains each layer from the dashboard. Then it summarizes how the layers compose.

Tenant roles

Three roles ship out of the box. You assign roles to users in your tenant under Settings → Members.

Role	What they can do
Owner	Everything an admin can do, plus billing, tenant deletion, and ownership transfer. There is exactly one owner per tenant.
Admin	Invite/remove users, configure secrets backends, enroll and configure components, write per-component grants, run any mission, see all findings. The default for technical staff.
Member	Run missions, view findings, query the knowledge graph, build and enroll their own components. Cannot configure tenant-wide settings or write grants beyond their own components.

To invite users:

1. Go to Settings → Members → Invite.
2. Enter their email address.
3. Pick a role.
4. They receive an invitation link. When they sign in, Gibson adds them to your tenant.

When you remove a user, Gibson revokes their session immediately and disables any component identities that they own. The components stay enrolled, so missions keep working. The dashboard flags them for re-assignment.

Per-component grants

Beyond tenant roles, every agent and tool that you enroll has its own component identity with its own permission set. This is how Gibson implements least privilege. An agent can read only what an explicit grant allows.

Gibson gates three actions per component:

Action	What it allows
Read	The component can see the target component's state, recent runs, and metadata.
Configure	The component can change the target component's settings, usually reserved for admin tooling.
Execute	The component can invoke the target component's methods (run an agent, call a tool).

Set grants in the dashboard:

1. Open the Permissions tab on the agent or tool's detail page.
2. Click Add grant.
3. Pick a target component and the actions to allow.
4. Save.

You can also set grants in the deploy wizard's Permissions step when you first enroll a component.

Component grants in practice

You want…	Grant
triage-agent to call port-scan and httpx tools	triage-agent → port-scan: execute, triage-agent → httpx: execute
report-agent to read findings produced by other agents in the tenant	report-agent → tenant: read findings
An admin tool to disable a misbehaving plugin	admin-tool → my-plugin: configure

Gibson denies anything that no grant explicitly allows. If a mission references a tool on which the agent has no execute grant, the call fails fast. The mission detail page shows the permission-denied error.

Plugin invocation

Gibson gates plugins separately. The reason is structural. Plugins hold credentials and persistent state, so Gibson is conservative about what can invoke them.

Two facts to remember:

• Only tools can invoke plugins. Agents cannot invoke them directly. If an agent needs Shodan data, it calls a tool that wraps the Shodan plugin.
• A tool can invoke a plugin only if it holds a can_invoke grant on that plugin.

Set this grant on the plugin detail page → Permissions tab → Allow tool. Pick the tool. Then save. From then on, that tool can call any of the plugin's declared methods.

This split (agent → tool → plugin) is intentional. It gives you a single point to audit and revoke plugin access. You do not need to touch agent code.

How the layers compose

For any action, Gibson checks the layers in order, and deny wins:

1. Tenant role: does this user or component belong to a tenant that is allowed this action?
2. Component grants: for cross-component actions, does the caller hold the necessary grant on the target?
3. Plugin invocation: for plugin calls, does the calling tool hold can_invoke?

A denial at any layer fails the call with a structured error. You can see the error in the dashboard's audit log. If the call happened during a mission run, the mission detail page also shows it.

Auditing

Gibson records every permission decision. The audit log under Settings → Audit log shows:

Column	Meaning
Time	When the action was attempted.
Actor	The user or component identity that attempted it.
Action	The RPC or operation.
Target	What it was attempted against.
Outcome	allow, deny, with reason on denials.

Filters let you slice by actor, action type, outcome, and date. You can export the filtered view as CSV or JSON for compliance evidence.

Common workflows

Onboard a new engineer

1. Invite them as Member under Settings → Members.
2. They install the gibson CLI, set GIBSON_URL, and register their own components against your tenant.
3. Their components inherit member-tier defaults. When needed, you can grant broader access per component.

Lock down a third-party tool

1. Enroll the tool with the deploy wizard. Do not grant any permissions yet.
2. On the tool's Permissions tab, grant only the specific targets that it needs. Grant execute on the agents that should call it. Grant read on the components whose data it must see.
3. Review the audit log periodically. Confirm that the tool does not attempt anything beyond its grants.

Rotate access when a contractor leaves

1. Go to Settings → Members → Remove. Gibson deactivates their session and components.
2. Re-assign their components to a remaining team member. If a component is no longer needed, retire it.
3. Filter the audit log on their actor ID for any forensic review.

Related

• Component bootstrap & auth explains how Gibson issues credentials and how to debug a 401.
• Plugins covers manifest-bound secret access. Only the plugin's own identity can read its bound secrets.
• Observability covers the audit log and replay.