Policy Sets: Backup & Version Control via API

Gomboc's Policy Sets can be fully managed through the Rules Service API, giving you programmatic access to export, back up, and restore your policy configuration. This is useful for:

• Disaster recovery — quickly restore your configuration after accidental changes.

• Environment promotion — copy policy sets from a staging org to production.

• Audit trails — track every change to your policy configuration in Git history.

• GitOps workflows — store the desired state of your policy sets in a repository and reconcile it on a schedule.

---

Prerequisites

Personal Access Token (PAT)

All Rules Service API calls require a Bearer token. Generate one from the Gomboc Portal:

1. Open the account dropdown (top-right corner) → Settings.

2. Select Personal Access Tokens.

3. Click Generate Token, give it a name and an expiry, then click Create.

4. Copy the token somewhere safe — it is shown only once.

Set it as an environment variable for the examples below:

export GOMBOC_TOKEN="<your-personal-access-token>"

The scripts on this page also require jq and curl.

API Base URL

All Rules Service endpoints are served at:

https://rules.app.gomboc.ai

---

Concepts

In the Gomboc Portal, a Policy Set is shown under Policy Management → Policy Sets.

Internally — and through the API — each policy set is a Channel: a named, saved search over the policy library that determines which rules are applied to your workspaces.

A channel has the following fields:

Field	Type	Description
name	string	Unique identifier (also used as the human-readable label)
query	string (optional)	ORL search query that selects rules
filters	array of strings	Additional filter expressions
annotations	object (optional)	Arbitrary key/value metadata tags

---

Exporting Policy Sets (Backup)

Use GET /api/v1/channels/search to retrieve all policy sets defined in your account. The endpoint supports pagination — iterate over pages until you have collected every record.

Shell export script

#!/usr/bin/env bash
# export-policy-sets.sh — exports all policy sets to policy-sets-<date>.json
set -euo pipefail

BASE_URL="https://rules.app.gomboc.ai"
PER_PAGE=1
USE_DATE=1

usage() {
  cat <<EOF
Usage: $(basename "$0") [--no-date]

Exports all policy sets to policy-sets-YYYY-MM-DD.json by default.
Use --no-date to write policy-sets.json instead.
EOF
}

while [ $# -gt 0 ]; do
  case "$1" in
    --no-date)
      USE_DATE=0
      shift
      ;;
    -h|--help)
      usage
      exit 0
      ;;
    *)
      echo "Error: unknown option: $1" >&2
      usage >&2
      exit 1
      ;;
  esac
done

if [ "$USE_DATE" -eq 1 ]; then
  OUTPUT="policy-sets-$(date +%Y-%m-%d).json"
else
  OUTPUT="policy-sets.json"
fi

if [ -z "${GOMBOC_TOKEN:-}" ]; then
  echo "Error: GOMBOC_TOKEN is not set" >&2
  exit 1
fi

