@takodotid/circuit 0.25.0 → 0.26.0

package/dist/types/adapters/devices/catalog.d.ts

@@ -53,6 +53,20 @@ export declare const catalog: {
             };
         };
     };
+    readonly fortios: {
+        readonly "FG-3700D": {
+            readonly ports: {
+                readonly "40g": 4;
+                readonly "10g": 28;
+                readonly "1g": 2;
+            };
+            readonly spelling: {
+                readonly "40g": "port{n}";
+                readonly "10g": "port{n+4}";
+                readonly "1g": "mgmt{n}";
+            };
+        };
+    };
 };
 export type Catalog = typeof catalog;
 export type PlatformName = keyof Catalog;

package/dist/types/adapters/devices/fortios/firewall.d.ts

@@ -0,0 +1,21 @@
+import type { AclRule, Device, Family, FilterMatch, FilterRule, NatRule, Ports, Protocol } from "../../../schema";
+import { Block } from "./tree";
+/** IP protocol numbers, for a protocol the platform names only by number. */
+export declare const PROTOCOL_NUMBER: Record<Protocol, number>;
+/** NAT rules of both directions, which central NAT needs turned on. */
+export declare function natRules(device: Device): NatRule<string, string>[];
+/** Which families a rule applies to: its own, its addresses', or both. */
+export declare function familiesOf(device: Device, match: FilterMatch<string, string> | undefined): Family[];
+/** A port or ports as the platform writes them in a service: `22`, `1000-2000`. */
+export declare function portList(ports: Ports | undefined): string[];
+/** The service a rule matches, by name, with what it holds. `ALL` when the rule names no protocol and no port; ports without a protocol are TCP's and UDP's. */
+export declare function serviceOf(match: FilterMatch<string, string> | undefined, family: Family): {
+    name: string;
+    block?: Block;
+};
+/** A rule the platform keeps without being told: replies to a session it let through, and packets that belong to one, pass on their own. */
+export declare function isImplied(rule: FilterRule<string, string>): boolean;
+/** Packet filtering, who reaches the device, NAT and stateless ACLs. */
+export declare function firewall(root: Block, device: Device): void;
+/** Whether a port's ACL drops before it accepts: an accept before a drop is an exception the platform's ACLs cannot hold. */
+export declare function acceptsBeforeDrop(rules: readonly AclRule<string>[]): boolean;

package/dist/types/adapters/devices/fortios/index.d.ts

