Skip to content

Admin Guide

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
---

# Cassian Gate v1 Administrator Guide

**Version:** v1 / v1.x  
**Status:** STABLE  
**Audience:** Network engineers, platform engineers, CI/CD operators  
**Scope:** Operating Cassian Gate v1 safely, correctly, and intentionally

This document explains **what Cassian Gate v1 is**, **how it is meant to be used**, and **how to interpret its results**.

It is written for engineers who want **deterministic proof before production**, not a flexible lab.

---

## 1) What Cassian Gate Is (and Is Not)

Cassian Gate is a:

* **deterministic network change-validation gate**
* **CI-first** and **artifact-driven**
* **behavior-validated**, not configuration-validated
* **engineer-first**, not lab-first
* **AI-assisted**, never AI-driven

Cassian Gate answers one question:

> *“Given this intent, does the network behave the way I expect?”*

---

### What Cassian Gate Is NOT

Cassian Gate is **not**:

* a general-purpose network lab
* a routing simulator
* a topology design tool
* a performance or ASIC emulator
* an AI that decides correctness
* an auto-remediation system

If you want exploration, improvisation, or heuristic behavior, Cassian Gate is the wrong tool — **by design**.

---

## 2) Authority Model (Critical)

Cassian Gate has a **strict authority model**.

**Only these things decide correctness:**

* declared **tests**
* declared **scenarios**

Everything else exists to support that authority.

| Component      | Role                    |
| -------------- | ----------------------- |
| Topology YAML  | Declares intent         |
| Tests          | Define correctness      |
| Scenarios      | Define failure behavior |
| Runtime images | Execute behavior        |
| AI             | Explains outcomes only  |

> **AI never decides pass/fail.**

If AI is disabled, unavailable, or removed, Cassian Gate still works identically.

---

## 3) Determinism Guarantees

Given:

* identical topology YAML
* identical Cassian Gate version
* identical container images
* identical timeouts

Cassian Gate **must produce**:

* identical resolved topology
* identical test verdicts
* identical artifacts
* identical exit codes

There is:

* no randomness
* no hidden retries
* no heuristic guessing
* no silent defaults

If something is ambiguous, **Cassian Gate fails fast**.

---

## 4) Gate-First Workflow

### Authoritative path: `cassian test`

`cassian test` is the **gate**.

It:

* starts from a clean state
* destroys any existing lab
* executes deterministically
* produces a binary verdict
* writes authoritative artifacts

Example:

