> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pwnbook.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitwarden Secrets Manager

> Store your integration credentials in Bitwarden Secrets Manager and reference them in Pwnbook using {{bw.secret_name}} — without ever exposing raw secrets inside Pwnbook.

## Overview

Pwnbook integrates with [Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/) so your team can store sensitive credentials — API tokens, passwords, private keys — in Bitwarden's vault and reference them inside Pwnbook using a simple template syntax:

```
{{bw.my_secret_name}}
```

Anywhere Pwnbook accepts credentials (integration config fields, API request headers, environment variables for scripts), you can use a `{{bw.*}}` reference instead of pasting a raw secret. Pwnbook resolves the value at runtime by calling the Bitwarden Secrets Manager API.

**Why this matters:**

* Secrets never live in Pwnbook's database — only the reference does
* Revoke the machine account token in Bitwarden and Pwnbook immediately loses access to all secrets
* Rotate individual secrets in Bitwarden without reconfiguring anything in Pwnbook
* Audit secret access in Bitwarden's event log

## Prerequisites

* A [Bitwarden](https://bitwarden.com) account with **Secrets Manager** enabled (Teams or Enterprise plan)
* Permission to create machine accounts and projects in your Bitwarden organization
* Admin or Owner access in Pwnbook to configure the integration

## Concepts

<AccordionGroup>
  <Accordion title="Secrets Manager vs Password Manager">
    Bitwarden offers two products. This integration uses **Secrets Manager** — the developer-focused secrets API designed for machine-to-machine access. It is separate from the Password Manager vault your team uses for logins.
  </Accordion>

  <Accordion title="Machine accounts">
    A machine account is a non-human Bitwarden identity that holds an access token. You create one specifically for Pwnbook, grant it access to the secrets Pwnbook needs, and give the token to Pwnbook. Revoking the machine account immediately cuts off Pwnbook's access.
  </Accordion>

  <Accordion title="Projects">
    In Bitwarden Secrets Manager, secrets are organized into projects. You can give Pwnbook access to a dedicated project (e.g., `pwnbook-integrations`) so it can only read the secrets you explicitly put there — not everything in your org.
  </Accordion>
</AccordionGroup>

## Setup

<Steps>
  <Step title="Enable Secrets Manager in Bitwarden">
    If you haven't already, enable Secrets Manager for your Bitwarden organization:

    1. Log in to the [Bitwarden web app](https://vault.bitwarden.com).
    2. Go to your **Organization → Settings → Subscription**.
    3. Enable **Secrets Manager**.
  </Step>

  <Step title="Create a project for Pwnbook secrets">
    1. In the Bitwarden web app, switch to **Secrets Manager** (toggle in the left sidebar).
    2. Go to **Projects → New Project**.
    3. Name it something clear, like `pwnbook-integrations`.
    4. Click **Save**.

    <Tip>Using a dedicated project gives Pwnbook access to only the secrets you put in it — nothing else in your Bitwarden organization.</Tip>
  </Step>

  <Step title="Add your secrets to the project">
    For each credential you want to use in Pwnbook, create a secret in the project:

    1. Go to **Secrets → New Secret**.
    2. Set a **Name** — this is the key you'll use in `{{bw.name}}` references. Use lowercase with underscores (e.g., `semgrep_api_token`, `checkmarx_api_key`).
    3. Set the **Value** — the actual credential.
    4. Assign it to your `pwnbook-integrations` project.
    5. Click **Save**.

    Repeat for each secret you want accessible from Pwnbook.

    <Note>Secret names are case-sensitive in `{{bw.*}}` references. `{{bw.Semgrep_Token}}` and `{{bw.semgrep_token}}` resolve to different secrets.</Note>
  </Step>

  <Step title="Create a machine account for Pwnbook">
    1. In Secrets Manager, go to **Machine Accounts → New Machine Account**.
    2. Name it `pwnbook` (or `pwnbook-<your-env>` if you run multiple environments).
    3. Click **Save**.
    4. On the machine account page, go to **Access Tokens → Generate Token**.
    5. Give the token a name and set an expiry (or leave it non-expiring — your choice).
    6. Copy the token value. **This is the only time it will be shown.**

    <Warning>Store the token somewhere safe immediately. If you lose it, you'll need to generate a new one.</Warning>
  </Step>

  <Step title="Grant the machine account access to your project">
    1. Go to **Projects → pwnbook-integrations → Access**.
    2. Click **Grant Access**.
    3. Select your `pwnbook` machine account.
    4. Set the permission to **Read** (Pwnbook only needs to read secrets, not create or modify them).
    5. Click **Save**.
  </Step>

  <Step title="Connect Bitwarden to Pwnbook">
    1. In Pwnbook, go to **Organization Settings → Marketplace → Bitwarden Secrets Manager**.
    2. Click **Configure**.
    3. Enter the **Access Token** you generated in the previous step.
    4. Click **Save & Test** to verify Pwnbook can authenticate and list accessible secrets.

    If the test succeeds, Pwnbook is connected and `{{bw.*}}` references will start resolving.
  </Step>
</Steps>

## Using `{{bw.*}}` references

Once connected, you can use `{{bw.secret_name}}` anywhere Pwnbook accepts a credential or configuration value.

### In integration settings

When configuring an integration (e.g., Semgrep, Checkmarx, Snyk), instead of pasting an API token directly into the field, enter a Bitwarden reference:

```
{{bw.semgrep_api_token}}
```

Pwnbook resolves this to the secret value at runtime when it needs to make an API call. The raw token is never stored in Pwnbook's database.

### In API request headers

When building API requests in the **API Testing** module, use `{{bw.*}}` references in headers, query parameters, or request bodies:

```http theme={null}
Authorization: Bearer {{bw.target_api_key}}
X-API-Key: {{bw.internal_service_token}}
```

### In script templates and packet templates

Reference secrets in community scripts and packet templates to avoid hardcoding credentials in shared scripts:

```bash theme={null}
curl -H "Authorization: Bearer {{bw.burp_api_token}}" https://...
```

## How secret resolution works

When Pwnbook encounters a `{{bw.secret_name}}` reference, it:

1. Calls the Bitwarden Secrets Manager API using the stored machine account token.
2. Looks up the secret by name within the projects the machine account has access to.
3. Substitutes the resolved value in-memory for that request.
4. The resolved value is **never logged or persisted** — only the `{{bw.secret_name}}` reference is stored.

If a secret cannot be resolved (name doesn't exist, token revoked, network error), Pwnbook returns an error rather than sending the request with an unresolved placeholder.

## Revoking access

To immediately cut off Pwnbook's access to all Bitwarden secrets:

1. In Bitwarden Secrets Manager, go to **Machine Accounts → pwnbook**.
2. Click on the access token.
3. Click **Revoke**.

All `{{bw.*}}` references in Pwnbook will stop resolving until you provide a new token.

To rotate the token without downtime:

1. Generate a new token on the same machine account.
2. Update the token in **Pwnbook → Organization Settings → Marketplace → Bitwarden**.
3. Revoke the old token.

## Disconnecting

To remove the Bitwarden integration from Pwnbook:

1. Go to **Organization Settings → Marketplace → Bitwarden Secrets Manager**.
2. Click **Disconnect**.

Pwnbook will stop resolving `{{bw.*}}` references. Any integration fields or API requests using references will fail until you either reconnect or replace the references with raw values.

<Note>Disconnecting does not delete secrets from your Bitwarden vault. It only removes the token from Pwnbook.</Note>