@node9/policy-engine 2.30.1 → 2.31.1
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/THIRD_PARTY_NOTICES.md +33 -0
- package/dist/index.d.mts +661 -543
- package/dist/index.d.ts +661 -543
- package/dist/index.js +9299 -5714
- package/dist/index.mjs +9288 -5718
- package/package.json +3 -2
package/dist/index.d.mts
CHANGED
|
@@ -105,119 +105,282 @@ interface RiskMetadata {
|
|
|
105
105
|
ruleDescription?: string;
|
|
106
106
|
}
|
|
107
107
|
|
|
108
|
-
type
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
108
|
+
type ToolInspectionEntry = string | {
|
|
109
|
+
kind: 'shell';
|
|
110
|
+
field: string;
|
|
111
|
+
};
|
|
112
|
+
type ToolInspection = Record<string, ToolInspectionEntry>;
|
|
113
|
+
type ShellInputResolution = {
|
|
114
|
+
kind: 'not-shell';
|
|
115
|
+
} | {
|
|
116
|
+
kind: 'uninspectable';
|
|
117
|
+
reason: string;
|
|
118
|
+
} | {
|
|
119
|
+
kind: 'shell';
|
|
120
|
+
command: string;
|
|
121
|
+
fieldPath: string;
|
|
122
|
+
};
|
|
123
|
+
declare const BASH_TOOL_NAMES: Set<string>;
|
|
124
|
+
declare function isBashTool(tool: string): boolean;
|
|
125
|
+
declare function isShellShapedTool(tool: string, inspection?: ToolInspection): boolean;
|
|
126
|
+
declare function resolveShellInput(tool: string, args: unknown, inspection?: ToolInspection): ShellInputResolution;
|
|
127
|
+
/** Only Bash-scoped rules receive the canonical projection. Caller data is never mutated. */
|
|
128
|
+
declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: ToolInspection): unknown;
|
|
129
|
+
|
|
130
|
+
type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
|
|
131
|
+
interface SsrfMatch {
|
|
132
|
+
tier: SsrfTier;
|
|
133
|
+
/** false for tier 1: no allowlist entry exempts it. */
|
|
134
|
+
overridable: boolean;
|
|
135
|
+
/** 'address' when an IP literal matched, 'hostname' for the metadata name list. */
|
|
136
|
+
kind: 'address' | 'hostname';
|
|
137
|
+
/** The canonical address; absent for a hostname match. Never an empty string:
|
|
138
|
+
* an empty value is dropped in flight by cloud.ts and the audit shipper. */
|
|
139
|
+
normalized?: string;
|
|
118
140
|
}
|
|
141
|
+
/** Longest legal DNS name. The caller does NOT reliably bound this: a URL with a
|
|
142
|
+
* 261-character host reaches us intact (measured), so we bound our own input. */
|
|
143
|
+
declare const SSRF_MAX_HOST = 253;
|
|
119
144
|
/**
|
|
120
|
-
*
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
-
*
|
|
124
|
-
*
|
|
145
|
+
* Fold any spelling of an IP literal to one canonical address, or null when the
|
|
146
|
+
* input is not an IP literal (a hostname, or malformed). Never throws.
|
|
147
|
+
*
|
|
148
|
+
* IPv4-mapped IPv6 folds to the IPv4 address it denotes (RFC 4291 2.5.5.2), so
|
|
149
|
+
* `[::ffff:a9fe:a9fe]` and `169.254.169.254` compare equal. Brackets and a zone
|
|
150
|
+
* id are stripped here: the caller does NOT strip them (measured).
|
|
125
151
|
*/
|
|
126
|
-
declare function
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
declare function
|
|
134
|
-
/**
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
152
|
+
declare function normalizeIpLiteral(host: string): string | null;
|
|
153
|
+
/** Is this tier reachable by default, waiting on the `ssrfStrict` knob?
|
|
154
|
+
* Exported so the non-shell path asks the SAME question rather than
|
|
155
|
+
* approximating it with `overridable`, which is a different property. */
|
|
156
|
+
declare function isStrictGatedTier(tier: SsrfTier): boolean;
|
|
157
|
+
/** The sentence a user reads when the floor stops them. One builder, so the
|
|
158
|
+
* shell path and the non-shell path cannot word the same block differently. */
|
|
159
|
+
declare function ssrfReason(m: SsrfMatch, asWritten: string): string;
|
|
160
|
+
/**
|
|
161
|
+
* Classify a destination host. Returns null when it is not a protected address,
|
|
162
|
+
* which means the ordinary egress policy decides. Never throws.
|
|
163
|
+
*
|
|
164
|
+
* Ordering is significant: the exact metadata addresses are checked before the
|
|
165
|
+
* link-local range that contains them, so the reason names metadata.
|
|
166
|
+
*/
|
|
167
|
+
declare function classifySsrf(host: string): SsrfMatch | null;
|
|
168
|
+
interface SsrfVerdict extends SsrfMatch {
|
|
169
|
+
/** The token as written in the command. */
|
|
170
|
+
host: string;
|
|
171
|
+
binary: string;
|
|
172
|
+
reason: string;
|
|
173
|
+
}
|
|
174
|
+
interface SsrfFloorOptions {
|
|
175
|
+
/** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
|
|
176
|
+
* rejected at config load with a reason, never silently). */
|
|
177
|
+
ssrfAllow?: readonly string[];
|
|
178
|
+
/** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
|
|
179
|
+
* those constantly (72 of 308 destinations on measured real history). */
|
|
180
|
+
ssrfStrict?: boolean;
|
|
142
181
|
}
|
|
143
182
|
/**
|
|
144
|
-
*
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
183
|
+
* Does this exemption list release this address?
|
|
184
|
+
*
|
|
185
|
+
* ONE function, because the shell floor and the declared-URL floor must answer
|
|
186
|
+
* identically. They had two spellings of it — `normalizeIpLiteral(e) ?? e.trim()
|
|
187
|
+
* .toLowerCase()` here and `classifySsrf(a)?.normalized ?? a` in
|
|
188
|
+
* destinations.ts — and for an entry classifySsrf does not match they already
|
|
189
|
+
* disagreed. Nothing depended on the difference, which is exactly when it is
|
|
190
|
+
* cheap to remove.
|
|
191
|
+
*
|
|
192
|
+
* An entry is an exact address or a CIDR range. The range form exists so an
|
|
193
|
+
* operator can exempt the mesh-VPN range they actually use (100.64.0.0/10)
|
|
194
|
+
* instead of listing peers one at a time, which is what the settings panel's
|
|
195
|
+
* "remove this default" control needs.
|
|
196
|
+
*
|
|
197
|
+
* ⚠ This answers "is it in the list", NOT "may it be released". The caller
|
|
198
|
+
* keeps its `m.overridable` guard, and that guard is per ADDRESS, decided by
|
|
199
|
+
* classifySsrf before this is consulted. So a range can never release a
|
|
200
|
+
* protected address inside it: 100.100.100.200 (Alibaba IMDS) sits inside
|
|
201
|
+
* 100.64.0.0/10 and is named in METADATA_ADDRESSES above the range check, so
|
|
202
|
+
* it classifies as metadata / overridable:false and stays blocked with the
|
|
203
|
+
* whole range exempted. Pinned by E2 in exempt-range.spec.ts.
|
|
204
|
+
*
|
|
205
|
+
* Never throws: this runs on the hook path for every tool call, and a bad
|
|
206
|
+
* entry in a hand-edited config must not break every command on the machine.
|
|
148
207
|
*/
|
|
149
|
-
declare function
|
|
208
|
+
declare function ssrfExemptMatches(entries: readonly string[] | undefined, normalized: string | undefined): boolean;
|
|
209
|
+
/**
|
|
210
|
+
* The floor. Returns the first protected destination, or null.
|
|
211
|
+
*
|
|
212
|
+
* Runs unconditionally: not gated on egress.enabled, mode, allow or allowPrivate.
|
|
213
|
+
* The one thing that does switch it off is `node9 pause`, which returns before
|
|
214
|
+
* every gate; that is stated as a limit rather than special-cased here.
|
|
215
|
+
*/
|
|
216
|
+
declare function ssrfFloor(tokens: ReadonlyArray<{
|
|
217
|
+
token: string;
|
|
218
|
+
binary: string;
|
|
219
|
+
}>, opts?: SsrfFloorOptions): SsrfVerdict | null;
|
|
150
220
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
221
|
+
/** The one value set every check uses. `log` runs the check and records the
|
|
222
|
+
* finding without stopping the call; it replaces skill pinning's `warn` and
|
|
223
|
+
* the per-check meaning of the global observe mode. */
|
|
224
|
+
type Verdict = 'off' | 'log' | 'review' | 'block';
|
|
225
|
+
declare const VERDICTS: readonly Verdict[];
|
|
226
|
+
declare const CHECK_VERDICT_RANK: Record<Verdict, number>;
|
|
227
|
+
declare function isVerdict(v: unknown): v is Verdict;
|
|
228
|
+
/** Groups are by what the user fears, not by the mechanism that catches it. */
|
|
229
|
+
type CheckGroup = 'commands' | 'data' | 'network' | 'files' | 'behavior' | 'loading';
|
|
230
|
+
declare const CHECK_GROUPS: readonly {
|
|
231
|
+
id: CheckGroup;
|
|
232
|
+
title: string;
|
|
233
|
+
}[];
|
|
234
|
+
interface CheckDef {
|
|
235
|
+
/** `group.name`, stable forever: audit rows and config files key on it. */
|
|
236
|
+
id: string;
|
|
237
|
+
group: CheckGroup;
|
|
238
|
+
title: string;
|
|
239
|
+
/** One line, shown under the title: what the check catches. */
|
|
240
|
+
catches: string;
|
|
241
|
+
/** What a user may pick, in order. */
|
|
242
|
+
values: readonly Verdict[];
|
|
243
|
+
defaultValue: Verdict;
|
|
244
|
+
/** Lowest value a user may pick. `block` means the check is locked. */
|
|
245
|
+
floor?: Verdict;
|
|
246
|
+
/** Set on a row a pack (a builtin shield) contributes; the row only exists
|
|
247
|
+
* while that pack is on. */
|
|
248
|
+
pack?: string;
|
|
249
|
+
/** Rule names and labels the code emits today for this check. Exact
|
|
250
|
+
* matches only; prefixed families are handled in `checkIdForRule`. */
|
|
251
|
+
legacy?: readonly string[];
|
|
252
|
+
/** Plain-language explanation (catalog-text.ts). */
|
|
253
|
+
plain?: string;
|
|
254
|
+
/** One concrete thing an agent might do that this check catches. */
|
|
255
|
+
example?: string;
|
|
256
|
+
/** When to change the default, and to what. */
|
|
257
|
+
advice?: string;
|
|
258
|
+
}
|
|
259
|
+
/** Words in the product's own dangerous-word list. Shields add their own. */
|
|
260
|
+
declare const BUILTIN_DANGEROUS_WORDS: readonly string[];
|
|
261
|
+
declare const CHECKS: readonly CheckDef[];
|
|
262
|
+
declare const CHECK_BY_ID: ReadonlyMap<string, CheckDef>;
|
|
263
|
+
declare function getCheck(id: string): CheckDef | undefined;
|
|
264
|
+
declare function isLockedCheck(def: CheckDef): boolean;
|
|
265
|
+
/** Which check an SSRF floor hit belongs to: the strict-gated tiers are the
|
|
266
|
+
* internal-address check, the rest are the locked metadata check. */
|
|
267
|
+
declare function ssrfCheckId(tier: SsrfTier): string;
|
|
268
|
+
declare function checkIdForRule(nameOrLabel: string | undefined): string | undefined;
|
|
269
|
+
/** The check behind an audit row's `checkedBy` tag, for rows whose verdict
|
|
270
|
+
* carried no rule name (the DLP, PII, loop and taint gates). */
|
|
271
|
+
declare function checkIdForCheckedBy(checkedBy: string | undefined): string | undefined;
|
|
272
|
+
/** The slice of the host config the resolver reads. The proxy's `Config`
|
|
273
|
+
* satisfies it structurally; the dashboard backend builds it from a row. */
|
|
274
|
+
interface CatalogSettings {
|
|
275
|
+
mode?: string;
|
|
276
|
+
commandChecks?: {
|
|
277
|
+
inlineExec?: string;
|
|
278
|
+
rmAdvisory?: string;
|
|
279
|
+
chmod?: string;
|
|
280
|
+
sqlDdl?: string;
|
|
281
|
+
evalDynamic?: string;
|
|
282
|
+
pipeChainHigh?: string;
|
|
283
|
+
};
|
|
284
|
+
dlp?: {
|
|
285
|
+
enabled?: boolean;
|
|
286
|
+
reviewAction?: string;
|
|
287
|
+
pii?: string;
|
|
288
|
+
};
|
|
289
|
+
egress?: {
|
|
290
|
+
enabled?: boolean;
|
|
291
|
+
mode?: string;
|
|
292
|
+
ssrfStrict?: boolean;
|
|
293
|
+
};
|
|
294
|
+
loopDetection?: {
|
|
295
|
+
enabled?: boolean;
|
|
296
|
+
};
|
|
297
|
+
injectionScan?: {
|
|
298
|
+
enabled?: boolean;
|
|
299
|
+
};
|
|
300
|
+
skillPinning?: {
|
|
301
|
+
enabled?: boolean;
|
|
302
|
+
mode?: string;
|
|
303
|
+
};
|
|
304
|
+
packageCheck?: {
|
|
305
|
+
enabled?: boolean;
|
|
306
|
+
onMalicious?: string;
|
|
307
|
+
};
|
|
308
|
+
/** Shields the host actually injected (`policy.appliedShields`). */
|
|
309
|
+
appliedShields?: readonly string[];
|
|
168
310
|
/**
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
* happens to contain a stopword substring is a real secret, roughly 1 in
|
|
173
|
-
* 3,000 real WIF keys); a failing one rejects it. Must never throw; a throw
|
|
174
|
-
* is treated as "not suppressed" so a validator bug cannot hide a match.
|
|
311
|
+
* Explicit per-check values, keyed by check id: the v2 config file's
|
|
312
|
+
* `checks` map, or the host's resolved map. Wins over the legacy knobs
|
|
313
|
+
* above; a value below a row's floor is raised to the floor.
|
|
175
314
|
*/
|
|
176
|
-
|
|
177
|
-
/** When the regex consumes delimiters around the secret, the capture group
|
|
178
|
-
* that holds the secret itself; redactText replaces only that group. Any
|
|
179
|
-
* other capture group (a scheme, a prefix) is NOT the secret, so the field
|
|
180
|
-
* is explicit rather than "group 1 if present". */
|
|
181
|
-
redactGroup?: number;
|
|
315
|
+
checks?: Readonly<Record<string, string>>;
|
|
182
316
|
}
|
|
183
|
-
|
|
317
|
+
/** Where a value came from. `configured` means it departs from the shipped
|
|
318
|
+
* default: the merged config carries every default as an explicit value, so
|
|
319
|
+
* "set" and "unset" cannot be told apart, and the departure is what a reader
|
|
320
|
+
* wants to know. A pack row never claims a source; its value says whether the
|
|
321
|
+
* pack is on. */
|
|
184
322
|
/**
|
|
185
|
-
*
|
|
186
|
-
*
|
|
187
|
-
*
|
|
188
|
-
*
|
|
189
|
-
* @param resolvedPath Absolute path, ideally with symlinks resolved by the host.
|
|
190
|
-
* @param originalPath The path as the user/agent wrote it. Used in the
|
|
191
|
-
* redactedSample so alerts show the original spelling.
|
|
192
|
-
* @returns A DlpMatch with severity 'block' if the path is sensitive, else null.
|
|
323
|
+
* The ONE projection from a host config (`settings` + `policy`) to what the
|
|
324
|
+
* resolver reads. The engine and the proxy both call it, so a new knob is
|
|
325
|
+
* threaded through once.
|
|
193
326
|
*/
|
|
194
|
-
declare function
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
327
|
+
declare function catalogSettingsFromConfig(settings: {
|
|
328
|
+
mode?: string;
|
|
329
|
+
}, policy: Omit<CatalogSettings, 'mode'>): CatalogSettings;
|
|
330
|
+
type CheckSource = 'default' | 'configured' | 'locked' | 'local' | 'project' | 'workspace';
|
|
331
|
+
interface ResolvedCheck {
|
|
332
|
+
id: string;
|
|
333
|
+
value: Verdict;
|
|
334
|
+
source: CheckSource;
|
|
335
|
+
}
|
|
199
336
|
/**
|
|
200
|
-
* The
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
* actually covered its input. Exported rather than duplicated at the call
|
|
205
|
-
* site so the two can never drift apart.
|
|
337
|
+
* The value in force for one check, read from today's config shape, and
|
|
338
|
+
* where it came from. A locked check always answers its floor. A pack row is
|
|
339
|
+
* `off` unless its pack is applied. Anything the config does not set is the
|
|
340
|
+
* catalog default.
|
|
206
341
|
*/
|
|
207
|
-
declare
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
declare function
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
342
|
+
declare function resolveCheck(settings: CatalogSettings, id: string): ResolvedCheck | undefined;
|
|
343
|
+
/** Every check resolved, in catalog order. */
|
|
344
|
+
declare function resolveAllChecks(settings: CatalogSettings): ResolvedCheck[];
|
|
345
|
+
/**
|
|
346
|
+
* The value a detector should act on: an explicit `checks[id]` entry when
|
|
347
|
+
* the settings carry one (raised to the row's floor), else the legacy
|
|
348
|
+
* resolution. Detectors call this and nothing else, so a check's value is
|
|
349
|
+
* decided in one place whatever file or payload it came from.
|
|
350
|
+
*/
|
|
351
|
+
declare function checkValue(settings: CatalogSettings, id: string): Verdict;
|
|
352
|
+
/** Resolve every check the way `checkValue` would, as one map. The host
|
|
353
|
+
* stores this on its config so every reader sees the same answers. */
|
|
354
|
+
declare function resolveCheckMap(settings: CatalogSettings): Record<string, Verdict>;
|
|
355
|
+
|
|
356
|
+
declare const SYSTEM_AUTH_FILES: readonly ["/etc/passwd", "/etc/shadow", "/etc/group", "/etc/gshadow", "/etc/sudoers"];
|
|
357
|
+
declare const SYSTEM_AUTH_DIRS: readonly ["/etc/security", "/etc/pam.d", "/etc/sudoers.d"];
|
|
358
|
+
declare const STARTUP_NAMES: readonly [".bashrc", ".zshrc", ".profile", ".bash_profile"];
|
|
359
|
+
declare function isPasswordHashPath(p: string): boolean;
|
|
360
|
+
/** Compatibility only: old callers do not tell DLP whether they read or write. */
|
|
361
|
+
declare function isLegacySystemPath(p: string): boolean;
|
|
362
|
+
/** Pure lexical normalization; host physical resolution keeps the original path. */
|
|
363
|
+
declare function normalizeFilePath(p: string, cwd?: string, home?: string): string;
|
|
364
|
+
interface FileAccess {
|
|
365
|
+
operation: 'read' | 'write' | 'remove' | 'create';
|
|
366
|
+
path: string;
|
|
367
|
+
cwd?: string;
|
|
368
|
+
/** Unquoted shell pattern. Quoted metacharacters are escaped in this value. */
|
|
369
|
+
glob?: string;
|
|
370
|
+
/** The pattern is find's, not the shell's: `*` also selects dotfiles. */
|
|
371
|
+
dotGlob?: boolean;
|
|
372
|
+
followFinal: boolean;
|
|
373
|
+
recursive?: boolean;
|
|
374
|
+
/** This basename-joined candidate applies only if this operand is a directory. */
|
|
375
|
+
directoryTarget?: string;
|
|
376
|
+
candidates?: string[];
|
|
377
|
+
resolution?: 'resolved' | 'missing' | 'failed' | 'lexical';
|
|
378
|
+
}
|
|
379
|
+
interface FileAccessContext {
|
|
380
|
+
cwd?: string;
|
|
381
|
+
homeDirs?: string[];
|
|
382
|
+
accesses?: FileAccess[];
|
|
383
|
+
}
|
|
221
384
|
|
|
222
385
|
/**
|
|
223
386
|
* The POSIX reading of a command. Kept as the single-string API every existing
|
|
@@ -311,8 +474,6 @@ interface FsOpVerdict {
|
|
|
311
474
|
/** The actual path argument from the user's command — for explainability. */
|
|
312
475
|
path: string;
|
|
313
476
|
}
|
|
314
|
-
declare const BASH_TOOL_NAMES: Set<string>;
|
|
315
|
-
declare function isBashTool(toolName: string): boolean;
|
|
316
477
|
declare const AST_FS_REGEX_RULES: Set<string>;
|
|
317
478
|
declare const COMMAND_WRAPPERS: Set<string>;
|
|
318
479
|
/**
|
|
@@ -324,7 +485,6 @@ declare const COMMAND_WRAPPERS: Set<string>;
|
|
|
324
485
|
* (/code-review 2026-08-13: the gate reviewed `sudo …` on `shell` while scan
|
|
325
486
|
* reported nothing, so the customer-facing report under-counted).
|
|
326
487
|
*/
|
|
327
|
-
declare function isShellShapedTool(toolName: string, toolInspection?: Record<string, string>): boolean;
|
|
328
488
|
/**
|
|
329
489
|
* Does a smart rule's `tool` scope cover this tool? Adds the shell-shape alias:
|
|
330
490
|
* the six default shell-safety rules and shield bundles are written
|
|
@@ -332,12 +492,12 @@ declare function isShellShapedTool(toolName: string, toolInspection?: Record<str
|
|
|
332
492
|
* `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
|
|
333
493
|
* void them. An absent rule scope matches everything (callers' prior semantics).
|
|
334
494
|
*/
|
|
335
|
-
declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?:
|
|
495
|
+
declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: ToolInspection): boolean;
|
|
336
496
|
/** Strip leading wrappers/runners from a resolved arg list, returning the index
|
|
337
497
|
* of the real command head. Handles `sudo -u www python3`, `env -u FOO python3`,
|
|
338
498
|
* `timeout 5 python3`, `uv run python`, `conda run -n env python`,
|
|
339
499
|
* `chroot /mnt python3`. */
|
|
340
|
-
declare function unwrapCommandHead(words: (string | null)[]): number;
|
|
500
|
+
declare function unwrapCommandHead(words: (string | null)[], stopAtFind?: boolean, stopAtDynamic?: boolean): number;
|
|
341
501
|
/**
|
|
342
502
|
* AST-aware inline-execution detector. Returns true when the command runs code
|
|
343
503
|
* supplied on the command line, via stdin, or via a pipe into a bare
|
|
@@ -436,257 +596,389 @@ interface ShellCommandAnalysis {
|
|
|
436
596
|
*/
|
|
437
597
|
declare function analyzeShellCommand(command: string): ShellCommandAnalysis;
|
|
438
598
|
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
599
|
+
/**
|
|
600
|
+
* A destination a tool call will reach, whichever carrier declared it: a
|
|
601
|
+
* shell command (extractShellDestinations) or a tool argument
|
|
602
|
+
* (extractToolDestinations). The interface is still spelled ShellDestination
|
|
603
|
+
* where it lives (shell/index.ts, which is hashed by the extractor-version
|
|
604
|
+
* gate, so a rename there is not free); this is the name that says what the
|
|
605
|
+
* shape is for.
|
|
606
|
+
*/
|
|
607
|
+
type Destination = ShellDestination;
|
|
608
|
+
interface EgressPolicy {
|
|
609
|
+
/** Master switch. Default false — opt-in, like dlp.pii. */
|
|
610
|
+
enabled: boolean;
|
|
611
|
+
/** Verdict for an UNKNOWN host (not in allow, not in deny, not private). */
|
|
612
|
+
mode: 'off' | 'review' | 'block';
|
|
613
|
+
/** Host globs always allowed (e.g. "*.github.com", "api.openai.com"). */
|
|
614
|
+
allow: string[];
|
|
615
|
+
/** Host globs always blocked — wins over allow/private. */
|
|
616
|
+
deny: string[];
|
|
617
|
+
/** Auto-allow localhost / RFC1918 / *.local. Default true. */
|
|
618
|
+
allowPrivate: boolean;
|
|
619
|
+
/** SSRF floor: exempts OVERRIDABLE tiers only (carrier-grade NAT, and
|
|
620
|
+
* loopback/RFC1918 when ssrfStrict is on). A tier-1 entry is ignored here
|
|
621
|
+
* and rejected at config load with a reason. */
|
|
622
|
+
ssrfAllow?: readonly string[];
|
|
623
|
+
/** SSRF floor tier 3: also block loopback and RFC1918. Off by default,
|
|
624
|
+
* because a developer talks to those constantly (72 of 308 destinations on
|
|
625
|
+
* measured real history). */
|
|
626
|
+
ssrfStrict?: boolean;
|
|
452
627
|
}
|
|
453
|
-
|
|
454
|
-
|
|
628
|
+
interface EgressVerdict {
|
|
629
|
+
verdict: 'block' | 'review';
|
|
630
|
+
host: string;
|
|
631
|
+
binary: string;
|
|
632
|
+
reason: string;
|
|
633
|
+
}
|
|
634
|
+
declare const DEFAULT_EGRESS_ALLOWLIST: readonly string[];
|
|
635
|
+
/** Glob host match: "*" = any, "*.x" = apex x + any subdomain, else exact. */
|
|
636
|
+
declare function hostMatches(host: string, pattern: string): boolean;
|
|
455
637
|
/**
|
|
456
|
-
*
|
|
457
|
-
*
|
|
458
|
-
*
|
|
459
|
-
*
|
|
460
|
-
*
|
|
461
|
-
*
|
|
638
|
+
* "Private" for the allowPrivate opt-in: loopback, RFC1918 and its IPv6
|
|
639
|
+
* analogue, the unspecified address, and the conventional local suffixes.
|
|
640
|
+
*
|
|
641
|
+
* The address half is classifySsrf's answer, so every spelling that file
|
|
642
|
+
* normalizes (brackets, zone id, IPv4-mapped IPv6) is one spelling here too.
|
|
643
|
+
* The old body had its own IPv4-only regexes and returned false for `[::1]`,
|
|
644
|
+
* which BLOCKED a local IPv6 dev server under allowPrivate (measured
|
|
645
|
+
* 2026-09-20; the shell extractor keeps the brackets, the declared-URL
|
|
646
|
+
* extractor strips them, and this function knew neither). Two parsers for
|
|
647
|
+
* one question is how that happens.
|
|
648
|
+
*
|
|
649
|
+
* NOT private here: link-local, multicast, the metadata endpoints. Those are
|
|
650
|
+
* the SSRF floor's tiers and allowPrivate must not be able to reach them;
|
|
651
|
+
* evaluateEgress documents that the floor runs first, and this function
|
|
652
|
+
* agrees with it rather than relying on it. CGNAT (100.64/10) is also out:
|
|
653
|
+
* a mesh-VPN peer is not everyone's private network, which is why the floor
|
|
654
|
+
* gave it its own tier; a Tailscale user lists the range in `allow`.
|
|
462
655
|
*/
|
|
463
|
-
declare function
|
|
656
|
+
declare function isPrivateHost(host: string): boolean;
|
|
657
|
+
/**
|
|
658
|
+
* Evaluate extracted destinations against the egress policy. Precedence per
|
|
659
|
+
* host: deny (block) > private-allow > allow/default-allow (skip) > unknown
|
|
660
|
+
* (policy.mode). Returns the most severe actionable verdict across all
|
|
661
|
+
* destinations — a deny or block-mode-unknown short-circuits; otherwise the
|
|
662
|
+
* first review; null if everything is allowed (or policy disabled / mode off).
|
|
663
|
+
* Pure.
|
|
664
|
+
*/
|
|
665
|
+
declare function evaluateEgress(dests: readonly Destination[], policy: EgressPolicy): EgressVerdict | null;
|
|
464
666
|
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
667
|
+
interface PolicyConfig {
|
|
668
|
+
policy: {
|
|
669
|
+
sandboxPaths: string[];
|
|
670
|
+
dangerousWords: string[];
|
|
671
|
+
ignoredTools: string[];
|
|
672
|
+
toolInspection: ToolInspection;
|
|
673
|
+
smartRules: SmartRule[];
|
|
674
|
+
dlp: {
|
|
675
|
+
enabled: boolean;
|
|
676
|
+
scanIgnoredTools: boolean;
|
|
677
|
+
/** Inline-ask v2: 'block' upgrades review-severity DLP matches to a hard
|
|
678
|
+
* block. Optional for back-compat with callers that don't set it. */
|
|
679
|
+
reviewAction?: 'review' | 'block';
|
|
680
|
+
};
|
|
681
|
+
/** Egress / destination control (GAP-5). Optional for back-compat with
|
|
682
|
+
* callers/tests that build a PolicyConfig without it. */
|
|
683
|
+
egress?: EgressPolicy;
|
|
684
|
+
/** Command-checks governance (command-checks-governance-spec.md): admin
|
|
685
|
+
* knobs for the built-in detections' REVIEW-severity findings only.
|
|
686
|
+
* Block-severity findings (pipe-critical, eval-remote, rm-rf-home,
|
|
687
|
+
* nuclear, suspect binary) have NO key here — non-weakenable by
|
|
688
|
+
* construction. Class-B keys (evalDynamic, pipeChainHigh) exclude 'off'.
|
|
689
|
+
* rmAdvisory is consumed by the PROXY at advisory-rule injection. */
|
|
690
|
+
commandChecks?: {
|
|
691
|
+
inlineExec?: 'off' | 'review' | 'block';
|
|
692
|
+
rmAdvisory?: 'off' | 'review' | 'block';
|
|
693
|
+
chmod?: 'off' | 'review' | 'block';
|
|
694
|
+
sqlDdl?: 'off' | 'review' | 'block';
|
|
695
|
+
evalDynamic?: 'review' | 'block';
|
|
696
|
+
pipeChainHigh?: 'review' | 'block';
|
|
697
|
+
};
|
|
698
|
+
/**
|
|
699
|
+
* Per-check values keyed by catalog id (`commands.sudo`: `off`), the
|
|
700
|
+
* resolved map the host builds from its config file(s). Wins over the
|
|
701
|
+
* legacy knobs above. Absent for a caller that still builds the legacy
|
|
702
|
+
* shape by hand; the catalog then answers from those knobs.
|
|
703
|
+
*/
|
|
704
|
+
checks?: Record<string, string>;
|
|
705
|
+
};
|
|
706
|
+
settings: {
|
|
707
|
+
mode: string;
|
|
708
|
+
};
|
|
709
|
+
}
|
|
710
|
+
interface PolicyContext extends FileAccessContext {
|
|
711
|
+
/** "Terminal" disables most blocks (manual user typing). */
|
|
712
|
+
agent?: string;
|
|
713
|
+
/** Working directory passed through to provenance hook. */
|
|
714
|
+
cwd?: string;
|
|
715
|
+
/**
|
|
716
|
+
* Resolved environment block from getActiveEnvironment() in the host.
|
|
717
|
+
* If `requireApproval === false`, strict mode skips the catch-all review.
|
|
718
|
+
*/
|
|
719
|
+
activeEnvironment?: {
|
|
720
|
+
requireApproval?: boolean;
|
|
721
|
+
};
|
|
722
|
+
/**
|
|
723
|
+
* Task #20: evaluate the full rule chain even for an ignoredTools match.
|
|
724
|
+
* Set by the orchestrator's jail guard AFTER it has already found a
|
|
725
|
+
* jailed/sensitive path in a file-tool call — without this, the tier-1
|
|
726
|
+
* fast path below returns 'allow' before the jail shield's `tool:'*'`
|
|
727
|
+
* rules are ever consulted, making the jail engine-invisible to
|
|
728
|
+
* Read/Grep/Glob. Opt-in per call; never set on the hot path.
|
|
729
|
+
*/
|
|
730
|
+
skipIgnoredFastPath?: boolean;
|
|
731
|
+
/**
|
|
732
|
+
* The host's own `scanArgumentSecrets(args)` result for these exact
|
|
733
|
+
* arguments, so the gate and the engine scan once per call. Set only by
|
|
734
|
+
* trusted host code; absent means the engine scans.
|
|
735
|
+
*/
|
|
736
|
+
argumentScan?: DlpMatch | null;
|
|
737
|
+
}
|
|
738
|
+
type ProvenanceTrust = 'system' | 'managed' | 'user' | 'suspect' | 'unknown';
|
|
739
|
+
interface ProvenanceLookup {
|
|
740
|
+
resolvedPath: string;
|
|
741
|
+
trustLevel: ProvenanceTrust;
|
|
742
|
+
reason: string;
|
|
743
|
+
}
|
|
744
|
+
interface PolicyHostHooks {
|
|
745
|
+
/** Resolves an absolute binary path to a trust classification. */
|
|
746
|
+
checkProvenance?: (binary: string, cwd?: string) => ProvenanceLookup;
|
|
747
|
+
/** Returns true if the host is on the user's trusted-hosts allowlist. */
|
|
748
|
+
isTrustedHost?: (host: string) => boolean;
|
|
749
|
+
}
|
|
750
|
+
interface PolicyVerdict {
|
|
751
|
+
decision: 'allow' | 'review' | 'block';
|
|
752
|
+
blockedByLabel?: string;
|
|
753
|
+
reason?: string;
|
|
754
|
+
matchedField?: string;
|
|
755
|
+
matchedWord?: string;
|
|
756
|
+
tier?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
|
|
757
|
+
/**
|
|
758
|
+
* False when NO human may override this verdict: the SSRF tier-1 floors,
|
|
759
|
+
* whose own reason string already tells the user "This address cannot be
|
|
760
|
+
* allowlisted". Absent means an override is a legitimate product decision,
|
|
761
|
+
* which is every other verdict.
|
|
762
|
+
*
|
|
763
|
+
* It exists because the host downgrades a hard block into a review whenever a
|
|
764
|
+
* human approver is reachable (orchestrator.ts, `mayDowngrade`). That is right
|
|
765
|
+
* for a smart-rule block and wrong for a floor, and the host could not tell
|
|
766
|
+
* the two apart: `overridable` was computed in egress/ssrf.ts, rendered into
|
|
767
|
+
* the reason sentence, and then dropped here.
|
|
768
|
+
*/
|
|
769
|
+
overridable?: boolean;
|
|
770
|
+
ruleName?: string;
|
|
771
|
+
/**
|
|
772
|
+
* True on an `allow` that records a finding: the check is set to `log`, so
|
|
773
|
+
* the call runs and the audit row names the check (through ruleName and
|
|
774
|
+
* checkId), but nothing stops. Never set together with review or block.
|
|
775
|
+
*/
|
|
776
|
+
logged?: boolean;
|
|
777
|
+
/**
|
|
778
|
+
* The catalog check this verdict belongs to (`commands.sudo`,
|
|
779
|
+
* `data.secrets`, ...). Set on every non-allow verdict a built-in detector,
|
|
780
|
+
* a product rule or a pack rule produces; absent on an allow and on a user
|
|
781
|
+
* or organisation rule, which are rules, not checks. See catalog.ts.
|
|
782
|
+
*/
|
|
783
|
+
checkId?: string;
|
|
784
|
+
/** State predicates from the matched smart rule (only when decision is 'block'). */
|
|
785
|
+
dependsOnStatePredicates?: string[];
|
|
786
|
+
/** Recovery command to suggest when this rule hard-blocks (from SmartRule.recoveryCommand). */
|
|
787
|
+
recoveryCommand?: string;
|
|
788
|
+
/** Plain-English description of what the rule does (from SmartRule.description). */
|
|
789
|
+
ruleDescription?: string;
|
|
475
790
|
}
|
|
476
|
-
/** Longest legal DNS name. The caller does NOT reliably bound this: a URL with a
|
|
477
|
-
* 261-character host reaches us intact (measured), so we bound our own input. */
|
|
478
|
-
declare const SSRF_MAX_HOST = 253;
|
|
479
791
|
/**
|
|
480
|
-
*
|
|
481
|
-
*
|
|
482
|
-
*
|
|
483
|
-
*
|
|
484
|
-
*
|
|
485
|
-
*
|
|
792
|
+
* Resolve which of several MATCHING smart rules decides the verdict (the
|
|
793
|
+
* pinned-only conflict engine, Phase 3b). The model:
|
|
794
|
+
* 1. If any matching rule is `pinned` (a manager "keep mine" cloud rule),
|
|
795
|
+
* only the pinned rules compete and the MOST-RESTRICTIVE pinned wins
|
|
796
|
+
* (block > review > allow) — so a manager's locked rule can't be
|
|
797
|
+
* overridden by a developer's local rule.
|
|
798
|
+
* 2. Otherwise the FIRST match wins — byte-for-byte the previous `.find()`
|
|
799
|
+
* behaviour. This is the zero-regression guarantee: with nothing pinned,
|
|
800
|
+
* nothing changes.
|
|
801
|
+
* Exported so the resolution is unit-testable in isolation.
|
|
486
802
|
*/
|
|
487
|
-
declare function
|
|
488
|
-
/** Is this tier reachable by default, waiting on the `ssrfStrict` knob?
|
|
489
|
-
* Exported so the non-shell path asks the SAME question rather than
|
|
490
|
-
* approximating it with `overridable`, which is a different property. */
|
|
491
|
-
declare function isStrictGatedTier(tier: SsrfTier): boolean;
|
|
492
|
-
/** The sentence a user reads when the floor stops them. One builder, so the
|
|
493
|
-
* shell path and the non-shell path cannot word the same block differently. */
|
|
494
|
-
declare function ssrfReason(m: SsrfMatch, asWritten: string): string;
|
|
803
|
+
declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
|
|
495
804
|
/**
|
|
496
|
-
*
|
|
497
|
-
*
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
805
|
+
* Checks a SQL string for dangerous unscoped mutations.
|
|
806
|
+
* Returns a reason string if dangerous, null if safe.
|
|
807
|
+
*/
|
|
808
|
+
declare function checkDangerousSql(sql: string): string | null;
|
|
809
|
+
declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hooks?: PolicyHostHooks): Promise<PolicyVerdict>;
|
|
810
|
+
/** Returns true when toolName matches the config's ignoredTools list. */
|
|
811
|
+
declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
|
|
812
|
+
|
|
813
|
+
type ProtectedFileVerdict = PolicyVerdict & {
|
|
814
|
+
path: string;
|
|
815
|
+
operation: FileAccess['operation'];
|
|
816
|
+
};
|
|
817
|
+
/**
|
|
818
|
+
* The file policy could not finish inspecting a call (a pattern the matcher
|
|
819
|
+
* cannot compile, or an exception while preparing accesses). That is never a
|
|
820
|
+
* clean result: the call needs an explicit approval, like an uninspectable
|
|
821
|
+
* shell command.
|
|
501
822
|
*/
|
|
502
|
-
declare function
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
823
|
+
declare function incompleteFileVerdict(operation?: FileAccess['operation']): ProtectedFileVerdict;
|
|
824
|
+
/** Closed adapters: an arbitrary tool's path-shaped argument is not an operation. */
|
|
825
|
+
declare function fileToolOperation(tool: string, args: unknown): FileAccess['operation'] | null;
|
|
826
|
+
declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: ToolInspection): FileAccess[];
|
|
827
|
+
declare function evaluateProtectedFileAccess(accesses: FileAccess[], context: FileAccessContext, settings: CatalogSettings): ProtectedFileVerdict | null;
|
|
828
|
+
|
|
829
|
+
type InjectionConfidence = 'low' | 'medium' | 'high';
|
|
830
|
+
interface InjectionMatch {
|
|
831
|
+
/** Names of the matched signals (+ 'untrusted-origin' when applicable). */
|
|
832
|
+
signals: string[];
|
|
833
|
+
confidence: InjectionConfidence;
|
|
508
834
|
}
|
|
509
|
-
interface
|
|
510
|
-
/**
|
|
511
|
-
*
|
|
512
|
-
|
|
513
|
-
/** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
|
|
514
|
-
* those constantly (72 of 308 destinations on measured real history). */
|
|
515
|
-
ssrfStrict?: boolean;
|
|
835
|
+
interface InjectionContext {
|
|
836
|
+
/** Tool that produced the output. Untrusted origins (web/network) raise
|
|
837
|
+
* confidence — a fetched page is attacker-influenceable; a local read isn't. */
|
|
838
|
+
tool?: string;
|
|
516
839
|
}
|
|
517
840
|
/**
|
|
518
|
-
*
|
|
519
|
-
*
|
|
520
|
-
*
|
|
521
|
-
*
|
|
522
|
-
* .
|
|
523
|
-
* destinations.ts — and for an entry classifySsrf does not match they already
|
|
524
|
-
* disagreed. Nothing depended on the difference, which is exactly when it is
|
|
525
|
-
* cheap to remove.
|
|
526
|
-
*
|
|
527
|
-
* An entry is an exact address or a CIDR range. The range form exists so an
|
|
528
|
-
* operator can exempt the mesh-VPN range they actually use (100.64.0.0/10)
|
|
529
|
-
* instead of listing peers one at a time, which is what the settings panel's
|
|
530
|
-
* "remove this default" control needs.
|
|
531
|
-
*
|
|
532
|
-
* ⚠ This answers "is it in the list", NOT "may it be released". The caller
|
|
533
|
-
* keeps its `m.overridable` guard, and that guard is per ADDRESS, decided by
|
|
534
|
-
* classifySsrf before this is consulted. So a range can never release a
|
|
535
|
-
* protected address inside it: 100.100.100.200 (Alibaba IMDS) sits inside
|
|
536
|
-
* 100.64.0.0/10 and is named in METADATA_ADDRESSES above the range check, so
|
|
537
|
-
* it classifies as metadata / overridable:false and stays blocked with the
|
|
538
|
-
* whole range exempted. Pinned by E2 in exempt-range.spec.ts.
|
|
539
|
-
*
|
|
540
|
-
* Never throws: this runs on the hook path for every tool call, and a bad
|
|
541
|
-
* entry in a hand-edited config must not break every command on the machine.
|
|
841
|
+
* Scan tool output for indirect prompt injection. Returns the matched signals +
|
|
842
|
+
* a confidence, or null when nothing matched. Scoring: +1 per matched signal,
|
|
843
|
+
* +1 booster when the origin is an untrusted tool (booster needs ≥1 real
|
|
844
|
+
* signal). score 1 → low (a single phrase, e.g. a doc discussing injection);
|
|
845
|
+
* 2 → medium; 3+ → high. Callers should act only on medium+.
|
|
542
846
|
*/
|
|
543
|
-
declare function
|
|
847
|
+
declare function scanInjection(text: string, ctx?: InjectionContext): InjectionMatch | null;
|
|
848
|
+
|
|
849
|
+
/** Remove zero-width and other invisible code points. */
|
|
850
|
+
declare function stripInvisible(text: string): string;
|
|
851
|
+
/** NFKC-fold, then map lookalike Cyrillic/Greek letters onto Latin. */
|
|
852
|
+
declare function foldHomoglyphs(text: string): string;
|
|
853
|
+
/** The scanner's normalised reading: invisibles stripped, lookalikes folded. */
|
|
854
|
+
declare function normalizeForScan(text: string): string;
|
|
855
|
+
/** Decode every base64 / base64url run of 32+ characters that decodes to text. */
|
|
856
|
+
declare function decodeEmbeddedBase64(text: string): string[];
|
|
857
|
+
/** Decode hex runs (48+ digits) and `\xNN` escape runs that decode to text. */
|
|
858
|
+
declare function decodeEmbeddedHex(text: string): string[];
|
|
859
|
+
interface ScanView {
|
|
860
|
+
/** Which pass produced this text. `original` is the input itself. */
|
|
861
|
+
kind: 'original' | 'normalized' | 'base64' | 'hex';
|
|
862
|
+
text: string;
|
|
863
|
+
}
|
|
544
864
|
/**
|
|
545
|
-
*
|
|
546
|
-
*
|
|
547
|
-
*
|
|
548
|
-
*
|
|
549
|
-
* every gate; that is stated as a limit rather than special-cased here.
|
|
865
|
+
* Every reading of `text` the injection patterns should run on: the input,
|
|
866
|
+
* its normalised form (when it differs), and the normalised decoding of each
|
|
867
|
+
* embedded base64 and hex blob. Decoding is one level deep by design: a blob
|
|
868
|
+
* inside a blob is not decoded.
|
|
550
869
|
*/
|
|
551
|
-
declare function
|
|
552
|
-
token: string;
|
|
553
|
-
binary: string;
|
|
554
|
-
}>, opts?: SsrfFloorOptions): SsrfVerdict | null;
|
|
870
|
+
declare function scanViews(text: string): ScanView[];
|
|
555
871
|
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
declare function isVerdict(v: unknown): v is Verdict;
|
|
563
|
-
/** Groups are by what the user fears, not by the mechanism that catches it. */
|
|
564
|
-
type CheckGroup = 'commands' | 'data' | 'network' | 'files' | 'behavior' | 'loading';
|
|
565
|
-
declare const CHECK_GROUPS: readonly {
|
|
566
|
-
id: CheckGroup;
|
|
567
|
-
title: string;
|
|
568
|
-
}[];
|
|
569
|
-
interface CheckDef {
|
|
570
|
-
/** `group.name`, stable forever: audit rows and config files key on it. */
|
|
571
|
-
id: string;
|
|
572
|
-
group: CheckGroup;
|
|
573
|
-
title: string;
|
|
574
|
-
/** One line, shown under the title: what the check catches. */
|
|
575
|
-
catches: string;
|
|
576
|
-
/** What a user may pick, in order. */
|
|
577
|
-
values: readonly Verdict[];
|
|
578
|
-
defaultValue: Verdict;
|
|
579
|
-
/** Lowest value a user may pick. `block` means the check is locked. */
|
|
580
|
-
floor?: Verdict;
|
|
581
|
-
/** Set on a row a pack (a builtin shield) contributes; the row only exists
|
|
582
|
-
* while that pack is on. */
|
|
583
|
-
pack?: string;
|
|
584
|
-
/** Rule names and labels the code emits today for this check. Exact
|
|
585
|
-
* matches only; prefixed families are handled in `checkIdForRule`. */
|
|
586
|
-
legacy?: readonly string[];
|
|
587
|
-
/** Plain-language explanation (catalog-text.ts). */
|
|
588
|
-
plain?: string;
|
|
589
|
-
/** One concrete thing an agent might do that this check catches. */
|
|
590
|
-
example?: string;
|
|
591
|
-
/** When to change the default, and to what. */
|
|
592
|
-
advice?: string;
|
|
593
|
-
}
|
|
594
|
-
/** Words in the product's own dangerous-word list. Shields add their own. */
|
|
595
|
-
declare const BUILTIN_DANGEROUS_WORDS: readonly string[];
|
|
596
|
-
declare const CHECKS: readonly CheckDef[];
|
|
597
|
-
declare const CHECK_BY_ID: ReadonlyMap<string, CheckDef>;
|
|
598
|
-
declare function getCheck(id: string): CheckDef | undefined;
|
|
599
|
-
declare function isLockedCheck(def: CheckDef): boolean;
|
|
600
|
-
/** Which check an SSRF floor hit belongs to: the strict-gated tiers are the
|
|
601
|
-
* internal-address check, the rest are the locked metadata check. */
|
|
602
|
-
declare function ssrfCheckId(tier: SsrfTier): string;
|
|
603
|
-
declare function checkIdForRule(nameOrLabel: string | undefined): string | undefined;
|
|
604
|
-
/** The check behind an audit row's `checkedBy` tag, for rows whose verdict
|
|
605
|
-
* carried no rule name (the DLP, PII, loop and taint gates). */
|
|
606
|
-
declare function checkIdForCheckedBy(checkedBy: string | undefined): string | undefined;
|
|
607
|
-
/** The slice of the host config the resolver reads. The proxy's `Config`
|
|
608
|
-
* satisfies it structurally; the dashboard backend builds it from a row. */
|
|
609
|
-
interface CatalogSettings {
|
|
610
|
-
mode?: string;
|
|
611
|
-
commandChecks?: {
|
|
612
|
-
inlineExec?: string;
|
|
613
|
-
rmAdvisory?: string;
|
|
614
|
-
chmod?: string;
|
|
615
|
-
sqlDdl?: string;
|
|
616
|
-
evalDynamic?: string;
|
|
617
|
-
pipeChainHigh?: string;
|
|
618
|
-
};
|
|
619
|
-
dlp?: {
|
|
620
|
-
enabled?: boolean;
|
|
621
|
-
reviewAction?: string;
|
|
622
|
-
pii?: string;
|
|
623
|
-
};
|
|
624
|
-
egress?: {
|
|
625
|
-
enabled?: boolean;
|
|
626
|
-
mode?: string;
|
|
627
|
-
ssrfStrict?: boolean;
|
|
628
|
-
};
|
|
629
|
-
loopDetection?: {
|
|
630
|
-
enabled?: boolean;
|
|
631
|
-
};
|
|
632
|
-
injectionScan?: {
|
|
633
|
-
enabled?: boolean;
|
|
634
|
-
};
|
|
635
|
-
skillPinning?: {
|
|
636
|
-
enabled?: boolean;
|
|
637
|
-
mode?: string;
|
|
638
|
-
};
|
|
639
|
-
packageCheck?: {
|
|
640
|
-
enabled?: boolean;
|
|
641
|
-
onMalicious?: string;
|
|
642
|
-
};
|
|
643
|
-
/** Shields the host actually injected (`policy.appliedShields`). */
|
|
644
|
-
appliedShields?: readonly string[];
|
|
872
|
+
interface DlpPattern {
|
|
873
|
+
name: string;
|
|
874
|
+
regex: RegExp;
|
|
875
|
+
severity: 'block' | 'review';
|
|
876
|
+
/** Lowercase keyword substrings — if none found in the string, skip regex entirely. */
|
|
877
|
+
keywords?: string[];
|
|
645
878
|
/**
|
|
646
|
-
*
|
|
647
|
-
*
|
|
648
|
-
* above; a value below a row's floor is raised to the floor.
|
|
879
|
+
* When true, a 'review' finding is promoted to 'block' if the string is in
|
|
880
|
+
* assignment context (e.g. export TOKEN=..., password: ..., api_key = ...).
|
|
649
881
|
*/
|
|
650
|
-
|
|
882
|
+
contextBoost?: boolean;
|
|
883
|
+
/**
|
|
884
|
+
* Minimum Shannon entropy (bits/char) the matched token must have.
|
|
885
|
+
* Suppresses obvious placeholders and sequential values (e.g. sk-aaaaaaaaaa…).
|
|
886
|
+
* Only set on broad patterns where the regex alone can't distinguish real secrets.
|
|
887
|
+
*/
|
|
888
|
+
minEntropy?: number;
|
|
889
|
+
/**
|
|
890
|
+
* Structural validator run on the matched token (checksum, version byte).
|
|
891
|
+
* When present it DECIDES: a passing validator accepts the match outright,
|
|
892
|
+
* skipping the stopword and entropy heuristics (a checksum-valid token that
|
|
893
|
+
* happens to contain a stopword substring is a real secret, roughly 1 in
|
|
894
|
+
* 3,000 real WIF keys); a failing one rejects it. Must never throw; a throw
|
|
895
|
+
* is treated as "not suppressed" so a validator bug cannot hide a match.
|
|
896
|
+
* `before` is up to 64 characters of the text ahead of the match, for a
|
|
897
|
+
* validator that reads the variable name the value is assigned to.
|
|
898
|
+
*/
|
|
899
|
+
validate?: (raw: string, before?: string) => boolean;
|
|
900
|
+
/** When the regex consumes delimiters around the secret, the capture group
|
|
901
|
+
* that holds the secret itself; redactText replaces only that group. Any
|
|
902
|
+
* other capture group (a scheme, a prefix) is NOT the secret, so the field
|
|
903
|
+
* is explicit rather than "group 1 if present". */
|
|
904
|
+
redactGroup?: number;
|
|
905
|
+
/**
|
|
906
|
+
* Only the bounded tool-argument gate (matchArgumentText, reached through
|
|
907
|
+
* inspectArgumentSecrets / scanArgumentSecrets) uses this pattern. The raw
|
|
908
|
+
* scanners skip it: scanArgs (prompts, tool output, history scans, audit
|
|
909
|
+
* attribution), scanText (response text) and redactText (output
|
|
910
|
+
* redaction). For the broad, context-based patterns that name a secret by
|
|
911
|
+
* its variable or query key: a review on a tool call is cheap, a hard block
|
|
912
|
+
* on a prompt or a rewrite of every file an agent reads is not.
|
|
913
|
+
*/
|
|
914
|
+
argumentsOnly?: boolean;
|
|
651
915
|
}
|
|
652
|
-
|
|
653
|
-
* default: the merged config carries every default as an explicit value, so
|
|
654
|
-
* "set" and "unset" cannot be told apart, and the departure is what a reader
|
|
655
|
-
* wants to know. A pack row never claims a source; its value says whether the
|
|
656
|
-
* pack is on. */
|
|
916
|
+
declare const DLP_PATTERNS: DlpPattern[];
|
|
657
917
|
/**
|
|
658
|
-
*
|
|
659
|
-
*
|
|
660
|
-
*
|
|
918
|
+
* Pure: tests an already-resolved absolute path against the sensitive-file
|
|
919
|
+
* blocklist. Symlink resolution is the host's job — it's I/O and lives in
|
|
920
|
+
* the proxy's scanFilePath wrapper.
|
|
921
|
+
*
|
|
922
|
+
* @param resolvedPath Absolute path, ideally with symlinks resolved by the host.
|
|
923
|
+
* @param originalPath The path as the user/agent wrote it. Used in the
|
|
924
|
+
* redactedSample so alerts show the original spelling.
|
|
925
|
+
* @returns A DlpMatch with severity 'block' if the path is sensitive, else null.
|
|
661
926
|
*/
|
|
662
|
-
declare function
|
|
663
|
-
|
|
664
|
-
}
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
927
|
+
declare function matchSensitivePath(resolvedPath: string, originalPath: string, options?: {
|
|
928
|
+
systemAccessHandled?: boolean;
|
|
929
|
+
}): DlpMatch | null;
|
|
930
|
+
/** Exposed so the proxy's I/O wrapper can build the same fail-closed match. */
|
|
931
|
+
declare function sensitivePathMatch(originalPath: string): DlpMatch;
|
|
932
|
+
/** Exposed so the proxy can apply the same patterns directly if needed. */
|
|
933
|
+
declare const SENSITIVE_PATH_REGEXES: readonly RegExp[];
|
|
934
|
+
/**
|
|
935
|
+
* The bounds scanArgs works within, published so callers can tell "scanned
|
|
936
|
+
* clean" apart from "never looked". A caller that must FAIL CLOSED on an
|
|
937
|
+
* unscanned value (e.g. the audit writer, which would otherwise persist an
|
|
938
|
+
* unexamined credential in plaintext) needs these to decide whether the scan
|
|
939
|
+
* actually covered its input. Exported rather than duplicated at the call
|
|
940
|
+
* site so the two can never drift apart.
|
|
941
|
+
*/
|
|
942
|
+
declare const DLP_SCAN_LIMITS: {
|
|
943
|
+
/** Max characters examined per individual string field; the remainder of an
|
|
944
|
+
* oversized string is NOT scanned. */
|
|
945
|
+
readonly maxStringBytes: 100000;
|
|
946
|
+
/** Max nesting depth walked; anything deeper is NOT scanned. */
|
|
947
|
+
readonly maxDepth: 5;
|
|
948
|
+
};
|
|
949
|
+
declare function scanArgs(args: unknown, depth?: number, fieldPath?: string): DlpMatch | null;
|
|
950
|
+
/** Scan a plain text string (e.g. Claude response prose) for DLP patterns. */
|
|
951
|
+
declare function scanText(text: string): DlpMatch | null;
|
|
952
|
+
declare function redactText(text: string): {
|
|
953
|
+
result: string;
|
|
954
|
+
found: string[];
|
|
955
|
+
};
|
|
956
|
+
|
|
957
|
+
type PackageEcosystem = 'npm' | 'PyPI';
|
|
958
|
+
interface PackageInstallRequest {
|
|
959
|
+
ecosystem: PackageEcosystem;
|
|
960
|
+
/** The front-end that would install it: npm, pnpm, yarn, bun, npx, pip, uv, poetry … */
|
|
961
|
+
manager: string;
|
|
962
|
+
/** Registry name, normalised: npm as written (scope kept); PyPI per PEP 503. */
|
|
963
|
+
name: string;
|
|
964
|
+
/** Exact pinned version when the spec names one; otherwise undefined. */
|
|
965
|
+
version?: string;
|
|
966
|
+
/** The argument as written. */
|
|
967
|
+
raw: string;
|
|
968
|
+
/** Literal cd steps before this call; null means the execution context is unknown. */
|
|
969
|
+
localCwd?: string[] | null;
|
|
670
970
|
}
|
|
971
|
+
/** PEP 503 normalisation: lowercase, runs of `-_.` collapse to `-`. */
|
|
972
|
+
declare function normalizePyPiName(name: string): string;
|
|
671
973
|
/**
|
|
672
|
-
*
|
|
673
|
-
*
|
|
674
|
-
* `
|
|
675
|
-
*
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
/** Every check resolved, in catalog order. */
|
|
679
|
-
declare function resolveAllChecks(settings: CatalogSettings): ResolvedCheck[];
|
|
680
|
-
/**
|
|
681
|
-
* The value a detector should act on: an explicit `checks[id]` entry when
|
|
682
|
-
* the settings carry one (raised to the row's floor), else the legacy
|
|
683
|
-
* resolution. Detectors call this and nothing else, so a check's value is
|
|
684
|
-
* decided in one place whatever file or payload it came from.
|
|
974
|
+
* Every registry package the command would install or run, in command order.
|
|
975
|
+
* Walks every simple command in the AST (so `cd x && npm i evil | tee log`
|
|
976
|
+
* still yields `evil`), and re-reads the script of `sh -c` / `bash -lc` /
|
|
977
|
+
* `eval` up to three levels deep. A command that does not parse yields
|
|
978
|
+
* nothing — the check fails open by construction; the policy engine's other
|
|
979
|
+
* detectors keep their own fallbacks.
|
|
685
980
|
*/
|
|
686
|
-
declare function
|
|
687
|
-
/** Resolve every check the way `checkValue` would, as one map. The host
|
|
688
|
-
* stores this on its config so every reader sees the same answers. */
|
|
689
|
-
declare function resolveCheckMap(settings: CatalogSettings): Record<string, Verdict>;
|
|
981
|
+
declare function extractPackageInstalls(command: string): PackageInstallRequest[];
|
|
690
982
|
|
|
691
983
|
interface CheckText {
|
|
692
984
|
plain: string;
|
|
@@ -784,74 +1076,6 @@ declare function configurableValues(id: string): readonly Verdict[];
|
|
|
784
1076
|
/** The ids a config file or a workspace can state today. */
|
|
785
1077
|
declare const CONFIGURABLE_CHECK_IDS: readonly string[];
|
|
786
1078
|
|
|
787
|
-
/**
|
|
788
|
-
* A destination a tool call will reach, whichever carrier declared it: a
|
|
789
|
-
* shell command (extractShellDestinations) or a tool argument
|
|
790
|
-
* (extractToolDestinations). The interface is still spelled ShellDestination
|
|
791
|
-
* where it lives (shell/index.ts, which is hashed by the extractor-version
|
|
792
|
-
* gate, so a rename there is not free); this is the name that says what the
|
|
793
|
-
* shape is for.
|
|
794
|
-
*/
|
|
795
|
-
type Destination = ShellDestination;
|
|
796
|
-
interface EgressPolicy {
|
|
797
|
-
/** Master switch. Default false — opt-in, like dlp.pii. */
|
|
798
|
-
enabled: boolean;
|
|
799
|
-
/** Verdict for an UNKNOWN host (not in allow, not in deny, not private). */
|
|
800
|
-
mode: 'off' | 'review' | 'block';
|
|
801
|
-
/** Host globs always allowed (e.g. "*.github.com", "api.openai.com"). */
|
|
802
|
-
allow: string[];
|
|
803
|
-
/** Host globs always blocked — wins over allow/private. */
|
|
804
|
-
deny: string[];
|
|
805
|
-
/** Auto-allow localhost / RFC1918 / *.local. Default true. */
|
|
806
|
-
allowPrivate: boolean;
|
|
807
|
-
/** SSRF floor: exempts OVERRIDABLE tiers only (carrier-grade NAT, and
|
|
808
|
-
* loopback/RFC1918 when ssrfStrict is on). A tier-1 entry is ignored here
|
|
809
|
-
* and rejected at config load with a reason. */
|
|
810
|
-
ssrfAllow?: readonly string[];
|
|
811
|
-
/** SSRF floor tier 3: also block loopback and RFC1918. Off by default,
|
|
812
|
-
* because a developer talks to those constantly (72 of 308 destinations on
|
|
813
|
-
* measured real history). */
|
|
814
|
-
ssrfStrict?: boolean;
|
|
815
|
-
}
|
|
816
|
-
interface EgressVerdict {
|
|
817
|
-
verdict: 'block' | 'review';
|
|
818
|
-
host: string;
|
|
819
|
-
binary: string;
|
|
820
|
-
reason: string;
|
|
821
|
-
}
|
|
822
|
-
declare const DEFAULT_EGRESS_ALLOWLIST: readonly string[];
|
|
823
|
-
/** Glob host match: "*" = any, "*.x" = apex x + any subdomain, else exact. */
|
|
824
|
-
declare function hostMatches(host: string, pattern: string): boolean;
|
|
825
|
-
/**
|
|
826
|
-
* "Private" for the allowPrivate opt-in: loopback, RFC1918 and its IPv6
|
|
827
|
-
* analogue, the unspecified address, and the conventional local suffixes.
|
|
828
|
-
*
|
|
829
|
-
* The address half is classifySsrf's answer, so every spelling that file
|
|
830
|
-
* normalizes (brackets, zone id, IPv4-mapped IPv6) is one spelling here too.
|
|
831
|
-
* The old body had its own IPv4-only regexes and returned false for `[::1]`,
|
|
832
|
-
* which BLOCKED a local IPv6 dev server under allowPrivate (measured
|
|
833
|
-
* 2026-09-20; the shell extractor keeps the brackets, the declared-URL
|
|
834
|
-
* extractor strips them, and this function knew neither). Two parsers for
|
|
835
|
-
* one question is how that happens.
|
|
836
|
-
*
|
|
837
|
-
* NOT private here: link-local, multicast, the metadata endpoints. Those are
|
|
838
|
-
* the SSRF floor's tiers and allowPrivate must not be able to reach them;
|
|
839
|
-
* evaluateEgress documents that the floor runs first, and this function
|
|
840
|
-
* agrees with it rather than relying on it. CGNAT (100.64/10) is also out:
|
|
841
|
-
* a mesh-VPN peer is not everyone's private network, which is why the floor
|
|
842
|
-
* gave it its own tier; a Tailscale user lists the range in `allow`.
|
|
843
|
-
*/
|
|
844
|
-
declare function isPrivateHost(host: string): boolean;
|
|
845
|
-
/**
|
|
846
|
-
* Evaluate extracted destinations against the egress policy. Precedence per
|
|
847
|
-
* host: deny (block) > private-allow > allow/default-allow (skip) > unknown
|
|
848
|
-
* (policy.mode). Returns the most severe actionable verdict across all
|
|
849
|
-
* destinations — a deny or block-mode-unknown short-circuits; otherwise the
|
|
850
|
-
* first review; null if everything is allowed (or policy disabled / mode off).
|
|
851
|
-
* Pure.
|
|
852
|
-
*/
|
|
853
|
-
declare function evaluateEgress(dests: readonly Destination[], policy: EgressPolicy): EgressVerdict | null;
|
|
854
|
-
|
|
855
1079
|
interface PipeChainAnalysis {
|
|
856
1080
|
isPipeline: boolean;
|
|
857
1081
|
hasSensitiveSource: boolean;
|
|
@@ -903,146 +1127,6 @@ declare function extractPositionalArgs(tokens: string[], binary: string): string
|
|
|
903
1127
|
*/
|
|
904
1128
|
declare function extractNetworkTargets(tokens: string[], binary: string): string[];
|
|
905
1129
|
|
|
906
|
-
interface PolicyConfig {
|
|
907
|
-
policy: {
|
|
908
|
-
sandboxPaths: string[];
|
|
909
|
-
dangerousWords: string[];
|
|
910
|
-
ignoredTools: string[];
|
|
911
|
-
toolInspection: Record<string, string>;
|
|
912
|
-
smartRules: SmartRule[];
|
|
913
|
-
dlp: {
|
|
914
|
-
enabled: boolean;
|
|
915
|
-
scanIgnoredTools: boolean;
|
|
916
|
-
/** Inline-ask v2: 'block' upgrades review-severity DLP matches to a hard
|
|
917
|
-
* block. Optional for back-compat with callers that don't set it. */
|
|
918
|
-
reviewAction?: 'review' | 'block';
|
|
919
|
-
};
|
|
920
|
-
/** Egress / destination control (GAP-5). Optional for back-compat with
|
|
921
|
-
* callers/tests that build a PolicyConfig without it. */
|
|
922
|
-
egress?: EgressPolicy;
|
|
923
|
-
/** Command-checks governance (command-checks-governance-spec.md): admin
|
|
924
|
-
* knobs for the built-in detections' REVIEW-severity findings only.
|
|
925
|
-
* Block-severity findings (pipe-critical, eval-remote, rm-rf-home,
|
|
926
|
-
* nuclear, suspect binary) have NO key here — non-weakenable by
|
|
927
|
-
* construction. Class-B keys (evalDynamic, pipeChainHigh) exclude 'off'.
|
|
928
|
-
* rmAdvisory is consumed by the PROXY at advisory-rule injection. */
|
|
929
|
-
commandChecks?: {
|
|
930
|
-
inlineExec?: 'off' | 'review' | 'block';
|
|
931
|
-
rmAdvisory?: 'off' | 'review' | 'block';
|
|
932
|
-
chmod?: 'off' | 'review' | 'block';
|
|
933
|
-
sqlDdl?: 'off' | 'review' | 'block';
|
|
934
|
-
evalDynamic?: 'review' | 'block';
|
|
935
|
-
pipeChainHigh?: 'review' | 'block';
|
|
936
|
-
};
|
|
937
|
-
/**
|
|
938
|
-
* Per-check values keyed by catalog id (`commands.sudo`: `off`), the
|
|
939
|
-
* resolved map the host builds from its config file(s). Wins over the
|
|
940
|
-
* legacy knobs above. Absent for a caller that still builds the legacy
|
|
941
|
-
* shape by hand; the catalog then answers from those knobs.
|
|
942
|
-
*/
|
|
943
|
-
checks?: Record<string, string>;
|
|
944
|
-
};
|
|
945
|
-
settings: {
|
|
946
|
-
mode: string;
|
|
947
|
-
};
|
|
948
|
-
}
|
|
949
|
-
interface PolicyContext {
|
|
950
|
-
/** "Terminal" disables most blocks (manual user typing). */
|
|
951
|
-
agent?: string;
|
|
952
|
-
/** Working directory passed through to provenance hook. */
|
|
953
|
-
cwd?: string;
|
|
954
|
-
/**
|
|
955
|
-
* Resolved environment block from getActiveEnvironment() in the host.
|
|
956
|
-
* If `requireApproval === false`, strict mode skips the catch-all review.
|
|
957
|
-
*/
|
|
958
|
-
activeEnvironment?: {
|
|
959
|
-
requireApproval?: boolean;
|
|
960
|
-
};
|
|
961
|
-
/**
|
|
962
|
-
* Task #20: evaluate the full rule chain even for an ignoredTools match.
|
|
963
|
-
* Set by the orchestrator's jail guard AFTER it has already found a
|
|
964
|
-
* jailed/sensitive path in a file-tool call — without this, the tier-1
|
|
965
|
-
* fast path below returns 'allow' before the jail shield's `tool:'*'`
|
|
966
|
-
* rules are ever consulted, making the jail engine-invisible to
|
|
967
|
-
* Read/Grep/Glob. Opt-in per call; never set on the hot path.
|
|
968
|
-
*/
|
|
969
|
-
skipIgnoredFastPath?: boolean;
|
|
970
|
-
}
|
|
971
|
-
type ProvenanceTrust = 'system' | 'managed' | 'user' | 'suspect' | 'unknown';
|
|
972
|
-
interface ProvenanceLookup {
|
|
973
|
-
resolvedPath: string;
|
|
974
|
-
trustLevel: ProvenanceTrust;
|
|
975
|
-
reason: string;
|
|
976
|
-
}
|
|
977
|
-
interface PolicyHostHooks {
|
|
978
|
-
/** Resolves an absolute binary path to a trust classification. */
|
|
979
|
-
checkProvenance?: (binary: string, cwd?: string) => ProvenanceLookup;
|
|
980
|
-
/** Returns true if the host is on the user's trusted-hosts allowlist. */
|
|
981
|
-
isTrustedHost?: (host: string) => boolean;
|
|
982
|
-
}
|
|
983
|
-
interface PolicyVerdict {
|
|
984
|
-
decision: 'allow' | 'review' | 'block';
|
|
985
|
-
blockedByLabel?: string;
|
|
986
|
-
reason?: string;
|
|
987
|
-
matchedField?: string;
|
|
988
|
-
matchedWord?: string;
|
|
989
|
-
tier?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
|
|
990
|
-
/**
|
|
991
|
-
* False when NO human may override this verdict: the SSRF tier-1 floors,
|
|
992
|
-
* whose own reason string already tells the user "This address cannot be
|
|
993
|
-
* allowlisted". Absent means an override is a legitimate product decision,
|
|
994
|
-
* which is every other verdict.
|
|
995
|
-
*
|
|
996
|
-
* It exists because the host downgrades a hard block into a review whenever a
|
|
997
|
-
* human approver is reachable (orchestrator.ts, `mayDowngrade`). That is right
|
|
998
|
-
* for a smart-rule block and wrong for a floor, and the host could not tell
|
|
999
|
-
* the two apart: `overridable` was computed in egress/ssrf.ts, rendered into
|
|
1000
|
-
* the reason sentence, and then dropped here.
|
|
1001
|
-
*/
|
|
1002
|
-
overridable?: boolean;
|
|
1003
|
-
ruleName?: string;
|
|
1004
|
-
/**
|
|
1005
|
-
* True on an `allow` that records a finding: the check is set to `log`, so
|
|
1006
|
-
* the call runs and the audit row names the check (through ruleName and
|
|
1007
|
-
* checkId), but nothing stops. Never set together with review or block.
|
|
1008
|
-
*/
|
|
1009
|
-
logged?: boolean;
|
|
1010
|
-
/**
|
|
1011
|
-
* The catalog check this verdict belongs to (`commands.sudo`,
|
|
1012
|
-
* `data.secrets`, ...). Set on every non-allow verdict a built-in detector,
|
|
1013
|
-
* a product rule or a pack rule produces; absent on an allow and on a user
|
|
1014
|
-
* or organisation rule, which are rules, not checks. See catalog.ts.
|
|
1015
|
-
*/
|
|
1016
|
-
checkId?: string;
|
|
1017
|
-
/** State predicates from the matched smart rule (only when decision is 'block'). */
|
|
1018
|
-
dependsOnStatePredicates?: string[];
|
|
1019
|
-
/** Recovery command to suggest when this rule hard-blocks (from SmartRule.recoveryCommand). */
|
|
1020
|
-
recoveryCommand?: string;
|
|
1021
|
-
/** Plain-English description of what the rule does (from SmartRule.description). */
|
|
1022
|
-
ruleDescription?: string;
|
|
1023
|
-
}
|
|
1024
|
-
/**
|
|
1025
|
-
* Resolve which of several MATCHING smart rules decides the verdict (the
|
|
1026
|
-
* pinned-only conflict engine, Phase 3b). The model:
|
|
1027
|
-
* 1. If any matching rule is `pinned` (a manager "keep mine" cloud rule),
|
|
1028
|
-
* only the pinned rules compete and the MOST-RESTRICTIVE pinned wins
|
|
1029
|
-
* (block > review > allow) — so a manager's locked rule can't be
|
|
1030
|
-
* overridden by a developer's local rule.
|
|
1031
|
-
* 2. Otherwise the FIRST match wins — byte-for-byte the previous `.find()`
|
|
1032
|
-
* behaviour. This is the zero-regression guarantee: with nothing pinned,
|
|
1033
|
-
* nothing changes.
|
|
1034
|
-
* Exported so the resolution is unit-testable in isolation.
|
|
1035
|
-
*/
|
|
1036
|
-
declare function resolvePinned(matches: SmartRule[]): SmartRule | undefined;
|
|
1037
|
-
/**
|
|
1038
|
-
* Checks a SQL string for dangerous unscoped mutations.
|
|
1039
|
-
* Returns a reason string if dangerous, null if safe.
|
|
1040
|
-
*/
|
|
1041
|
-
declare function checkDangerousSql(sql: string): string | null;
|
|
1042
|
-
declare function evaluatePolicy(config: PolicyConfig, toolName: string, args?: unknown, context?: PolicyContext, hooks?: PolicyHostHooks): Promise<PolicyVerdict>;
|
|
1043
|
-
/** Returns true when toolName matches the config's ignoredTools list. */
|
|
1044
|
-
declare function isIgnoredTool(toolName: string, config: PolicyConfig): boolean;
|
|
1045
|
-
|
|
1046
1130
|
/**
|
|
1047
1131
|
* Glob match a tool name against one pattern or a list, with case-insensitive
|
|
1048
1132
|
* matching and a leading-`./` tolerance: `./bin/foo` matches `bin/foo` and
|
|
@@ -1695,7 +1779,7 @@ interface ExtractContext {
|
|
|
1695
1779
|
}>;
|
|
1696
1780
|
/** toolInspection map from PolicyConfig — drives shell-command extraction
|
|
1697
1781
|
* for tools that aren't the standard 'bash' name. Defaults handled by caller. */
|
|
1698
|
-
toolInspection:
|
|
1782
|
+
toolInspection: ToolInspection;
|
|
1699
1783
|
/** DLP enabled flag from PolicyConfig. */
|
|
1700
1784
|
dlpEnabled: boolean;
|
|
1701
1785
|
/** Decoy credentials registered on this machine (value plus kind and plant
|
|
@@ -1753,7 +1837,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
|
|
|
1753
1837
|
* and fails CI when the hash drifts without a version bump — forgetting
|
|
1754
1838
|
* is loud, not silent.
|
|
1755
1839
|
*/
|
|
1756
|
-
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-
|
|
1840
|
+
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
|
|
1757
1841
|
/**
|
|
1758
1842
|
* SHA-256 prefix of the detector-source files
|
|
1759
1843
|
* (canonical.ts + pii.ts + destructive-regex.ts).
|
|
@@ -1764,7 +1848,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v21";
|
|
|
1764
1848
|
* files changed, this hash must change too, and you must consciously
|
|
1765
1849
|
* decide whether to bump CANONICAL_EXTRACTOR_VERSION."
|
|
1766
1850
|
*/
|
|
1767
|
-
declare const CANONICAL_EXTRACTOR_HASH = "
|
|
1851
|
+
declare const CANONICAL_EXTRACTOR_HASH = "d734bd7389fbaf7e";
|
|
1768
1852
|
declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
|
|
1769
1853
|
declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
|
|
1770
1854
|
/**
|
|
@@ -1836,7 +1920,41 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
|
|
|
1836
1920
|
ssrfAllow?: readonly string[];
|
|
1837
1921
|
}): DestinationHit | null;
|
|
1838
1922
|
|
|
1923
|
+
declare const ARGUMENT_SCAN_LIMITS: {
|
|
1924
|
+
readonly maxDepth: 12;
|
|
1925
|
+
readonly maxNodes: 16384;
|
|
1926
|
+
/** Raw text is matched in windows of this size; decoding views use the first window. */
|
|
1927
|
+
readonly maxStringCharacters: 100000;
|
|
1928
|
+
/** Windows overlap by this much so a token on a window edge is still seen whole. */
|
|
1929
|
+
readonly windowOverlap: 4096;
|
|
1930
|
+
/** Budget for the first window of every string, so one large field cannot starve the rest. */
|
|
1931
|
+
readonly maxSourceBytes: 1048576;
|
|
1932
|
+
/** Separate budget for the text beyond each string's first window. */
|
|
1933
|
+
readonly maxTailBytes: 4194304;
|
|
1934
|
+
readonly maxJsonCharacters: 10000;
|
|
1935
|
+
};
|
|
1936
|
+
interface ArgumentInspectionResult {
|
|
1937
|
+
match: DlpMatch | null;
|
|
1938
|
+
/**
|
|
1939
|
+
* `incomplete` when any part of the input was not fully inspected. Reasons
|
|
1940
|
+
* starting with `argument-` mean raw text or structure was skipped; reasons
|
|
1941
|
+
* starting with `decode-` mean every byte of raw text was matched but the
|
|
1942
|
+
* derived decoding views were cut short.
|
|
1943
|
+
*/
|
|
1944
|
+
coverage: 'complete' | 'incomplete';
|
|
1945
|
+
reasons: string[];
|
|
1946
|
+
}
|
|
1947
|
+
/** Bounded input inspection. Output redaction deliberately retains its own API. */
|
|
1948
|
+
declare function inspectArgumentSecrets(args: unknown): ArgumentInspectionResult;
|
|
1949
|
+
/**
|
|
1950
|
+
* Existing DLP approval routing. A finding wins. Otherwise raw text or
|
|
1951
|
+
* structure that was skipped (`argument-*` reasons) requires review; a cut
|
|
1952
|
+
* short decoding budget over fully matched raw text does not interrupt the
|
|
1953
|
+
* call, because ordinary documents full of links or hashes exhaust it.
|
|
1954
|
+
*/
|
|
1955
|
+
declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
|
|
1956
|
+
|
|
1839
1957
|
/** Engine version stamped on audit entries for future drift detection. */
|
|
1840
1958
|
declare const ENGINE_VERSION = "1.4.0";
|
|
1841
1959
|
|
|
1842
|
-
export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, type CatalogSettings, type CheckDef, type CheckGroup, type CheckSource, type CheckText, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PackageEcosystem, type PackageInstallRequest, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type ResolvedCheck, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, type ScanFinding, type ScanSignals, type ScanSummary, type ScanView, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, TUNING_FIELDS, type ToolCallEntry, type ToolCallRecord, type TuningField, VERDICTS, type Verdict, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifySsrf, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isKnobGoverned, isLockedCheck, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeForScan, normalizeIpLiteral, normalizePyPiName, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, safeMessage, sampleCopyCommand, scanArgs, scanInjection, scanText, scanViews, sensitivePathMatch, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
|
|
1960
|
+
export { ARGUMENT_SCAN_LIMITS, AST_FS_REGEX_RULES, type ArgumentInspectionResult, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_DANGEROUS_WORDS, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, CHECKS, CHECK_BY_ID, CHECK_GROUPS, CHECK_TEXT, CHECK_VERDICT_RANK, COMMAND_WRAPPERS, CONFIGURABLE_CHECK_IDS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, type CatalogSettings, type CheckDef, type CheckGroup, type CheckSource, type CheckText, DEFAULT_EGRESS_ALLOWLIST, DESTINATION_ARGS, DESTRUCTIVE_OP_RE, DLP_PATTERNS, DLP_SCAN_LIMITS, type Destination, type DlpMatch, ENGINE_VERSION, type EgressPolicy, type EgressVerdict, type ExtractContext, FILE_TOOLS, FLAGS_WITH_VALUES, FS_READ_TOOLS, type FileAccess, type FileAccessContext, type FsOpVerdict, type InjectionConfidence, type InjectionContext, type InjectionMatch, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PackageEcosystem, type PackageInstallRequest, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProtectedFileVerdict, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type ResolvedCheck, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, STARTUP_NAMES, SYSTEM_AUTH_DIRS, SYSTEM_AUTH_FILES, type ScanFinding, type ScanSignals, type ScanSummary, type ScanView, type ScoreTier, type SessionExtractContext, type SessionToolCall, type Severity, type ShellCommandAnalysis, type ShellDestToken, type ShellDestination, type ShellInputResolution, type ShieldDefinition, type ShieldOverrides, type ShieldVerdict, type SmartCondition, type SmartRule, type SsrfFloorOptions, type SsrfMatch, type SsrfTier, type SsrfVerdict, TUNING_FIELDS, type ToolCallEntry, type ToolCallRecord, type ToolInspection, type ToolInspectionEntry, type TuningField, VERDICTS, type Verdict, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, catalogSettingsFromConfig, checkDangerousSql, checkIdForCheckedBy, checkIdForRule, checkToLegacyPolicy, checkValue, checksFromLegacyPolicy, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, isBashTool, isIgnoredTool, isKnobGoverned, isLegacySystemPath, isLockedCheck, isPasswordHashPath, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, isVerdict, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeFilePath, normalizeForScan, normalizeIpLiteral, normalizePyPiName, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolveAllChecks, resolveCheck, resolveCheckMap, resolvePinned, resolveShellInput, safeMessage, sampleCopyCommand, scanArgs, scanArgumentSecrets, scanInjection, scanText, scanViews, sensitivePathMatch, shellRuleArgs, ssrfCheckId, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripInvisible, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, tuningFromLegacyPolicy, tuningToLegacyPolicy, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
|