```bash
cassian test three-frr-two-hosts-fw-routed

If this command fails, the change must not be deployed.

Exploratory path: cassian run

cassian run exists for debugging only.

It:

  • is explicitly non-authoritative
  • may leave labs running
  • must never be used in CI gating

Use it to understand failures — not to approve changes.

5) Topology Files Are Authoritative

Topology YAML files declare intent.

They are one of the only inputs that can affect validation outcomes.

Cassian Gate v1 will:

  • validate schema strictly
  • reject unknown fields
  • reject ambiguous references
  • fail fast on invalid intent

Editing anything under labs/ is unsupported and undefined.

6) Nodes and Runtime Behavior

Nodes represent containers participating in validation.

Each node must declare:

  • a unique name
  • a valid type

Example:

1
2
3
nodes:
  - name: h1
    type: host

Node Types (v1)

Cassian Gate v1 supports a small, explicit set of node types.

No others are allowed.

host

A simple Linux endpoint.

  • no routing semantics
  • used as traffic source or destination
  • suitable for ping and tcp tests

frr

A router node running FRR.

FRR nodes have two mutually exclusive modes:

1
2
3
4
- name: r1
  type: frr
  frr_mode: generated | preconfigured
  image: <optional>
frr_mode: generated (default)
  • Cassian Gate generates minimal FRR config
  • no routing intent is inferred
  • suitable for routing-neutral validation

This keeps v1 honest and routing-agnostic.

frr_mode: preconfigured
  • routing config is baked into the image
  • Cassian Gate does not touch /etc/frr/*
  • required for multi-hop expect: pass tests

This mode exists only to support demos and onboarding.

nft-fw

A Linux firewall node using nftables.

  • forwarding enabled
  • rules generated deterministically
  • explicit allow/deny semantics
  • ideal for negative tests

Links define L2 connectivity, not routing.

1
2
links:
  - endpoints: ["h1:eth1", "r1:eth1"]

Rules:

  • endpoints must be explicit
  • exactly two endpoints per link
  • ambiguity fails fast
  • Cassian Gate never guesses

8) Tests (The Source of Truth)

Tests define expected behavior.

They are the only authority for pass/fail outcomes.

Supported Atomic Tests (v1 / v1.x)

  • ping
  • tcp
  • bgp_neighbor

No others are permitted.

ping

1
2
3
4
5
6
tests:
  - name: h1_to_r1
    type: ping
    from: h1
    to: r1
    expect: pass

Negative intent:

1
expect: fail

Blocked traffic is success when failure is expected.

Multi-Hop Guardrail (Very Important)

This fails fast in v1:

1
2
3
4
type: ping
from: h1
to: h2
expect: pass

Unless all routers in the path declare:

1
frr_mode: preconfigured

Cassian Gate never assumes routing exists.

tcp

1
2
3
4
5
type: tcp
from: h1
to_ip: 192.168.2.10
port: 443
expect: pass
  • IPv4 literal only
  • deterministic timeout handling
  • negative intent supported

bgp_neighbor (v1.x)

1
2
3
4
type: bgp_neighbor
node: r1
neighbor: 10.0.0.1
expect: pass

Asserts session state only.

No policy or routing validation.

9) Scenarios (Failure Choreography)

Scenarios orchestrate ordered, deterministic failures.

They reuse atomic tests.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
scenarios:
  - id: interface_failure
    steps:
      - fault:
          interface_down:
            node: r1
            interface: eth1

      - wait_for_bgp:
          node: r2
          timeout: 30

      - run:
          include: all

Rules:

  • ordered
  • explicit
  • exactly one action per step
  • ambiguity fails fast

10) Demo Experience (v1.x)

The demo experience exists to provide a <10-minute success path without violating v1 semantics.

Why demos exist

v1 is intentionally routing-agnostic.

New users still need:

  • a passing gate
  • real routing behavior
  • meaningful failures

Demo FRR Images

Preconfigured FRR images include baked routing config.

Examples:

  • frr-demo-bgp-r1:v1x
  • frr-demo-bgp-r2:v1x
  • frr-demo-static-r1:v1x
  • frr-demo-static-r2:v1x

These images:

  • own /etc/frr/*
  • start FRR internally
  • are explicitly opt-in

Demo Topologies

Shipped demos include:

  • examples/01_connected_smoke.yaml Direct connectivity, zero routing assumptions

  • examples/02_bgp_multihop_tcp.yaml Real BGP neighbor + multi-hop TCP

  • examples/03_static_multihop_ping.yaml Static routing without BGP

  • three-frr-two-hosts-fw-routed.yaml Firewall behavior + fault injection

These demos teach the contract — they do not weaken it.

11) Artifacts and Evidence

Authoritative artifacts:

  • topology.resolved.yaml
  • results.json

Human-readable:

  • results.summary.txt

Logs and state capture are evidence only — never gating.

12) Assistive AI (Optional)

AI entrypoint:

  • cassian ai

AI:

  • is explicitly invoked
  • remains advisory only
  • remains non-authoritative
  • consumes supporting artifact/context surfaces only
  • never affects verdicts
  • never affects exit codes

If AI is unavailable or not used, Cassian Gate’s deterministic engine behavior remains unchanged.

13) What v1 Explicitly Does NOT Do

  • no routing protocol modeling
  • no EVPN semantics
  • no VM runtime
  • no performance simulation
  • no AI-driven decisions

These belong to v1.5+.

14) Final Mental Model

  • topology declares intent
  • tests define correctness
  • scenarios define failure behavior
  • routing lives outside v1 authority
  • determinism is sacred

If Cassian Gate fails, it is telling you something important.

End of Cassian Gate v1 Administrator Guide

1