# Bundles

A bundle is a versioned collection of rules packaged as a release unit. Bundles are the mechanism for deploying security policies to the gateway.

## Concepts

* A bundle has a `name` and a `version`
* It contains one or more `rules` — either built-in rules configured via `.conf` files, or custom rules written in `.yaml` files
* Bundles can optionally be `signed` with an NKey — the gateway can be configured to only accept bundles signed by trusted identities. This feature coupled with the internal integrity checks ensures that the artifact has not been tampered with.
* Only one bundle instance of a given bundle name can be active on a given port
* Different ports could have different versions of the same bundle active
* Avoid conflicting rules on the same port

## Lifecycle

```
create → install → activate → (upgrade) → deactivate → uninstall
```

| Step         | Description                                                     |
| ------------ | --------------------------------------------------------------- |
| `create`     | package rules into a bundle file                                |
| `install`    | upload the bundle to the gateway (validated but not yet active) |
| `activate`   | deploy the bundle on a specific port                            |
| `upgrade`    | replace the active bundle on a port with a different version    |
| `deactivate` | remove the bundle from a port (rules stop evaluating)           |
| `uninstall`  | permanently remove the bundle from the gateway                  |

## Built-in rules

The gateway ships with built-in rules covering common use cases. List them with:

```
$ protect admin bundle builtins list --local
```

Built-in rules follow a naming convention:

```
com.synadia.protect.builtins.v1.<action>.<category>.<type>
```

Where `action` is `allow`, `deny`, or `suspend`; `category` describes what the rule inspects; and `type` is `connect` or `message`.

Get details on any built-in rule:

```
$ protect admin bundle builtins info --local <rule-id>
```

See the [built-in rules reference](/protect/1.0/reference/builtins.md) for full documentation on each rule.

## Creating a bundle

### 1. Write a configuration file

Create a directory for the bundle and add a `.conf` file that activates and configures the built-in rules:

```
$ mkdir mybundle
```

Create `mybundle/deny-sensitive-payloads.conf`:

```
activations:

  com.synadia.protect.builtins.v1.deny.payload.message: true



configurations:

  com.synadia.protect.builtins.v1.deny.payload.message:

    'logs.>': '(?i)password|secret|api_key'
```

The activation section declares which built-in rules to enable. The configuration section provides settings for each activated rule.

In the example above, the config activates and configures the deny payload rule — any message published to `logs.>` with a payload matching `password`, `secret`, or `api_key` (case-insensitive) will be denied.

A single `.conf` file can activate and configure multiple built-in rules. For example, adding a header check and a time restriction:

```
activations:

  com.synadia.protect.builtins.v1.deny.payload.message: true

  com.synadia.protect.builtins.v1.allow.header.message: true

  com.synadia.protect.builtins.v1.deny.time.message: true



configurations:

  com.synadia.protect.builtins.v1.deny.payload.message:

    'logs.>': '(?i)password|secret|api_key'

  com.synadia.protect.builtins.v1.allow.header.message:

    X-Tenant: '^acme$'

  com.synadia.protect.builtins.v1.deny.time.message:

    - schedule: '* 0-9 * * *'

      subject: 'orders.>'

    - schedule: '* 17-23 * * *'

      subject: 'orders.>'
```

### 2. Create the bundle

```
$ protect admin bundle create --name mybundle mybundle 1.0.0

Successfully created bundle: mybundle-1.0.0.zip
```

The first positional argument is the directory containing the rule files, the second is the version.

note

To sign the bundle, add `--signer-key my_gateway/bundle-signer.nk`. If the gateway has `trusted_bundle_signers` configured, unsigned bundles will be rejected on install.

### 3. Install the bundle

```
$ protect admin --context admin bundle install mybundle-1.0.0.zip

Successfully installed bundle: mybundle@1.0.0
```

The gateway validates the bundle (and verifies the signature if `trusted_bundle_signers` is configured) but does not activate it yet.

List installed bundles:

```
$ protect admin --context admin bundle list

╭─────────────────────────────────────────────────────────────────────────────────────╮

│                                  Installed Bundles                                  │

├──────────┬─────────┬───────────────────────────┬───────────────────────────┬────────┤

│ Name     │ Version │ Created                   │ Installed                 │ Active │

├──────────┼─────────┼───────────────────────────┼───────────────────────────┼────────┤

│ mybundle │ 1.0.0   │ 2026-04-03T15:16:04-05:00 │ 2026-04-03T15:16:11-05:00 │        │

╰──────────┴─────────┴───────────────────────────┴───────────────────────────┴────────╯
```

note

Installation copies the artifact to internal storage, verifies the bundle was issued by a trusted signer, checks internal integrity, and validates that the bundle can be activated. It does not activate the bundle — activation maps a bundle to a port and installs a runnable version so its rules process protocol traffic.

### 4. Activate the bundle on a port

Activating a bundle requires three parameters: the port name (or `*` for all ports), a bundle name, and a version. The port name refers to the named entry point defined in your gateway configuration (e.g., `clients`), not a TCP port number. Use `protect admin --context admin bundle ports` to list available port names.

Only one version of a given bundle can be active on a port.

```
$ protect admin --context admin bundle activate clients mybundle 1.0.0

Successfully activated bundle: mybundle@1.0.0 on port "clients"
```

The bundle is now evaluating traffic on the `clients` port:

