ZeroRoot Docs

Secrets Management

Store credentials, configure your secrets backend, and bind secrets to plugins, all from the dashboard.

Gibson stores credentials (API keys, tokens, passwords) for you. Your plugins get them at runtime. The values never appear in agent logs, tool outputs, or audit streams.

This guide shows the everyday tasks of a tenant admin. The tasks are: add secrets, connect a custom backend, register a plugin, rotate credentials, review audit logs, and understand active grants.


Adding your first secret

Go to Settings > Secrets. If you just created your account, the page shows a confirmation that your secrets backend is ready.

  1. Click Add secret.
  2. Fill in the fields:
    • Name, a short identifier that your plugin resolves. Use the convention cred:<purpose>, for example cred:openai_api_key or cred:db_password.
    • Value, paste your credential here. The field is masked. Gibson sends the value directly to secure storage and never shows it again.
    • Category, choose cred for API keys and passwords. Choose provider_config for LLM provider configuration. Use provider_config when you wire an LLM key through the secrets system.
  3. Click Save. The dashboard returns you to the secrets list. The list shows the secret name, category, version number, and the last access time. The list never shows the value.

Can I see the value later? No. Gibson stores credentials in encrypted form. If you need to replace a value, use the Rotate action. By design, the dashboard has no "reveal value" button.


Connecting your own secrets backend (BYO broker)

By default, new accounts use Gibson-managed secrets storage. Gibson provisions this secure storage backend for your account at signup. It needs no configuration.

If your organization's security policy requires credentials in your own infrastructure, switch to a bring-your-own (BYO) backend. Do this on the Settings > Secrets backend page. You need the Admin role to make this change.

Before you switch: a backend change does not move existing secrets. Secrets that you added before the switch stay in the old backend. New secrets go to the new backend. If you need all secrets in one place, recreate them after the switch.

When you save a new backend configuration, Gibson first tests connectivity with a "probe". The probe writes and reads a temporary value in your backend. This confirms that the permissions are correct. If the probe passes, Gibson commits the save. If the probe fails, Gibson does not commit the save.

HashiCorp Vault (self-hosted)

You need a KV v2 secrets engine and a Vault auth method that your Gibson instance can use. We recommend the JWT auth method for production. Gibson presents its service identity as a JWT. Gibson also supports AppRole and static Token.

Required configuration fields:

FieldExampleNotes
Vault addresshttps://vault.example.comMust be reachable from Gibson's network
Namespacegibson/tenant-acmeVault Enterprise only; leave blank for Community Edition
Path prefixsecret/data/tenant/acme/Community Edition: use this instead of namespace
KV mountsecretThe KV v2 mount name
Auth methodjwtOne of: token, approle, jwt, kubernetes, aws_iam
Auth credentials(depends on method)For token: the token value; for approle: role ID + secret ID; for jwt: the JWT role name

Common issues:

  • If the probe returns permission denied, check your Vault ACL policy. The policy must grant create, read, update, delete, and list on the KV path.
  • If the probe returns KV v1 mount detected, enable a KV v2 mount in your Vault. Then update the KV mount field.
  • For Community Edition, use Path prefix mode, not Namespace.

AWS Secrets Manager

Gibson assumes an IAM role to access your Secrets Manager. Your IAM role must trust Gibson's identity.

Required configuration fields:

FieldExampleNotes
IAM role ARNarn:aws:iam::123456789012:role/gibson-secretsThe role Gibson will assume
External IDacme-gibson-prodOptional; required if your trust policy enforces one
Regionus-east-1The AWS region where your secrets live

IAM policy required on the assumed role:

{
  "Effect": "Allow",
  "Action": [
    "secretsmanager:CreateSecret",
    "secretsmanager:GetSecretValue",
    "secretsmanager:UpdateSecret",
    "secretsmanager:DeleteSecret",
    "secretsmanager:ListSecrets"
  ],
  "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:gibson/tenant/*"
}

If your Secrets Manager uses a customer-managed KMS key, also add kms:GenerateDataKey and kms:Decrypt on that key.