@@ -0,0 +1,55 @@
+import type { Client } from "ssh2";
+import type { Device, Family } from "../../../schema";
+import type { ApplyOptions, DeviceAdapter, Plan } from "../types";
+/** What a session reads and writes: an SSH shell, or anything else that streams the CLI. */
+export type Channel = {
+    write(data: string): unknown;
+    on(event: "data", listener: (chunk: Buffer) => void): unknown;
+    on(event: "close", listener: () => void): unknown;
+    removeListener(event: "data", listener: (chunk: Buffer) => void): unknown;
+    removeListener(event: "close", listener: () => void): unknown;
+};
+/** A CLI over a channel: one line at a time, and what the device printed until its prompt came back. */
+export declare class Cli {
+    private readonly channel;
+    private readonly newline;
+    /** The prompt that ended the last answer, which shows where the session is: `(port1)` inside an entry. */
+    prompt: string;
+    constructor(channel: Channel, newline?: string);
+    /** Wait for the prompt, after logging in. */
+    ready(timeout?: number): Promise<void>;
+    /** Send one line and return what the device printed after it, without the echo or the prompt. */
+    run(line: string, timeout?: number): Promise<string>;
+    /** Answer a question the device asked. */
+    answer(reply: "y" | "n", timeout?: number): Promise<string>;
+    /** What the device prints until its prompt or a question. A session the device ended, or that went silent, fails. */
+    private collect;
+}
+export declare function login(device: Device): Promise<Client>;
+/** Refuse a device on a release this adapter was not proved on, before anything is read or sent. */
+export declare function checkVersion(cli: Cli, device: Device): Promise<void>;
+/** Secrets the device prints: a password or an SNMPv3 key as a cipher, a certificate's key encrypted, and the SNMP community in clear. None leave the read. */
+export declare function scrub(text: string): string;
+/** Every section Circuit manages, as the device holds it, credentials scrubbed. */
+export declare function readConfig(cli: Cli, device: Device): Promise<string>;
+export declare function read(device: Device): Promise<string>;
+/**
+ * A line with each secret's value in place, escaped inside its quotes. A certificate's key from a variable is PEM encoded as one line of base64, and is sent as the PEM it holds. A file saved with Windows line endings is sent with plain ones: the CLI takes each carriage return as a line of its own, and refuses the key, `Invalid private key`. A `?`, which the CLI takes as a call for help, is typed literally.
+ */
+export declare function withSecrets(line: string): string;
+/** How a change that could cut access is guarded: the device reloads its saved configuration after `seconds` unless `prove` shows access survived. */
+export type Guard = {
+    seconds: number;
+    prove: () => Promise<void>;
+};
+/**
+ * Send a plan line by line, each applied as it arrives. The device is first set to revert what is not saved, so a refused line or a fresh login that fails reloads its saved configuration. Once access is proved the change is saved, and changes save themselves again.
+ */
+export declare function configure(cli: Cli, plan: Plan, guard: Guard): Promise<void>;
+export declare function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void>;
+/** The lines that replace a prefix list's entries with what a registry returned: every entry is purged, then each prefix added, matching it and anything more specific. */
+export declare function fillLines(set: string, family: Family, prefixes: string[]): string[];
+/** Replace a prefix list `refresh` fetched. It cannot cut access, so it is sent without a guard, and saved as it goes. `purge` asks to confirm, and is answered yes. */
+export declare function fill(device: Device, _network: readonly Device[], set: string, family: Family, prefixes: string[]): Promise<void>;
+export declare function unsupported(device: Device): string[];
+export declare const fortios: DeviceAdapter;

package/dist/types/adapters/devices/fortios/models.d.ts

@@ -0,0 +1,14 @@
+export declare const models: {
+    readonly "FG-3700D": {
+        readonly ports: {
+            readonly "40g": 4;
+            readonly "10g": 28;
+            readonly "1g": 2;
+        };
+        readonly spelling: {
+            readonly "40g": "port{n}";
+            readonly "10g": "port{n+4}";
+            readonly "1g": "mgmt{n}";
+        };
+    };
+};

package/dist/types/adapters/devices/fortios/names.d.ts

@@ -0,0 +1,32 @@
+import type { Device, Family } from "../../../schema";
+type Addressed = {
+    addresses?: readonly (string | {
+        address: string;
+        peer?: string;
+    })[];
+    vrf?: string;
+    lag?: string;
+};
+/** The name the platform gives a port or an interface: a port by its spelling, any other interface by its key. */
+export declare function nameOf(device: Device, name: string): string;
+/** A port's or an interface's settings, by its key. */
+export declare function settingsOf(device: Device, name: string): Addressed | undefined;
+/** Every address of a port or an interface. */
+export declare function addressesOf(settings: Addressed | undefined): string[];
+/** An address or prefix with its length, a bare address taken as a host. */
+export declare const withLength: (value: string) => string;
+/** The family of an address or prefix. */
+export declare const familyOfPrefix: (value: string) => Family;
+/** `192.0.2.0 255.255.255.0`, how the platform writes an IPv4 prefix. */
+export declare const subnet: (prefix: string) => string;
+/** The canonical form of a prefix: its network address and length, a bare address taken as a host. */
+export declare const network: (prefix: string) => string;
+/** The number of a VRF on the platform: its place among the device's VRFs, the default table being 0. */
+export declare function vrfNumber(device: Device, vrf: string | undefined): number;
+/** The interface whose own network holds an address, the most specific when several do, in one routing table. */
+export declare function interfaceFor(device: Device, address: string, vrf?: string): string | undefined;
+/** The interface that holds an address as its own. */
+export declare function holderOf(device: Device, address: string): string | undefined;
+/** Every port and interface with an address, by key, where the device's services answer. */
+export declare function addressed(device: Device): string[];
+export {};

