Roles & Permissions
How tenant roles, per-component grants, and plugin invocation gates work in Gibson, and how to set them up for your team.
Gibson's permission model has three layers:
- 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.
- Per-component grants define which agents and tools can read, configure, or execute which other components.
- 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
Four roles ship out of the box. You assign them under Organization, then Users.
| 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. Ownership moves only by transfer, never by invitation. |
| Admin | Manage users, roles and settings, and everything an Editor can do. This covers invites, secrets, per-component grants and connector authorization. The default for technical staff. |
| Editor | Create and run missions, edit targets and connectors, enroll components, configure model providers, export findings. |
| Viewer | Read missions, findings, reports and the knowledge graph. Change nothing. |
Editor is the lowest role that can run a mission. Submitting a mission writes a mission definition, which a Viewer cannot do. Invite a person as Editor if they must use the product, and as Viewer if they only watch.
To invite a person:
- Go to Organization, then Users.
- Select Invite User.
- Enter the email address and pick a role.
- Gibson sends one invitation email. The link is good for seven days.
That email is the only one the person gets. It carries the accept link. It also carries the commands to install the CLI, sign in and run a first mission. This workspace's platform URL and slug are already filled in.
Opening the link creates the account and the role, then hands the person a one-time link to set a password. Gibson stores no password of its own, and the identity service sends no mail of its own.
One address belongs to one workspace. An invitation to an address that already belongs elsewhere reports "sent", and only that mailbox learns about the conflict.
When you remove a user, Gibson revokes every one of their sessions at once. Their next request fails. Gibson then revokes their tenant role and deletes their identity account, which frees their email address for another workspace. Their missions and findings stay in the workspace under the name recorded at the time. The Owner cannot be removed. Transfer ownership first.
Removal does not touch the components that the user enrolled. Those components stay enrolled, with the grants they had, and keep their enrolling user as owner. No dashboard page lists them for re-assignment. Review them yourself after a removal.
Gibson enforces removal in
tenant_admin_removal.go.
The dashboard calls it from
member.ts.
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:
- Open the Permissions tab on the agent or tool's detail page.
- Click Add grant.
- Pick a target component and the actions to allow.
- 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_invokegrant 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:
- Tenant role: does this user or component belong to a tenant that is allowed this action?
- Component grants: for cross-component actions, does the caller hold the necessary grant on the target?
- 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
- Invite them as Member under Settings → Members.
- They install the
gibsonCLI, setGIBSON_URL, and register their own components against your tenant. - Their components inherit member-tier defaults. When needed, you can grant broader access per component.
Lock down a third-party tool
- Enroll the tool with the deploy wizard. Do not grant any permissions yet.
- On the tool's Permissions tab, grant only the specific targets
that it needs. Grant
executeon the agents that should call it. Grantreadon the components whose data it must see. - Review the audit log periodically. Confirm that the tool does not attempt anything beyond its grants.
Rotate access when a contractor leaves
- Go to Organization, then Users, then Remove on their row. Gibson revokes their sessions and deletes their account.
- Review the components that they enrolled. Removal leaves them as they are. If a component is no longer needed, retire it.
- 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.