> For the complete documentation index, see [llms.txt](https://govplane.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://govplane.gitbook.io/docs/documentation/advanced/isolated-mode.md).

# Isolated Mode

{% hint style="info" %}
**Isolated mode is only available on Pro and Enterprise plans.**
{% endhint %}

### 1. Overview

Govplane runtimes evaluate governance policies locally within the application environment. Under normal operation, runtimes periodically poll the Govplane control plane to retrieve updated policy bundles.

While this architecture provides low-latency policy evaluation and rapid policy propagation, it introduces a residual risk: if the control plane, credentials, or policy management interface were compromised, malicious or unintended policy changes could automatically propagate to runtimes through the bundle update mechanism.

To mitigate this risk, Govplane introduces **Isolated Mode**.

**Isolated Mode** allows operators to immediately sever the runtime's connection to the control plane and force the runtime to operate exclusively using a **previously approved local safe bundle** stored on the host filesystem.

This mechanism provides a **runtime containment capability** during security incidents without interrupting application operation.

***

### 2. Goals

The primary goals of Isolated Mode are:

* Prevent propagation of malicious or unauthorized policy changes
* Allow continued runtime policy evaluation during control plane incidents
* Provide an out-of-band emergency containment mechanism
* Ensure activation does not depend on the Govplane control plane
* Enable deterministic runtime behaviour using a trusted approved bundle

***

### 3. Threat Model

Isolated Mode addresses the following threat scenarios.

#### 3.1 Credential Compromise

An attacker obtains access to:

* Govplane API credentials
* Policy management interface
* CI/CD pipeline used to publish policies

The attacker modifies policies and publishes a new bundle.

Without isolation:

1. Runtime polls control plane
2. Malicious bundle is retrieved
3. Policies are applied automatically

Isolated Mode breaks this chain.

#### 3.2 Control Plane Compromise

If the control plane itself is compromised or misconfigured:

* malicious bundles may be distributed
* runtimes could adopt them automatically

Isolated Mode ensures runtimes can operate independently from the control plane.

#### 3.3 Incident Containment

During a security incident, operators may need to:

* stop policy updates immediately
* freeze runtime configuration
* maintain application availability

Isolated Mode provides this capability.

***

### 4. Runtime Operation Modes

Govplane runtimes support two operational modes.

#### 4.1 Normal Mode

Default runtime behaviour.

**Characteristics:**

* Runtime evaluates policies locally
* SDK polls control plane (default: 10 seconds)
* Updated bundles are automatically retrieved
* Policies update dynamically

**Source of truth:**

Govplane Control Plane

#### 4.2 Isolated Mode

Emergency containment mode.

Characteristics:

* No network communication with control plane
* Polling disabled
* Remote bundle fetch disabled
* Runtime loads policies exclusively from a local safe bundle
* Policy configuration becomes deterministic and frozen

Source of truth:

Local Safe Bundle

***

### 5. Safe Bundle Concept

A **Safe Bundle** is a policy bundle explicitly generated from the Govplane control plane and approved for contingency use.

It represents a **known-good governance state**.

The bundle is exported and stored locally in a secure filesystem location controlled by the customer.

Safe bundles are **not the same as runtime cache bundles**.

| Bundle Type   | Purpose                              |
| ------------- | ------------------------------------ |
| Runtime Cache | Automatic bundle fetched via polling |
| Safe Bundle   | Manually generated trusted snapshot  |

***

### 6. Safe Bundle Generation

Safe bundles are generated from the Govplane control plane.

**Typical workflow:**

1. Operator selects project, environment and policy versions to be included.
2. Generates bundle snapshot
3. Bundle is cryptographically signed
4. Bundle is exported
5. Bundle is stored securely

**Distribution methods may include:**

* CI/CD artifact storage
* Configuration management systems
* Infrastructure provisioning pipelines
* Secure manual transfer

***

### 7. Example Safe Bundle Structure

Safe bundles are automatically generated by Govplane. Once you have requested the Safe Bundle to be generated, your request will be placed in a queue. The Bundle will then be available via the Security section of the project control panel within a few minutes.

The structure is the same as a normal bundle. The difference is that this is not retrieved from the control plane but is instead generated and stored locally and that this bundle also includes a cryptographic signature.

```json
{
    "success": true,
    "data": {
        "schemaVersion": 1,
        "orgId": "org_17d896f4c743f4ce24cfbe5f3fa81519",
        "projectId": "proj_a115df02e112708c4921fd8fb0b6e87d",
        "env": "prod",
        "generatedAt": "2026-03-15T11:51:21.505Z",
        "policies": [
            {
                "policyKey": "api-rate-limiting",
                "activeVersion": 1,
                "defaults": {
                    "effect": "allow"
                },
                "rules": [
                    {
                        "id": "rl-global-ip",
                        "status": "active",
                        "priority": 100,
                        "target": {
                            "service": "api-gateway",
                            "resource": "*",
                            "action": "request"
                        },
                        "effect": {
                            "type": "throttle",
                            "throttle": {
                                "limit": 200,
                                "windowSeconds": 60,
                                "key": "ip"
                            }
                        },
                        "description": "Throttle all API requests to 200 req/min per IP"
                    }
                ]
            }
            // Other policies
        ],
        "bundleVersion": 10,
        "signature": {
          "algorithm": "Ed25519",
          "keyId": "govplane-signing-key-1",
          "value": "base64-signature"
        },
        "checksum": "sha256:e4ca3555f8a71b4e1a2b5de294e5503744f7d054da9fdf3a2c58852b88203689"
    }
}
```

***

### 8. Runtime Validation

Before loading a safe bundle the runtime should validate:

#### Signature

* Verify bundle signature
* Ensure signing key is trusted

#### Integrity

* Validate payload integrity

#### Environment Consistency

* Organization ID matches
* Project ID matches
* Environment matches runtime configuration

{% hint style="warning" %}
**If validation fails the runtime must reject the bundle.**
{% endhint %}

***

### 9. Activation Mechanisms

Isolated Mode must be activatable **without relying on the control plane**.

#### Environment Variable

`GOVPLANE_MODE=isolated`

#### Safe Bundle Path

`GOVPLANE_SAFE_BUNDLE_PATH=/etc/govplane/safe-bundle.json`

#### Optional Local Trigger File

`/etc/govplane/isolated.mode`

If the file exists, the runtime automatically activates isolated mode.

#### Orchestrator Configuration

Examples include:<br>

* Kubernetes ConfigMap
* Kubernetes Secret
* Docker environment variables
* systemd configuration
* Infrastructure as code settings

***

### 10. Runtime Behaviour in Isolated Mode

When Isolated Mode is enabled:

#### Network

The runtime must:

* Disable polling
* Disable bundle fetching
* Disable control plane calls

No outbound communication is performed.

#### Policy Loading

Policies are loaded exclusively from the safe bundle file.

#### Bundle Refresh

Safe bundles are **not refreshed automatically**.

Updating requires replacing the file and restarting the runtime.

***

### 11. Observability

Runtimes must clearly expose when operating in isolated mode.

#### Example Log

Govplane runtime started in ISOLATED MODE\
Safe bundle version: 42\
Bundle generated at: 2026-03-16T10:15:00Z

#### Suggested Metrics

* govplane\_runtime\_mode{mode="isolated"} = 1
* govplane\_safe\_bundle\_version
* govplane\_safe\_bundle\_age\_seconds

***

### 12. Incident Response Workflow

#### Normal Operation

Runtime polls control plane for updates.

#### Incident Detected

Examples:

* credential compromise
* suspicious policy modifications
* control plane outage

#### Isolation Activation

1. Operator enables isolated mode.

> Example:
>
> export GOVPLANE\_MODE=isolated

2. Operator restarts the runtime.

#### Runtime Containment

Runtime behaviour:

* polling stops
* no remote updates
* safe bundle becomes the source of truth

Application continues operating.

#### Incident Remediation

Operators:

* rotate credentials
* audit policy changes
* restore control plane integrity

#### Return to Normal Mode

Disable isolated mode and restart runtime.

***

### 13. Security Considerations

#### Safe Bundle Storage

Bundles should be stored in restricted filesystem locations.

Example:

/etc/govplane/safe-bundles/

#### Access Control

Recommended permissions:

* root ownership
* read-only for runtime

#### Bundle Rotation

Organizations should periodically regenerate safe bundles to avoid stale policies.

***

### 14. Trade-offs

**Advantages:**

* Prevents propagation of malicious policy updates
* Enables incident containment
* Maintains runtime governance enforcement
* Removes dependency on control plane connectivity

**Limitations:**

* Policies cannot update dynamically
* Safe bundle may become outdated
* Requires operational procedures

***

### 15. Recommended Best Practices

Organizations should:

* Maintain at least one approved safe bundle
* Store bundles securely
* Test isolated mode periodically
* Document incident response procedures
* Monitor bundle age

***

### 16. Summary

Govplane's **Isolated Mode** provides a security-focused operational capability that allows runtimes to continue enforcing governance policies even during control plane incidents.

By allowing operators to switch runtimes to a **locally trusted safe bundle**, the system reduces the risk of malicious policy propagation while preserving application availability.

This capability is particularly valuable for enterprise environments requiring strong operational control and incident response mechanisms.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://govplane.gitbook.io/docs/documentation/advanced/isolated-mode.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.