package/dist/types/adapters/devices/fortios/plan.d.ts

@@ -0,0 +1,26 @@
+import type { ApplyOptions, Plan } from "../types";
+import { Block } from "./tree";
+/** How the plan treats the entries of one table. */
+type Table = {
+    /** Entries the factory holds. The plan neither reads nor removes them. */
+    factory?: readonly string[];
+    /** The device keeps the entries in an order of their own, which `move` changes. */
+    ordered?: true;
+    /** An entry is known by what it holds, not by its number. */
+    byContent?: true;
+    /** Settings the device gives an entry it creates. They are unset when the render does not hold them. */
+    created?: (entry: Block) => readonly string[];
+    /** Settings an entry keeps for life. A change deletes the entry and creates it again. */
+    fixed?: readonly string[];
+};
+/** Tables whose entries need more than a plain comparison, by section. */
+export declare const TABLES: Record<string, Table>;
+/** The configuration as the plan reads it: factory entries and the device's own settings left out. */
+export declare function clean(text: string): string;
+/**
+ * What changes, by section, in the order the render lists them. Entries that go are deleted after everything else, in the reverse order, so nothing is deleted while another section still names it.
+ *
+ * A secret is sent when its entry is new, or with `secrets` set; it cannot be read back to compare.
+ */
+export declare function plan(desired: string, current: string, options: Pick<ApplyOptions, "secrets">): Plan;
+export {};

package/dist/types/adapters/devices/fortios/render.d.ts

@@ -0,0 +1,36 @@
+import type { Device, Helper, Severity } from "../../../schema";
+/** Where the pre-login banner's text is kept. */
+export declare const BANNER = "system replacemsg admin \"pre_admin-disclaimer-text\"";
+/** Every section Circuit manages, in the order a change goes in: what others name comes first. */
+export declare const SECTIONS: readonly ["vpn certificate local", "vpn certificate ca", "system global", "system replacemsg admin \"pre_admin-disclaimer-text\"", "system settings", "system accprofile", "system admin", "system interface", "system gre-tunnel", "system vxlan", "system dns", "system dns-server", "system ntp", "system snmp sysinfo", "system snmp community", "system snmp user", "log memory setting", "log memory filter", "log disk setting", ...string[], "system sflow", "system netflow", "system dhcp server", "router static", "router static6", "router prefix-list", "router prefix-list6", "router community-list", "router route-map", "router ospf", "router ospf6", "router bgp", "system session-helper", "firewall address", "firewall address6", "firewall addrgrp", "firewall addrgrp6", "firewall service custom", "firewall ippool", "firewall vip", "firewall policy", "firewall policy6", "firewall local-in-policy", "firewall local-in-policy6", "firewall central-snat-map", "firewall acl", "firewall acl6"];
+export type Section = (typeof SECTIONS)[number];
+/** Sections `show` prints without what matters, which `show full-configuration` prints: a certificate's text. */
+export declare const FULL: readonly string[];
+/** The zone number for an IANA zone. UTC when the config names none. */
+export declare function zoneOf(timezone?: string): string | undefined;
+/** What each role may do: the factory profile for an admin, and a profile Circuit adds for the others. */
+export declare const PROFILE: {
+    readonly admin: "super_admin";
+    readonly operator: "circuit-operator";
+    readonly "read-only": "circuit-read-only";
+};
+/** The most public keys a user holds. */
+export declare const SSH_KEYS = 3;
+/** The most resolvers the device and a DHCP server hold, per family. */
+export declare const RESOLVERS: {
+    readonly device: 2;
+    readonly dhcp: 4;
+};
+/** The most syslog collectors the device sends to. */
+export declare const COLLECTORS = 4;
+/** The most VRFs the device holds besides its default table. */
+export declare const VRFS = 31;
+/** A severity as the platform names it. */
+export declare const LEVEL: Record<Severity, string>;
+/** The helpers the factory runs, by the name a config gives them: protocol and port of each. */
+export declare const HELPERS: Partial<Record<Helper, readonly [string, number, number][]>>;
+/** Speed by the platform's spelling, for each class a port's cage takes. */
+export declare const SPEEDS: Record<string, Partial<Record<string, string>>>;
+export declare function render(device: Device): string;
+/** The one port or LAG that carries a VLAN tagged, which its VLAN interface sits on. `unsupported()` refuses any other case. */
+export declare function vlanParent(device: Device, vlan: string): string | undefined;