decode_jwt_payload() {
  local token="$1"
  local payload padded rem

  payload=$(printf '%s' "$token" | cut -d. -f2)
  if [ -z "$payload" ]; then
    return 1
  fi

  padded="$payload"
  rem=$((${#padded} % 4))
  case "$rem" in
    2) padded="${padded}==" ;;
    3) padded="${padded}=" ;;
  esac

  printf '%s' "$padded" | tr '_-' '/+' | base64 -d 2>/dev/null
}

ACCOUNT_ID=$(decode_jwt_payload "$GOMBOC_TOKEN" | jq -er '.tenantId // .accountId // empty' 2>/dev/null || true)
if [ -z "$ACCOUNT_ID" ]; then
  echo "Error: could not extract accountId from GOMBOC_TOKEN" >&2
  exit 1
fi

page=1
echo "[]" > "$OUTPUT"

while :; do
  resp=$(curl -sS "${BASE_URL}/api/v1/channels/search?page=${page}&perPage=${PER_PAGE}" \
    -H "Authorization: Bearer ${GOMBOC_TOKEN}")

  if [ "$(jq -r '.status' <<<"$resp")" != "success" ]; then
    echo "Error: $resp" >&2
    exit 1
  fi

  jq -s --arg accountId "$ACCOUNT_ID" \
    '.[0] + (.[1].data.channels | map(select(.accountId == $accountId)))' \
    "$OUTPUT" <(echo "$resp") > "${OUTPUT}.tmp"
  mv "${OUTPUT}.tmp" "$OUTPUT"

  count=$(jq -r '.data.channels | length' <<<"$resp")
  [ "$count" -lt "$PER_PAGE" ] && break
  page=$((page + 1))
done

echo "Exported $(jq 'length' "$OUTPUT") policy sets for account $ACCOUNT_ID to $OUTPUT"

Example output (policy-sets.json)

[
  {
    "id": "a1b2c3d4-...",
    "accountId": "f0e1d2c3-...",
    "name": "default",
    "query": "",
    "filters": ["provider:aws", "risk:high"],
    "annotations": { "env": "production" },
    "createdAt": "2025-01-10T14:23:00.000Z",
    "updatedAt": "2025-04-03T09:01:00.000Z"
  },
  {
    "id": "e5f6a7b8-...",
    "accountId": "f0e1d2c3-...",
    "name": "cis-aws-hardening",
    "query": "classification:cis-aws",
    "filters": [],
    "annotations": { "framework": "CIS", "env": "all" },
    "createdAt": "2025-02-18T11:00:00.000Z",
    "updatedAt": "2025-05-01T16:30:00.000Z"
  }
]

---

Restoring Policy Sets

Use POST /api/v1/channels/batch/upsert to restore from a backup file. This endpoint creates or updates up to 200 channels in a single request.

Note: Only name, query, filters, and annotations are writable. The id, accountId, createdAt, and updatedAt fields are read-only and are stripped automatically by the script below.

Shell restore script

#!/usr/bin/env bash
# restore-policy-sets.sh — restores policy sets from a backup file
set -euo pipefail

BASE_URL="https://rules.app.gomboc.ai"
INPUT="${1:-policy-sets.json}"

payload=$(jq '{channels: [.[] | {name, query, filters, annotations}]}' "$INPUT")

curl -sS -X POST "${BASE_URL}/api/v1/channels/batch/upsert" \
  -H "Authorization: Bearer ${GOMBOC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "$payload" | jq .

If the backup file contains more than 200 policy sets, split it into chunks of 200 and call the script once per chunk.

---

Version Control with Git

Combine the export script with a Git repository to maintain a full history of every change to your policy configuration.

Recommended repository layout

policy-config/
├── policy-sets.json      ← exported channels (policy sets)
├── export.sh             ← export script
├── restore.sh            ← restore script
└── .github/
    └── workflows/
        └── backup.yml    ← automated daily backup

GitHub Actions: automated daily backup

name: Backup Gomboc Policy Sets

on:
  schedule:
    - cron: "0 3 * * *"   # every day at 03:00 UTC
  workflow_dispatch:

permissions:
  contents: write

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install jq
        run: sudo apt-get update && sudo apt-get install -y jq

      - name: Export policy sets
        env:
          GOMBOC_TOKEN: ${{ secrets.GOMBOC_TOKEN }}
        run: bash export.sh

      - name: Commit if changed
        run: |
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add policy-sets.json
          if git diff --cached --quiet; then
            echo "No changes — policy sets are up to date."
          else
            git commit -m "chore: update policy sets backup $(date -u +%Y-%m-%d)"
            git push
          fi

Add GOMBOC_TOKEN as a repository secret in your GitHub repository settings.

---

Restoring to a Different Environment

You can use the same backup file to copy policy sets across Gomboc organizations (e.g., from staging to production):

export GOMBOC_TOKEN="<production-org-token>"
bash restore.sh policy-sets.json

---

API Quick Reference

All endpoints are on https://rules.app.gomboc.ai. Authentication: Authorization: Bearer <PAT>.

Operation	Method	Path	Key parameters
List all policy sets	GET	/api/v1/channels/search	page, perPage, query
Get one policy set	GET	/api/v1/channels/get	name (query param)
Create a policy set	POST	/api/v1/channels/create	name, query, filters, annotations
Update a policy set	PUT	/api/v1/channels/update	name, query, filters, annotations
Batch create	POST	/api/v1/channels/batch/create	array of channels, onConflict
Batch upsert (restore)	POST	/api/v1/channels/batch/upsert	array of channels
Delete a policy set	DELETE	/api/v1/channels/delete	name (query param)
List rules in a policy set	GET	/api/v1/channels/rules	name, page, perPage

For the full OpenAPI specification, see the Rule Service API reference.

---

FAQ

Will restoring a policy set overwrite the existing one? Yes. batch/upsert updates existing channels matched by name and creates any that do not exist yet. To add new channels without touching existing ones, use batch/create with "onConflict": "skip" instead.

Do I need to back up the rules themselves? Built-in Gomboc rules are managed by Gomboc and do not need to be backed up. If you have published custom ORL rules, those can be exported separately using the /api/v1/rules/search endpoint — see the Rule Service API documentation.

What happens to workspaces if I delete and re-create a policy set? Workspace assignments are stored separately. Deleting and re-creating a policy set with the same name may require you to re-assign it to workspaces in the Portal. Use batch/upsert (update-in-place) to avoid this.