@octopi-agent/engine 0.86.38 → 0.97.15
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/dist/config-admin/agent-presets.d.ts +70 -0
- package/dist/config-admin/agent-presets.js +243 -0
- package/dist/config-admin/discover.d.ts +30 -0
- package/dist/config-admin/discover.js +48 -0
- package/dist/config-admin/env.d.ts +22 -0
- package/dist/config-admin/env.js +41 -0
- package/dist/config-admin/index.d.ts +20 -0
- package/dist/config-admin/index.js +15 -0
- package/dist/config-admin/model-presets.d.ts +75 -0
- package/dist/config-admin/model-presets.js +249 -0
- package/dist/config-admin/name-guard.d.ts +14 -0
- package/dist/config-admin/name-guard.js +24 -0
- package/dist/config-admin/patch.d.ts +56 -0
- package/dist/config-admin/patch.js +201 -0
- package/dist/config-admin/port.d.ts +68 -0
- package/dist/config-admin/port.js +21 -0
- package/dist/config-admin/redact.d.ts +39 -0
- package/dist/config-admin/redact.js +42 -0
- package/dist/config-schema/agent.d.ts +43 -1
- package/dist/config-schema/agent.js +12 -5
- package/dist/config-schema/context.d.ts +7 -2
- package/dist/config-schema/context.js +8 -0
- package/dist/config-schema/engine.d.ts +110 -8
- package/dist/config-schema/governance.d.ts +43 -1
- package/dist/config-schema/governance.js +160 -2
- package/dist/config-schema/models.d.ts +7 -4
- package/dist/config-schema/models.js +4 -1
- package/dist/config-schema/observability.d.ts +9 -0
- package/dist/config-schema/observability.js +29 -0
- package/dist/config-schema/run.d.ts +3 -0
- package/dist/config-schema/run.js +14 -0
- package/dist/config-schema/shared.d.ts +3 -0
- package/dist/config-schema/shared.js +12 -0
- package/dist/config-schema/substrate.d.ts +1 -1
- package/dist/config.d.ts +60 -13
- package/dist/config.js +81 -78
- package/dist/harness/activation/dispatcher.d.ts +8 -2
- package/dist/harness/activation/dispatcher.js +33 -5
- package/dist/harness/activation/inbox.d.ts +87 -0
- package/dist/harness/activation/inbox.js +169 -0
- package/dist/harness/activation/runtime.d.ts +9 -8
- package/dist/harness/activation/runtime.js +100 -8
- package/dist/harness/activation/types.d.ts +19 -0
- package/dist/harness/activation/types.js +2 -0
- package/dist/harness/agent/builder.d.ts +18 -3
- package/dist/harness/agent/builder.js +42 -17
- package/dist/harness/agent/config-bridge.d.ts +5 -0
- package/dist/harness/agent/config-bridge.js +7 -1
- package/dist/harness/agent/config-integrity.d.ts +72 -0
- package/dist/harness/agent/config-integrity.js +146 -0
- package/dist/harness/agent/tool-purpose.d.ts +9 -1
- package/dist/harness/agent/tool-purpose.js +11 -2
- package/dist/harness/agent/wire-agent-builder.js +11 -3
- package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.d.ts +11 -1
- package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +11 -1
- package/dist/harness/collaboration/autonomous-subsystem/loader.d.ts +13 -0
- package/dist/harness/collaboration/autonomous-subsystem/loader.js +16 -1
- package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -0
- package/dist/harness/collaboration/autonomous-subsystem/runtime.js +3 -1
- package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
- package/dist/harness/collaboration/delegation/child-run.js +21 -5
- package/dist/harness/collaboration/delegation/notifier.js +4 -3
- package/dist/harness/collaboration/delegation/service.js +2 -3
- package/dist/harness/collaboration/delegation/wiring.js +6 -5
- package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
- package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
- package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
- package/dist/harness/context/capabilities/compact/engine.js +198 -46
- package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
- package/dist/harness/context/capabilities/compact/handover.js +107 -0
- package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
- package/dist/harness/context/capabilities/compact/index.js +2 -1
- package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
- package/dist/harness/context/capabilities/summary/executor.js +2 -1
- package/dist/harness/context/capabilities/summary/policies.js +8 -5
- package/dist/harness/context/constitution/default-agents.md +11 -10
- package/dist/harness/context/default-context-engine.d.ts +34 -4
- package/dist/harness/context/default-context-engine.js +198 -53
- package/dist/harness/context/hybrid-compressor.js +6 -0
- package/dist/harness/context/layer-types.d.ts +36 -0
- package/dist/harness/context/layer-types.js +38 -0
- package/dist/harness/context/llm-summarizer.d.ts +2 -8
- package/dist/harness/context/llm-summarizer.js +69 -91
- package/dist/harness/context/message-selector.js +4 -3
- package/dist/harness/context/root-instructions.js +1 -1
- package/dist/harness/context/summarize.d.ts +2 -0
- package/dist/harness/context/summarize.js +7 -2
- package/dist/harness/context/system-prompt-assembler.js +10 -4
- package/dist/harness/context/tool-result-aging.js +2 -2
- package/dist/harness/context/truncate-compressor.js +7 -0
- package/dist/harness/context/turn-envelope.d.ts +4 -3
- package/dist/harness/context/turn-envelope.js +4 -3
- package/dist/harness/context/types.d.ts +33 -1
- package/dist/harness/extension/execution-environment/dangerous-commands.d.ts +28 -0
- package/dist/harness/extension/execution-environment/dangerous-commands.js +129 -0
- package/dist/harness/extension/execution-environment/effect-policy.d.ts +133 -4
- package/dist/harness/extension/execution-environment/effect-policy.js +263 -14
- package/dist/harness/extension/execution-environment/index.d.ts +4 -2
- package/dist/harness/extension/execution-environment/index.js +2 -1
- package/dist/harness/extension/execution-environment/isolation.js +5 -1
- package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
- package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
- package/dist/harness/extension/execution-environment/ops-audit.d.ts +200 -0
- package/dist/harness/extension/execution-environment/ops-audit.js +338 -0
- package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
- package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
- package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
- package/dist/harness/extension/execution-environment/process-info.js +466 -0
- package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
- package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
- package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
- package/dist/harness/extension/execution-environment/sandbox.js +264 -29
- package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
- package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
- package/dist/harness/extension/execution-environment/types.d.ts +19 -0
- package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
- package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +6 -0
- package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +50 -0
- package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +4 -5
- package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +5 -15
- package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +3 -0
- package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +53 -2
- package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +10 -17
- package/dist/harness/extension/plugin-ecosystem/tools/git-runner.d.ts +31 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-runner.js +104 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.d.ts +111 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.js +197 -0
- package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +8 -8
- package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +9 -100
- package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +6 -0
- package/dist/harness/extension/plugin-ecosystem/tools/index.js +4 -0
- package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
- package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
- package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
- package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
- package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
- package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
- package/dist/harness/governance/security/temp-path.d.ts +9 -0
- package/dist/harness/governance/security/temp-path.js +13 -2
- package/dist/harness/governance/session-acl/seed-roles.js +14 -0
- package/dist/harness/index.d.ts +4 -0
- package/dist/harness/index.js +3 -0
- package/dist/harness/knowledge/file-identity.d.ts +8 -0
- package/dist/harness/knowledge/file-identity.js +26 -1
- package/dist/harness/knowledge/fts.js +1 -2
- package/dist/harness/knowledge/grounding.js +5 -5
- package/dist/harness/knowledge/index-store.d.ts +31 -4
- package/dist/harness/knowledge/index-store.js +180 -48
- package/dist/harness/knowledge/ingest.d.ts +115 -115
- package/dist/harness/knowledge/ingest.js +150 -150
- package/dist/harness/knowledge/knowledge-serve-child.js +1 -1
- package/dist/harness/knowledge/purge.js +4 -1
- package/dist/harness/memory/backfill-coverage.js +3 -1
- package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
- package/dist/harness/memory/sqlite/keyword-search.js +4 -3
- package/dist/harness/observability/observer/hub.js +38 -1
- package/dist/harness/observability/observer/run-snapshot.js +1 -0
- package/dist/harness/observability/observer/types.d.ts +27 -0
- package/dist/harness/run/agent/agent.d.ts +7 -0
- package/dist/harness/run/agent/agent.js +23 -1
- package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
- package/dist/harness/run/reliability/fallback-provider.js +262 -22
- package/dist/harness/run/reliability/harness-events.d.ts +24 -1
- package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
- package/dist/harness/run/reliability/model-error-policy.js +42 -0
- package/dist/harness/run/reliability/provider-wrapper.js +29 -2
- package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
- package/dist/harness/run/reliability/refusal-guard.js +102 -0
- package/dist/harness/run/reliability/run-agent.js +231 -33
- package/dist/harness/run/run-guard/default-run-guard.js +1 -1
- package/dist/harness/run/run-scope.d.ts +31 -0
- package/dist/harness/run/runner.d.ts +132 -2
- package/dist/harness/run/runner.js +679 -60
- package/dist/harness/session/attachments/llm-intent.js +2 -1
- package/dist/harness/session/history/port.js +15 -5
- package/dist/harness/session/in-memory-store.d.ts +5 -0
- package/dist/harness/session/in-memory-store.js +33 -2
- package/dist/harness/session/tasks/render.d.ts +4 -1
- package/dist/harness/session/tasks/render.js +10 -7
- package/dist/harness/session/title.js +25 -9
- package/dist/harness/shared/events/agent-event-map.d.ts +92 -0
- package/dist/harness/shared/events/agent-event-map.js +7 -0
- package/dist/index.d.ts +6 -4
- package/dist/index.js +4 -3
- package/dist/integration/agent-runtime/channel-message-source.js +19 -1
- package/dist/integration/index.d.ts +2 -0
- package/dist/integration/index.js +1 -0
- package/dist/integration/observability/loop-watchdog.d.ts +56 -0
- package/dist/integration/observability/loop-watchdog.js +177 -0
- package/dist/integration/observability/metrics.d.ts +3 -0
- package/dist/integration/observability/metrics.js +18 -7
- package/dist/integration/observability/run-telemetry.d.ts +8 -0
- package/dist/integration/observability/run-telemetry.js +31 -8
- package/dist/integration/observability/trace-collector.js +26 -4
- package/dist/integration/observability/trace-events.d.ts +1 -0
- package/dist/integration/observability/trace-events.js +2 -0
- package/dist/integration/observability/trace-logger.js +27 -17
- package/dist/integration/providers/anthropic.d.ts +23 -0
- package/dist/integration/providers/anthropic.js +97 -12
- package/dist/integration/providers/fetch-timeout.d.ts +42 -0
- package/dist/integration/providers/fetch-timeout.js +51 -0
- package/dist/integration/providers/openai.d.ts +10 -0
- package/dist/integration/providers/openai.js +58 -11
- package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
- package/dist/integration/providers/provider-diagnostics.js +89 -0
- package/dist/integration/providers/timeout-coherence.d.ts +52 -0
- package/dist/integration/providers/timeout-coherence.js +68 -0
- package/dist/integration/providers/wire-dump.d.ts +62 -0
- package/dist/integration/providers/wire-dump.js +111 -2
- package/dist/integration/storage/jsonl.d.ts +19 -1
- package/dist/integration/storage/jsonl.js +100 -4
- package/dist/paths.d.ts +19 -0
- package/dist/paths.js +38 -1
- package/dist/subsystems/cognition-steward/conceptualize/handler.js +1 -1
- package/dist/subsystems/memory-steward/backfill/handler.js +1 -1
- package/dist/subsystems/safety-guard/config.yaml +3 -1
- package/dist/subsystems/wisdom-steward/formation/handler.js +1 -1
- package/package.json +3 -2
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 运维审计账本(ops P2,`arch/ops-privileged-mode.md` §5 P2 / §7)
|
|
3
|
+
*
|
|
4
|
+
* 提权(P3)的前置条件:碰过什么必须可查。本模块提供:
|
|
5
|
+
* - **hash 链 JSONL 账本**(`OpsAuditJournal`):追加即锚定前条 hash,事后可验证
|
|
6
|
+
* 改写/插入/中间截断(`verify()`);**尾部截断与整文件删除无法本地自证**——那需要
|
|
7
|
+
* 外部见证(P5 外送的计数/尾 hash 锚点)。这是 T0 档的「防篡改」上限(同 uid 进程
|
|
8
|
+
* 可写账本所在目录),真正不可抵赖靠 P5 外送,见规格原则 8。
|
|
9
|
+
* - **事件词表**:`ops.command.executed`(统一动作记录)/ `ops.system_path.write`
|
|
10
|
+
* (效应 root 之外的写入)/ `ops.policy.degraded` / `ops.config.security_changed`
|
|
11
|
+
* / `ops.jail.state`。
|
|
12
|
+
* - **`ToolFileEffects` 包装器**:文件效应写口集中拦截 roots 外写入(覆盖全部经
|
|
13
|
+
* fileEffects 的文件工具写口)。**shell 的 roots 外写入不在其内**:shell 账本只
|
|
14
|
+
* 清点 roots,任意命令的写盘面无法穷举追踪——`jail: none`(unconfined)命令以
|
|
15
|
+
* `jail.unconfined: true` 声明「写入未入账」;根因追踪属 P5/增强。
|
|
16
|
+
*
|
|
17
|
+
* 只追加不修改;写失败向上抛(调用方决定降级),绝不静默丢账。
|
|
18
|
+
*/
|
|
19
|
+
import type { ToolFileEffects } from '@octopi-agent/core/types/tools.js';
|
|
20
|
+
/** 审计事件词表(§7) */
|
|
21
|
+
export type OpsAuditEvent = 'ops.jail.state' | 'ops.command.executed' | 'ops.system_path.write' | 'ops.policy.degraded' | 'ops.config.security_changed' | 'ops.escalation.requested' | 'ops.escalation.denied' | 'ops.privileged.exec' | 'ops.kill_switch.tripped';
|
|
22
|
+
/** 账本条目(hash 链节点) */
|
|
23
|
+
export interface OpsAuditEntry {
|
|
24
|
+
/** 从 1 起单调递增 */
|
|
25
|
+
seq: number;
|
|
26
|
+
/** epoch ms */
|
|
27
|
+
ts: number;
|
|
28
|
+
event: OpsAuditEvent;
|
|
29
|
+
data: Record<string, unknown>;
|
|
30
|
+
/** 前一条 hash;首条为 `GENESIS_HASH` */
|
|
31
|
+
prevHash: string;
|
|
32
|
+
/** sha256(canonical({seq,ts,event,data,prevHash})) */
|
|
33
|
+
hash: string;
|
|
34
|
+
}
|
|
35
|
+
/** 链首哨兵 */
|
|
36
|
+
export declare const GENESIS_HASH: string;
|
|
37
|
+
/**
|
|
38
|
+
* 规范化 JSON(对象键排序)——hash 输入必须与键序无关。
|
|
39
|
+
*
|
|
40
|
+
* @param value - 任意 JSON 兼容值
|
|
41
|
+
* @returns 稳定序列化文本
|
|
42
|
+
*/
|
|
43
|
+
export declare function canonicalJson(value: unknown): string;
|
|
44
|
+
/**
|
|
45
|
+
* 计算账目 hash(链的唯一真相源)。
|
|
46
|
+
*
|
|
47
|
+
* @param entry - 不含 hash 的条目字段
|
|
48
|
+
* @returns sha256 十六进制
|
|
49
|
+
*/
|
|
50
|
+
export declare function computeOpsAuditEntryHash(entry: Omit<OpsAuditEntry, 'hash'>): string;
|
|
51
|
+
/**
|
|
52
|
+
* 验证一段链(整文件或任意连续片段)。
|
|
53
|
+
*
|
|
54
|
+
* @param entries - 按 seq 升序的条目
|
|
55
|
+
* @returns ok 或首个断裂点
|
|
56
|
+
*/
|
|
57
|
+
export declare function verifyOpsAuditChain(entries: readonly OpsAuditEntry[]): {
|
|
58
|
+
ok: true;
|
|
59
|
+
entries: number;
|
|
60
|
+
} | {
|
|
61
|
+
ok: false;
|
|
62
|
+
entries: number;
|
|
63
|
+
brokenAtSeq: number;
|
|
64
|
+
reason: string;
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* 读回账本全文(供验证/查询)。
|
|
68
|
+
*
|
|
69
|
+
* **只有 ENOENT 是合法空账**(尚未建账);其余读失败抛 `ops_audit_unreadable`、
|
|
70
|
+
* 坏行抛 `ops_audit_corrupt`——把读失败当空账会静默重链并把账本写坏(评审实证)。
|
|
71
|
+
*
|
|
72
|
+
* @param path - 账本文件路径
|
|
73
|
+
* @returns 条目(按写入序);文件不存在返回空数组
|
|
74
|
+
* @throws `ops_audit_unreadable` / `ops_audit_corrupt`
|
|
75
|
+
*/
|
|
76
|
+
export declare function readOpsAuditEntries(path: string): OpsAuditEntry[];
|
|
77
|
+
/** 账本追加结果 */
|
|
78
|
+
export interface OpsAuditAppendResult {
|
|
79
|
+
entry: OpsAuditEntry;
|
|
80
|
+
/** tail 衔接被验证过(追加即轻校验) */
|
|
81
|
+
tailVerified: boolean;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* 运维审计账本(append-only JSONL + hash 链)。
|
|
85
|
+
*
|
|
86
|
+
* 追加为同步写(`appendFileSync`):审计语义优先于吞吐,且顺序天然确定。
|
|
87
|
+
* 启动/首次追加时回读尾条衔接 `seq/prevHash`;尾部不可解析 → 抛
|
|
88
|
+
* `ops_audit_corrupt`(**拒绝续链**——静默重链会把篡改洗成新链)。
|
|
89
|
+
*/
|
|
90
|
+
export declare class OpsAuditJournal {
|
|
91
|
+
private readonly path;
|
|
92
|
+
private tail;
|
|
93
|
+
/**
|
|
94
|
+
* @param options - `path` 为账本 JSONL 绝对路径
|
|
95
|
+
*/
|
|
96
|
+
constructor(options: {
|
|
97
|
+
path: string;
|
|
98
|
+
});
|
|
99
|
+
/** 账本路径(诊断/测试用) */
|
|
100
|
+
get filePath(): string;
|
|
101
|
+
private bootstrapTail;
|
|
102
|
+
/**
|
|
103
|
+
* 追加一条账目。
|
|
104
|
+
*
|
|
105
|
+
* @param event - 事件名(§7 词表)
|
|
106
|
+
* @param data - 事件载荷(键序无关,hash 走 canonicalJson)
|
|
107
|
+
* @returns 落盘的账目
|
|
108
|
+
*/
|
|
109
|
+
append(event: OpsAuditEvent, data: Record<string, unknown>): OpsAuditEntry;
|
|
110
|
+
/**
|
|
111
|
+
* 全链验证(追加只验尾;中段篡改靠本方法)。
|
|
112
|
+
*
|
|
113
|
+
* @returns ok 或首个断裂点
|
|
114
|
+
*/
|
|
115
|
+
verify(): ReturnType<typeof verifyOpsAuditChain>;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* 工具上下文回传的事件输入(core 契约 shape)
|
|
119
|
+
*/
|
|
120
|
+
export interface OpsEventInput {
|
|
121
|
+
event: OpsAuditEvent;
|
|
122
|
+
data: Record<string, unknown>;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* 审计外送信封(P5 唯一不可抵赖档,原则 8)。
|
|
126
|
+
*
|
|
127
|
+
* 本地账本的 hash 链防「改写/插入」,但**尾部截断与整文件删除本地无法自证**——
|
|
128
|
+
* 那需要外部见证。外送档把每条账目(连同链证据)推到宿主可达的收口
|
|
129
|
+
* (宿主侧文件 / HTTP),宿主按 `count`(= 账本 seq)查缺、用 `entry` 原样重验链:
|
|
130
|
+
*
|
|
131
|
+
* - `count`:单调递增账目序号——外送流缺号 = 丢账可查;
|
|
132
|
+
* - `tailHash`:本条落链后的尾锚点——与宿主已收最后一条对得上才叫连续;
|
|
133
|
+
* - `entry`:账目原样(含 `prevHash`/`hash`,`verifyOpsAuditChain` 可直接重放)。
|
|
134
|
+
*/
|
|
135
|
+
export interface OpsAuditExportEnvelope {
|
|
136
|
+
count: number;
|
|
137
|
+
tailHash: string;
|
|
138
|
+
entry: OpsAuditEntry;
|
|
139
|
+
/** 外送时刻(epoch ms;账目 `ts` 是发生时刻,两者都留) */
|
|
140
|
+
forwardedAt: number;
|
|
141
|
+
}
|
|
142
|
+
/** 外送收口(append-only) */
|
|
143
|
+
export interface OpsAuditExportSink {
|
|
144
|
+
forward(envelope: OpsAuditExportEnvelope): void;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* 文件外送收口:宿主侧 append-only JSONL(每行一个信封)。
|
|
148
|
+
*
|
|
149
|
+
* 路径应放在 **agent 可写面之外**(`~/.octopi` 在 host 模式的可写面内——放那里
|
|
150
|
+
* 等于没外送)。写失败向上抛,由调用方降级申报,绝不静默丢外送。
|
|
151
|
+
*/
|
|
152
|
+
export declare class OpsAuditFileExportSink implements OpsAuditExportSink {
|
|
153
|
+
private readonly path;
|
|
154
|
+
/**
|
|
155
|
+
* @param options.path - 外送文件绝对路径(宿主侧,agent 不可写)
|
|
156
|
+
*/
|
|
157
|
+
constructor(options: {
|
|
158
|
+
path: string;
|
|
159
|
+
});
|
|
160
|
+
/** 外送文件路径(诊断用) */
|
|
161
|
+
get filePath(): string;
|
|
162
|
+
/** @inheritdoc */
|
|
163
|
+
forward(envelope: OpsAuditExportEnvelope): void;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* `ToolFileEffects` 装饰器:效应 root 之外的写入统一入 `ops.system_path.write`。
|
|
167
|
+
*
|
|
168
|
+
* 单点覆盖全部文件工具与 shell 账本(它们都经 `fileEffects` 写口),不逐工具打补丁。
|
|
169
|
+
* 记账失败不影响业务写(与 §5.6 记账同策略),但会抛给调用方的降级通道。
|
|
170
|
+
*/
|
|
171
|
+
export declare class OpsAuditedFileEffects implements ToolFileEffects {
|
|
172
|
+
private readonly inner;
|
|
173
|
+
private readonly roots;
|
|
174
|
+
private readonly record;
|
|
175
|
+
/**
|
|
176
|
+
* @param inner - 被装饰的真实效应 journal
|
|
177
|
+
* @param options.roots - 效应 root(root 内写入不记 system_path 账)
|
|
178
|
+
* @param options.record - 账目回传(通常进 OpsAuditJournal)
|
|
179
|
+
*/
|
|
180
|
+
constructor(inner: ToolFileEffects, options: {
|
|
181
|
+
roots: readonly string[];
|
|
182
|
+
record: (event: OpsAuditEvent, data: Record<string, unknown>) => void;
|
|
183
|
+
});
|
|
184
|
+
private underRoots;
|
|
185
|
+
private noteWrite;
|
|
186
|
+
/** @inheritdoc */
|
|
187
|
+
writeFile(path: string, data: string | Uint8Array): Promise<void>;
|
|
188
|
+
/** @inheritdoc */
|
|
189
|
+
appendFile(path: string, data: string | Uint8Array): Promise<void>;
|
|
190
|
+
/** @inheritdoc */
|
|
191
|
+
recordDelete(path: string, before: string | Uint8Array): Promise<void>;
|
|
192
|
+
/** @inheritdoc */
|
|
193
|
+
recordCreate(path: string, after?: string | Uint8Array): Promise<void>;
|
|
194
|
+
/** @inheritdoc */
|
|
195
|
+
recordRename(from: string, to: string): Promise<void>;
|
|
196
|
+
/** @inheritdoc */
|
|
197
|
+
recordOverwrite(path: string, before: string | Uint8Array, after?: string | Uint8Array): Promise<void>;
|
|
198
|
+
/** @inheritdoc */
|
|
199
|
+
noteNotReversed(payload: Parameters<ToolFileEffects['noteNotReversed']>[0]): Promise<void>;
|
|
200
|
+
}
|
|
@@ -0,0 +1,338 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 运维审计账本(ops P2,`arch/ops-privileged-mode.md` §5 P2 / §7)
|
|
3
|
+
*
|
|
4
|
+
* 提权(P3)的前置条件:碰过什么必须可查。本模块提供:
|
|
5
|
+
* - **hash 链 JSONL 账本**(`OpsAuditJournal`):追加即锚定前条 hash,事后可验证
|
|
6
|
+
* 改写/插入/中间截断(`verify()`);**尾部截断与整文件删除无法本地自证**——那需要
|
|
7
|
+
* 外部见证(P5 外送的计数/尾 hash 锚点)。这是 T0 档的「防篡改」上限(同 uid 进程
|
|
8
|
+
* 可写账本所在目录),真正不可抵赖靠 P5 外送,见规格原则 8。
|
|
9
|
+
* - **事件词表**:`ops.command.executed`(统一动作记录)/ `ops.system_path.write`
|
|
10
|
+
* (效应 root 之外的写入)/ `ops.policy.degraded` / `ops.config.security_changed`
|
|
11
|
+
* / `ops.jail.state`。
|
|
12
|
+
* - **`ToolFileEffects` 包装器**:文件效应写口集中拦截 roots 外写入(覆盖全部经
|
|
13
|
+
* fileEffects 的文件工具写口)。**shell 的 roots 外写入不在其内**:shell 账本只
|
|
14
|
+
* 清点 roots,任意命令的写盘面无法穷举追踪——`jail: none`(unconfined)命令以
|
|
15
|
+
* `jail.unconfined: true` 声明「写入未入账」;根因追踪属 P5/增强。
|
|
16
|
+
*
|
|
17
|
+
* 只追加不修改;写失败向上抛(调用方决定降级),绝不静默丢账。
|
|
18
|
+
*/
|
|
19
|
+
import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync } from 'node:fs';
|
|
20
|
+
import { createHash } from 'node:crypto';
|
|
21
|
+
import { dirname, resolve, sep } from 'node:path';
|
|
22
|
+
/** 链首哨兵 */
|
|
23
|
+
export const GENESIS_HASH = '0'.repeat(64);
|
|
24
|
+
/**
|
|
25
|
+
* 规范化 JSON(对象键排序)——hash 输入必须与键序无关。
|
|
26
|
+
*
|
|
27
|
+
* @param value - 任意 JSON 兼容值
|
|
28
|
+
* @returns 稳定序列化文本
|
|
29
|
+
*/
|
|
30
|
+
export function canonicalJson(value) {
|
|
31
|
+
if (value === null || typeof value !== 'object')
|
|
32
|
+
return JSON.stringify(value) ?? 'null';
|
|
33
|
+
if (Array.isArray(value))
|
|
34
|
+
return `[${value.map((v) => canonicalJson(v)).join(',')}]`;
|
|
35
|
+
const entries = Object.entries(value)
|
|
36
|
+
.filter(([, v]) => v !== undefined)
|
|
37
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
38
|
+
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* 计算账目 hash(链的唯一真相源)。
|
|
42
|
+
*
|
|
43
|
+
* @param entry - 不含 hash 的条目字段
|
|
44
|
+
* @returns sha256 十六进制
|
|
45
|
+
*/
|
|
46
|
+
export function computeOpsAuditEntryHash(entry) {
|
|
47
|
+
return createHash('sha256').update(canonicalJson(entry)).digest('hex');
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* 验证一段链(整文件或任意连续片段)。
|
|
51
|
+
*
|
|
52
|
+
* @param entries - 按 seq 升序的条目
|
|
53
|
+
* @returns ok 或首个断裂点
|
|
54
|
+
*/
|
|
55
|
+
export function verifyOpsAuditChain(entries) {
|
|
56
|
+
let prevHash = GENESIS_HASH;
|
|
57
|
+
let prevSeq = 0;
|
|
58
|
+
const allowedKeys = ['data', 'event', 'hash', 'prevHash', 'seq', 'ts'];
|
|
59
|
+
for (const entry of entries) {
|
|
60
|
+
// 附加字段不受 hash 保护——读取方不得信任;有即判断裂(防「加字段伪造」)
|
|
61
|
+
const keys = Object.keys(entry).sort();
|
|
62
|
+
if (keys.join(',') !== allowedKeys.join(',')) {
|
|
63
|
+
return { ok: false, entries: entries.length, brokenAtSeq: entry.seq, reason: 'extra_fields' };
|
|
64
|
+
}
|
|
65
|
+
if (entry.seq !== prevSeq + 1) {
|
|
66
|
+
return { ok: false, entries: entries.length, brokenAtSeq: entry.seq, reason: 'seq_gap' };
|
|
67
|
+
}
|
|
68
|
+
if (entry.prevHash !== prevHash) {
|
|
69
|
+
return { ok: false, entries: entries.length, brokenAtSeq: entry.seq, reason: 'prev_hash_mismatch' };
|
|
70
|
+
}
|
|
71
|
+
const expected = computeOpsAuditEntryHash({
|
|
72
|
+
seq: entry.seq,
|
|
73
|
+
ts: entry.ts,
|
|
74
|
+
event: entry.event,
|
|
75
|
+
data: entry.data,
|
|
76
|
+
prevHash: entry.prevHash,
|
|
77
|
+
});
|
|
78
|
+
if (expected !== entry.hash) {
|
|
79
|
+
return { ok: false, entries: entries.length, brokenAtSeq: entry.seq, reason: 'hash_mismatch' };
|
|
80
|
+
}
|
|
81
|
+
prevHash = entry.hash;
|
|
82
|
+
prevSeq = entry.seq;
|
|
83
|
+
}
|
|
84
|
+
return { ok: true, entries: entries.length };
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* 读回账本全文(供验证/查询)。
|
|
88
|
+
*
|
|
89
|
+
* **只有 ENOENT 是合法空账**(尚未建账);其余读失败抛 `ops_audit_unreadable`、
|
|
90
|
+
* 坏行抛 `ops_audit_corrupt`——把读失败当空账会静默重链并把账本写坏(评审实证)。
|
|
91
|
+
*
|
|
92
|
+
* @param path - 账本文件路径
|
|
93
|
+
* @returns 条目(按写入序);文件不存在返回空数组
|
|
94
|
+
* @throws `ops_audit_unreadable` / `ops_audit_corrupt`
|
|
95
|
+
*/
|
|
96
|
+
export function readOpsAuditEntries(path) {
|
|
97
|
+
let body;
|
|
98
|
+
try {
|
|
99
|
+
body = readFileSync(path, 'utf8');
|
|
100
|
+
}
|
|
101
|
+
catch (err) {
|
|
102
|
+
if (err?.code === 'ENOENT')
|
|
103
|
+
return [];
|
|
104
|
+
throw new Error(`ops_audit_unreadable: cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
|
|
105
|
+
}
|
|
106
|
+
const entries = [];
|
|
107
|
+
let lineNo = 0;
|
|
108
|
+
for (const line of body.split('\n')) {
|
|
109
|
+
lineNo += 1;
|
|
110
|
+
if (line.trim() === '')
|
|
111
|
+
continue;
|
|
112
|
+
try {
|
|
113
|
+
entries.push(JSON.parse(line));
|
|
114
|
+
}
|
|
115
|
+
catch {
|
|
116
|
+
// 半行(崩溃/写断电)或外部损坏:拒绝当正常读,绝不静默跳行
|
|
117
|
+
throw new Error(`ops_audit_corrupt: unparseable line ${lineNo} in ${path}`);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
return entries;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* 运维审计账本(append-only JSONL + hash 链)。
|
|
124
|
+
*
|
|
125
|
+
* 追加为同步写(`appendFileSync`):审计语义优先于吞吐,且顺序天然确定。
|
|
126
|
+
* 启动/首次追加时回读尾条衔接 `seq/prevHash`;尾部不可解析 → 抛
|
|
127
|
+
* `ops_audit_corrupt`(**拒绝续链**——静默重链会把篡改洗成新链)。
|
|
128
|
+
*/
|
|
129
|
+
export class OpsAuditJournal {
|
|
130
|
+
path;
|
|
131
|
+
tail;
|
|
132
|
+
/**
|
|
133
|
+
* @param options - `path` 为账本 JSONL 绝对路径
|
|
134
|
+
*/
|
|
135
|
+
constructor(options) {
|
|
136
|
+
this.path = options.path;
|
|
137
|
+
}
|
|
138
|
+
/** 账本路径(诊断/测试用) */
|
|
139
|
+
get filePath() {
|
|
140
|
+
return this.path;
|
|
141
|
+
}
|
|
142
|
+
bootstrapTail() {
|
|
143
|
+
if (this.tail)
|
|
144
|
+
return this.tail;
|
|
145
|
+
let entries;
|
|
146
|
+
try {
|
|
147
|
+
entries = readOpsAuditEntries(this.path);
|
|
148
|
+
}
|
|
149
|
+
catch (err) {
|
|
150
|
+
// 读失败/坏行一律拒绝续链(静默重链会把篡改洗成新链);附上类型码
|
|
151
|
+
throw err instanceof Error && err.message.startsWith('ops_audit_')
|
|
152
|
+
? err
|
|
153
|
+
: new Error(`ops_audit_corrupt: ${err instanceof Error ? err.message : String(err)}`);
|
|
154
|
+
}
|
|
155
|
+
const last = entries.at(-1);
|
|
156
|
+
if (!last) {
|
|
157
|
+
this.tail = { seq: 0, hash: GENESIS_HASH };
|
|
158
|
+
return this.tail;
|
|
159
|
+
}
|
|
160
|
+
// 尾条必须能自证:hash 对不上 = 文件被动过,拒绝把新账接上去
|
|
161
|
+
const expected = computeOpsAuditEntryHash({
|
|
162
|
+
seq: last.seq,
|
|
163
|
+
ts: last.ts,
|
|
164
|
+
event: last.event,
|
|
165
|
+
data: last.data,
|
|
166
|
+
prevHash: last.prevHash,
|
|
167
|
+
});
|
|
168
|
+
if (expected !== last.hash) {
|
|
169
|
+
throw new Error(`ops_audit_corrupt: tail entry hash mismatch at seq ${last.seq} (${this.path})`);
|
|
170
|
+
}
|
|
171
|
+
this.tail = { seq: last.seq, hash: last.hash };
|
|
172
|
+
return this.tail;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* 追加一条账目。
|
|
176
|
+
*
|
|
177
|
+
* @param event - 事件名(§7 词表)
|
|
178
|
+
* @param data - 事件载荷(键序无关,hash 走 canonicalJson)
|
|
179
|
+
* @returns 落盘的账目
|
|
180
|
+
*/
|
|
181
|
+
append(event, data) {
|
|
182
|
+
const tail = this.bootstrapTail();
|
|
183
|
+
// 载荷先 JSON 归一:hash 口径必须与落盘字节一致(Date 等对象若不归一,
|
|
184
|
+
// verify 会对未篡改的账报 hash_mismatch——评审实证的假告警)
|
|
185
|
+
const normalized = JSON.parse(JSON.stringify(data));
|
|
186
|
+
const body = {
|
|
187
|
+
seq: tail.seq + 1,
|
|
188
|
+
ts: Date.now(),
|
|
189
|
+
event,
|
|
190
|
+
data: normalized,
|
|
191
|
+
prevHash: tail.hash,
|
|
192
|
+
};
|
|
193
|
+
const entry = { ...body, hash: computeOpsAuditEntryHash(body) };
|
|
194
|
+
mkdirSync(dirname(this.path), { recursive: true });
|
|
195
|
+
// 耐久写(fsync):一次崩溃/磁盘满留半行会让账本拒绝续链(fail-loud),
|
|
196
|
+
// 但那是人工修复成本——先把半行概率压到最低
|
|
197
|
+
const fd = openSync(this.path, 'a');
|
|
198
|
+
try {
|
|
199
|
+
writeSync(fd, `${JSON.stringify(entry)}\n`);
|
|
200
|
+
fsyncSync(fd);
|
|
201
|
+
}
|
|
202
|
+
finally {
|
|
203
|
+
closeSync(fd);
|
|
204
|
+
}
|
|
205
|
+
this.tail = { seq: entry.seq, hash: entry.hash };
|
|
206
|
+
return entry;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* 全链验证(追加只验尾;中段篡改靠本方法)。
|
|
210
|
+
*
|
|
211
|
+
* @returns ok 或首个断裂点
|
|
212
|
+
*/
|
|
213
|
+
verify() {
|
|
214
|
+
// 读不到/坏行也是「验不过」的一种——返回结论而不是把异常抛给调用方
|
|
215
|
+
let entries;
|
|
216
|
+
try {
|
|
217
|
+
entries = readOpsAuditEntries(this.path);
|
|
218
|
+
}
|
|
219
|
+
catch (err) {
|
|
220
|
+
return {
|
|
221
|
+
ok: false,
|
|
222
|
+
entries: 0,
|
|
223
|
+
brokenAtSeq: -1,
|
|
224
|
+
reason: err instanceof Error ? err.message : String(err),
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
return verifyOpsAuditChain(entries);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* 文件外送收口:宿主侧 append-only JSONL(每行一个信封)。
|
|
232
|
+
*
|
|
233
|
+
* 路径应放在 **agent 可写面之外**(`~/.octopi` 在 host 模式的可写面内——放那里
|
|
234
|
+
* 等于没外送)。写失败向上抛,由调用方降级申报,绝不静默丢外送。
|
|
235
|
+
*/
|
|
236
|
+
export class OpsAuditFileExportSink {
|
|
237
|
+
path;
|
|
238
|
+
/**
|
|
239
|
+
* @param options.path - 外送文件绝对路径(宿主侧,agent 不可写)
|
|
240
|
+
*/
|
|
241
|
+
constructor(options) {
|
|
242
|
+
this.path = options.path;
|
|
243
|
+
}
|
|
244
|
+
/** 外送文件路径(诊断用) */
|
|
245
|
+
get filePath() {
|
|
246
|
+
return this.path;
|
|
247
|
+
}
|
|
248
|
+
/** @inheritdoc */
|
|
249
|
+
forward(envelope) {
|
|
250
|
+
mkdirSync(dirname(this.path), { recursive: true });
|
|
251
|
+
const fd = openSync(this.path, 'a');
|
|
252
|
+
try {
|
|
253
|
+
writeSync(fd, `${JSON.stringify(envelope)}\n`);
|
|
254
|
+
fsyncSync(fd);
|
|
255
|
+
}
|
|
256
|
+
finally {
|
|
257
|
+
closeSync(fd);
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
/**
|
|
262
|
+
* `ToolFileEffects` 装饰器:效应 root 之外的写入统一入 `ops.system_path.write`。
|
|
263
|
+
*
|
|
264
|
+
* 单点覆盖全部文件工具与 shell 账本(它们都经 `fileEffects` 写口),不逐工具打补丁。
|
|
265
|
+
* 记账失败不影响业务写(与 §5.6 记账同策略),但会抛给调用方的降级通道。
|
|
266
|
+
*/
|
|
267
|
+
export class OpsAuditedFileEffects {
|
|
268
|
+
inner;
|
|
269
|
+
roots;
|
|
270
|
+
record;
|
|
271
|
+
/**
|
|
272
|
+
* @param inner - 被装饰的真实效应 journal
|
|
273
|
+
* @param options.roots - 效应 root(root 内写入不记 system_path 账)
|
|
274
|
+
* @param options.record - 账目回传(通常进 OpsAuditJournal)
|
|
275
|
+
*/
|
|
276
|
+
constructor(inner, options) {
|
|
277
|
+
this.inner = inner;
|
|
278
|
+
this.roots = options.roots;
|
|
279
|
+
this.record = options.record;
|
|
280
|
+
}
|
|
281
|
+
underRoots(path) {
|
|
282
|
+
// resolve + sep 感知;win32 大小写不敏感卷按 toLowerCase 口径(对齐 isPathAllowed)
|
|
283
|
+
const norm = (p) => process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p);
|
|
284
|
+
const target = norm(path);
|
|
285
|
+
return this.roots.some((root) => {
|
|
286
|
+
const base = norm(root);
|
|
287
|
+
return target === base || target.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
|
|
288
|
+
});
|
|
289
|
+
}
|
|
290
|
+
noteWrite(op, path, fromPath) {
|
|
291
|
+
// 经 fileEffects 写口的写入本身是 undo 账在管(before/after 都在 TurnFileUndoLog,
|
|
292
|
+
// 含 root 外路径)——本账目只是「越权写告警」的可见层,不虚报可逆性
|
|
293
|
+
const outside = [path, fromPath].filter((p) => p !== undefined && !this.underRoots(p));
|
|
294
|
+
if (outside.length === 0)
|
|
295
|
+
return;
|
|
296
|
+
this.record('ops.system_path.write', {
|
|
297
|
+
op,
|
|
298
|
+
path,
|
|
299
|
+
...(fromPath !== undefined ? { fromPath } : {}),
|
|
300
|
+
outsideRoots: outside,
|
|
301
|
+
});
|
|
302
|
+
}
|
|
303
|
+
/** @inheritdoc */
|
|
304
|
+
async writeFile(path, data) {
|
|
305
|
+
await this.inner.writeFile(path, data);
|
|
306
|
+
this.noteWrite('writeFile', path);
|
|
307
|
+
}
|
|
308
|
+
/** @inheritdoc */
|
|
309
|
+
async appendFile(path, data) {
|
|
310
|
+
await this.inner.appendFile(path, data);
|
|
311
|
+
this.noteWrite('appendFile', path);
|
|
312
|
+
}
|
|
313
|
+
/** @inheritdoc */
|
|
314
|
+
async recordDelete(path, before) {
|
|
315
|
+
await this.inner.recordDelete(path, before);
|
|
316
|
+
this.noteWrite('recordDelete', path);
|
|
317
|
+
}
|
|
318
|
+
/** @inheritdoc */
|
|
319
|
+
async recordCreate(path, after) {
|
|
320
|
+
await this.inner.recordCreate(path, after);
|
|
321
|
+
this.noteWrite('recordCreate', path);
|
|
322
|
+
}
|
|
323
|
+
/** @inheritdoc */
|
|
324
|
+
async recordRename(from, to) {
|
|
325
|
+
await this.inner.recordRename(from, to);
|
|
326
|
+
// mv 进 root = root 外文件消失:from 端也要入账
|
|
327
|
+
this.noteWrite('recordRename', to, from);
|
|
328
|
+
}
|
|
329
|
+
/** @inheritdoc */
|
|
330
|
+
async recordOverwrite(path, before, after) {
|
|
331
|
+
await this.inner.recordOverwrite(path, before, after);
|
|
332
|
+
this.noteWrite('recordOverwrite', path);
|
|
333
|
+
}
|
|
334
|
+
/** @inheritdoc */
|
|
335
|
+
async noteNotReversed(payload) {
|
|
336
|
+
await this.inner.noteNotReversed(payload);
|
|
337
|
+
}
|
|
338
|
+
}
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 独立提权执行通道(ops P3,`arch/ops-privileged-mode.md` §5 P3 / §8)
|
|
3
|
+
*
|
|
4
|
+
* 设计要点(拍板 + 评审修复):
|
|
5
|
+
* - **提权走独立通道,不与牢笼抢轴**:引擎侧 `execFile` 执行完整 argv——不经 shell
|
|
6
|
+
* (无插值/无通配)、不包 jail、env 消毒、cwd 钉住(规则显式或 `/`,**不受 agent
|
|
7
|
+
* 控制**)、超时 + 真树杀(detached 进程组)。
|
|
8
|
+
* - **全等匹配**(effect-policy `matchEscalationRule`):`cmd` 绝对路径 + `args` 逐项
|
|
9
|
+
* 全等;执行即所配 argv,无任何隐式前缀。
|
|
10
|
+
* - **二进制不可换(TOCTOU 护栏)**:对规则的**每一个有效目标**(`via: sudo` 形态下是
|
|
11
|
+
* sudo 之后的真实二进制,不只是 `cmd`)检查:不在 agent 可写面(含符号链接解析后)、
|
|
12
|
+
* 文件与父目录链均不可被 agent uid / 组 / 世界写(可写目录 + rename 即可换二进制)。
|
|
13
|
+
* - **启动期探测,拿不到即拒绝启动**(拍板 #5):`via: sudo` 跑 `sudo -n true`(绝对
|
|
14
|
+
* 路径);`via: direct` 断言高权限(geteuid 0 / win32 `fsutil dirty query`)。
|
|
15
|
+
* 探测证明「通道可用」,不证明「每条规则被 sudoers 授权」(文档如实声明)。
|
|
16
|
+
*/
|
|
17
|
+
/** 白名单提权规则(§4) */
|
|
18
|
+
export interface EscalationRule {
|
|
19
|
+
/** 稳定规则标识(审计关联);缺省 `allow[<下标>]`(重排会断裂——显式 id 更好) */
|
|
20
|
+
id?: string;
|
|
21
|
+
/** 绝对路径(拒绝相对路径:PATH 解析 = 可换二进制) */
|
|
22
|
+
cmd: string;
|
|
23
|
+
/** 逐项全等的 argv 尾部;`via: sudo` 形态必须以 `-n` 开头 + 真实目标绝对路径 */
|
|
24
|
+
args?: string[];
|
|
25
|
+
/** true → 执行前走 HitlDecision 确认闸(缓存 key 含完整 argv) */
|
|
26
|
+
confirm?: boolean;
|
|
27
|
+
/** 提权进程的工作目录(绝对路径);缺省 `/`——绝不取 agent 的 cwd */
|
|
28
|
+
cwd?: string;
|
|
29
|
+
}
|
|
30
|
+
/** 提权策略(resolved) */
|
|
31
|
+
export interface EscalationPolicy {
|
|
32
|
+
/**
|
|
33
|
+
* `none`(缺省)| `allowlist`(cmd+args 全等)| `full`(全量档,P4)。
|
|
34
|
+
* `full` 仅在 `jail: "none"` + `privilegedAck` + `mode: "host"` 下合法(§4.1)。
|
|
35
|
+
*/
|
|
36
|
+
policy: 'none' | 'allowlist' | 'full';
|
|
37
|
+
via: 'sudo' | 'direct';
|
|
38
|
+
allow: EscalationRule[];
|
|
39
|
+
}
|
|
40
|
+
/** 提权执行输入 */
|
|
41
|
+
export interface PrivilegedExecOptions {
|
|
42
|
+
/** 已通过全等匹配的 cmd(绝对路径) */
|
|
43
|
+
cmd: string;
|
|
44
|
+
args: string[];
|
|
45
|
+
via: 'sudo' | 'direct';
|
|
46
|
+
/** 特权进程 cwd(缺省 `/`;规则可显式指定) */
|
|
47
|
+
cwd?: string;
|
|
48
|
+
timeoutMs?: number;
|
|
49
|
+
/** run 中止信号:触发即时树杀(与超时同一收回路径,不等 timeoutMs 兜底) */
|
|
50
|
+
abortSignal?: AbortSignal;
|
|
51
|
+
}
|
|
52
|
+
/** 提权执行结果 */
|
|
53
|
+
export interface PrivilegedExecResult {
|
|
54
|
+
/** false = 进程从未成功 spawn(区别于「执行了但非零退出」) */
|
|
55
|
+
executed: boolean;
|
|
56
|
+
exitCode: number | null;
|
|
57
|
+
stdout: string;
|
|
58
|
+
stderr: string;
|
|
59
|
+
durationMs: number;
|
|
60
|
+
timedOut: boolean;
|
|
61
|
+
/** run 中止即时树杀所致(区别于 timedOut:外部中止,不是命令超时) */
|
|
62
|
+
aborted?: boolean;
|
|
63
|
+
}
|
|
64
|
+
/** 启动探测结论 */
|
|
65
|
+
export type EscalationReadiness = {
|
|
66
|
+
ok: true;
|
|
67
|
+
} | {
|
|
68
|
+
ok: false;
|
|
69
|
+
reason: string;
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* 执行一条已匹配的提权命令(不经 shell、不包 jail、cwd 钉住)。
|
|
73
|
+
*
|
|
74
|
+
* @param options - cmd/args(完整 argv)、via、cwd、timeoutMs
|
|
75
|
+
* @returns 执行结果(spawn 从未成功时 executed=false)
|
|
76
|
+
*/
|
|
77
|
+
export declare function runPrivilegedExec(options: PrivilegedExecOptions): Promise<PrivilegedExecResult>;
|
|
78
|
+
/**
|
|
79
|
+
* 列出规则的**有效提权目标**(TOCTOU 护栏逐个检查的对象)。
|
|
80
|
+
*
|
|
81
|
+
* `via: sudo` 形态的真正目标是 sudo 之后的二进制(`args[1]`)——只查 `cmd` 等于不查。
|
|
82
|
+
*
|
|
83
|
+
* @param rule - 白名单规则
|
|
84
|
+
* @param via - 通道形态
|
|
85
|
+
* @returns 目标路径列表;形态非法时 `invalid` 给出原因
|
|
86
|
+
*/
|
|
87
|
+
export declare function escalationRuleTargets(rule: EscalationRule, via: 'sudo' | 'direct'): {
|
|
88
|
+
targets: string[];
|
|
89
|
+
} | {
|
|
90
|
+
invalid: string;
|
|
91
|
+
};
|
|
92
|
+
/**
|
|
93
|
+
* TOCTOU 护栏:目标二进制不可被换(agent 可写面 / 文件或父目录可写 → 拒绝)。
|
|
94
|
+
*
|
|
95
|
+
* 检查口径(评审修复):
|
|
96
|
+
* - 路径与其 `realpath` 都做可写面判定(符号链接穿透);
|
|
97
|
+
* - 文件本体 **与父目录链**都不可写(可写目录 + rename 即可替换 0555 文件);
|
|
98
|
+
* - 目标不存在(可后装)时仅当父目录链安全才放行。
|
|
99
|
+
*
|
|
100
|
+
* @param target - 目标二进制绝对路径
|
|
101
|
+
* @param writableRoots - agent 可写根(workspace/home/tmp/transactionRoots/…)
|
|
102
|
+
* @returns 违规原因;通过返回 null
|
|
103
|
+
*/
|
|
104
|
+
export declare function checkEscalationBinary(target: string, writableRoots: readonly string[]): string | null;
|
|
105
|
+
/**
|
|
106
|
+
* 提权可写根的统一口径(daemon 启动探测与 resolve 校验共用,防两处漂移)。
|
|
107
|
+
*
|
|
108
|
+
* @param options.workspaces - agent workspace 集合
|
|
109
|
+
* @param options.transactionRoots - 配置 transactionRoots
|
|
110
|
+
* @returns 可写根列表(含 home/tmp/OCTOPI_HOME)
|
|
111
|
+
*/
|
|
112
|
+
export declare function escalationWritableRoots(options?: {
|
|
113
|
+
workspaces?: readonly string[];
|
|
114
|
+
transactionRoots?: readonly string[];
|
|
115
|
+
}): string[];
|
|
116
|
+
/**
|
|
117
|
+
* 启动期探测:声明了提权就必须真的拿得到(拍板 #5:拒绝启动,禁止降级静默)。
|
|
118
|
+
*
|
|
119
|
+
* @param config - 提权策略(配置形或 resolved 均可)
|
|
120
|
+
* @param options.writableRoots - TOCTOU 护栏的可写根集合
|
|
121
|
+
* @returns ok 或拒绝原因
|
|
122
|
+
*/
|
|
123
|
+
export declare function probeEscalationReadiness(config: EscalationPolicy | {
|
|
124
|
+
policy?: 'none' | 'allowlist' | 'full';
|
|
125
|
+
via?: 'sudo' | 'direct';
|
|
126
|
+
allow?: EscalationRule[];
|
|
127
|
+
} | undefined, options?: {
|
|
128
|
+
writableRoots?: readonly string[];
|
|
129
|
+
}): Promise<EscalationReadiness>;
|
|
130
|
+
/**
|
|
131
|
+
* 本进程是否已高权限(root / Windows elevated 管理员令牌)。
|
|
132
|
+
*
|
|
133
|
+
* POSIX 同步读 `geteuid()`;win32 走 `fsutil dirty query` 行为探测(与
|
|
134
|
+
* `probeEscalationReadiness` 的 direct 分支同口径,不读配置位、不猜 token)。
|
|
135
|
+
* 结果按进程生命期缓存(权限不可自行提升,探测一次即事实不变)。
|
|
136
|
+
*
|
|
137
|
+
* @returns true = 高权限进程
|
|
138
|
+
*/
|
|
139
|
+
export declare function isProcessElevated(): Promise<boolean>;
|
|
140
|
+
/** 同步口径的高权限猜测(POSIX 可判;win32 同步不可判时如实返回 false 交由异步探测补) */
|
|
141
|
+
export declare function isProcessElevatedSync(): boolean;
|
|
142
|
+
/**
|
|
143
|
+
* root/elevated 部署的显式 privileged 声明断言(§5 P4 root 部署语义)。
|
|
144
|
+
*
|
|
145
|
+
* daemon 以 root 跑时没有 sudo,危险轴变成「笼不笼 × uid=0」——启动期高权限进程
|
|
146
|
+
* 必须在 effectPolicy 里显式 `privilegedAck` 表态,拿不到声明就拒绝启动,
|
|
147
|
+
* 不允许「root 就这么跑着」的静默特权态。
|
|
148
|
+
*
|
|
149
|
+
* @param params.elevated - 进程是否高权限(`isProcessElevated` 探测值)
|
|
150
|
+
* @param params.privilegedAck - effectPolicy.privilegedAck(可缺省)
|
|
151
|
+
* @param params.scope - 出错信息里的配置面标识(如 `<top>` / agent id)
|
|
152
|
+
* @throws `privileged_declaration_required`(elevated 且无声明)
|
|
153
|
+
*/
|
|
154
|
+
export declare function assertPrivilegedDeclaration(params: {
|
|
155
|
+
elevated: boolean;
|
|
156
|
+
privilegedAck?: string;
|
|
157
|
+
scope: string;
|
|
158
|
+
}): void;
|