Getting started
Connect a repository and a cloud account, enable the PR gate, and read your first CBX Guard verdict.
Getting started
Coming soon. CBX Guard is in active development and not yet generally available. This walkthrough describes the onboarding flow so you can plan ahead. Request early access.
Getting to your first verdict is four steps. Each one is read-only until you explicitly choose to turn on the merge check.
- Connect a repository — give CBX Guard read access to your IaC.
- Connect a cloud account — let it resolve changes against your live state.
- Enable the PR gate — turn on the merge check (optional, opt-in).
- Read your first verdict — open a pull request and see the result.
Step 1 — Connect a repository
CBX Guard connects to a GitLab project or a GitHub repository and indexes the infrastructure config it
finds — Terraform (*.tf, *.tf.json, *.hcl), plus Helm, Kubernetes, and GitOps YAML. This is the
context graph the engine reasons over, and it is read-only.
You have two ways in on each provider:
- GitLab — connect with OAuth (CBX Guard provisions a dedicated bot for you, on GitLab Premium and
above), or paste an
api-scoped bot token (works on every tier, including Free). - GitHub — install the CBX Guard GitHub App (the clean, install-once path), or paste a bot token / fine-grained PAT.
Connect a repository →
Full instructions for GitLab and GitHub, and what each option can and can't do.
Connecting a repository only ever requests read access. The merge check (Step 3) is a separate, explicit step — it's the only thing that ever writes to your repo.
Step 2 — Connect a cloud account
A verdict is only as good as the live state it's resolved against. CBX Guard watches an AWS account through a read-only cross-account IAM role that you create in your own account — it never holds long-lived keys, and it assumes the role on demand.
You launch a CloudFormation stack (one click) that creates a role with AWS-managed ViewOnlyAccess
plus read-only CloudTrail access — no write permission anywhere in the template. The role's trust
policy names CBX Guard's account and a one-time External ID, so only CBX Guard, with that exact
secret, can assume it. Deleting the stack revokes access instantly.
Connect an AWS account →
Launch the read-only role, understand the External ID trust model, and verify the connection.
Step 3 — Enable the PR gate
By default CBX Guard is observing only. When you're ready for it to weigh in on merges, enable the gate for a connected repository. This is the one and only write CBX Guard makes to your repo, and it never touches your default branch:
- GitLab — adds a CI check that runs on each merge request.
- GitHub — posts a
cbxguard/policycheck-run on each pull request.
Once enabled, the repository's connection is shown as read + gate rather than read-only, so it's always clear what CBX Guard can do.
The gate is opt-in per repository. Until you enable it, CBX Guard never writes to your repository — it only indexes IaC for context.
Step 4 — Read your first verdict
Open a pull request that changes your infrastructure. CBX Guard resolves the change against your live cloud state and posts a verdict in one of four tiers:
| Verdict | What it means | How it's delivered |
|---|---|---|
| Critical | Every condition for real, reachable, production danger is satisfied with facts. Look now. | Loud notification; the PR check fails. |
| High | A real danger that's missing exactly one condition, or where one condition is known only by inference. | Quiet notification; the PR check is neutral. |
| Watch | The change is one step from dangerous, or its context couldn't be fully resolved. Never silent. | Surfaced for a human to review. |
| Clean | No new exposure — including the routine "what changed today" baseline. | Silent. |
Open the verdict to see why: the specific change, the live-state facts it was resolved against (reachability, production scope), and the remediation guidance.
Understand the verdict tiers →
The rubric behind Critical / High / Watch / Clean, and the resolved-effect model.
What's next
- Concepts — the verdict tiers, resolved-effect, and read-only-first model.
- Connect a repository — GitLab and GitHub in detail.
- Connect an AWS account — the read-only role, step by step.
- What's coming — real-time detection and guided remediation.