```
$ protect admin --context admin bundle list

╭──────────────────────────────────────────────────────────────────────────────────────╮

│                                   Installed Bundles                                  │

├──────────┬─────────┬───────────────────────────┬───────────────────────────┬─────────┤

│ Name     │ Version │ Created                   │ Installed                 │ Active  │

├──────────┼─────────┼───────────────────────────┼───────────────────────────┼─────────┤

│ mybundle │ 1.0.0   │ 2026-04-03T15:16:04-05:00 │ 2026-04-03T15:16:11-05:00 │ clients │

╰──────────┴─────────┴───────────────────────────┴───────────────────────────┴─────────╯
```

## Upgrading a bundle

Create a new version with updated rules, install it, then run the upgrade to change the version running on the port. You can "upgrade" to a lower version too.

```
$ protect admin bundle create --name mybundle --signer-key my_gateway/bundle-signer.nk mybundle 1.1.0

$ protect admin --context admin bundle install mybundle-1.1.0.zip

$ protect admin --context admin bundle upgrade clients mybundle 1.1.0

Successfully upgraded bundle: mybundle from mybundle@1.0.0 to mybundle@1.1.0 on port "clients"
```

## Deactivating and uninstalling

Remove a bundle from the list of rules that a port uses to evaluate traffic, deactivate it.

```
$ protect admin --context admin bundle deactivate clients mybundle 1.0.0

Successfully deactivated bundle: mybundle@1.0.0 on port "clients"
```

Remove a bundle from the gateway entirely:

```
$ protect admin --context admin bundle uninstall mybundle 1.0.0

Successfully uninstalled bundle: mybundle@1.0.0
```

note

A bundle must be deactivated from all ports before it can be uninstalled.

warning

Uninstalling a bundle permanently deletes it from the gateway. There is no separate "delete" command — `uninstall` is the deletion. To preserve a history of deployed artifacts, keep bundles installed even when inactive.

## Bundle structure

A bundle is a ZIP file containing rules, configuration, metadata, and integrity checksums:

```
mybundle-1.0.0.zip

├── config/deny-sensitive-payloads.conf   # built-in rule configurations

├── rules/client_connect.yaml            # custom rules (if any)

├── MANIFEST                             # bundle metadata (name, version, date)

├── RULESBOM.json                        # rule bill of materials

├── SHA256SUMS                           # checksums for every file

└── SHA256SUMS.sig                       # signature over the checksums
```

Bundles containing only built-in rule configurations have files under `config/`. Bundles with custom rules have `.yaml` files under `rules/`. A bundle can contain both.

## Inspecting a bundle

Inspect a bundle file to see its contents without installing it:

```
$ protect admin bundle inspect mybundle-1.0.0.zip

Bundle Information



      Version: 1.0.0

  Description:

       Signer: UDHLNCKJRIFWS4QYOMMN4EPB7UIMIHDHXSRYSDOTDW4LPDDIV3IYXSOT



Rules:



 No rules found



Files:



               MANIFEST

               RULESBOM.json

               SHA256SUMS

               SHA256SUMS.sig

               config/deny-sensitive-payloads.conf
```

A bundle with custom rules shows them in the Rules section:

```
$ protect admin bundle inspect myrules-1.0.0.zip

Bundle Information



      Version: 1.0.0

  Description:

       Signer: UDHLNCKJRIFWS4QYOMMN4EPB7UIMIHDHXSRYSDOTDW4LPDDIV3IYXSOT



Rules:



               rules/client_connect.yaml



Files:



               MANIFEST

               RULESBOM.json

               SHA256SUMS

               SHA256SUMS.sig

               rules/client_connect.yaml
```

Use `--json` for machine-readable output.

## Verifying a bundle

Bundles are checksummed and signed. Each file is checksummed into `SHA256SUMS`, and `SHA256SUMS` is signed into `SHA256SUMS.sig`. Any modification to the bundle after creation will be detected:

```
$ protect admin bundle verify mybundle-1.0.0.zip

Bundle verification successful: mybundle-1.0.0.zip
```

If the bundle has been tampered with:

```
$ protect admin bundle verify mybundle-1.0.0.zip

protect: error: failed to load bundle: bundle validation: checksum mismatch for "MANIFEST": expected "494e6d35..." got "faac746d..."
```

To verify against a specific public key:

```
$ protect admin bundle verify --public-key <public-nkey> mybundle-1.0.0.zip
```

## Listing available ports

List the ports where bundles can be activated:

```
$ protect admin --context admin bundle ports

╭─────────╮

│  Ports  │

├─────────┤

│ Name    │

├─────────┤

│ clients │

╰─────────╯
```

## Downloading installed bundles

Download a bundle that is already installed on the gateway:

```
$ protect admin --context admin bundle download mybundle 1.0.0 --output mybundle-downloaded.zip

Downloading bundle mybundle 1.0.0 to mybundle-downloaded.zip...

Successfully downloaded bundle to: mybundle-downloaded.zip
```

This retrieves the exact binary image of the bundle that was installed.

## Bundle signing

Bundle signing is opt-in but recommended. When the gateway has `trusted_bundle_signers` configured, it only accepts bundles signed by the listed identities. This is a tamper-proof mechanism ensuring bundles have not been modified on their way to installation.

warning

Removing a trusted signer from the gateway's configuration revokes all bundles issued by that identity. The gateway will auto-deactivate those bundles.

Sign a bundle at creation time:

```
$ protect admin bundle create --name mybundle --signer-key my_gateway/bundle-signer.nk mybundle 1.0.0
```

The `my_gateway/bundle-signer.nk` file contains the private NKey seed. The corresponding public key must be listed in the gateway's `rules.trusted_bundle_signers`.

Verify a bundle's signature:

```
$ protect admin bundle verify mybundle-1.0.0.zip
```