Common issues:

  • AccessDeniedException, check that the trust policy of the IAM role allows Gibson's principal. Also check that the permission policy of the role covers gibson/tenant/* secrets.
  • failed to assume role, make sure that the role ARN is correct. If you use an external ID, make sure that it matches exactly.

GCP Secret Manager

Gibson authenticates to GCP with a service account JSON key or with Workload Identity Federation. We recommend Workload Identity Federation for GKE-hosted Gibson deployments.

Required configuration fields:

FieldExampleNotes
GCP projectmy-gcp-projectThe project where Secret Manager is enabled
Auth methodwif or sa_jsonWorkload Identity (recommended) or service account JSON key
Service account JSON(file upload)Only for sa_json auth; the key must have Secret Manager Admin rights

Required IAM role on the service account: roles/secretmanager.admin (or the narrower roles/secretmanager.secretAdmin).

Before you configure: make sure that the Secret Manager API is enabled in your GCP project:

gcloud services enable secretmanager.googleapis.com --project my-gcp-project

Common issues:

  • 403 PERMISSION_DENIED with API not enabled, run the command above.
  • invalid_grant, your service account JSON key was rotated or revoked. Generate a new key in the GCP console and upload it again.

Azure Key Vault

Gibson authenticates to Azure Key Vault with a service principal (SP) or with Workload Identity.

Required configuration fields:

FieldExampleNotes
Vault URLhttps://my-vault.vault.azure.netThe full DNS name of your Key Vault
Azure AD tenant IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxYour Azure AD directory (tenant) ID, found in Azure Portal under Azure Active Directory > Overview
Client IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxThe service principal's application (client) ID
Client secret(masked field)The SP's client secret; use Workload Identity to avoid managing this
Auth methodservice_principal or workload_identity

The service principal needs Get, Set, and Delete permissions on secrets in the access policies of your Key Vault. If the vault uses Azure RBAC mode, the service principal needs the Key Vault Secrets Officer role instead.

Common issues:

  • Forbidden 403, check that the SP has the correct access policy or RBAC role on the specific Key Vault. A role at subscription level only is not enough.
  • authentication failed: client secret expired, rotate the SP secret in Azure AD. Then update the configuration here.
  • AADSTS700016, the client ID or tenant ID is incorrect.

Granting a plugin its secrets

Plugins are the only components in Gibson that can retrieve credential values at runtime. A plugin declares no secret. A tenant admin grants the plugin access to named secrets, and Gibson records a permission between the identity of the plugin and each granted secret.

The secret access step

When you deploy a plugin from the dashboard, the deploy wizard has a Secret access step. Select the secrets of this workspace that the plugin can read. The plugin can read no other secret. You can select none.

When you finish the wizard, Gibson records the permission for each selected secret before it shows the bootstrap token.

Start your plugin host

On the machine where your plugin runs, put the bootstrap token and the address of your platform in the environment. Then start the plugin:

export GIBSON_URL=https://<your-platform>
export GIBSON_BOOTSTRAP_TOKEN=eyJ...
gibson component run --kind plugin

The first start exchanges the token for a persistent host key. Your plugin process uses this host key on every later connection. The token is single-use and expires shortly after issuance.

A plugin that resolves a secret at start fails the boot with the secret named when it has no grant for it. Grant the secret, then start the plugin again.

Removing a grant

The detail page of the plugin lists each granted secret. Revoke a grant there. The running plugin learns of the revocation within seconds and reports itself degraded.


Rotating secrets

Rotation replaces the value of a secret. The name, the bindings, and the plugins that use the secret stay the same.

When to rotate

  • A credential was exposed (breach response).
  • Your security policy requires periodic rotation (for example, every 90 days for API keys).
  • A service provider forces rotation (for example, an OAuth token expired).

How to rotate

  1. Go to Settings > Secrets.
  2. Click the name of the secret to open the detail page. Then click Rotate. Or click the kebab menu on the list row and choose Rotate.
  3. Paste the new value and confirm.