package/dist/types/adapters/devices/fortios/routing.d.ts

@@ -0,0 +1,32 @@
+import type { Device, Family, Neighbor, NeighborSettings, PolicyRule } from "../../../schema";
+import { Block } from "./tree";
+type AnyRule = PolicyRule<string, string>;
+type AnyNeighbor = Neighbor<string, string>;
+/** The route map a session takes when its config states none, so it learns or announces nothing. */
+export declare const REJECT_ALL = "circuit-reject-all";
+/** The start of the comment on a prefix list `refresh` fills. The plan keeps the entries the device holds in one. */
+export declare const FILLED = "Filled by circuit refresh";
+/** The table a prefix list of one family sits in. */
+export declare const PREFIX_LIST: {
+    readonly ipv4: "router prefix-list";
+    readonly ipv6: "router prefix-list6";
+};
+/** The longest prefix of each family. */
+export declare const BITS: {
+    readonly ipv4: 32;
+    readonly ipv6: 128;
+};
+/** A neighbor's settings with its group's beneath them. */
+export declare function neighborSettings(device: Device, neighbor: AnyNeighbor): NeighborSettings<string>;
+/** The families a session carries: its own, or the family of its address. */
+export declare function familiesOfNeighbor(device: Device, neighbor: AnyNeighbor): Family[];
+/** Whether OSPF or BGP detects a dead neighbor with BFD, which the device then runs. */
+export declare function usesBfd(device: Device): boolean;
+export declare function routing(root: Block, device: Device): void;
+/** The family a rule is limited to, by its match: a family, a prefix, or a prefix set of one family. */
+export declare function familyOfRule(device: Device, rule: AnyRule): Family | undefined;
+/** A policy's rules with each call replaced by the rules it calls, in order. A called policy that decides nothing hands back to the caller. */
+export declare function flatten(device: Device, policy: string, seen?: string[]): AnyRule[];
+/** Routing the platform cannot express, or that this adapter does not yet write. */
+export declare function routingGaps(device: Device): string[];
+export {};

package/dist/types/adapters/devices/fortios/tree.d.ts

@@ -0,0 +1,33 @@
+/** A setting the device prints as `unset <key>`, a key it holds empty on purpose, such as an ICMP service's type. */
+export declare const UNSET = "\0unset";
+/** One `edit` of a table: its name as written, and what it holds. */
+export type Entry = {
+    id: string;
+    block: Block;
+};
+export declare class Block {
+    readonly settings: Map<string, string>;
+    readonly blocks: Map<string, Block>;
+    readonly entries: Map<string, Entry>;
+    /** Set a key. A value of several words is written as given. */
+    set(key: string, value: string | number): this;
+    /** The nested `config` block with this header, created when absent. */
+    block(header: string): Block;
+    /** The table entry with this name, created when absent. A name is quoted unless it is a number, or the table prints it bare, such as an OSPF area or an IPv6 prefix. */
+    entry(id: string | number, plain?: boolean): Block;
+    isEmpty(): boolean;
+}
+/** A string as the CLI takes it, in double quotes. */
+export declare function quote(text: string): string;
+/** Each of several strings quoted, as a list setting takes them. */
+export declare const quoteAll: (texts: readonly string[]) => string;
+/** A value's words; a quoted string is one word with its quotes. */
+export declare function wordsOf(value: string): string[];
+/** A word as the device means it, without quotes or escapes. */
+export declare function bare(word: string): string;
+/** The lines that build a block, at an indent, in the form `show` prints and the CLI takes. */
+export declare function linesOf(block: Block, indent?: string): string[];
+/** The whole configuration: each top-level block as `config <section>` to `end`. */
+export declare function print(root: Block): string;
+/** The tree of what `show` printed. Lines that are not configuration, such as the version header, are skipped. */
+export declare function parse(text: string): Block;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.25.0",
+    "version": "0.26.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",
@@ -15,7 +15,10 @@
         "huawei",
         "raisecom",
         "junos",
