Secrets Management

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 manifest references. 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:

Field	Example	Notes
Vault address	https://vault.example.com	Must be reachable from Gibson's network
Namespace	gibson/tenant-acme	Vault Enterprise only; leave blank for Community Edition
Path prefix	secret/data/tenant/acme/	Community Edition: use this instead of namespace
KV mount	secret	The KV v2 mount name
Auth method	jwt	One 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. Your Gibson account team provides this identity.

Required configuration fields:

Field	Example	Notes
IAM role ARN	arn:aws:iam::123456789012:role/gibson-secrets	The role Gibson will assume
External ID	acme-gibson-prod	Optional; required if your trust policy enforces one
Region	us-east-1	The 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:

Field	Example	Notes
GCP project	my-gcp-project	The project where Secret Manager is enabled
Auth method	wif or sa_json	Workload 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:

Field	Example	Notes
Vault URL	https://my-vault.vault.azure.net	The full DNS name of your Key Vault
Azure AD tenant ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Your Azure AD directory (tenant) ID, found in Azure Portal under Azure Active Directory > Overview
Client ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	The service principal's application (client) ID
Client secret	(masked field)	The SP's client secret; use Workload Identity to avoid managing this
Auth method	service_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.

---

Registering a plugin with secret bindings

Plugins are the only components in Gibson that can retrieve credential values at runtime. When you register a plugin, you declare which secrets it needs. Gibson then creates a secure binding between the identity of the plugin and those secrets.

Starting the wizard

Go to Settings > Plugins. Click Add plugin. The wizard guides you through five steps.

Step 1: Upload your plugin manifest

Paste your plugin.yaml content or drag in the file. The wizard validates the schema immediately. Each error appears with the line number and a description.

A minimal manifest looks like this:

name: my-shodan-plugin
version: "1.0.0"
spec:
  runtime: process
  secrets:
    - name: cred:shodan_api_key
      rotation: live
  methods:
    - name: search_hosts
      description: Search Shodan for hosts matching a query

The spec.secrets list declares which secrets the plugin needs. In Step 3, you bind each declared secret to a stored value.

Step 2: Server-side validation

Gibson checks the manifest against the server. It confirms that your account has a working secrets backend. It also confirms that each declared secret exists in your account, or that Gibson can create it. The wizard shows each issue with a specific error message.

Step 3: Bind secrets

For each secret in spec.secrets, choose one option:

• Use an existing secret, pick from a dropdown of secrets in your account that match the declared name.
• Create a new secret, paste the value inline. This works exactly like the Add Secret form. Gibson handles the value with the same security guarantees.

If you create secrets inline here, they appear on your Secrets page after registration.

Step 4: Review and confirm

A summary shows the plugin name, the declared methods, and each secret binding. When you click Register, Gibson does these actions as one atomic operation:

1. Creates a dedicated identity (service account) for this plugin.
2. Records the permission that allows this plugin's identity to retrieve each bound secret, and only those secrets.
3. Issues a one-time bootstrap token.

If any action fails, the entire registration rolls back. Gibson leaves no partial state.

Step 5: Register your plugin host

The wizard shows a bootstrap token and a CLI command. Run the command on the machine where your plugin runs:

gibson component register --kind plugin --token eyJ...

Run this command in the directory that contains your plugin.yaml. The command 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. The dashboard shows the exact TTL for your tenant.

After registration, start your plugin:

gibson component run

---

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 plugins based on the rotation policy in their manifest:

Policy	What happens
live	The plugin's credential cache is invalidated. The next time the plugin requests the credential, it receives the new value, no restart needed.
restart	The plugin process exits cleanly after draining any in-flight work, then restarts and loads the new value. You may see a brief (~5 second) unavailability window while the plugin restarts.

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 plan for expected restarts before you confirm.

What if a plugin is unavailable during rotation?

For live rotation, the plugin gets the new value on its next credential request. You need no action.

For restart rotation, if the plugin process is stopped at rotation time, the plugin gets the new value at its next start. The plugin SDK triggers the restart when it reconnects to Gibson and receives the rotation notification.

---

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

Event	When it appears
secret.create	A secret was added
secret.read	A plugin retrieved a credential value (the value itself is never logged, only the secret's name)
secret.update	A secret was rotated
secret.delete	A secret was deleted
secret.bind	A plugin was granted access to a secret
secret.revoke_access	A plugin's access to a secret was removed
secret.config_set	The secrets backend configuration was changed
plugin.register	A plugin was registered
plugin.invoke	A plugin method was called by a tool
authz.deny	A 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

Column	Meaning
Recipient	The specific component instance that holds the grant
Type	agent, tool, or plugin. Only plugins hold grants that cover credential retrieval.
Allowed actions	The list of operations this grant authorizes
Expires	When 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.