The version counter increments immediately. Gibson notifies each plugin that holds a grant on the secret. The plugin drops its cached value, and the next time the plugin requests the credential, it receives the new value. No restart is needed.

What plugins are affected

The detail page of the secret lists every bound plugin under Plugin associations. The Rotate confirmation modal shows the same list. Use it to see which plugins the rotation reaches before you confirm.

What if a plugin is unavailable during rotation?

The plugin gets the new value on its next credential request. You need no action.


Reviewing audit logs

Gibson records every secret operation in the audit log. Go to Settings > Audit log, or use the audit log link in the navigation menu.

What is logged

EventWhen it appears
secret.createA secret was added
secret.readA plugin retrieved a credential value (the value itself is never logged, only the secret's name)
secret.updateA secret was rotated
secret.deleteA secret was deleted
secret.bindA plugin was granted access to a secret
secret.revoke_accessA plugin's access to a secret was removed
secret.config_setThe secrets backend configuration was changed
plugin.registerA plugin was registered
plugin.invokeA plugin method was called by a tool
authz.denyA request was denied (for example, a plugin tried to access a secret it wasn't bound to)

Filtering the log

Use the Event type dropdown to filter by category. Combine it with the Date range and Actor filters to narrow results.

Example: to see all credential reads in the last 7 days:

  • Event type: secret.read
  • Date range: last 7 days

Example: to find who added the cred:openai_api_key secret:

  • Event type: secret.create
  • Actor: (leave blank to see all actors)

Then look for the row with resource name cred:openai_api_key.

Exporting for compliance

Click Export (CSV or JSON) to download the filtered log. Each row includes the event type, timestamp, actor, resource name, and outcome. Export files never include credential values.


Understanding grants

A grant is a time-limited authorization. Gibson issues it to a component (agent, tool, or plugin) at the start of a mission. The grant specifies exactly which actions the component can take. The grant expires when the mission ends, or after a fixed window, whichever comes first.

Where to find them

Go to Settings > Grants to see all active grants in your account.

What the columns mean

ColumnMeaning
RecipientThe specific component instance that holds the grant
Typeagent, tool, or plugin. Only plugins hold grants that cover credential retrieval.
Allowed actionsThe list of operations this grant authorizes
ExpiresWhen the grant stops being valid

Why grants expire

Grants are short-lived by design. Nobody can use an expired grant, even if it is replayed. This limits the blast radius of a compromised or misbehaving component. At most, the component can act within its granted scope until the grant expires.

If a grant seems unexpectedly long-lived, check the mission that issued it. Some missions are designed for long-running tasks and receive longer grants.

Near-expiry highlighting

Amber rows are within 5 minutes of expiry. This is informational. The component can still act on the grant until expiry. Gibson issues a new grant at the next mission dispatch.

Can I revoke a grant?

The Grants page is read-only in the current release. Active missions manage their own grant lifecycles. If you need to stop a mission immediately, use the mission control actions on the Missions page. This causes the associated grants to expire.


What gets logged about secrets accessed during a mission

The detail page of a mission has a Secrets accessed panel. The panel lists the names of the secrets that plugins retrieved during that mission. It shows the names only, never the values. This helps you correlate mission outcomes with specific credentials:

  • Which plugin retrieved which credentials
  • How many times each was retrieved
  • The first and last access time within the mission

Each entry links to the full secret detail page. There you can see metadata, plugin associations, and the broader audit history.


Deleting a secret

Before you delete a secret, check which plugins are bound to it. The Delete confirmation dialog lists the affected plugins. When you delete a secret, Gibson:

  1. Removes the credential value from storage immediately.
  2. Removes all plugin bindings.
  3. Leaves plugins that used the secret in a Degraded state. These plugins continue to serve methods that do not need the deleted credential. Methods that need it fail until you register the plugin again with a replacement binding.

To disable a credential for a time and keep the plugin bindings, rotate it to a known-invalid value. Do not delete it.

On this page