Security Groups & Firewall Policies

Security groups are how Catalyst Networks turns a plain list of nodes into a firewalled network. You tag nodes to put them in a group, then write policies (firewall rules) that say which traffic those tagged nodes accept or send. The platform compiles those policies into the firewall: section of each affected node’s config.yml and re-signs the node’s certificate so the change takes effect on its next sync.

Everything on this page lives under /organizations/<slug>/security-groups/. Viewing is available to any org member; creating or changing groups, policies, and memberships requires the owner or admin role.

Core Concepts

Term	What it is
Tag (security group)	A membership label attached to nodes. A node’s tags become the Nebula certificate’s `groups:` entries, which is what firewall rules match on.
Policy (firewall rule)	A single rule with a direction, a protocol/port, a source, and a destination (the tag or node the rule applies to).
Matrix	A node × tag grid for assigning membership in bulk.
Recipe	A preset bundle of rules (web tier, database tier, etc.) applied to a tag in one click.

A tag by itself does nothing to traffic — it is just a label. Traffic is only allowed or denied once a policy targets that tag. In the dashboard sidebar, tags surface under Tags (security groups) and policies under Rules; both write to the same underlying data.

How a tag becomes a Nebula group

When you assign a tag to a node, the platform records the membership and queues a certificate re-sign for that node. The node’s new certificate carries the tag names in its Nebula groups: field. Firewall rules that name that tag as a source or destination then match the node by group. Because this changes the certificate, membership changes are not instant — they land when the affected nodes pull fresh config.

Creating a Group and Assigning Nodes

Go to Security Groups (/organizations/<slug>/security-groups/) and choose Create (create/).
Give the group a name (and optional description). On save you are taken straight to the Assign Nodes step (<sg_id>/assign-nodes/).
Select which nodes belong to the group and save. Adding or removing a node triggers a certificate regeneration for every node whose membership changed.

You can revisit membership any time from the group’s detail page (<sg_id>/), remove a single node with unassign (<sg_id>/unassign-node/<node_id>/), or edit/delete the group itself (<sg_id>/edit/, <sg_id>/delete/).

Bulk membership: the node × tag matrix

For managing many nodes at once, open the matrix (matrix/). It renders an org-wide grid of every node against every tag. Toggle the cells to add or remove memberships, then apply (matrix/apply/) to commit the whole batch in a single transaction. Every node affected by the batch is queued for a certificate re-sign. If the apply fails partway, the entire batch rolls back and no re-signs are queued.

Writing Policies

There are two editors for firewall rules; both persist to the same policy records.

Source → Destination policy form

The Policies list (policies/) is the flat, searchable, sortable view of every firewall rule in the organization. Create one with policies/create/, choosing:

Destination — a tag (group) or a single node the rule applies to.
Protocol / port — TCP, UDP, ICMP, or Any. TCP and UDP require a port or port range; ICMP and Any carry no ports.
Source — a tag (group) or a specific node. (The source node is matched by its Nebula IP; see below.)

Edit and delete are at policies/<rule_id>/edit/ and policies/<rule_id>/delete/. The older per-group rule URLs (<sg_id>/rules/add/, .../rules/<rule_id>/edit/, .../rules/<rule_id>/delete/) still work — they redirect into this unified policy form, pre-filled with the group as the destination.

Direction-first rule editor with live preview

The direction-first editor (rules/new/) is built around the idea that a rule is either inbound (gating traffic into the target) or outbound (gating traffic out). You pick:

Direction — inbound or outbound.
Target tags — one or more tags this rule applies to.
Protocol / port — with support for a min-max port range.
Source — one of: a tag, a specific host/node, a CIDR block, or any.

As you fill the form it can render a live preview (rules/preview/) that shows the exact Nebula firewall entries the rule will produce, how many nodes it will apply to, and — for outbound rules — a warning when it is the first outbound rule for those nodes (see the deny-by-default note below). The preview builds the rule in a rolled-back transaction, so nothing is saved until you submit.

Recipes (quick-start wizard)

The recipes page (recipes/) applies a preset bundle of rules to a tag in one step. Built-in recipes:

Recipe	Effect
Web tier	Accept TCP 80 and 443 from anywhere
Database tier	Accept TCP 5432 (PostgreSQL) from the `web` tag
Admin-only	Accept TCP 22 (SSH) from the `admin` tag
Jump host	Accept TCP 22 (SSH) from anywhere

Applying a recipe is idempotent: it replaces the tag’s recipe-generated rules with a fresh set and leaves any hand-authored rules untouched. Recipes that reference another tag (for example the database tier referencing web) create that tag automatically if it does not yet exist.

How Rules Become Node Config

When a node fetches its configuration, the platform gathers every rule that applies to it — rules attached directly to the node, plus rules targeting any tag the node wears — and splits them by direction into the Nebula firewall.inbound and firewall.outbound lists.

Each rule renders to one or more firewall entries, one per source:

Protocol/port becomes proto and port (any, a single port, or a min-max range; ICMP carries no port).
Source is emitted with this precedence: source tags → groups:; source nodes → a /32 cidr: of each node’s Nebula IP; a CIDR source → cidr:. (Nebula’s host key matches a certificate name, not an IP, so node and CIDR sources are always emitted as cidr.)

Default (allow-all) behavior

The direction of your rules changes the network’s default posture:

Inbound — if a node has no inbound rules, the config keeps Nebula’s default allow-all inbound entry (port: any, proto: any, host: any). As soon as you author one inbound rule, that default is dropped and inbound becomes an explicit allow-list.
Outbound — outbound stays allow-all until you author the first outbound rule for a node. That first rule flips egress to deny-by-default: only the traffic your outbound rules permit is allowed out. This is why the direction-first editor warns you when you are about to create the first outbound rule for a set of nodes.

Because rules are compiled into the certificate/config bundle, changes to memberships or policies take effect when affected nodes re-sync — either automatically after the re-sign is queued or via cvpn-manager sync-config.

Roles Required

Action	Minimum role
View groups, policies, and the matrix	Member
Create/edit/delete groups	Owner or admin
Assign/unassign nodes, apply the matrix	Owner or admin
Create/edit/delete policies and rules	Owner or admin
Apply recipes	Owner or admin

Next Steps

Web Dashboard Overview — where security groups sit in the dashboard
Sync configuration — pull updated firewall config onto a node
Webhooks & Audit Logs — get notified when groups and policies change