-        "juniper"
+        "juniper",
+        "fortios",
+        "fortinet",
+        "fortigate"
     ],
     "homepage": "https://circuit.tako.id",
     "bugs": {

package/src/adapters/devices/catalog.ts

@@ -1,11 +1,12 @@
 // Every model each platform supports. Types read from here, so a model or port name that does not exist fails to compile.
 
+import { models as fortios } from "./fortios/models";
 import { models as junos } from "./junos/models";
 import { models as raisecom } from "./raisecom-ros/models";
 import { models as routeros } from "./routeros/models";
 import { models as vrp } from "./vrp/models";
 
-export const catalog = { routeros, vrp, "raisecom-ros": raisecom, junos } as const;
+export const catalog = { routeros, vrp, "raisecom-ros": raisecom, junos, fortios } as const;
 
 export type Catalog = typeof catalog;
 export type PlatformName = keyof Catalog;

package/src/adapters/devices/fortios/TRAPS.md

@@ -0,0 +1,40 @@
+# FortiOS traps
+
+Behaviour that looks like something else. Each one has been hit on a FortiGate 3700D running FortiOS 6.2.2, without a licence.
+
+- A change applies at `next` or `end`, and with `cfg-save automatic`, the factory setting, it is saved at once. `abort` discards the changes of the one object being edited, and only there: inside a table it is `Unknown action 0`, and the entries already left with `next` are applied.
+- `cfg-save revert` keeps changes running but unsaved, and `cfg-revert-timeout` seconds after a change the device announces `System will reload` and reloads its saved configuration. The reload restarts the configuration, not the hardware, and takes about two minutes. `execute cfg reload` does the same at once, without asking, and says `no config to be reloaded` when nothing is unsaved. `execute cfg save` saves; setting `cfg-save automatic` again saves too.
+- `cfg-save revert` set while saving is automatic is saved itself. After a reload the device is still in revert mode, and from then on every change made by hand is undone after the timeout until someone saves it or sets `cfg-save automatic`. Circuit sets it back at the end of every apply.
+- `execute config-transaction start N` opens a candidate that `commit` applies and `abort` discards, but Circuit does not use it on 6.2.2. Inside one, deleting an entry does not release what its lists name, so deleting a policy and then the address it named is refused: `The entry is used by other 1 entries`. A transaction whose session is cut off keeps every object it touched locked until its N minutes run out: `Can not config the object since it's being configured by another transaction`. Editing a `firewall policy6` entry after `unset central-nat` ends the session at `edit`. Deleting the user you are logged in as ends the session with `cmdb_txn_cache_data ... failed` and breaks every later transaction until the device restarts. `show` prints a new static route or policy with the comment of the last new one, which the commit corrects. OSPF's `config redistribute` is refused, `config child object 'redistribute' is not handled in transaction`, and a certificate added in one cannot be named until the commit. None of these happen outside a transaction.
+- The CLI pages long output with `--More--`, and erases the prompt with spaces and a carriage return once it is answered.
+- A `?` typed anywhere shows help at once and is never sent. Ctrl-V before it types it literally.
+- The idle timeout, `admintimeout`, is 5 minutes by default; the session then returns to `login:`.
+- With `pre-login-banner` on, the console shows the banner and waits on `(Press 'a' to accept):` before `login:`. Circuit answers `a`.
+- `grep` after a pipe takes no `-E`, and a command ending in `| grep` reports `Command fail. Return code -27` after printing its matches.
+- `show` prints a setting only when it differs from its default, and prints keys in its own order, not the order they were set. A new aggregate is given `device-identification enable` and `lldp-transmission enable`, a new VLAN interface `device-identification enable` and `role lan`, without being asked. Circuit unsets them.
+- A port joins an aggregate only while nothing names it, such as a static route, `entry not found in datasource`, and its speed cannot change while it is in one, not even back to `auto`: `Interface speed cannot be set for aggregated interfaces`. Circuit frees ports first: what names a port that joins is deleted and created again after, a port whose speed changes leaves its aggregate and joins again, and an aggregate that goes, or is left with no port, goes before anything else with what names it.
+- `unset secondary-IP` hides the list of secondary addresses and drops it. NTP's `unset type` hides its servers but keeps them: `set type custom` brings them back. NTP refuses to delete its last server while `ntpsync` is on, and to empty the interfaces it serves on while `server-mode` is on, `There aren't any interfaces with NTP server enabled`; `unset server-mode` hides that list and lets go of the interfaces in it. The plan deletes a nested list before the setting that hides it, except `ntpsync`, which goes first.
+- A DHCP server prints `dns-server1` only while `dns-service` is `specify`, the default, which `show` does not print. The factory server on `mgmt1` uses `default`, so the render states `specify` before its resolvers.
+- The timezone is a number of the platform's own, such as `53` for Jakarta, Bangkok and Hanoi. The default is `00`, Eniwetok, at UTC+12; UTC is `80`.
+- Global `alias` is set again at every start, whatever was saved.
+- `log memory setting` prints its `status` whether on or off, and `unset status` turns memory logging on.
+- Two interfaces that are up cannot hold overlapping subnets, `Subnets overlap between ...`, so an address moving from one to another must leave the first before it joins the second.
+- A static route identical to another is refused, `Duplicated entry`. An IPv4 route's destination is not printed when it is the default route; neither is IPv6's.
+- A deny policy is given `logtraffic disable`, and its action is not printed, since deny is the default. `send-deny-packet` exists only while a policy denies: set before `action deny` or unset after `action accept`, it is `command parse error`. The render states `action deny`, and the plan undoes what goes before it sets what comes.
+- `show` prints `unset` in two places: an ICMP service's `unset icmptype`, and a prefix list rule's `unset ge` and `unset le` for a bound it does not hold.
+- An SNMPv3 user authenticates with MD5 or SHA1 only, and has no list of sources: only a community has hosts. Circuit decides who reaches every service with local-in policies instead.
+- The console ignores a user's trusted hosts.
+- A tunnel's interface takes an IPv4 address only as a host, with the far end in `remote-ip`: `set ip 10.0.0.1 255.255.255.252` on one is dropped without a word.
+- A GRE or VXLAN tunnel creates an interface of its own, named after it, which goes when the tunnel goes. VXLAN has no local address: it leaves from the address of the interface it names.
+- A static route has no VRF of its own. It lands in the VRF of the interface it leaves through, as `get router info routing-table all` shows, so a blackhole route cannot go in a VRF. OSPF and BGP have no VRF setting.
+- The stateless ACL, `firewall acl` and `acl6`, only drops: it has no action.
+- A route map stops at the first rule that matches, with no way to go on to the next, and its rules permit unless told to deny.
+- `show vpn certificate local` prints a certificate without its text or key. `show full-configuration` prints both, the key encrypted.
+- A private key the device cannot read is answered `Invalid private key, password may be required`, with no `Command fail`, and the session goes on, as it is for one whose lines end in CR LF: the CLI takes each CR as a line of its own; the certificate fails only at `end`, `Attribute 'private-key' MUST be set`.
+- A GRE or VXLAN interface takes no flow sampler, and says so without `Command fail`: `Netflow sampler isn't supported on Tunnel interface..`, and the same for sFlow and for VXLAN.
+- A port in an aggregate has no `icmp-send-redirect`, `command parse error`, and loses it when it joins one.
+- `purge` empties a table after asking `(y/n)`.
+- A loopback has no MTU of its own and runs no VRRP. An interface's name has at most 15 characters.
+- There is no WireGuard and no RPKI, `command parse error`. A route map has no large community and a BGP neighbor no role: neither is among their settings. SNMPv3 offers no SHA256.
+- `execute backup config flash <comment>` keeps a revision on the device, and `execute restore config flash <id>` restores one.
+- The ports are `port1` to `port4` at 40G and `port5` to `port32` at 10G, then `mgmt1` and `mgmt2`. The factory dedicates both management ports to management and gives them addresses `192.168.1.99` and `192.168.2.99`.