@node9/policy-engine 2.26.2 → 2.27.0-next.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/dist/index.d.mts +405 -94
- package/dist/index.d.ts +405 -94
- package/dist/index.js +3814 -1889
- package/dist/index.mjs +3778 -1889
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -62,6 +62,12 @@ interface SmartRule {
|
|
|
62
62
|
* resolved exactly as today (first match wins).
|
|
63
63
|
*/
|
|
64
64
|
pinned?: boolean;
|
|
65
|
+
/**
|
|
66
|
+
* Set by the host on the rules it ships (the default and advisory rules and
|
|
67
|
+
* a pack's rules). The catalog's per-check value governs ONLY these: a user
|
|
68
|
+
* rule that reuses a shipped name keeps its own verdict.
|
|
69
|
+
*/
|
|
70
|
+
builtin?: boolean;
|
|
65
71
|
}
|
|
66
72
|
/**
|
|
67
73
|
* Result of a DLP scan — either a single match or null. The redactedSample
|
|
@@ -119,6 +125,29 @@ interface InjectionContext {
|
|
|
119
125
|
*/
|
|
120
126
|
declare function scanInjection(text: string, ctx?: InjectionContext): InjectionMatch | null;
|
|
121
127
|
|
|
128
|
+
/** Remove zero-width and other invisible code points. */
|
|
129
|
+
declare function stripInvisible(text: string): string;
|
|
130
|
+
/** NFKC-fold, then map lookalike Cyrillic/Greek letters onto Latin. */
|
|
131
|
+
declare function foldHomoglyphs(text: string): string;
|
|
132
|
+
/** The scanner's normalised reading: invisibles stripped, lookalikes folded. */
|
|
133
|
+
declare function normalizeForScan(text: string): string;
|
|
134
|
+
/** Decode every base64 / base64url run of 32+ characters that decodes to text. */
|
|
135
|
+
declare function decodeEmbeddedBase64(text: string): string[];
|
|
136
|
+
/** Decode hex runs (48+ digits) and `\xNN` escape runs that decode to text. */
|
|
137
|
+
declare function decodeEmbeddedHex(text: string): string[];
|
|
138
|
+
interface ScanView {
|
|
139
|
+
/** Which pass produced this text. `original` is the input itself. */
|
|
140
|
+
kind: 'original' | 'normalized' | 'base64' | 'hex';
|
|
141
|
+
text: string;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* Every reading of `text` the injection patterns should run on: the input,
|
|
145
|
+
* its normalised form (when it differs), and the normalised decoding of each
|
|
146
|
+
* embedded base64 and hex blob. Decoding is one level deep by design: a blob
|
|
147
|
+
* inside a blob is not decoded.
|
|
148
|
+
*/
|
|
149
|
+
declare function scanViews(text: string): ScanView[];
|
|
150
|
+
|
|
122
151
|
interface DlpPattern {
|
|
123
152
|
name: string;
|
|
124
153
|
regex: RegExp;
|
|
@@ -145,6 +174,11 @@ interface DlpPattern {
|
|
|
145
174
|
* is treated as "not suppressed" so a validator bug cannot hide a match.
|
|
146
175
|
*/
|
|
147
176
|
validate?: (raw: string) => boolean;
|
|
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;
|
|
148
182
|
}
|
|
149
183
|
declare const DLP_PATTERNS: DlpPattern[];
|
|
150
184
|
/**
|
|
@@ -402,6 +436,354 @@ interface ShellCommandAnalysis {
|
|
|
402
436
|
*/
|
|
403
437
|
declare function analyzeShellCommand(command: string): ShellCommandAnalysis;
|
|
404
438
|
|
|
439
|
+
type PackageEcosystem = 'npm' | 'PyPI';
|
|
440
|
+
interface PackageInstallRequest {
|
|
441
|
+
ecosystem: PackageEcosystem;
|
|
442
|
+
/** The front-end that would install it: npm, pnpm, yarn, bun, npx, pip, uv, poetry … */
|
|
443
|
+
manager: string;
|
|
444
|
+
/** Registry name, normalised: npm as written (scope kept); PyPI per PEP 503. */
|
|
445
|
+
name: string;
|
|
446
|
+
/** Exact pinned version when the spec names one; otherwise undefined. */
|
|
447
|
+
version?: string;
|
|
448
|
+
/** The argument as written. */
|
|
449
|
+
raw: string;
|
|
450
|
+
}
|
|
451
|
+
/** PEP 503 normalisation: lowercase, runs of `-_.` collapse to `-`. */
|
|
452
|
+
declare function normalizePyPiName(name: string): string;
|
|
453
|
+
/**
|
|
454
|
+
* Every registry package the command would install or run, in command order.
|
|
455
|
+
* Walks every simple command in the AST (so `cd x && npm i evil | tee log`
|
|
456
|
+
* still yields `evil`), and re-reads the script of `sh -c` / `bash -lc` /
|
|
457
|
+
* `eval` up to three levels deep. A command that does not parse yields
|
|
458
|
+
* nothing — the check fails open by construction; the policy engine's other
|
|
459
|
+
* detectors keep their own fallbacks.
|
|
460
|
+
*/
|
|
461
|
+
declare function extractPackageInstalls(command: string): PackageInstallRequest[];
|
|
462
|
+
|
|
463
|
+
type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
|
|
464
|
+
interface SsrfMatch {
|
|
465
|
+
tier: SsrfTier;
|
|
466
|
+
/** false for tier 1: no allowlist entry exempts it. */
|
|
467
|
+
overridable: boolean;
|
|
468
|
+
/** 'address' when an IP literal matched, 'hostname' for the metadata name list. */
|
|
469
|
+
kind: 'address' | 'hostname';
|
|
470
|
+
/** The canonical address; absent for a hostname match. Never an empty string:
|
|
471
|
+
* an empty value is dropped in flight by cloud.ts and the audit shipper. */
|
|
472
|
+
normalized?: string;
|
|
473
|
+
}
|
|
474
|
+
/** Longest legal DNS name. The caller does NOT reliably bound this: a URL with a
|
|
475
|
+
* 261-character host reaches us intact (measured), so we bound our own input. */
|
|
476
|
+
declare const SSRF_MAX_HOST = 253;
|
|
477
|
+
/**
|
|
478
|
+
* Fold any spelling of an IP literal to one canonical address, or null when the
|
|
479
|
+
* input is not an IP literal (a hostname, or malformed). Never throws.
|
|
480
|
+
*
|
|
481
|
+
* IPv4-mapped IPv6 folds to the IPv4 address it denotes (RFC 4291 2.5.5.2), so
|
|
482
|
+
* `[::ffff:a9fe:a9fe]` and `169.254.169.254` compare equal. Brackets and a zone
|
|
483
|
+
* id are stripped here: the caller does NOT strip them (measured).
|
|
484
|
+
*/
|
|
485
|
+
declare function normalizeIpLiteral(host: string): string | null;
|
|
486
|
+
/** Is this tier reachable by default, waiting on the `ssrfStrict` knob?
|
|
487
|
+
* Exported so the non-shell path asks the SAME question rather than
|
|
488
|
+
* approximating it with `overridable`, which is a different property. */
|
|
489
|
+
declare function isStrictGatedTier(tier: SsrfTier): boolean;
|
|
490
|
+
/** The sentence a user reads when the floor stops them. One builder, so the
|
|
491
|
+
* shell path and the non-shell path cannot word the same block differently. */
|
|
492
|
+
declare function ssrfReason(m: SsrfMatch, asWritten: string): string;
|
|
493
|
+
/**
|
|
494
|
+
* Classify a destination host. Returns null when it is not a protected address,
|
|
495
|
+
* which means the ordinary egress policy decides. Never throws.
|
|
496
|
+
*
|
|
497
|
+
* Ordering is significant: the exact metadata addresses are checked before the
|
|
498
|
+
* link-local range that contains them, so the reason names metadata.
|
|
499
|
+
*/
|
|
500
|
+
declare function classifySsrf(host: string): SsrfMatch | null;
|
|
501
|
+
interface SsrfVerdict extends SsrfMatch {
|
|
502
|
+
/** The token as written in the command. */
|
|
503
|
+
host: string;
|
|
504
|
+
binary: string;
|
|
505
|
+
reason: string;
|
|
506
|
+
}
|
|
507
|
+
interface SsrfFloorOptions {
|
|
508
|
+
/** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
|
|
509
|
+
* rejected at config load with a reason, never silently). */
|
|
510
|
+
ssrfAllow?: readonly string[];
|
|
511
|
+
/** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
|
|
512
|
+
* those constantly (72 of 308 destinations on measured real history). */
|
|
513
|
+
ssrfStrict?: boolean;
|
|
514
|
+
}
|
|
515
|
+
/**
|
|
516
|
+
* Does this exemption list release this address?
|
|
517
|
+
*
|
|
518
|
+
* ONE function, because the shell floor and the declared-URL floor must answer
|
|
519
|
+
* identically. They had two spellings of it — `normalizeIpLiteral(e) ?? e.trim()
|
|
520
|
+
* .toLowerCase()` here and `classifySsrf(a)?.normalized ?? a` in
|
|
521
|
+
* destinations.ts — and for an entry classifySsrf does not match they already
|
|
522
|
+
* disagreed. Nothing depended on the difference, which is exactly when it is
|
|
523
|
+
* cheap to remove.
|
|
524
|
+
*
|
|
525
|
+
* An entry is an exact address or a CIDR range. The range form exists so an
|
|
526
|
+
* operator can exempt the mesh-VPN range they actually use (100.64.0.0/10)
|
|
527
|
+
* instead of listing peers one at a time, which is what the settings panel's
|
|
528
|
+
* "remove this default" control needs.
|
|
529
|
+
*
|
|
530
|
+
* ⚠ This answers "is it in the list", NOT "may it be released". The caller
|
|
531
|
+
* keeps its `m.overridable` guard, and that guard is per ADDRESS, decided by
|
|
532
|
+
* classifySsrf before this is consulted. So a range can never release a
|
|
533
|
+
* protected address inside it: 100.100.100.200 (Alibaba IMDS) sits inside
|
|
534
|
+
* 100.64.0.0/10 and is named in METADATA_ADDRESSES above the range check, so
|
|
535
|
+
* it classifies as metadata / overridable:false and stays blocked with the
|
|
536
|
+
* whole range exempted. Pinned by E2 in exempt-range.spec.ts.
|
|
537
|
+
*
|
|
538
|
+
* Never throws: this runs on the hook path for every tool call, and a bad
|
|
539
|
+
* entry in a hand-edited config must not break every command on the machine.
|
|
540
|
+
*/
|
|
541
|
+
declare function ssrfExemptMatches(entries: readonly string[] | undefined, normalized: string | undefined): boolean;
|
|
542
|
+
/**
|
|
543
|
+
* The floor. Returns the first protected destination, or null.
|
|
544
|
+
*
|
|
545
|
+
* Runs unconditionally: not gated on egress.enabled, mode, allow or allowPrivate.
|
|
546
|
+
* The one thing that does switch it off is `node9 pause`, which returns before
|
|
547
|
+
* every gate; that is stated as a limit rather than special-cased here.
|
|
548
|
+
*/
|
|
549
|
+
declare function ssrfFloor(tokens: ReadonlyArray<{
|
|
550
|
+
token: string;
|
|
551
|
+
binary: string;
|
|
552
|
+
}>, opts?: SsrfFloorOptions): SsrfVerdict | null;
|
|
553
|
+
|
|
554
|
+
/** The one value set every check uses. `log` runs the check and records the
|
|
555
|
+
* finding without stopping the call; it replaces skill pinning's `warn` and
|
|
556
|
+
* the per-check meaning of the global observe mode. */
|
|
557
|
+
type Verdict = 'off' | 'log' | 'review' | 'block';
|
|
558
|
+
declare const VERDICTS: readonly Verdict[];
|
|
559
|
+
declare const CHECK_VERDICT_RANK: Record<Verdict, number>;
|
|
560
|
+
declare function isVerdict(v: unknown): v is Verdict;
|
|
561
|
+
/** Groups are by what the user fears, not by the mechanism that catches it. */
|
|
562
|
+
type CheckGroup = 'commands' | 'data' | 'network' | 'files' | 'behavior' | 'loading';
|
|
563
|
+
declare const CHECK_GROUPS: readonly {
|
|
564
|
+
id: CheckGroup;
|
|
565
|
+
title: string;
|
|
566
|
+
}[];
|
|
567
|
+
interface CheckDef {
|
|
568
|
+
/** `group.name`, stable forever: audit rows and config files key on it. */
|
|
569
|
+
id: string;
|
|
570
|
+
group: CheckGroup;
|
|
571
|
+
title: string;
|
|
572
|
+
/** One line, shown under the title: what the check catches. */
|
|
573
|
+
catches: string;
|
|
574
|
+
/** What a user may pick, in order. */
|
|
575
|
+
values: readonly Verdict[];
|
|
576
|
+
defaultValue: Verdict;
|
|
577
|
+
/** Lowest value a user may pick. `block` means the check is locked. */
|
|
578
|
+
floor?: Verdict;
|
|
579
|
+
/** Set on a row a pack (a builtin shield) contributes; the row only exists
|
|
580
|
+
* while that pack is on. */
|
|
581
|
+
pack?: string;
|
|
582
|
+
/** Rule names and labels the code emits today for this check. Exact
|
|
583
|
+
* matches only; prefixed families are handled in `checkIdForRule`. */
|
|
584
|
+
legacy?: readonly string[];
|
|
585
|
+
/** Plain-language explanation (catalog-text.ts). */
|
|
586
|
+
plain?: string;
|
|
587
|
+
/** One concrete thing an agent might do that this check catches. */
|
|
588
|
+
example?: string;
|
|
589
|
+
/** When to change the default, and to what. */
|
|
590
|
+
advice?: string;
|
|
591
|
+
}
|
|
592
|
+
/** Words in the product's own dangerous-word list. Shields add their own. */
|
|
593
|
+
declare const BUILTIN_DANGEROUS_WORDS: readonly string[];
|
|
594
|
+
declare const CHECKS: readonly CheckDef[];
|
|
595
|
+
declare const CHECK_BY_ID: ReadonlyMap<string, CheckDef>;
|
|
596
|
+
declare function getCheck(id: string): CheckDef | undefined;
|
|
597
|
+
declare function isLockedCheck(def: CheckDef): boolean;
|
|
598
|
+
/** Which check an SSRF floor hit belongs to: the strict-gated tiers are the
|
|
599
|
+
* internal-address check, the rest are the locked metadata check. */
|
|
600
|
+
declare function ssrfCheckId(tier: SsrfTier): string;
|
|
601
|
+
/**
|
|
602
|
+
* The check behind a rule name or a verdict label the code emits today.
|
|
603
|
+
* Undefined for a user or organisation rule (`org:` and unnamed rules are
|
|
604
|
+
* rules, not checks) and for a label no check claims.
|
|
605
|
+
*/
|
|
606
|
+
declare function checkIdForRule(nameOrLabel: string | undefined): string | undefined;
|
|
607
|
+
/** The check behind an audit row's `checkedBy` tag, for rows whose verdict
|
|
608
|
+
* carried no rule name (the DLP, PII, loop and taint gates). */
|
|
609
|
+
declare function checkIdForCheckedBy(checkedBy: string | undefined): string | undefined;
|
|
610
|
+
/** The slice of the host config the resolver reads. The proxy's `Config`
|
|
611
|
+
* satisfies it structurally; the dashboard backend builds it from a row. */
|
|
612
|
+
interface CatalogSettings {
|
|
613
|
+
mode?: string;
|
|
614
|
+
commandChecks?: {
|
|
615
|
+
inlineExec?: string;
|
|
616
|
+
rmAdvisory?: string;
|
|
617
|
+
chmod?: string;
|
|
618
|
+
sqlDdl?: string;
|
|
619
|
+
evalDynamic?: string;
|
|
620
|
+
pipeChainHigh?: string;
|
|
621
|
+
};
|
|
622
|
+
dlp?: {
|
|
623
|
+
enabled?: boolean;
|
|
624
|
+
reviewAction?: string;
|
|
625
|
+
pii?: string;
|
|
626
|
+
};
|
|
627
|
+
egress?: {
|
|
628
|
+
enabled?: boolean;
|
|
629
|
+
mode?: string;
|
|
630
|
+
ssrfStrict?: boolean;
|
|
631
|
+
};
|
|
632
|
+
loopDetection?: {
|
|
633
|
+
enabled?: boolean;
|
|
634
|
+
};
|
|
635
|
+
injectionScan?: {
|
|
636
|
+
enabled?: boolean;
|
|
637
|
+
};
|
|
638
|
+
skillPinning?: {
|
|
639
|
+
enabled?: boolean;
|
|
640
|
+
mode?: string;
|
|
641
|
+
};
|
|
642
|
+
packageCheck?: {
|
|
643
|
+
enabled?: boolean;
|
|
644
|
+
onMalicious?: string;
|
|
645
|
+
};
|
|
646
|
+
/** Shields the host actually injected (`policy.appliedShields`). */
|
|
647
|
+
appliedShields?: readonly string[];
|
|
648
|
+
/**
|
|
649
|
+
* Explicit per-check values, keyed by check id: the v2 config file's
|
|
650
|
+
* `checks` map, or the host's resolved map. Wins over the legacy knobs
|
|
651
|
+
* above; a value below a row's floor is raised to the floor.
|
|
652
|
+
*/
|
|
653
|
+
checks?: Readonly<Record<string, string>>;
|
|
654
|
+
}
|
|
655
|
+
/** Where a value came from. `configured` means it departs from the shipped
|
|
656
|
+
* default: the merged config carries every default as an explicit value, so
|
|
657
|
+
* "set" and "unset" cannot be told apart, and the departure is what a reader
|
|
658
|
+
* wants to know. A pack row never claims a source; its value says whether the
|
|
659
|
+
* pack is on. */
|
|
660
|
+
/**
|
|
661
|
+
* The ONE projection from a host config (`settings` + `policy`) to what the
|
|
662
|
+
* resolver reads. The engine and the proxy both call it, so a new knob is
|
|
663
|
+
* threaded through once.
|
|
664
|
+
*/
|
|
665
|
+
declare function catalogSettingsFromConfig(settings: {
|
|
666
|
+
mode?: string;
|
|
667
|
+
}, policy: Omit<CatalogSettings, 'mode'>): CatalogSettings;
|
|
668
|
+
type CheckSource = 'default' | 'configured' | 'locked' | 'local' | 'project' | 'workspace';
|
|
669
|
+
interface ResolvedCheck {
|
|
670
|
+
id: string;
|
|
671
|
+
value: Verdict;
|
|
672
|
+
source: CheckSource;
|
|
673
|
+
}
|
|
674
|
+
/**
|
|
675
|
+
* The value in force for one check, read from today's config shape, and
|
|
676
|
+
* where it came from. A locked check always answers its floor. A pack row is
|
|
677
|
+
* `off` unless its pack is applied. Anything the config does not set is the
|
|
678
|
+
* catalog default.
|
|
679
|
+
*/
|
|
680
|
+
declare function resolveCheck(settings: CatalogSettings, id: string): ResolvedCheck | undefined;
|
|
681
|
+
/** Every check resolved, in catalog order. */
|
|
682
|
+
declare function resolveAllChecks(settings: CatalogSettings): ResolvedCheck[];
|
|
683
|
+
/**
|
|
684
|
+
* The value a detector should act on: an explicit `checks[id]` entry when
|
|
685
|
+
* the settings carry one (raised to the row's floor), else the legacy
|
|
686
|
+
* resolution. Detectors call this and nothing else, so a check's value is
|
|
687
|
+
* decided in one place whatever file or payload it came from.
|
|
688
|
+
*/
|
|
689
|
+
declare function checkValue(settings: CatalogSettings, id: string): Verdict;
|
|
690
|
+
/** Resolve every check the way `checkValue` would, as one map. The host
|
|
691
|
+
* stores this on its config so every reader sees the same answers. */
|
|
692
|
+
declare function resolveCheckMap(settings: CatalogSettings): Record<string, Verdict>;
|
|
693
|
+
|
|
694
|
+
interface CheckText {
|
|
695
|
+
plain: string;
|
|
696
|
+
example?: string;
|
|
697
|
+
advice: string;
|
|
698
|
+
}
|
|
699
|
+
declare const CHECK_TEXT: Readonly<Record<string, CheckText>>;
|
|
700
|
+
|
|
701
|
+
type Obj = Record<string, unknown>;
|
|
702
|
+
/** The legacy policy knobs, loosely typed: a config file, a managed config
|
|
703
|
+
* row and a merged Config all satisfy it. */
|
|
704
|
+
interface LegacyPolicyKnobs {
|
|
705
|
+
commandChecks?: Record<string, string | undefined>;
|
|
706
|
+
dlp?: {
|
|
707
|
+
enabled?: boolean;
|
|
708
|
+
pii?: string;
|
|
709
|
+
reviewAction?: string;
|
|
710
|
+
scanIgnoredTools?: boolean;
|
|
711
|
+
};
|
|
712
|
+
egress?: {
|
|
713
|
+
enabled?: boolean;
|
|
714
|
+
mode?: string;
|
|
715
|
+
ssrfStrict?: boolean;
|
|
716
|
+
allow?: string[];
|
|
717
|
+
deny?: string[];
|
|
718
|
+
allowPrivate?: boolean;
|
|
719
|
+
ssrfAllow?: string[];
|
|
720
|
+
};
|
|
721
|
+
loopDetection?: {
|
|
722
|
+
enabled?: boolean;
|
|
723
|
+
threshold?: number;
|
|
724
|
+
windowSeconds?: number;
|
|
725
|
+
};
|
|
726
|
+
injectionScan?: {
|
|
727
|
+
enabled?: boolean;
|
|
728
|
+
minConfidence?: string;
|
|
729
|
+
allow?: string[];
|
|
730
|
+
};
|
|
731
|
+
skillPinning?: {
|
|
732
|
+
enabled?: boolean;
|
|
733
|
+
mode?: string;
|
|
734
|
+
roots?: string[];
|
|
735
|
+
};
|
|
736
|
+
packageCheck?: {
|
|
737
|
+
enabled?: boolean;
|
|
738
|
+
onMalicious?: string;
|
|
739
|
+
registrySignals?: boolean;
|
|
740
|
+
maxAgeHours?: number;
|
|
741
|
+
onlineFallback?: boolean;
|
|
742
|
+
allow?: string[];
|
|
743
|
+
};
|
|
744
|
+
}
|
|
745
|
+
interface TuningField {
|
|
746
|
+
checkId: string;
|
|
747
|
+
/** Field name in the v2 tuning object. */
|
|
748
|
+
name: string;
|
|
749
|
+
/** Path under the legacy policy block. */
|
|
750
|
+
legacy: readonly [block: string, key: string];
|
|
751
|
+
}
|
|
752
|
+
declare const TUNING_FIELDS: readonly TuningField[];
|
|
753
|
+
/** Every tuning field a legacy policy block states, as `{ checkId: { name: value } }`. */
|
|
754
|
+
declare function tuningFromLegacyPolicy(policy: LegacyPolicyKnobs): Record<string, Obj>;
|
|
755
|
+
/** Write a tuning map into a legacy policy block. Returns the unknown
|
|
756
|
+
* `checkId.name` pairs it could not place. */
|
|
757
|
+
declare function tuningToLegacyPolicy(policy: Obj, tuning: Record<string, unknown>): string[];
|
|
758
|
+
/** Read the checks a legacy policy block states explicitly. */
|
|
759
|
+
declare function checksFromLegacyPolicy(policy: LegacyPolicyKnobs, mode?: string): Record<string, Verdict>;
|
|
760
|
+
/**
|
|
761
|
+
* Write one check's value into a legacy policy block. Returns false when the
|
|
762
|
+
* legacy shape cannot carry the value.
|
|
763
|
+
*/
|
|
764
|
+
declare function checkToLegacyPolicy(policy: Obj, id: string, v: Verdict): boolean;
|
|
765
|
+
/**
|
|
766
|
+
* Checks whose detector reads the resolved checks map: every value the
|
|
767
|
+
* catalog row offers works. Pack rows (`packs.*`) qualify too.
|
|
768
|
+
*/
|
|
769
|
+
declare const MAP_GOVERNED: ReadonlySet<string>;
|
|
770
|
+
/**
|
|
771
|
+
* Checks whose gate still reads a legacy knob: only the values that knob
|
|
772
|
+
* can carry.
|
|
773
|
+
*/
|
|
774
|
+
declare const KNOB_GOVERNED: Readonly<Record<string, readonly Verdict[]>>;
|
|
775
|
+
declare function isKnobGoverned(id: string): boolean;
|
|
776
|
+
/**
|
|
777
|
+
* The values a config file or a workspace may set for a check TODAY. Empty
|
|
778
|
+
* for a check whose detector reads neither the map nor a knob yet (the
|
|
779
|
+
* canary, the credential-file and taint gates, MCP pins, the jail): stating
|
|
780
|
+
* it would change nothing, and a screen would then show a value that is not
|
|
781
|
+
* in force. Those rows are "not configurable yet".
|
|
782
|
+
*/
|
|
783
|
+
declare function configurableValues(id: string): readonly Verdict[];
|
|
784
|
+
/** The ids a config file or a workspace can state today. */
|
|
785
|
+
declare const CONFIGURABLE_CHECK_IDS: readonly string[];
|
|
786
|
+
|
|
405
787
|
/**
|
|
406
788
|
* A destination a tool call will reach, whichever carrier declared it: a
|
|
407
789
|
* shell command (extractShellDestinations) or a tool argument
|
|
@@ -552,6 +934,13 @@ interface PolicyConfig {
|
|
|
552
934
|
evalDynamic?: 'review' | 'block';
|
|
553
935
|
pipeChainHigh?: 'review' | 'block';
|
|
554
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>;
|
|
555
944
|
};
|
|
556
945
|
settings: {
|
|
557
946
|
mode: string;
|
|
@@ -612,6 +1001,19 @@ interface PolicyVerdict {
|
|
|
612
1001
|
*/
|
|
613
1002
|
overridable?: boolean;
|
|
614
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;
|
|
615
1017
|
/** State predicates from the matched smart rule (only when decision is 'block'). */
|
|
616
1018
|
dependsOnStatePredicates?: string[];
|
|
617
1019
|
/** Recovery command to suggest when this rule hard-blocks (from SmartRule.recoveryCommand). */
|
|
@@ -1351,7 +1753,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
|
|
|
1351
1753
|
* and fails CI when the hash drifts without a version bump — forgetting
|
|
1352
1754
|
* is loud, not silent.
|
|
1353
1755
|
*/
|
|
1354
|
-
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-
|
|
1756
|
+
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v21";
|
|
1355
1757
|
/**
|
|
1356
1758
|
* SHA-256 prefix of the detector-source files
|
|
1357
1759
|
* (canonical.ts + pii.ts + destructive-regex.ts).
|
|
@@ -1362,7 +1764,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v20";
|
|
|
1362
1764
|
* files changed, this hash must change too, and you must consciously
|
|
1363
1765
|
* decide whether to bump CANONICAL_EXTRACTOR_VERSION."
|
|
1364
1766
|
*/
|
|
1365
|
-
declare const CANONICAL_EXTRACTOR_HASH = "
|
|
1767
|
+
declare const CANONICAL_EXTRACTOR_HASH = "efe6e39d25bedd78";
|
|
1366
1768
|
declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
|
|
1367
1769
|
declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
|
|
1368
1770
|
/**
|
|
@@ -1386,97 +1788,6 @@ declare function dedupeCanonicalFindings(findings: ReadonlyArray<CanonicalFindin
|
|
|
1386
1788
|
declare function toScanFinding(c: CanonicalFinding): ScanFinding | null;
|
|
1387
1789
|
declare function previewArgs(input: Record<string, unknown>, max: number): string;
|
|
1388
1790
|
|
|
1389
|
-
type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
|
|
1390
|
-
interface SsrfMatch {
|
|
1391
|
-
tier: SsrfTier;
|
|
1392
|
-
/** false for tier 1: no allowlist entry exempts it. */
|
|
1393
|
-
overridable: boolean;
|
|
1394
|
-
/** 'address' when an IP literal matched, 'hostname' for the metadata name list. */
|
|
1395
|
-
kind: 'address' | 'hostname';
|
|
1396
|
-
/** The canonical address; absent for a hostname match. Never an empty string:
|
|
1397
|
-
* an empty value is dropped in flight by cloud.ts and the audit shipper. */
|
|
1398
|
-
normalized?: string;
|
|
1399
|
-
}
|
|
1400
|
-
/** Longest legal DNS name. The caller does NOT reliably bound this: a URL with a
|
|
1401
|
-
* 261-character host reaches us intact (measured), so we bound our own input. */
|
|
1402
|
-
declare const SSRF_MAX_HOST = 253;
|
|
1403
|
-
/**
|
|
1404
|
-
* Fold any spelling of an IP literal to one canonical address, or null when the
|
|
1405
|
-
* input is not an IP literal (a hostname, or malformed). Never throws.
|
|
1406
|
-
*
|
|
1407
|
-
* IPv4-mapped IPv6 folds to the IPv4 address it denotes (RFC 4291 2.5.5.2), so
|
|
1408
|
-
* `[::ffff:a9fe:a9fe]` and `169.254.169.254` compare equal. Brackets and a zone
|
|
1409
|
-
* id are stripped here: the caller does NOT strip them (measured).
|
|
1410
|
-
*/
|
|
1411
|
-
declare function normalizeIpLiteral(host: string): string | null;
|
|
1412
|
-
/** Is this tier reachable by default, waiting on the `ssrfStrict` knob?
|
|
1413
|
-
* Exported so the non-shell path asks the SAME question rather than
|
|
1414
|
-
* approximating it with `overridable`, which is a different property. */
|
|
1415
|
-
declare function isStrictGatedTier(tier: SsrfTier): boolean;
|
|
1416
|
-
/** The sentence a user reads when the floor stops them. One builder, so the
|
|
1417
|
-
* shell path and the non-shell path cannot word the same block differently. */
|
|
1418
|
-
declare function ssrfReason(m: SsrfMatch, asWritten: string): string;
|
|
1419
|
-
/**
|
|
1420
|
-
* Classify a destination host. Returns null when it is not a protected address,
|
|
1421
|
-
* which means the ordinary egress policy decides. Never throws.
|
|
1422
|
-
*
|
|
1423
|
-
* Ordering is significant: the exact metadata addresses are checked before the
|
|
1424
|
-
* link-local range that contains them, so the reason names metadata.
|
|
1425
|
-
*/
|
|
1426
|
-
declare function classifySsrf(host: string): SsrfMatch | null;
|
|
1427
|
-
interface SsrfVerdict extends SsrfMatch {
|
|
1428
|
-
/** The token as written in the command. */
|
|
1429
|
-
host: string;
|
|
1430
|
-
binary: string;
|
|
1431
|
-
reason: string;
|
|
1432
|
-
}
|
|
1433
|
-
interface SsrfFloorOptions {
|
|
1434
|
-
/** Exempts OVERRIDABLE tiers only. A tier-1 entry here is ignored (and is
|
|
1435
|
-
* rejected at config load with a reason, never silently). */
|
|
1436
|
-
ssrfAllow?: readonly string[];
|
|
1437
|
-
/** Opt-in tier 3: loopback and RFC1918. Off by default: a developer talks to
|
|
1438
|
-
* those constantly (72 of 308 destinations on measured real history). */
|
|
1439
|
-
ssrfStrict?: boolean;
|
|
1440
|
-
}
|
|
1441
|
-
/**
|
|
1442
|
-
* Does this exemption list release this address?
|
|
1443
|
-
*
|
|
1444
|
-
* ONE function, because the shell floor and the declared-URL floor must answer
|
|
1445
|
-
* identically. They had two spellings of it — `normalizeIpLiteral(e) ?? e.trim()
|
|
1446
|
-
* .toLowerCase()` here and `classifySsrf(a)?.normalized ?? a` in
|
|
1447
|
-
* destinations.ts — and for an entry classifySsrf does not match they already
|
|
1448
|
-
* disagreed. Nothing depended on the difference, which is exactly when it is
|
|
1449
|
-
* cheap to remove.
|
|
1450
|
-
*
|
|
1451
|
-
* An entry is an exact address or a CIDR range. The range form exists so an
|
|
1452
|
-
* operator can exempt the mesh-VPN range they actually use (100.64.0.0/10)
|
|
1453
|
-
* instead of listing peers one at a time, which is what the settings panel's
|
|
1454
|
-
* "remove this default" control needs.
|
|
1455
|
-
*
|
|
1456
|
-
* ⚠ This answers "is it in the list", NOT "may it be released". The caller
|
|
1457
|
-
* keeps its `m.overridable` guard, and that guard is per ADDRESS, decided by
|
|
1458
|
-
* classifySsrf before this is consulted. So a range can never release a
|
|
1459
|
-
* protected address inside it: 100.100.100.200 (Alibaba IMDS) sits inside
|
|
1460
|
-
* 100.64.0.0/10 and is named in METADATA_ADDRESSES above the range check, so
|
|
1461
|
-
* it classifies as metadata / overridable:false and stays blocked with the
|
|
1462
|
-
* whole range exempted. Pinned by E2 in exempt-range.spec.ts.
|
|
1463
|
-
*
|
|
1464
|
-
* Never throws: this runs on the hook path for every tool call, and a bad
|
|
1465
|
-
* entry in a hand-edited config must not break every command on the machine.
|
|
1466
|
-
*/
|
|
1467
|
-
declare function ssrfExemptMatches(entries: readonly string[] | undefined, normalized: string | undefined): boolean;
|
|
1468
|
-
/**
|
|
1469
|
-
* The floor. Returns the first protected destination, or null.
|
|
1470
|
-
*
|
|
1471
|
-
* Runs unconditionally: not gated on egress.enabled, mode, allow or allowPrivate.
|
|
1472
|
-
* The one thing that does switch it off is `node9 pause`, which returns before
|
|
1473
|
-
* every gate; that is stated as a limit rather than special-cased here.
|
|
1474
|
-
*/
|
|
1475
|
-
declare function ssrfFloor(tokens: ReadonlyArray<{
|
|
1476
|
-
token: string;
|
|
1477
|
-
binary: string;
|
|
1478
|
-
}>, opts?: SsrfFloorOptions): SsrfVerdict | null;
|
|
1479
|
-
|
|
1480
1791
|
/**
|
|
1481
1792
|
* Tools whose named argument really is a destination the agent is about to
|
|
1482
1793
|
* reach. Keyed on the BARE tool name (an `mcp__server__` prefix is stripped
|
|
@@ -1528,4 +1839,4 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
|
|
|
1528
1839
|
/** Engine version stamped on audit entries for future drift detection. */
|
|
1529
1840
|
declare const ENGINE_VERSION = "1.4.0";
|
|
1530
1841
|
|
|
1531
|
-
export { AST_FS_REGEX_RULES, type AuditEntryForClassify, BASH_TOOL_NAMES, BUILTIN_SHIELDS, type BlastEnvFinding, type BlastFinding, type BlastResult, type BlastSummary, CANARY_MIN_LENGTH, CANONICAL_EXTRACTOR_HASH, CANONICAL_EXTRACTOR_VERSION, COMMAND_WRAPPERS, COPY_VERBS, COST_PER_LOOP_ITER_USD, type CanaryHit, type CanaryValue, type CanaryView, type CanonicalAgent, type CanonicalFinding, type CanonicalFindingType, type CanonicalSourceType, 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, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LoopWindowEvaluation, MAX_BLAST_PATH, NET_BINARIES, PATTERN_VERB_NAMES, PRIVILEGE_ESCALATION_RE, type PiiPattern, type PipeChainAnalysis, type PolicyConfig, type PolicyContext, type PolicyHostHooks, type PolicyVerdict, type PositionedArg, type ProvenanceLookup, type ProvenanceTrust, REALTIME_PII_PATTERNS, type RiskMetadata, SCAN_SIGNAL_WEIGHTS, SENSITIVE_PATH_RE, SENSITIVE_PATH_REGEXES, SSRF_MAX_HOST, type ScanFinding, type ScanSignals, type ScanSummary, 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, type ToolCallEntry, type ToolCallRecord, analyzeFsOperation, analyzePipeChain, analyzeShellCommand, checkDangerousSql, classifyAuditEntry, classifyRuleSeverity, classifyScanSignal, classifySsrf, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, dedupeCanonicalFindings, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateSmartConditions, extractAllSshHosts, extractCanonicalFindings, extractNetworkTargets, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, getCompiledRegex, getNestedValue, hostMatches, isBashTool, isIgnoredTool, isPrivateHost, isProtectedHomePath, isShellShapedTool, isShieldVerdict, isStrictGatedTier, matchCanary, matchCanaryArgs, matchSensitivePath, matchesPattern, narrativeRuleLabel, normalizeCommandForPolicy, normalizeIpLiteral, parseAllSshHostsFromCommand, parseDestHost, patternShapeOf, positionedArgs, previewArgs, redactText, resolvePinned, safeMessage, sampleCopyCommand, scanArgs, scanInjection, scanText, sensitivePathMatch, ssrfDestinationFloor, ssrfExemptMatches, ssrfFloor, ssrfReason, stripControlChars, stripTerminalEscapes, summarizeBlast, summarizeScan, toScanFinding, toolMatchesRule, truncateBlastPath, unwrapCommandHead, validateOverrides, validateRegex, validateShieldDefinition };
|
|
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 };
|