@astrofoundry/pi-astro 0.40.20 → 0.40.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -19,6 +19,8 @@ describe("approvals", () => {
|
|
|
19
19
|
expect(isRisky("network", ["unifi", "mira", "networks", "x"])).toBe(false);
|
|
20
20
|
expect(isRisky("network", ["unifi", "37", "write", "DELETE", "/v1/sites/x/acl-rules/y"])).toBe(true);
|
|
21
21
|
expect(isRisky("network", ["unifi", "mira", "--local", "write", "PUT", "/v1/sites/x/networks/y", "{}"])).toBe(true);
|
|
22
|
+
expect(isRisky("network", ["unifi", "mira", "nat-write", "POST", "{}"])).toBe(true);
|
|
23
|
+
expect(isRisky("network", ["unifi", "37", "nat"])).toBe(false);
|
|
22
24
|
expect(isRisky("arcane", ["projects", "list"])).toBe(false);
|
|
23
25
|
expect(isRisky("arcane", ["projects", "redeploy", "mealie"])).toBe(false);
|
|
24
26
|
expect(isRisky("arcane", ["projects", "upgrade", "media", "sonarr", "--yes"])).toBe(false);
|
|
@@ -33,7 +33,7 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
|
|
|
33
33
|
],
|
|
34
34
|
identity: [/^zitadel\s+(DELETE|POST|PUT|PATCH)\b/, /^dmz\s+(deploy-config|pomerium-restart|render|lego-renew)\b/],
|
|
35
35
|
// Every UniFi write, on either console.
|
|
36
|
-
network: [/^unifi\s+\S+\s+write\b/],
|
|
36
|
+
network: [/^unifi\s+\S+\s+(write|nat-write)\b/],
|
|
37
37
|
dns: [
|
|
38
38
|
/^technitium\s+primary\s+(zone-create|zone-catalog|zone-delete|record-add|record-update|record-delete|cluster-init|cluster-delete|cluster-remove|server-domain)\b/,
|
|
39
39
|
/^technitium\s+node\s+\S+\s+(server-domain|stale-zone-delete)\b/,
|
package/package.json
CHANGED
package/skills/dns/SKILL.md
CHANGED
|
@@ -40,9 +40,13 @@ Record parameters by type (the API's names): `A`/`AAAA` `ipAddress` (update: `ne
|
|
|
40
40
|
{ "args": ["technitium", "primary", "cluster-state"] }
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
Every internal service name is its own Primary zone (`auth.37pla.net`, `kuma.37pla.net`,
|
|
43
|
+
Every internal service name is its own Primary zone (`auth.37pla.net`, `kuma.37pla.net`, ...), plus the `orange.es` forwarder and the cluster zones. There is no internal `37pla.net` zone: run `zones` first, then use the exact zone name, and create a new zone with `zone-create <fqdn>` before adding its records.
|
|
44
44
|
|
|
45
|
-
Zone, record, and cluster writes are refused with `node`.
|
|
45
|
+
Zone, record, and cluster writes are refused with `node`. Record changes replicate within seconds. A new zone reaches the other nodes only when they refresh the cluster catalog: if a node does not answer it after a minute, run `zone-resync cluster-catalog.dns.home.arpa` on that node, then check again. If it still fails, report a replication problem.
|
|
46
|
+
|
|
47
|
+
Change users, passwords, settings, blocklists, and apps only on the primary. Joining replaced those sections on the other nodes, and the cluster copies them from the primary; the Technitium docs describe no sync in the other direction.
|
|
48
|
+
|
|
49
|
+
API reference: grimoire products `technitium-api` (HTTP API) and `technitium-dns`. The live cluster state lists nodes under `clusterNodes`; the docs call the field `nodes`.
|
|
46
50
|
|
|
47
51
|
`technitium join <nodeUrl> <nodeIp>` adds a fresh node as a Secondary node: it refuses a node whose default `admin`/`admin` login was already changed, creates a one-time admin with a random password on the primary for the join, and deletes it afterwards. The join replaces the node's settings, blocklists, apps, and users with the primary's. Check `cluster-state` afterwards.
|
|
48
52
|
|
package/skills/network/SKILL.md
CHANGED
|
@@ -8,7 +8,7 @@ description: How the network specialist reads and changes the UniFi consoles of
|
|
|
8
8
|
Two UniFi sites, each with its own console:
|
|
9
9
|
|
|
10
10
|
- `37` (Madrid, console `10.0.10.1`): the homelab. Nine VLANs, inter-zone traffic denied unless a policy allows it, Wi-Fi `Ardilla-37` (EAP-TLS via FreeRADIUS on LXC 108), `Ardilla-IoT`, `Ardilla-GUEST`. LXC 105 runs the Tailscale subnet router for remote administration.
|
|
11
|
-
- `mira` (console `
|
|
11
|
+
- `mira` (Cortex reaches its console at `10.1.60.1` over Site Magic): the second location, `10.1.0.0/16`, with the same zone model as 37 (Management 10, Services 40, Trusted 60, IoT 70, Guest 80). 37 and Mira are run as one network.
|
|
12
12
|
|
|
13
13
|
The consoles are joined by Site Magic (SD-WAN). Never call either site "home". The `network` tool has three families.
|
|
14
14
|
|
|
@@ -27,7 +27,7 @@ Reads of that console's Network API. `<siteId>` is the UUID that `sites` returns
|
|
|
27
27
|
| `device <siteId> <deviceId>` | one device with ports and radios |
|
|
28
28
|
| `clients <siteId>` | connected clients |
|
|
29
29
|
| `networks <siteId>` | networks and VLANs |
|
|
30
|
-
| `firewall-policies <siteId>` | zone policies (filter with `--filter "name.like('
|
|
30
|
+
| `firewall-policies <siteId>` | zone policies (filter with `--filter "name.like('*from Cortex')"`) |
|
|
31
31
|
| `firewall-policy <siteId> <policyId>` | one policy, full object |
|
|
32
32
|
| `firewall-zones <siteId>` | zones with ids and member networks |
|
|
33
33
|
| `wans <siteId>` | WAN interfaces |
|
|
@@ -53,11 +53,41 @@ Procedure for every write:
|
|
|
53
53
|
3. Write, then read the object back and report its id, name, and the fields that changed.
|
|
54
54
|
|
|
55
55
|
```json
|
|
56
|
-
{ "args": ["unifi", "37", "firewall-policies", "<siteId>", "--filter", "name.like('
|
|
56
|
+
{ "args": ["unifi", "37", "firewall-policies", "<siteId>", "--filter", "name.like('*from Cortex')"] }
|
|
57
57
|
{ "args": ["unifi", "37", "write", "POST", "/v1/sites/<siteId>/firewall/policies", "{\"name\":\"Proxmox API - from Cortex\", ...}"] }
|
|
58
58
|
{ "args": ["unifi", "mira", "write", "DELETE", "/v1/sites/<siteId>/acl-rules/<aclRuleId>"] }
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
+
## What the Network API can and cannot do
|
|
62
|
+
|
|
63
|
+
Both consoles run Network `10.6.109`. The console serves no `openapi.json` (404); the spec is at `https://developer.ui.com/network/v10.6.109/openapi.json` and in grimoire as `unifi-network-api` (11.0.97, same endpoints). Look a field up there before you report that the API cannot do something.
|
|
64
|
+
|
|
65
|
+
| Object (under `/v1/sites/<siteId>/`) | Methods | Notes |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `networks`, `networks/{id}` | GET POST PUT DELETE | VLAN, zone, DHCP range and lease, DHCP DNS servers, gateway override, NTP, isolation, mDNS, internet access; `networks/{id}/references` shows what uses a network |
|
|
68
|
+
| `wifi/broadcasts` | GET POST PUT DELETE | SSIDs |
|
|
69
|
+
| `firewall/zones` | GET POST PUT DELETE | custom zones and their networks |
|
|
70
|
+
| `firewall/policies` | GET POST PUT PATCH DELETE | PATCH changes only `loggingEnabled` and `reportFlowEnabled`; `firewall/policies/ordering` GET PUT |
|
|
71
|
+
| `acl-rules` | GET POST PUT DELETE | switch ACLs; `acl-rules/ordering` GET PUT |
|
|
72
|
+
| `dns/policies` | GET POST PUT DELETE | gateway DNS records: `A_RECORD`, `AAAA_RECORD`, `CNAME_RECORD`, `MX_RECORD`, `SRV_RECORD`, `TXT_RECORD`, `FORWARD_DOMAIN` |
|
|
73
|
+
| `traffic-matching-lists` | GET POST PUT DELETE | IP and port lists for policies |
|
|
74
|
+
| `hotspot/vouchers` | GET POST DELETE | guest vouchers |
|
|
75
|
+
| `devices` | GET, POST (adopt), DELETE | `devices/{id}/actions`: `RESTART`; `devices/{id}/interfaces/ports/{idx}/actions`: `POWER_CYCLE`; `statistics/latest` |
|
|
76
|
+
| `clients` | GET | `clients/{id}/actions`: `AUTHORIZE_GUEST_ACCESS`, `UNAUTHORIZE_GUEST_ACCESS` |
|
|
77
|
+
| `wans`, `vpn/servers`, `vpn/site-to-site-tunnels`, `radius/profiles`, `switching/*`, `device-tags` | GET | read only |
|
|
78
|
+
|
|
79
|
+
No endpoint exists for these, so they stay owner tasks in the UniFi UI: Site Magic (read it with `unifi cloud`), switch port profiles and per-port settings (only power cycle), device settings (name, LEDs, uplink, management VLAN), client fixed IPs and names, port forwarding and NAT, static and traffic routes, VPN server and Teleport settings, admins, and console settings.
|
|
80
|
+
|
|
81
|
+
Behavior learned on the live consoles:
|
|
82
|
+
|
|
83
|
+
- A GET omits an optional field that is unset. A missing field is not proof that the API lacks it: `ipv4Configuration.dhcpConfiguration.dnsServerIpAddressesOverride` (the DHCP DNS servers) appears only once set. Check the schema.
|
|
84
|
+
- PUT replaces the whole object: send the full GET body without `id`, `metadata`, `default`, and `index`. To set DHCP DNS on a network, PUT it with `dnsServerIpAddressesOverride: ["<dns1>", "<dns2>"]`; remove the field to return to automatic.
|
|
85
|
+
- `like` uses `*` for any characters and `.` for one character; escape them with `\`. SQL `%` matches nothing and still returns `totalCount: 0` without an error.
|
|
86
|
+
- Lists return 25 items by default. 37 has about 390 firewall policies, mostly `SYSTEM_DEFINED` zone defaults and `DERIVED` return rules: page with `--offset`, or filter `metadata.origin.eq('USER_DEFINED')` (69 on 37 on 2026-10-31).
|
|
87
|
+
- Protocol filters: one protocol is `{"type":"NAMED_PROTOCOL","protocol":{"name":"TCP"},"matchOpposite":false}`; TCP and UDP together is `{"type":"PRESET","preset":{"name":"TCP_UDP"}}` with no `matchOpposite`. Omit `protocolFilter` to match every protocol.
|
|
88
|
+
- A policy has exactly one source zone and one destination zone; several destination zones need one policy each. The `SYSTEM_DEFINED` policies show each zone pair's default (on 37: Vpn to Dmz allows, Vpn to Services blocks).
|
|
89
|
+
- Traffic between 37 and Mira crosses two firewalls: `<zone> to Vpn` on the sending site and `Vpn to <zone>` on the receiving site. A subnet routes only if Site Magic shares it: `unifi cloud /v1/sd-wan-configs/<id>` lists the shared networks per site. 37 shares Services, Management, Trusted, and DMZ; Mira shares Trusted, IoT, Services, and Management.
|
|
90
|
+
|
|
61
91
|
## `unifi cloud <path>`
|
|
62
92
|
|
|
63
93
|
Reads of the Site Manager API itself (`/v1/` or `/ea/`): `/v1/hosts` (consoles and their host ids), `/v1/sites`, `/v1/devices`, `/v1/sd-wan-configs` and `/v1/sd-wan-configs/{id}/status` (Site Magic), `/v1/isp-metrics/{type}`. Lists page with `pageSize` and `nextToken` in the query.
|
|
@@ -77,6 +77,8 @@ ${Object.values(UNIFI_READS)
|
|
|
77
77
|
unifi <37|mira> get <path> [--local] any GET under /v1/ of the console's Network API
|
|
78
78
|
unifi <37|mira> write <POST|PUT|PATCH|DELETE> <path> [json] [--local]
|
|
79
79
|
any write under /v1/sites/<siteId>/ (JSON body except for DELETE)
|
|
80
|
+
unifi <37|mira> nat [--local] the console's NAT rules (Policy Table; not in the official API)
|
|
81
|
+
unifi <37|mira> nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId> [--local]
|
|
80
82
|
unifi <37|mira> fingerprint the local console's certificate fingerprint (for the pin)
|
|
81
83
|
unifi cloud <path> any GET of the Site Manager API (/v1/ or /ea/, not /v1/connector/)
|
|
82
84
|
pulsar <command> [args] fixed operations through a forced-command SSH key
|
|
@@ -166,6 +168,17 @@ export interface UnifiWrite {
|
|
|
166
168
|
body?: string;
|
|
167
169
|
}
|
|
168
170
|
|
|
171
|
+
function jsonBody(json: string): string {
|
|
172
|
+
let parsed: unknown;
|
|
173
|
+
try {
|
|
174
|
+
parsed = JSON.parse(json);
|
|
175
|
+
} catch {
|
|
176
|
+
throw new UsageError("body must be JSON");
|
|
177
|
+
}
|
|
178
|
+
if (typeof parsed !== "object" || parsed === null) throw new UsageError("body must be a JSON object or array");
|
|
179
|
+
return JSON.stringify(parsed);
|
|
180
|
+
}
|
|
181
|
+
|
|
169
182
|
/** `write <method> <path> [json]`: any write under one site of the Network API; the console validates the body. */
|
|
170
183
|
export function unifiWrite(args: string[]): UnifiWrite {
|
|
171
184
|
const [method, path, json, ...extra] = args;
|
|
@@ -177,14 +190,23 @@ export function unifiWrite(args: string[]): UnifiWrite {
|
|
|
177
190
|
return { method, path };
|
|
178
191
|
}
|
|
179
192
|
if (json === undefined) throw new UsageError(`${method} needs a JSON body`);
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
193
|
+
return { method: method as WriteMethod, path, body: jsonBody(json) };
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** The Network application's own NAT rules (Policy Table, type NAT). The official API has no NAT endpoint. */
|
|
197
|
+
export const NAT_PATH = "/v2/api/site/default/nat";
|
|
198
|
+
const NAT_ID = /^[0-9a-f]{24}$/;
|
|
199
|
+
|
|
200
|
+
/** `nat-write POST <json>`, `nat-write PUT <ruleId> <json>`, or `nat-write DELETE <ruleId>`. */
|
|
201
|
+
export function natWrite(args: string[]): UnifiWrite {
|
|
202
|
+
const [method, first, second, ...extra] = args;
|
|
203
|
+
if (method === "POST" && first !== undefined && second === undefined) return { method, path: NAT_PATH, body: jsonBody(first) };
|
|
204
|
+
if ((method === "PUT" || method === "DELETE") && first !== undefined && NAT_ID.test(first) && extra.length === 0) {
|
|
205
|
+
const path = `${NAT_PATH}/${first}`;
|
|
206
|
+
if (method === "DELETE" && second === undefined) return { method, path };
|
|
207
|
+
if (method === "PUT" && second !== undefined) return { method, path, body: jsonBody(second) };
|
|
185
208
|
}
|
|
186
|
-
|
|
187
|
-
return { method: method as WriteMethod, path, body: JSON.stringify(parsed) };
|
|
209
|
+
throw new UsageError("nat-write POST <json> | PUT <ruleId> <json> | DELETE <ruleId>");
|
|
188
210
|
}
|
|
189
211
|
|
|
190
212
|
/** `cloud <path>`: a Site Manager read; the connector is reached through the site commands. */
|
|
@@ -228,9 +250,13 @@ async function cloudRequest(path: string, method: string, body?: string): Promis
|
|
|
228
250
|
return { status: response.status, body: await response.text() };
|
|
229
251
|
}
|
|
230
252
|
|
|
231
|
-
|
|
253
|
+
/** `integration` is the official API under /proxy/network/integration; `app` is the Network application's own paths under /proxy/network. */
|
|
254
|
+
type Api = "integration" | "app";
|
|
255
|
+
|
|
256
|
+
async function localRequest(site: Site, config: SiteConfig, path: string, method: string, body: string | undefined, api: Api): Promise<Answer> {
|
|
232
257
|
const base = new URL(config.localUrl);
|
|
233
|
-
const
|
|
258
|
+
const prefix = base.pathname.replace(/\/$/, "");
|
|
259
|
+
const url = new URL(`${api === "app" ? prefix.replace(/\/integration$/, "") : prefix}${path}`, base);
|
|
234
260
|
return pinnedGet(url, readSecret(SERVICE, SITE_ACCESS[site].localKey), config.certSha256, method, body);
|
|
235
261
|
}
|
|
236
262
|
|
|
@@ -239,9 +265,9 @@ async function localRequest(site: Site, config: SiteConfig, path: string, method
|
|
|
239
265
|
* `local`; a read the cloud cannot serve retries on the console itself. A
|
|
240
266
|
* write never retries, because the cloud may have applied it before failing.
|
|
241
267
|
*/
|
|
242
|
-
async function siteRequest(site: Site, config: SiteConfig, local: boolean, path: string, method = "GET", body?: string): Promise<Answer> {
|
|
243
|
-
if (local) return localRequest(site, config, path, method, body);
|
|
244
|
-
const connector = `/v1/connector/consoles/${config.hostId}/network/integration${path}`;
|
|
268
|
+
async function siteRequest(site: Site, config: SiteConfig, local: boolean, path: string, method = "GET", body?: string, api: Api = "integration"): Promise<Answer> {
|
|
269
|
+
if (local) return localRequest(site, config, path, method, body, api);
|
|
270
|
+
const connector = `/v1/connector/consoles/${config.hostId}/network${api === "integration" ? "/integration" : ""}${path}`;
|
|
245
271
|
let reason: string;
|
|
246
272
|
try {
|
|
247
273
|
const answer = await cloudRequest(connector, method, body);
|
|
@@ -252,7 +278,7 @@ async function siteRequest(site: Site, config: SiteConfig, local: boolean, path:
|
|
|
252
278
|
reason = err instanceof Error ? err.message : String(err);
|
|
253
279
|
}
|
|
254
280
|
process.stderr.write(`network: ${reason}; reading from the ${site} console directly\n`);
|
|
255
|
-
return localRequest(site, config, path, method, body);
|
|
281
|
+
return localRequest(site, config, path, method, body, api);
|
|
256
282
|
}
|
|
257
283
|
|
|
258
284
|
function printAnswer(answer: Answer, source: string): number {
|
|
@@ -277,6 +303,11 @@ async function unifi(args: string[]): Promise<number> {
|
|
|
277
303
|
printJson({ site, host: base.host, fingerprint256: probe.fingerprint });
|
|
278
304
|
return 0;
|
|
279
305
|
}
|
|
306
|
+
if (rest[0] === "nat" || rest[0] === "nat-write") {
|
|
307
|
+
if (rest[0] === "nat" && rest.length > 1) throw new UsageError("unifi <37|mira> nat takes no arguments");
|
|
308
|
+
const call = rest[0] === "nat" ? { method: "GET", path: NAT_PATH, body: undefined } : natWrite(rest.slice(1));
|
|
309
|
+
return printAnswer(await siteRequest(site, readSite(site), local, call.path, call.method, call.body, "app"), `UniFi ${site} NAT`);
|
|
310
|
+
}
|
|
280
311
|
const write = rest[0] === "write" ? unifiWrite(rest.slice(1)) : null;
|
|
281
312
|
const path = write ? write.path : unifiPath(rest);
|
|
282
313
|
return printAnswer(await siteRequest(site, readSite(site), local, path, write?.method, write?.body), `UniFi ${site}`);
|
|
@@ -11,7 +11,7 @@ import { buildInferenceRemote, command as inferenceCommand } from "./inference/r
|
|
|
11
11
|
import { MAX_ADD_IDS, MAX_EXCLUDE_IDS, buildTrendarrCall, interpretRun, parseImdbIds, trendarrConfig, trendarrError, trendarrWarnings, command as mediaCommand } from "./media/run.ts";
|
|
12
12
|
import { ServiceError, UsageError } from "./lib/errors.ts";
|
|
13
13
|
import { safeRepoPath, safeWritePath } from "./lib/repo.ts";
|
|
14
|
-
import { buildPulsarRemote, cloudPath, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
|
|
14
|
+
import { buildPulsarRemote, cloudPath, NAT_PATH, natWrite, parseQuery, parseSiteArgs, unifiPath, unifiWrite, command as networkCommand } from "./network/run.ts";
|
|
15
15
|
import { buildHostRemote, needsConfirm, parseSetPairs, parseVmid, validateApiPath as validatePvePath, command as proxmoxCommand } from "./proxmox/run.ts";
|
|
16
16
|
import { banLength, buildObsRemote, compactDecisions, parseGoDuration, summariseAlerts, summariseVulns, summariseWazuh, vulnEvents, wazuhEvents, command as securityCommand } from "./security/run.ts";
|
|
17
17
|
|
|
@@ -115,6 +115,18 @@ describe("network wrapper", () => {
|
|
|
115
115
|
expect(() => unifiPath(["reboot"])).toThrow(/unknown unifi read/);
|
|
116
116
|
});
|
|
117
117
|
|
|
118
|
+
it("maps NAT rule writes to the application path", () => {
|
|
119
|
+
const id = "0123456789abcdef01234567";
|
|
120
|
+
expect(natWrite(["POST", '{"type":"DNAT"}'])).toEqual({ method: "POST", path: NAT_PATH, body: '{"type":"DNAT"}' });
|
|
121
|
+
expect(natWrite(["PUT", id, "{}"])).toEqual({ method: "PUT", path: `${NAT_PATH}/${id}`, body: "{}" });
|
|
122
|
+
expect(natWrite(["DELETE", id])).toEqual({ method: "DELETE", path: `${NAT_PATH}/${id}` });
|
|
123
|
+
expect(() => natWrite(["DELETE", id, "{}"])).toThrow(UsageError);
|
|
124
|
+
expect(() => natWrite(["PUT", "not-an-id", "{}"])).toThrow(UsageError);
|
|
125
|
+
expect(() => natWrite(["POST"])).toThrow(UsageError);
|
|
126
|
+
expect(() => natWrite(["POST", "{"])).toThrow(/JSON/);
|
|
127
|
+
expect(() => natWrite(["PATCH", id, "{}"])).toThrow(UsageError);
|
|
128
|
+
});
|
|
129
|
+
|
|
118
130
|
it("maps writes under one site and checks the body", () => {
|
|
119
131
|
const body = JSON.stringify({ name: "x", enabled: true });
|
|
120
132
|
expect(unifiWrite(["POST", `/v1/sites/${site}/firewall/policies`, body])).toEqual({ method: "POST", path: `/v1/sites/${site}/firewall/policies`, body });
|