dsh-ssh-hub 0.0.0-stage → 0.2.0
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.
- package/LICENSE +202 -0
- package/README.md +271 -2
- package/cordis.patch.yml +16 -0
- package/icon.svg +3 -0
- package/lib/client.js +13975 -0
- package/lib/index.js +6908 -0
- package/lib/types/activity/history.d.ts +50 -0
- package/lib/types/alerting/notify.d.ts +89 -0
- package/lib/types/alerting/prompt-summary.d.ts +28 -0
- package/lib/types/alerting/rules.d.ts +135 -0
- package/lib/types/alerting/tools.d.ts +30 -0
- package/lib/types/audit/audit-log.d.ts +84 -0
- package/lib/types/audit/recorder.d.ts +50 -0
- package/lib/types/client/api.d.ts +222 -0
- package/lib/types/client/index.d.ts +45 -0
- package/lib/types/client/locales.d.ts +319 -0
- package/lib/types/client/native-panel.d.ts +70 -0
- package/lib/types/client/panel/ClusterTab.d.ts +7 -0
- package/lib/types/client/panel/DeployTab.d.ts +10 -0
- package/lib/types/client/panel/FleetTab.d.ts +10 -0
- package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
- package/lib/types/client/panel/HostsTab.d.ts +25 -0
- package/lib/types/client/panel/LogsTab.d.ts +10 -0
- package/lib/types/client/panel/SshPanel.d.ts +14 -0
- package/lib/types/client/panel/TerminalTab.d.ts +27 -0
- package/lib/types/client/panel/TransferTab.d.ts +7 -0
- package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
- package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
- package/lib/types/client/panel/controller.d.ts +253 -0
- package/lib/types/client/panel/helpers.d.ts +45 -0
- package/lib/types/client/panel/tabs.d.ts +62 -0
- package/lib/types/client/panel/xterm.css.d.ts +2 -0
- package/lib/types/client/settings-binding.d.ts +71 -0
- package/lib/types/deploy/orchestrator.d.ts +158 -0
- package/lib/types/deploy/tools.d.ts +14 -0
- package/lib/types/dsh-home.d.ts +16 -0
- package/lib/types/engine/cluster.d.ts +19 -0
- package/lib/types/engine/connection-pool.d.ts +183 -0
- package/lib/types/engine/proxy-command.d.ts +36 -0
- package/lib/types/engine/pty.d.ts +32 -0
- package/lib/types/engine/sftp.d.ts +20 -0
- package/lib/types/engine/terminal-sessions.d.ts +67 -0
- package/lib/types/engine/tunnel-discovery.d.ts +89 -0
- package/lib/types/engine/tunnel-remarks.d.ts +49 -0
- package/lib/types/engine/tunnel.d.ts +76 -0
- package/lib/types/engine.d.ts +103 -0
- package/lib/types/http.d.ts +59 -0
- package/lib/types/index.d.ts +128 -0
- package/lib/types/inspect/checks.d.ts +118 -0
- package/lib/types/inspect/inspection.d.ts +111 -0
- package/lib/types/inspect/tools.d.ts +50 -0
- package/lib/types/logs/search.d.ts +131 -0
- package/lib/types/logs/tools.d.ts +6 -0
- package/lib/types/loopback.d.ts +64 -0
- package/lib/types/monitor/loop.d.ts +133 -0
- package/lib/types/monitor/metrics.d.ts +151 -0
- package/lib/types/mount-once.d.ts +55 -0
- package/lib/types/protocol.d.ts +524 -0
- package/lib/types/routes.d.ts +82 -0
- package/lib/types/security/known-hosts.d.ts +153 -0
- package/lib/types/security/master-secret.d.ts +157 -0
- package/lib/types/security/redact.d.ts +44 -0
- package/lib/types/security/secrets.d.ts +70 -0
- package/lib/types/ssh-config.d.ts +42 -0
- package/lib/types/store.d.ts +183 -0
- package/lib/types/tool-surface.d.ts +72 -0
- package/lib/types/tools.d.ts +56 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +126 -6
- package/src/activity/history.ts +117 -0
- package/src/alerting/notify.ts +212 -0
- package/src/alerting/prompt-summary.ts +71 -0
- package/src/alerting/rules.ts +281 -0
- package/src/alerting/tools.ts +263 -0
- package/src/audit/audit-log.ts +199 -0
- package/src/audit/recorder.ts +73 -0
- package/src/client/api.ts +782 -0
- package/src/client/css-modules.d.ts +5 -0
- package/src/client/index.ts +150 -0
- package/src/client/locales.ts +654 -0
- package/src/client/native-panel.tsx +141 -0
- package/src/client/panel/ClusterTab.tsx +141 -0
- package/src/client/panel/DeployTab.tsx +314 -0
- package/src/client/panel/FleetTab.tsx +494 -0
- package/src/client/panel/HostFormDialog.tsx +289 -0
- package/src/client/panel/HostsTab.tsx +395 -0
- package/src/client/panel/LogsTab.tsx +208 -0
- package/src/client/panel/SshPanel.tsx +105 -0
- package/src/client/panel/TerminalTab.tsx +550 -0
- package/src/client/panel/TransferTab.tsx +238 -0
- package/src/client/panel/TunnelEditDialog.tsx +174 -0
- package/src/client/panel/TunnelsTab.tsx +328 -0
- package/src/client/panel/controller.ts +507 -0
- package/src/client/panel/helpers.ts +84 -0
- package/src/client/panel/panel.module.css +1734 -0
- package/src/client/panel/tabs.ts +52 -0
- package/src/client/panel/xterm.css.ts +2 -0
- package/src/client/settings-binding.ts +184 -0
- package/src/deploy/orchestrator.ts +326 -0
- package/src/deploy/tools.ts +225 -0
- package/src/dsh-home.ts +42 -0
- package/src/engine/cluster.ts +60 -0
- package/src/engine/connection-pool.ts +721 -0
- package/src/engine/proxy-command.ts +248 -0
- package/src/engine/pty.ts +78 -0
- package/src/engine/sftp.ts +229 -0
- package/src/engine/terminal-sessions.ts +280 -0
- package/src/engine/tunnel-discovery.ts +353 -0
- package/src/engine/tunnel-remarks.ts +120 -0
- package/src/engine/tunnel.ts +300 -0
- package/src/engine.ts +195 -0
- package/src/http.ts +127 -0
- package/src/index.ts +690 -0
- package/src/inspect/checks.ts +251 -0
- package/src/inspect/inspection.ts +321 -0
- package/src/inspect/tools.ts +366 -0
- package/src/logs/search.ts +251 -0
- package/src/logs/tools.ts +160 -0
- package/src/loopback.ts +119 -0
- package/src/monitor/loop.ts +265 -0
- package/src/monitor/metrics.ts +333 -0
- package/src/mount-once.ts +142 -0
- package/src/protocol.ts +534 -0
- package/src/routes.ts +998 -0
- package/src/security/known-hosts.ts +342 -0
- package/src/security/master-secret.ts +334 -0
- package/src/security/redact.ts +119 -0
- package/src/security/secrets.ts +152 -0
- package/src/ssh-config.ts +182 -0
- package/src/store.ts +757 -0
- package/src/tool-surface.ts +96 -0
- package/src/tools.ts +550 -0
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Inspection runner and result retention.
|
|
3
|
+
*
|
|
4
|
+
* Runs the built-in checks across a selected set of hosts (reusing the
|
|
5
|
+
* engine's pool, so no extra connections are opened), stores each round as
|
|
6
|
+
* a JSON Lines record, and answers "what changed since last time".
|
|
7
|
+
*
|
|
8
|
+
* The comparison is the point: a raw dump of "disk 71%" says nothing, while
|
|
9
|
+
* "disk 71% (was 42% an hour ago)" says the fleet is filling up. Every round
|
|
10
|
+
* is therefore retained, and the diff is computed from the two newest
|
|
11
|
+
* rounds by default.
|
|
12
|
+
*/
|
|
13
|
+
import type { SshEngine } from '../engine.ts';
|
|
14
|
+
import { type Check, type CheckResult } from './checks.ts';
|
|
15
|
+
/**
|
|
16
|
+
* How many hosts one inspection round works on at a time.
|
|
17
|
+
*
|
|
18
|
+
* Chosen to finish a 50-host sweep inside the default 60-second interval while
|
|
19
|
+
* keeping the number of simultaneously open SSH connections in the same range
|
|
20
|
+
* the connection pool already uses for other fan-out (8). Raising it trades
|
|
21
|
+
* sockets for wall clock; lowering it risks a round that outlasts its own
|
|
22
|
+
* timer and reports "上一轮尚未结束" instead of a result.
|
|
23
|
+
*/
|
|
24
|
+
export declare const DEFAULT_INSPECT_CONCURRENCY = 8;
|
|
25
|
+
/** One inspection round. */
|
|
26
|
+
export interface InspectionRound {
|
|
27
|
+
/** Epoch milliseconds when the round started. */
|
|
28
|
+
startedAt: number;
|
|
29
|
+
/** How long the round took. */
|
|
30
|
+
durationMs: number;
|
|
31
|
+
/** The hosts covered. */
|
|
32
|
+
targets: string[];
|
|
33
|
+
/** Every check result, flattened. */
|
|
34
|
+
results: CheckResult[];
|
|
35
|
+
}
|
|
36
|
+
/** One host's change between two rounds. */
|
|
37
|
+
export interface HostChange {
|
|
38
|
+
alias: string;
|
|
39
|
+
checkId: string;
|
|
40
|
+
title: string;
|
|
41
|
+
/** The previous display value, or undefined when the check is new. */
|
|
42
|
+
before?: string;
|
|
43
|
+
/** The current display value. */
|
|
44
|
+
after: string;
|
|
45
|
+
/** Whether the breach state changed (and in which direction). */
|
|
46
|
+
stateChange?: 'new-breach' | 'recovered';
|
|
47
|
+
}
|
|
48
|
+
/** The inspection history file. */
|
|
49
|
+
export declare function historyPath(): string;
|
|
50
|
+
/**
|
|
51
|
+
* The inspection runner.
|
|
52
|
+
*
|
|
53
|
+
* One instance per plugin apply. Holds no long-lived state beyond the file
|
|
54
|
+
* path: rounds are written as they complete, so a crash loses at most the
|
|
55
|
+
* round in flight.
|
|
56
|
+
*/
|
|
57
|
+
export declare class Inspector {
|
|
58
|
+
/** The history file this inspector appends to. */
|
|
59
|
+
readonly path: string;
|
|
60
|
+
/** How many rounds to keep for comparison and display. */
|
|
61
|
+
readonly maxRounds: number;
|
|
62
|
+
constructor(path?: string, maxRounds?: number);
|
|
63
|
+
/**
|
|
64
|
+
* Run one round of checks.
|
|
65
|
+
*
|
|
66
|
+
* @param engine - the SSH engine (the connection pool is reused).
|
|
67
|
+
* @param targets - the host aliases to inspect.
|
|
68
|
+
* @param checkIds - which checks to run (default: all built-in checks).
|
|
69
|
+
* @param timeoutMs - per-command timeout.
|
|
70
|
+
* @returns the completed round.
|
|
71
|
+
*/
|
|
72
|
+
run(engine: SshEngine, targets: string[], checkIds?: string[], timeoutMs?: number, concurrency?: number): Promise<InspectionRound>;
|
|
73
|
+
/**
|
|
74
|
+
* Append one round to the history file.
|
|
75
|
+
*
|
|
76
|
+
* @param round - the round to store.
|
|
77
|
+
*/
|
|
78
|
+
append(round: InspectionRound): void;
|
|
79
|
+
/**
|
|
80
|
+
* Called after every round is durably appended.
|
|
81
|
+
*
|
|
82
|
+
* Used by the metric store to derive series from rounds, so the tiers stay
|
|
83
|
+
* current whether the round came from the timer or from a tool call.
|
|
84
|
+
*/
|
|
85
|
+
onRound?: (round: InspectionRound) => void;
|
|
86
|
+
/**
|
|
87
|
+
* Read the most recent rounds, oldest first.
|
|
88
|
+
*
|
|
89
|
+
* @param limit - how many rounds to return.
|
|
90
|
+
* @returns the rounds.
|
|
91
|
+
*/
|
|
92
|
+
read(limit?: number): InspectionRound[];
|
|
93
|
+
/**
|
|
94
|
+
* Compare the two newest rounds.
|
|
95
|
+
*
|
|
96
|
+
* @returns the changes, newest round against the one before it. An empty
|
|
97
|
+
* array means either fewer than two rounds exist or nothing changed — the
|
|
98
|
+
* caller distinguishes the two by looking at {@link read}.
|
|
99
|
+
*/
|
|
100
|
+
diff(): HostChange[];
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* The checks selected by the given ids.
|
|
104
|
+
*
|
|
105
|
+
* An unknown id throws: silently skipping it would let a typo look like a
|
|
106
|
+
* clean inspection.
|
|
107
|
+
*
|
|
108
|
+
* @param checkIds - the requested ids, or undefined for all.
|
|
109
|
+
* @returns the checks to run.
|
|
110
|
+
*/
|
|
111
|
+
export declare function selectChecks(checkIds?: string[]): readonly Check[];
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Agent tools for the inspection layer.
|
|
3
|
+
*
|
|
4
|
+
* Two tools, deliberately split by intent:
|
|
5
|
+
* - `hub_inspect` runs a round of checks and returns the results
|
|
6
|
+
* - `hub_inspect_diff` returns what changed since the previous round
|
|
7
|
+
*
|
|
8
|
+
* The split matters: "check the fleet" and "what changed since I last
|
|
9
|
+
* looked" are different questions, and an agent that has to re-run the
|
|
10
|
+
* whole fleet to answer the second one pays for it in round trips.
|
|
11
|
+
*/
|
|
12
|
+
import type { SshEngine } from '../engine.ts';
|
|
13
|
+
import type { Inspector } from './inspection.ts';
|
|
14
|
+
/**
|
|
15
|
+
* Resolve the target hosts for an inspection.
|
|
16
|
+
*
|
|
17
|
+
* At least one selector is required, for the same reason `ssh_cluster`
|
|
18
|
+
* requires one: a fleet tool that silently inspects EVERY host when the
|
|
19
|
+
* selector is empty is a foot-gun, and an inspection is cheap but not free
|
|
20
|
+
* on 50 machines.
|
|
21
|
+
*
|
|
22
|
+
* @param engine - the SSH engine (the host list).
|
|
23
|
+
* @param aliases - explicit aliases.
|
|
24
|
+
* @param environment - an environment label (exact match).
|
|
25
|
+
* @param tags - tags that must ALL be present.
|
|
26
|
+
* @returns the selected aliases.
|
|
27
|
+
*/
|
|
28
|
+
export declare function resolveTargets(engine: SshEngine, aliases?: string[], environment?: string, tags?: string[]): string[];
|
|
29
|
+
/** The inspection tool: run a round of checks. */
|
|
30
|
+
export declare function hubInspectTool(engine: SshEngine, inspector: Inspector): import("@deepseek-ai/dsh-tools").ToolDefinition;
|
|
31
|
+
/** The catalogue tool: list the available checks. */
|
|
32
|
+
export declare function hubInspectCatalogTool(): import("@deepseek-ai/dsh-tools").ToolDefinition;
|
|
33
|
+
/** The diff tool: what changed since the previous round. */
|
|
34
|
+
export declare function hubInspectDiffTool(inspector: Inspector): import("@deepseek-ai/dsh-tools").ToolDefinition;
|
|
35
|
+
/**
|
|
36
|
+
* The monitoring-loop tool: is the fleet being watched, and what did the
|
|
37
|
+
* last round see?
|
|
38
|
+
*
|
|
39
|
+
* This is separate from `hub_inspect` on purpose. `hub_inspect` *runs* a
|
|
40
|
+
* round; this reports on the loop that runs rounds on its own. An agent
|
|
41
|
+
* asked "is the fleet being monitored?" must not have to run a round to
|
|
42
|
+
* answer, because running a round changes the thing being asked about.
|
|
43
|
+
*
|
|
44
|
+
* @param monitor - the loop (absent when the plugin mounted without one).
|
|
45
|
+
* @param store - the host store, for the configured target count.
|
|
46
|
+
* @returns the tool definition.
|
|
47
|
+
*/
|
|
48
|
+
export declare function hubMonitorTool(monitor: {
|
|
49
|
+
status(): Record<string, unknown>;
|
|
50
|
+
} | undefined): import("@deepseek-ai/dsh-tools").ToolDefinition;
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cross-host log search.
|
|
3
|
+
*
|
|
4
|
+
* The agentless way to search logs on 50 Linux machines: run a read-only
|
|
5
|
+
* grep over the log files on each host and aggregate the matches. No agent
|
|
6
|
+
* is installed on the remote side, nothing is written, and the whole thing
|
|
7
|
+
* is one SSH round trip per host.
|
|
8
|
+
*
|
|
9
|
+
* Two sources are supported, because a Linux fleet has both:
|
|
10
|
+
* - `journalctl` for the systemd journal
|
|
11
|
+
* - plain files under a log directory (grep over a file set)
|
|
12
|
+
*
|
|
13
|
+
* The search is BOUNDED on purpose: a grep across a fleet can return
|
|
14
|
+
* megabytes, which would flood the model's context. Per-host match counts
|
|
15
|
+
* and a global match cap keep the result readable, and the truncation is
|
|
16
|
+
* reported rather than hidden.
|
|
17
|
+
*/
|
|
18
|
+
import type { SshEngine } from '../engine.ts';
|
|
19
|
+
/** Where to search. */
|
|
20
|
+
export type LogSource =
|
|
21
|
+
/** The systemd journal. */
|
|
22
|
+
'journal'
|
|
23
|
+
/** A set of log files under a directory. */
|
|
24
|
+
| 'files';
|
|
25
|
+
/** A log search request. */
|
|
26
|
+
export interface LogSearchRequest {
|
|
27
|
+
/** The search source. */
|
|
28
|
+
source: LogSource;
|
|
29
|
+
/** The pattern to search for (a grep pattern or a journalctl match). */
|
|
30
|
+
pattern: string;
|
|
31
|
+
/** The log directory, when the source is 'files'. */
|
|
32
|
+
directory?: string;
|
|
33
|
+
/** How many lines to keep per host. */
|
|
34
|
+
maxLinesPerHost?: number;
|
|
35
|
+
/** The systemd unit to filter on, when the source is 'journal'. */
|
|
36
|
+
unit?: string;
|
|
37
|
+
/** The time window start (epoch seconds), when the source is 'journal'. */
|
|
38
|
+
since?: number;
|
|
39
|
+
/** How long the command may take per host. */
|
|
40
|
+
timeoutMs?: number;
|
|
41
|
+
/** How many hosts to search at once. */
|
|
42
|
+
maxWorkers?: number;
|
|
43
|
+
}
|
|
44
|
+
/** One host's search outcome. */
|
|
45
|
+
export interface LogHostResult {
|
|
46
|
+
alias: string;
|
|
47
|
+
ok: boolean;
|
|
48
|
+
/** The matching lines (bounded). */
|
|
49
|
+
lines: string[];
|
|
50
|
+
/** How many matches the host reported in total. */
|
|
51
|
+
totalMatches?: number;
|
|
52
|
+
/** Whether the output was truncated. */
|
|
53
|
+
truncated?: boolean;
|
|
54
|
+
/** The error, when the search failed. */
|
|
55
|
+
error?: string;
|
|
56
|
+
/** How long the search took on this host. */
|
|
57
|
+
durationMs?: number;
|
|
58
|
+
}
|
|
59
|
+
/** The outcome of a fleet-wide search. */
|
|
60
|
+
export interface LogSearchResult {
|
|
61
|
+
ok: boolean;
|
|
62
|
+
/** The hosts that were searched. */
|
|
63
|
+
targets: string[];
|
|
64
|
+
/** The per-host outcomes. */
|
|
65
|
+
results: LogHostResult[];
|
|
66
|
+
/** The total number of matching lines returned. */
|
|
67
|
+
totalLines: number;
|
|
68
|
+
/** Whether any host's output was truncated. */
|
|
69
|
+
truncated: boolean;
|
|
70
|
+
/** How long the whole search took. */
|
|
71
|
+
durationMs: number;
|
|
72
|
+
/** The error, when the search could not run at all. */
|
|
73
|
+
error?: string;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Build the remote command for one search.
|
|
77
|
+
*
|
|
78
|
+
* The pattern is passed as a shell argument, quoted so a pattern with
|
|
79
|
+
* spaces or quotes does not break the command. The pattern itself is a
|
|
80
|
+
* grep pattern — that is the operator's choice, and it runs on their own
|
|
81
|
+
* hosts.
|
|
82
|
+
*
|
|
83
|
+
* @param request - the search request.
|
|
84
|
+
* @returns the command to run on the remote host.
|
|
85
|
+
*/
|
|
86
|
+
export declare function buildSearchCommand(request: LogSearchRequest): string;
|
|
87
|
+
/**
|
|
88
|
+
* Quote a value for a POSIX shell.
|
|
89
|
+
*
|
|
90
|
+
* @param value - the value to quote.
|
|
91
|
+
* @returns the quoted value.
|
|
92
|
+
*/
|
|
93
|
+
export declare function shellQuote(value: string): string;
|
|
94
|
+
/**
|
|
95
|
+
* Format a "since" timestamp for journalctl.
|
|
96
|
+
*
|
|
97
|
+
* @param epochSeconds - the timestamp in seconds.
|
|
98
|
+
* @returns the journalctl argument.
|
|
99
|
+
*/
|
|
100
|
+
export declare function formatSince(epochSeconds: number): string;
|
|
101
|
+
/**
|
|
102
|
+
* Search the logs on many hosts.
|
|
103
|
+
*
|
|
104
|
+
* @param engine - the SSH engine.
|
|
105
|
+
* @param request - the search request.
|
|
106
|
+
* @param targets - the host aliases.
|
|
107
|
+
* @returns the fleet-wide outcome.
|
|
108
|
+
*/
|
|
109
|
+
export declare function searchLogs(engine: SshEngine, request: LogSearchRequest, targets: string[]): Promise<LogSearchResult>;
|
|
110
|
+
/**
|
|
111
|
+
* Parse the combined output of a search command.
|
|
112
|
+
*
|
|
113
|
+
* The command prints the matched lines, then the total count on the last
|
|
114
|
+
* line. The count line is numeric only, so it is unambiguous.
|
|
115
|
+
*
|
|
116
|
+
* @param stdout - the command output.
|
|
117
|
+
* @param maxLines - the per-host cap.
|
|
118
|
+
* @returns the lines and the total count.
|
|
119
|
+
*/
|
|
120
|
+
export declare function parseSearchOutput(stdout: string, maxLines: number): {
|
|
121
|
+
lines: string[];
|
|
122
|
+
total: number;
|
|
123
|
+
truncated: boolean;
|
|
124
|
+
};
|
|
125
|
+
/**
|
|
126
|
+
* A human-readable rendering of a search outcome.
|
|
127
|
+
*
|
|
128
|
+
* @param result - the search outcome.
|
|
129
|
+
* @returns the report text.
|
|
130
|
+
*/
|
|
131
|
+
export declare function renderLogSearch(result: LogSearchResult): string;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Loopback trust fence shared by the host route families: socket address,
|
|
3
|
+
* Host header, and browser same-origin markers. Packages receive this file as
|
|
4
|
+
* a generated copy via scripts/sync-shared.mjs; edit the shared source and
|
|
5
|
+
* re-run the sync instead of editing a copy.
|
|
6
|
+
*
|
|
7
|
+
* Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
|
|
8
|
+
* remote-web-ui gate), localhost hostnames, plus the browser same-origin
|
|
9
|
+
* markers (sec-fetch-site and Origin) for the request-level fence.
|
|
10
|
+
*
|
|
11
|
+
* A reverse proxy in front of the host rewrites the Host header to its own
|
|
12
|
+
* upstream literal (a Cloudflare tunnel, frp and an nginx reverse proxy all
|
|
13
|
+
* dial 127.0.0.1:<port>), and the socket the origin sees is the proxy's, which
|
|
14
|
+
* is loopback by construction. Both halves of the fence then hold for a public
|
|
15
|
+
* request. Forwarding headers are the signal that a hop stands in between: a
|
|
16
|
+
* request that carries CF-Connecting-IP or X-Forwarded-For is answered through
|
|
17
|
+
* a proxy and is never treated as a local one (issue #1906).
|
|
18
|
+
*
|
|
19
|
+
* An operator who runs that proxy or tunnel themselves can opt into the
|
|
20
|
+
* narrower case: isForwardedLoopbackRequest describes a forwarded request that
|
|
21
|
+
* still landed on this machine's loopback upstream, and a route family admits
|
|
22
|
+
* it only behind its own default-off switch (issue #1918).
|
|
23
|
+
* @module dsh-web-shared/host/loopback
|
|
24
|
+
*/
|
|
25
|
+
import type { IncomingMessage } from 'node:http';
|
|
26
|
+
/** IPv4 127/8 predicate (four decimal octets, first == 127). */
|
|
27
|
+
export declare function isIPv4Loopback(v4: string): boolean;
|
|
28
|
+
/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
|
|
29
|
+
export declare function isLoopbackAddress(address: string | undefined): boolean;
|
|
30
|
+
/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
|
|
31
|
+
export declare function isLoopbackHostname(hostname: string): boolean;
|
|
32
|
+
/**
|
|
33
|
+
* Whether a reverse proxy stood between the client and this host: the request
|
|
34
|
+
* carries CF-Connecting-IP or X-Forwarded-For. Either header is stamped by a
|
|
35
|
+
* hop that forwards traffic, so the request did not originate on this machine.
|
|
36
|
+
* @param request - node HTTP request.
|
|
37
|
+
* @returns true when a forwarding header is present.
|
|
38
|
+
*/
|
|
39
|
+
export declare function isProxiedRequest(request: IncomingMessage): boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Request-level trust fence: a loopback socket address AND a loopback Host
|
|
42
|
+
* header, plus browser same-origin markers. The socket address is
|
|
43
|
+
* authoritative for a direct connection; a request that carries a forwarding
|
|
44
|
+
* header is refused outright, because a proxy in front of the host makes both
|
|
45
|
+
* the socket address and the Host header describe the proxy rather than the
|
|
46
|
+
* client. X-Forwarded-For is therefore never evidence *for* loopback.
|
|
47
|
+
*/
|
|
48
|
+
export declare function isLoopbackRequest(request: IncomingMessage): boolean;
|
|
49
|
+
/**
|
|
50
|
+
* Whether a forwarded request landed on this machine's loopback upstream: a
|
|
51
|
+
* forwarding header (the proxy's own stamp), a loopback socket address (the
|
|
52
|
+
* proxy dials 127.0.0.1:<port>), and a loopback Host header (the proxy rewrote
|
|
53
|
+
* the authority to its upstream literal).
|
|
54
|
+
*
|
|
55
|
+
* This is a fact about the route, not a trust decision. A public request to a
|
|
56
|
+
* tunnel satisfies all three by construction, because the proxy is the client
|
|
57
|
+
* of this process: only a caller that operates the proxy can decide it stands
|
|
58
|
+
* for the browser, which is why every consumer keeps this behind an explicit
|
|
59
|
+
* default-off switch and its own browser markers. isLoopbackRequest is
|
|
60
|
+
* unchanged and still refuses a forwarded request (issue #1906).
|
|
61
|
+
* @param request - node HTTP request.
|
|
62
|
+
* @returns true when a forwarding header, a loopback socket, and a loopback Host all hold.
|
|
63
|
+
*/
|
|
64
|
+
export declare function isForwardedLoopbackRequest(request: IncomingMessage): boolean;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The monitoring loop: inspection on a timer, feeding the alert engine.
|
|
3
|
+
*
|
|
4
|
+
* This is the piece that turns the inspection layer from "an agent can ask
|
|
5
|
+
* for a health check" into "the fleet is watched". Without it, an alert
|
|
6
|
+
* only advances when a human (or an agent) happens to run hub_inspect, so a
|
|
7
|
+
* disk filling up at 03:00 is discovered whenever someone next looks —
|
|
8
|
+
* which is exactly the failure a monitoring tool exists to prevent.
|
|
9
|
+
*
|
|
10
|
+
* The loop is deliberately conservative, because its failure mode is
|
|
11
|
+
* expensive:
|
|
12
|
+
*
|
|
13
|
+
* - **One round at a time.** A round that outlasts the interval does not
|
|
14
|
+
* stack: the next tick is skipped, not queued. Fifty hosts with a slow
|
|
15
|
+
* connection would otherwise pile up overlapping rounds until the pool
|
|
16
|
+
* is exhausted.
|
|
17
|
+
* - **The timer belongs to the plugin's fiber.** `ctx.timer.interval`
|
|
18
|
+
* disposes with the fiber, so disabling the plugin stops the loop
|
|
19
|
+
* instead of leaving an orphan timer probing servers forever.
|
|
20
|
+
* - **A failed round is not a fleet-wide alert.** If every host fails, the
|
|
21
|
+
* cause is almost always the local link or the pool, not fifty machines
|
|
22
|
+
* dying at once. The round is reported as a degraded round, and the
|
|
23
|
+
* alert engine's null-freeze keeps the previous states rather than
|
|
24
|
+
* inventing fifty recoveries.
|
|
25
|
+
*/
|
|
26
|
+
import type { SshEngine } from '../engine.ts';
|
|
27
|
+
import type { Inspector, InspectionRound } from '../inspect/inspection.ts';
|
|
28
|
+
import type { AlertEngine, AlertNotification, AlertRule } from '../alerting/rules.ts';
|
|
29
|
+
import type { AlertEvent } from '../alerting/tools.ts';
|
|
30
|
+
/** Where the tick callback gets its timer from (the cordis timer service). */
|
|
31
|
+
export interface TimerHost {
|
|
32
|
+
interval(callback: () => void, delay: number): () => void;
|
|
33
|
+
}
|
|
34
|
+
/** Monitoring loop options. */
|
|
35
|
+
export interface MonitorOptions {
|
|
36
|
+
/** How often to run a round, in milliseconds. */
|
|
37
|
+
intervalMs: number;
|
|
38
|
+
/** The hosts to watch (a fixed set captured at start; re-resolved per round). */
|
|
39
|
+
targets?: () => string[];
|
|
40
|
+
/** Which checks to run (default: all built-in checks). */
|
|
41
|
+
checks?: string[];
|
|
42
|
+
/** Per-command timeout. */
|
|
43
|
+
timeoutMs?: number;
|
|
44
|
+
/** The alert rules. */
|
|
45
|
+
rules: AlertRule[];
|
|
46
|
+
}
|
|
47
|
+
/** A round's outcome as the loop records it. */
|
|
48
|
+
export interface MonitorTick {
|
|
49
|
+
/** Epoch milliseconds when the round started. */
|
|
50
|
+
at: number;
|
|
51
|
+
/** Whether the round actually ran (false when skipped as overlapping). */
|
|
52
|
+
ran: boolean;
|
|
53
|
+
/** How many hosts were inspected. */
|
|
54
|
+
hosts: number;
|
|
55
|
+
/** How many results breached their threshold. */
|
|
56
|
+
breaches: number;
|
|
57
|
+
/** How many probe failures (unreadable values) occurred. */
|
|
58
|
+
blind: number;
|
|
59
|
+
/** The notifications this round produced. */
|
|
60
|
+
notifications: AlertNotification[];
|
|
61
|
+
/** Why the round did not run, when it did not. */
|
|
62
|
+
skippedBecause?: string;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* The monitoring loop.
|
|
66
|
+
*
|
|
67
|
+
* Owns no state beyond `running` and the recent ticks: the inspection
|
|
68
|
+
* history and the alert state each have their own store, so a restart of
|
|
69
|
+
* the loop does not lose either.
|
|
70
|
+
*/
|
|
71
|
+
export declare class Monitor {
|
|
72
|
+
private readonly engine;
|
|
73
|
+
private readonly inspector;
|
|
74
|
+
private readonly alerts;
|
|
75
|
+
private readonly events;
|
|
76
|
+
private readonly onNotify?;
|
|
77
|
+
private readonly options;
|
|
78
|
+
/** Recent ticks, newest last (bounded). */
|
|
79
|
+
readonly ticks: MonitorTick[];
|
|
80
|
+
/** The interval disposer, while the loop runs. */
|
|
81
|
+
private dispose;
|
|
82
|
+
/** Whether a round is in flight (the overlap guard). */
|
|
83
|
+
private inFlight;
|
|
84
|
+
/** The last round, for the panel to read without re-reading the file. */
|
|
85
|
+
lastRound: InspectionRound | undefined;
|
|
86
|
+
constructor(engine: SshEngine, inspector: Inspector, alerts: AlertEngine, events: AlertEvent[], options: MonitorOptions, onNotify?: (notification: AlertNotification) => void | Promise<void>);
|
|
87
|
+
/** Whether the loop is currently armed. */
|
|
88
|
+
get running(): boolean;
|
|
89
|
+
/**
|
|
90
|
+
* Start the loop.
|
|
91
|
+
*
|
|
92
|
+
* A second start is a no-op rather than a second timer: two timers would
|
|
93
|
+
* double every probe against the fleet.
|
|
94
|
+
*
|
|
95
|
+
* @param timer - the cordis timer service.
|
|
96
|
+
* @returns the disposer that stops the loop.
|
|
97
|
+
*/
|
|
98
|
+
start(timer: TimerHost): () => void;
|
|
99
|
+
/** Stop the loop (idempotent). */
|
|
100
|
+
stop(): void;
|
|
101
|
+
/**
|
|
102
|
+
* Run one round now.
|
|
103
|
+
*
|
|
104
|
+
* @returns the round's outcome, or undefined when a round was already in
|
|
105
|
+
* flight (the tick is skipped, not queued).
|
|
106
|
+
*/
|
|
107
|
+
tick(): Promise<MonitorTick | undefined>;
|
|
108
|
+
/** Append a tick to the bounded history. */
|
|
109
|
+
private record;
|
|
110
|
+
/**
|
|
111
|
+
* The current state, for the status route and the panel.
|
|
112
|
+
*
|
|
113
|
+
* @returns the loop's health summary.
|
|
114
|
+
*/
|
|
115
|
+
status(): {
|
|
116
|
+
running: boolean;
|
|
117
|
+
intervalMs: number;
|
|
118
|
+
lastTick?: MonitorTick;
|
|
119
|
+
nextTickAt?: number;
|
|
120
|
+
hosts: number;
|
|
121
|
+
lastRoundAt?: number;
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Render one round as operator-facing text.
|
|
126
|
+
*
|
|
127
|
+
* Used by the status route and the panel's inspection tab, so both show the
|
|
128
|
+
* same thing the agent sees.
|
|
129
|
+
*
|
|
130
|
+
* @param round - the round.
|
|
131
|
+
* @returns the report text.
|
|
132
|
+
*/
|
|
133
|
+
export declare function renderRound(round: InspectionRound): string;
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Metric sampling and tiered retention.
|
|
3
|
+
*
|
|
4
|
+
* A fleet operator needs two different things from history, and they pull in
|
|
5
|
+
* opposite directions:
|
|
6
|
+
*
|
|
7
|
+
* - **"What happened at 03:12?"** wants fine resolution, recently.
|
|
8
|
+
* - **"Is this box slowly filling up over months?"** wants a long window,
|
|
9
|
+
* and does not care about per-second detail.
|
|
10
|
+
*
|
|
11
|
+
* Keeping every raw sample forever answers both and costs unbounded disk on
|
|
12
|
+
* the operator's own workstation. Keeping only hourly averages answers the
|
|
13
|
+
* second and makes the first unanswerable. So this keeps three tiers and
|
|
14
|
+
* lets the coarse tiers outlive the fine ones:
|
|
15
|
+
*
|
|
16
|
+
* raw one sample per round, pruned after RAW_WINDOW
|
|
17
|
+
* 1m one sample per minute, pruned after MINUTE_WINDOW
|
|
18
|
+
* 15m one sample per 15 min, pruned after QUARTER_WINDOW
|
|
19
|
+
* 1h one sample per hour, never pruned
|
|
20
|
+
*
|
|
21
|
+
* Each tier is derived from the tier below it by averaging, so a tier never
|
|
22
|
+
* invents a sample that no measurement supports — a bucket with no raw
|
|
23
|
+
* samples produces no aggregated sample at all. That distinction matters:
|
|
24
|
+
* a gap in the graph means "we did not measure", not "the value was zero".
|
|
25
|
+
*
|
|
26
|
+
* Storage is one JSON Lines file per host and tier. JSONL because a partial
|
|
27
|
+
* write loses one line, not the file, and because an operator can read it
|
|
28
|
+
* with `tail` without a tool.
|
|
29
|
+
*/
|
|
30
|
+
import type { CheckResult } from '../inspect/checks.ts';
|
|
31
|
+
/** One metric sample. */
|
|
32
|
+
export interface MetricSample {
|
|
33
|
+
/** Epoch milliseconds. */
|
|
34
|
+
at: number;
|
|
35
|
+
/** The metric id (equal to the check id that produced it). */
|
|
36
|
+
metric: string;
|
|
37
|
+
/** The value; null when the probe could not read it. */
|
|
38
|
+
value: number | null;
|
|
39
|
+
}
|
|
40
|
+
/** One aggregated bucket. */
|
|
41
|
+
export interface MetricBucket {
|
|
42
|
+
/** Bucket start, epoch milliseconds. */
|
|
43
|
+
at: number;
|
|
44
|
+
metric: string;
|
|
45
|
+
/** Mean of the raw samples in the bucket; null when every sample was blind. */
|
|
46
|
+
value: number | null;
|
|
47
|
+
/** How many raw samples fed this bucket. */
|
|
48
|
+
samples: number;
|
|
49
|
+
}
|
|
50
|
+
/** A retention tier. */
|
|
51
|
+
export interface Tier {
|
|
52
|
+
/** Tier name, also its directory name. */
|
|
53
|
+
name: 'raw' | '1m' | '15m' | '1h';
|
|
54
|
+
/** Bucket width in milliseconds (0 for raw, which keeps the sample's own `at`). */
|
|
55
|
+
widthMs: number;
|
|
56
|
+
/** How long a bucket survives, in milliseconds; 0 means forever. */
|
|
57
|
+
keepMs: number;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The tiers, coarse to fine windows.
|
|
61
|
+
*
|
|
62
|
+
* The raw window is deliberately short (24h): raw samples are the bulky tier,
|
|
63
|
+
* and anything older is answerable from the 1m tier for a month.
|
|
64
|
+
*/
|
|
65
|
+
export declare const TIERS: readonly Tier[];
|
|
66
|
+
/** The metrics store root. */
|
|
67
|
+
export declare function metricsRoot(): string;
|
|
68
|
+
/**
|
|
69
|
+
* The file a (host, tier) pair lives in.
|
|
70
|
+
*
|
|
71
|
+
* @param alias - the host alias.
|
|
72
|
+
* @param tier - the tier name.
|
|
73
|
+
* @param root - store root override (tests).
|
|
74
|
+
* @returns the absolute path.
|
|
75
|
+
*/
|
|
76
|
+
export declare function tierPath(alias: string, tier: Tier['name'], root?: string): string;
|
|
77
|
+
/**
|
|
78
|
+
* The metric store: append raw samples, derive coarser tiers, prune.
|
|
79
|
+
*
|
|
80
|
+
* One instance per plugin apply. Every method is synchronous: samples are
|
|
81
|
+
* small and arrive once per inspection round, so a write is microseconds,
|
|
82
|
+
* and making it async would only add a window in which an in-flight round's
|
|
83
|
+
* samples could interleave with a prune.
|
|
84
|
+
*/
|
|
85
|
+
export declare class MetricStore {
|
|
86
|
+
private readonly root;
|
|
87
|
+
constructor(root?: string);
|
|
88
|
+
/**
|
|
89
|
+
* Append one round's samples and roll the tiers up.
|
|
90
|
+
*
|
|
91
|
+
* @param alias - the host alias.
|
|
92
|
+
* @param samples - the samples from this round.
|
|
93
|
+
*/
|
|
94
|
+
record(alias: string, samples: readonly MetricSample[]): void;
|
|
95
|
+
/** Append entries to one tier file. */
|
|
96
|
+
private appendTier;
|
|
97
|
+
/**
|
|
98
|
+
* Delete every stored series for one alias.
|
|
99
|
+
*
|
|
100
|
+
* Called when a host is removed from the store: its metric history is keyed
|
|
101
|
+
* only by alias, so leaving it behind means a later host that happens to
|
|
102
|
+
* reuse the name inherits a stranger's numbers. That is worse than losing
|
|
103
|
+
* history, because the numbers look plausible.
|
|
104
|
+
*
|
|
105
|
+
* @param alias - the host alias.
|
|
106
|
+
* @returns true when something was removed.
|
|
107
|
+
*/
|
|
108
|
+
forget(alias: string): boolean;
|
|
109
|
+
/** Read one tier. */
|
|
110
|
+
readTier(alias: string, tier: Tier | Tier['name']): Array<Record<string, unknown>>;
|
|
111
|
+
/**
|
|
112
|
+
* Derive every coarse tier from the tier below and prune expired buckets.
|
|
113
|
+
*
|
|
114
|
+
* Idempotent: a bucket that already exists is replaced, not duplicated, so
|
|
115
|
+
* running this after every round converges instead of accumulating.
|
|
116
|
+
*/
|
|
117
|
+
rollUp(alias: string): void;
|
|
118
|
+
/**
|
|
119
|
+
* Aggregate a finer tier into a coarser one.
|
|
120
|
+
*
|
|
121
|
+
* Buckets are aligned to the width, so a bucket always covers the same
|
|
122
|
+
* wall-clock window regardless of when the round happened.
|
|
123
|
+
*/
|
|
124
|
+
private aggregate;
|
|
125
|
+
/** Drop buckets older than the tier's retention window. */
|
|
126
|
+
private prune;
|
|
127
|
+
/**
|
|
128
|
+
* Read a series for display.
|
|
129
|
+
*
|
|
130
|
+
* @param alias - the host.
|
|
131
|
+
* @param tier - which tier to read.
|
|
132
|
+
* @param metric - optional metric filter.
|
|
133
|
+
* @param limit - most recent N buckets (default 120).
|
|
134
|
+
* @returns the series, oldest first.
|
|
135
|
+
*/
|
|
136
|
+
series(alias: string, tier: Tier['name'], metric?: string, limit?: number): MetricBucket[];
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Extract numeric samples from one inspection round for one host.
|
|
140
|
+
*
|
|
141
|
+
* Only checks with a numeric kind become metrics: a boolean check ("sshd is
|
|
142
|
+
* running") has no meaningful average, and a text check has no series at all.
|
|
143
|
+
* The timestamp comes from the round, because a CheckResult carries no time
|
|
144
|
+
* of its own — every result in a round shares the round's start.
|
|
145
|
+
*
|
|
146
|
+
* @param at - the round's start, epoch milliseconds.
|
|
147
|
+
* @param results - the round's results for that host.
|
|
148
|
+
* @param kindOf - resolves a check id to its kind.
|
|
149
|
+
* @returns the numeric samples.
|
|
150
|
+
*/
|
|
151
|
+
export declare function samplesFromRound(at: number, results: readonly CheckResult[], kindOf: (checkId: string) => string | undefined): MetricSample[];
|