@node9/policy-engine 2.32.0 → 2.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +44 -18
- package/dist/index.d.ts +44 -18
- package/dist/index.js +313 -85
- package/dist/index.mjs +311 -85
- package/package.json +1 -1
package/dist/index.d.mts
CHANGED
|
@@ -113,6 +113,19 @@ type ToolInspectionEntry = string | {
|
|
|
113
113
|
field: string;
|
|
114
114
|
};
|
|
115
115
|
type ToolInspection = Record<string, ToolInspectionEntry>;
|
|
116
|
+
/**
|
|
117
|
+
* Inspection mappings by provenance. `trusted` is the shipped defaults plus the
|
|
118
|
+
* user's own and the workspace's entries, with full authority. `project` is a
|
|
119
|
+
* repository-carried config file, which an agent can write in-session: it may
|
|
120
|
+
* add a shell tool or a shell field, never turn a recognized executor into a
|
|
121
|
+
* non-shell tool or point its inspection at a decoy field (fw#338, review 3).
|
|
122
|
+
*/
|
|
123
|
+
interface InspectionLayers {
|
|
124
|
+
trusted: ToolInspection;
|
|
125
|
+
project?: ToolInspection;
|
|
126
|
+
}
|
|
127
|
+
/** A plain map is read as trusted with no project layer. */
|
|
128
|
+
type InspectionInput = ToolInspection | InspectionLayers;
|
|
116
129
|
type ShellInputResolution = {
|
|
117
130
|
kind: 'not-shell';
|
|
118
131
|
} | {
|
|
@@ -125,10 +138,17 @@ type ShellInputResolution = {
|
|
|
125
138
|
};
|
|
126
139
|
declare const BASH_TOOL_NAMES: Set<string>;
|
|
127
140
|
declare function isBashTool(tool: string): boolean;
|
|
128
|
-
|
|
129
|
-
declare function
|
|
141
|
+
/** The merged policy's maps as layers; the host keeps the project layer apart. */
|
|
142
|
+
declare function inspectionLayers(policy: {
|
|
143
|
+
toolInspection: ToolInspection;
|
|
144
|
+
projectToolInspection?: ToolInspection;
|
|
145
|
+
}): InspectionLayers;
|
|
146
|
+
/** The first matching entry, trusted layer first. For legacy (SQL, explain) lookups. */
|
|
147
|
+
declare function inspectionEntry(tool: string, inspection?: InspectionInput): ToolInspectionEntry | undefined;
|
|
148
|
+
declare function isShellShapedTool(tool: string, inspection?: InspectionInput): boolean;
|
|
149
|
+
declare function resolveShellInput(tool: string, args: unknown, inspection?: InspectionInput): ShellInputResolution;
|
|
130
150
|
/** Only Bash-scoped rules receive the canonical projection. Caller data is never mutated. */
|
|
131
|
-
declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?:
|
|
151
|
+
declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: InspectionInput): unknown;
|
|
132
152
|
|
|
133
153
|
type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
|
|
134
154
|
interface SsrfMatch {
|
|
@@ -511,7 +531,7 @@ declare const COMMAND_WRAPPERS: Set<string>;
|
|
|
511
531
|
* `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
|
|
512
532
|
* void them. An absent rule scope matches everything (callers' prior semantics).
|
|
513
533
|
*/
|
|
514
|
-
declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?:
|
|
534
|
+
declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: InspectionInput): boolean;
|
|
515
535
|
/** Strip leading wrappers/runners from a resolved arg list, returning the index
|
|
516
536
|
* of the real command head. Handles `sudo -u www python3`, `env -u FOO python3`,
|
|
517
537
|
* `timeout 5 python3`, `uv run python`, `conda run -n env python`,
|
|
@@ -689,6 +709,8 @@ interface PolicyConfig {
|
|
|
689
709
|
dangerousWords: string[];
|
|
690
710
|
ignoredTools: string[];
|
|
691
711
|
toolInspection: ToolInspection;
|
|
712
|
+
/** Entries from a repository-carried config file; they may only add inspection. */
|
|
713
|
+
projectToolInspection?: ToolInspection;
|
|
692
714
|
smartRules: SmartRule[];
|
|
693
715
|
dlp: {
|
|
694
716
|
enabled: boolean;
|
|
@@ -842,7 +864,7 @@ type ProtectedFileVerdict = PolicyVerdict & {
|
|
|
842
864
|
declare function incompleteFileVerdict(operation?: FileAccess['operation']): ProtectedFileVerdict;
|
|
843
865
|
/** Closed adapters: an arbitrary tool's path-shaped argument is not an operation. */
|
|
844
866
|
declare function fileToolOperation(tool: string, args: unknown): FileAccess['operation'] | null;
|
|
845
|
-
declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?:
|
|
867
|
+
declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: InspectionInput): FileAccess[];
|
|
846
868
|
declare function evaluateProtectedFileAccess(accesses: FileAccess[], context: FileAccessContext, settings: CatalogSettings): ProtectedFileVerdict | null;
|
|
847
869
|
|
|
848
870
|
type InjectionConfidence = 'low' | 'medium' | 'high';
|
|
@@ -855,6 +877,10 @@ interface InjectionContext {
|
|
|
855
877
|
/** Tool that produced the output. Untrusted origins (web/network) raise
|
|
856
878
|
* confidence — a fetched page is attacker-influenceable; a local read isn't. */
|
|
857
879
|
tool?: string;
|
|
880
|
+
/** The caller's own answer to "did this output come from outside?" (the
|
|
881
|
+
* #318 source roles: an unannotated MCP tool, a shell fetch). When set it
|
|
882
|
+
* decides the booster; when absent the tool-name regex below does. */
|
|
883
|
+
untrusted?: boolean;
|
|
858
884
|
}
|
|
859
885
|
/**
|
|
860
886
|
* Scan tool output for indirect prompt injection. Returns the matched signals +
|
|
@@ -1866,7 +1892,7 @@ interface ExtractContext {
|
|
|
1866
1892
|
}>;
|
|
1867
1893
|
/** toolInspection map from PolicyConfig — drives shell-command extraction
|
|
1868
1894
|
* for tools that aren't the standard 'bash' name. Defaults handled by caller. */
|
|
1869
|
-
toolInspection:
|
|
1895
|
+
toolInspection: InspectionInput;
|
|
1870
1896
|
/** DLP enabled flag from PolicyConfig. */
|
|
1871
1897
|
dlpEnabled: boolean;
|
|
1872
1898
|
/** Decoy credentials registered on this machine (value plus kind and plant
|
|
@@ -1924,7 +1950,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
|
|
|
1924
1950
|
* and fails CI when the hash drifts without a version bump — forgetting
|
|
1925
1951
|
* is loud, not silent.
|
|
1926
1952
|
*/
|
|
1927
|
-
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-
|
|
1953
|
+
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v26";
|
|
1928
1954
|
/**
|
|
1929
1955
|
* SHA-256 prefix of the detector-source files
|
|
1930
1956
|
* (canonical.ts + pii.ts + destructive-regex.ts).
|
|
@@ -1935,7 +1961,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
|
|
|
1935
1961
|
* files changed, this hash must change too, and you must consciously
|
|
1936
1962
|
* decide whether to bump CANONICAL_EXTRACTOR_VERSION."
|
|
1937
1963
|
*/
|
|
1938
|
-
declare const CANONICAL_EXTRACTOR_HASH = "
|
|
1964
|
+
declare const CANONICAL_EXTRACTOR_HASH = "dec8c65145686360";
|
|
1939
1965
|
declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
|
|
1940
1966
|
declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
|
|
1941
1967
|
/**
|
|
@@ -2010,7 +2036,7 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
|
|
|
2010
2036
|
declare const ARGUMENT_SCAN_LIMITS: {
|
|
2011
2037
|
readonly maxDepth: 12;
|
|
2012
2038
|
readonly maxNodes: 16384;
|
|
2013
|
-
/**
|
|
2039
|
+
/** Text is matched and decoded in windows of this size. */
|
|
2014
2040
|
readonly maxStringCharacters: 100000;
|
|
2015
2041
|
/** Windows overlap by this much so a token on a window edge is still seen whole. */
|
|
2016
2042
|
readonly windowOverlap: 4096;
|
|
@@ -2023,10 +2049,11 @@ declare const ARGUMENT_SCAN_LIMITS: {
|
|
|
2023
2049
|
interface ArgumentInspectionResult {
|
|
2024
2050
|
match: DlpMatch | null;
|
|
2025
2051
|
/**
|
|
2026
|
-
* `incomplete` when any part of the input was not fully inspected
|
|
2027
|
-
*
|
|
2028
|
-
*
|
|
2029
|
-
*
|
|
2052
|
+
* `incomplete` when any part of the input was not fully inspected: raw text
|
|
2053
|
+
* or structure skipped (`argument-*`), a decoding layer past the nested
|
|
2054
|
+
* limits (`decode-nested`), a flood of joinable hostname labels
|
|
2055
|
+
* (`decode-labels`), or the recovery-phrase hash budget (`mnemonic-budget`).
|
|
2056
|
+
* Every reason requires review; none is a documented allow.
|
|
2030
2057
|
*/
|
|
2031
2058
|
coverage: 'complete' | 'incomplete';
|
|
2032
2059
|
reasons: string[];
|
|
@@ -2034,14 +2061,13 @@ interface ArgumentInspectionResult {
|
|
|
2034
2061
|
/** Bounded input inspection. Output redaction deliberately retains its own API. */
|
|
2035
2062
|
declare function inspectArgumentSecrets(args: unknown): ArgumentInspectionResult;
|
|
2036
2063
|
/**
|
|
2037
|
-
* Existing DLP approval routing. A finding wins. Otherwise
|
|
2038
|
-
*
|
|
2039
|
-
*
|
|
2040
|
-
* call, because ordinary documents full of links or hashes exhaust it.
|
|
2064
|
+
* Existing DLP approval routing. A finding wins. Otherwise any part of the
|
|
2065
|
+
* input that was not fully inspected requires review: there is no limit an
|
|
2066
|
+
* attacker can reach that ends in a clean result.
|
|
2041
2067
|
*/
|
|
2042
2068
|
declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
|
|
2043
2069
|
|
|
2044
2070
|
/** Engine version stamped on audit entries for future drift detection. */
|
|
2045
2071
|
declare const ENGINE_VERSION = "1.4.0";
|
|
2046
2072
|
|
|
2047
|
-
export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, 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 DestinationKind, 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, MAX_DESTINATIONS, 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 ShellExposure, 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, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, 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 };
|
|
2073
|
+
export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, 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 DestinationKind, 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, type InspectionInput, type InspectionLayers, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, 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 ShellExposure, 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, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, 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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -113,6 +113,19 @@ type ToolInspectionEntry = string | {
|
|
|
113
113
|
field: string;
|
|
114
114
|
};
|
|
115
115
|
type ToolInspection = Record<string, ToolInspectionEntry>;
|
|
116
|
+
/**
|
|
117
|
+
* Inspection mappings by provenance. `trusted` is the shipped defaults plus the
|
|
118
|
+
* user's own and the workspace's entries, with full authority. `project` is a
|
|
119
|
+
* repository-carried config file, which an agent can write in-session: it may
|
|
120
|
+
* add a shell tool or a shell field, never turn a recognized executor into a
|
|
121
|
+
* non-shell tool or point its inspection at a decoy field (fw#338, review 3).
|
|
122
|
+
*/
|
|
123
|
+
interface InspectionLayers {
|
|
124
|
+
trusted: ToolInspection;
|
|
125
|
+
project?: ToolInspection;
|
|
126
|
+
}
|
|
127
|
+
/** A plain map is read as trusted with no project layer. */
|
|
128
|
+
type InspectionInput = ToolInspection | InspectionLayers;
|
|
116
129
|
type ShellInputResolution = {
|
|
117
130
|
kind: 'not-shell';
|
|
118
131
|
} | {
|
|
@@ -125,10 +138,17 @@ type ShellInputResolution = {
|
|
|
125
138
|
};
|
|
126
139
|
declare const BASH_TOOL_NAMES: Set<string>;
|
|
127
140
|
declare function isBashTool(tool: string): boolean;
|
|
128
|
-
|
|
129
|
-
declare function
|
|
141
|
+
/** The merged policy's maps as layers; the host keeps the project layer apart. */
|
|
142
|
+
declare function inspectionLayers(policy: {
|
|
143
|
+
toolInspection: ToolInspection;
|
|
144
|
+
projectToolInspection?: ToolInspection;
|
|
145
|
+
}): InspectionLayers;
|
|
146
|
+
/** The first matching entry, trusted layer first. For legacy (SQL, explain) lookups. */
|
|
147
|
+
declare function inspectionEntry(tool: string, inspection?: InspectionInput): ToolInspectionEntry | undefined;
|
|
148
|
+
declare function isShellShapedTool(tool: string, inspection?: InspectionInput): boolean;
|
|
149
|
+
declare function resolveShellInput(tool: string, args: unknown, inspection?: InspectionInput): ShellInputResolution;
|
|
130
150
|
/** Only Bash-scoped rules receive the canonical projection. Caller data is never mutated. */
|
|
131
|
-
declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?:
|
|
151
|
+
declare function shellRuleArgs(tool: string, args: unknown, ruleTool: string | string[] | undefined, inspection?: InspectionInput): unknown;
|
|
132
152
|
|
|
133
153
|
type SsrfTier = 'metadata' | 'link-local' | 'multicast' | 'unspecified' | 'cgnat' | 'private';
|
|
134
154
|
interface SsrfMatch {
|
|
@@ -511,7 +531,7 @@ declare const COMMAND_WRAPPERS: Set<string>;
|
|
|
511
531
|
* `run_shell_command`, `execute_bash`, `terminal.execute`) must not silently
|
|
512
532
|
* void them. An absent rule scope matches everything (callers' prior semantics).
|
|
513
533
|
*/
|
|
514
|
-
declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?:
|
|
534
|
+
declare function toolMatchesRule(toolName: string, ruleTool: string | string[] | undefined, toolInspection?: InspectionInput): boolean;
|
|
515
535
|
/** Strip leading wrappers/runners from a resolved arg list, returning the index
|
|
516
536
|
* of the real command head. Handles `sudo -u www python3`, `env -u FOO python3`,
|
|
517
537
|
* `timeout 5 python3`, `uv run python`, `conda run -n env python`,
|
|
@@ -689,6 +709,8 @@ interface PolicyConfig {
|
|
|
689
709
|
dangerousWords: string[];
|
|
690
710
|
ignoredTools: string[];
|
|
691
711
|
toolInspection: ToolInspection;
|
|
712
|
+
/** Entries from a repository-carried config file; they may only add inspection. */
|
|
713
|
+
projectToolInspection?: ToolInspection;
|
|
692
714
|
smartRules: SmartRule[];
|
|
693
715
|
dlp: {
|
|
694
716
|
enabled: boolean;
|
|
@@ -842,7 +864,7 @@ type ProtectedFileVerdict = PolicyVerdict & {
|
|
|
842
864
|
declare function incompleteFileVerdict(operation?: FileAccess['operation']): ProtectedFileVerdict;
|
|
843
865
|
/** Closed adapters: an arbitrary tool's path-shaped argument is not an operation. */
|
|
844
866
|
declare function fileToolOperation(tool: string, args: unknown): FileAccess['operation'] | null;
|
|
845
|
-
declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?:
|
|
867
|
+
declare function collectFileAccesses(tool: string, args: unknown, context?: FileAccessContext, inspection?: InspectionInput): FileAccess[];
|
|
846
868
|
declare function evaluateProtectedFileAccess(accesses: FileAccess[], context: FileAccessContext, settings: CatalogSettings): ProtectedFileVerdict | null;
|
|
847
869
|
|
|
848
870
|
type InjectionConfidence = 'low' | 'medium' | 'high';
|
|
@@ -855,6 +877,10 @@ interface InjectionContext {
|
|
|
855
877
|
/** Tool that produced the output. Untrusted origins (web/network) raise
|
|
856
878
|
* confidence — a fetched page is attacker-influenceable; a local read isn't. */
|
|
857
879
|
tool?: string;
|
|
880
|
+
/** The caller's own answer to "did this output come from outside?" (the
|
|
881
|
+
* #318 source roles: an unannotated MCP tool, a shell fetch). When set it
|
|
882
|
+
* decides the booster; when absent the tool-name regex below does. */
|
|
883
|
+
untrusted?: boolean;
|
|
858
884
|
}
|
|
859
885
|
/**
|
|
860
886
|
* Scan tool output for indirect prompt injection. Returns the matched signals +
|
|
@@ -1866,7 +1892,7 @@ interface ExtractContext {
|
|
|
1866
1892
|
}>;
|
|
1867
1893
|
/** toolInspection map from PolicyConfig — drives shell-command extraction
|
|
1868
1894
|
* for tools that aren't the standard 'bash' name. Defaults handled by caller. */
|
|
1869
|
-
toolInspection:
|
|
1895
|
+
toolInspection: InspectionInput;
|
|
1870
1896
|
/** DLP enabled flag from PolicyConfig. */
|
|
1871
1897
|
dlpEnabled: boolean;
|
|
1872
1898
|
/** Decoy credentials registered on this machine (value plus kind and plant
|
|
@@ -1924,7 +1950,7 @@ declare const LONG_OUTPUT_THRESHOLD_BYTES: number;
|
|
|
1924
1950
|
* and fails CI when the hash drifts without a version bump — forgetting
|
|
1925
1951
|
* is loud, not silent.
|
|
1926
1952
|
*/
|
|
1927
|
-
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-
|
|
1953
|
+
declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v26";
|
|
1928
1954
|
/**
|
|
1929
1955
|
* SHA-256 prefix of the detector-source files
|
|
1930
1956
|
* (canonical.ts + pii.ts + destructive-regex.ts).
|
|
@@ -1935,7 +1961,7 @@ declare const CANONICAL_EXTRACTOR_VERSION = "canonical-v25";
|
|
|
1935
1961
|
* files changed, this hash must change too, and you must consciously
|
|
1936
1962
|
* decide whether to bump CANONICAL_EXTRACTOR_VERSION."
|
|
1937
1963
|
*/
|
|
1938
|
-
declare const CANONICAL_EXTRACTOR_HASH = "
|
|
1964
|
+
declare const CANONICAL_EXTRACTOR_HASH = "dec8c65145686360";
|
|
1939
1965
|
declare function extractCanonicalFindings(call: ToolCallEntry, ctx: ExtractContext): CanonicalFinding[];
|
|
1940
1966
|
declare function extractSessionLevelFindings(calls: ReadonlyArray<SessionToolCall>, ctx: SessionExtractContext): CanonicalFinding[];
|
|
1941
1967
|
/**
|
|
@@ -2010,7 +2036,7 @@ declare function ssrfDestinationFloor(toolName: string, args: unknown, opts?: {
|
|
|
2010
2036
|
declare const ARGUMENT_SCAN_LIMITS: {
|
|
2011
2037
|
readonly maxDepth: 12;
|
|
2012
2038
|
readonly maxNodes: 16384;
|
|
2013
|
-
/**
|
|
2039
|
+
/** Text is matched and decoded in windows of this size. */
|
|
2014
2040
|
readonly maxStringCharacters: 100000;
|
|
2015
2041
|
/** Windows overlap by this much so a token on a window edge is still seen whole. */
|
|
2016
2042
|
readonly windowOverlap: 4096;
|
|
@@ -2023,10 +2049,11 @@ declare const ARGUMENT_SCAN_LIMITS: {
|
|
|
2023
2049
|
interface ArgumentInspectionResult {
|
|
2024
2050
|
match: DlpMatch | null;
|
|
2025
2051
|
/**
|
|
2026
|
-
* `incomplete` when any part of the input was not fully inspected
|
|
2027
|
-
*
|
|
2028
|
-
*
|
|
2029
|
-
*
|
|
2052
|
+
* `incomplete` when any part of the input was not fully inspected: raw text
|
|
2053
|
+
* or structure skipped (`argument-*`), a decoding layer past the nested
|
|
2054
|
+
* limits (`decode-nested`), a flood of joinable hostname labels
|
|
2055
|
+
* (`decode-labels`), or the recovery-phrase hash budget (`mnemonic-budget`).
|
|
2056
|
+
* Every reason requires review; none is a documented allow.
|
|
2030
2057
|
*/
|
|
2031
2058
|
coverage: 'complete' | 'incomplete';
|
|
2032
2059
|
reasons: string[];
|
|
@@ -2034,14 +2061,13 @@ interface ArgumentInspectionResult {
|
|
|
2034
2061
|
/** Bounded input inspection. Output redaction deliberately retains its own API. */
|
|
2035
2062
|
declare function inspectArgumentSecrets(args: unknown): ArgumentInspectionResult;
|
|
2036
2063
|
/**
|
|
2037
|
-
* Existing DLP approval routing. A finding wins. Otherwise
|
|
2038
|
-
*
|
|
2039
|
-
*
|
|
2040
|
-
* call, because ordinary documents full of links or hashes exhaust it.
|
|
2064
|
+
* Existing DLP approval routing. A finding wins. Otherwise any part of the
|
|
2065
|
+
* input that was not fully inspected requires review: there is no limit an
|
|
2066
|
+
* attacker can reach that ends in a clean result.
|
|
2041
2067
|
*/
|
|
2042
2068
|
declare function scanArgumentSecrets(args: unknown): DlpMatch | null;
|
|
2043
2069
|
|
|
2044
2070
|
/** Engine version stamped on audit entries for future drift detection. */
|
|
2045
2071
|
declare const ENGINE_VERSION = "1.4.0";
|
|
2046
2072
|
|
|
2047
|
-
export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, 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 DestinationKind, 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, MAX_DESTINATIONS, 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 ShellExposure, 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, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, 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 };
|
|
2073
|
+
export { AGENT_INSTRUCTION_DIRS, AGENT_INSTRUCTION_FILES, 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 DestinationKind, 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, type InspectionInput, type InspectionLayers, KNOB_GOVERNED, LONG_OUTPUT_THRESHOLD_BYTES, LOOP_MAX_RECORDS, LOOP_THRESHOLD_FOR_WASTE, type LegacyPolicyKnobs, type LoopWindowEvaluation, MAP_GOVERNED, MAX_BLAST_PATH, MAX_DESTINATIONS, 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 ShellExposure, 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, classifyShellExposure, classifySsrf, collectFileAccesses, computeAgentDeviceScore, computeArgsHash, computeBlendedSecurityScore, computeScanScore, computeSecurityScore, configurableValues, decodeEmbeddedBase64, decodeEmbeddedHex, dedupeCanonicalFindings, destinationDomain, destinationKind, destinationValue, detectArgsPii, detectDangerousEval, detectDangerousShellExec, detectInlineExec, detectPii, evaluateEgress, evaluateLoopWindow, evaluatePolicy, evaluateProtectedFileAccess, evaluateSmartConditions, extractAllSshHosts, extractArgDestinations, extractCanonicalFindings, extractContentDestinations, extractNetworkTargets, extractPackageInstalls, extractPositionalArgs, extractSessionLevelFindings, extractShellDestTokens, extractShellDestinations, extractToolDestinations, fileOperandFlagsOf, fileToolOperation, foldHomoglyphs, getCheck, getCompiledRegex, getNestedValue, gitRepoPath, hostMatches, incompleteFileVerdict, inspectArgumentSecrets, inspectionEntry, inspectionLayers, isAgentInstructionPath, isBashTool, isDestructiveToolName, isIgnoredTool, isInside, isKnobGoverned, isLegacySystemPath, isLockedCheck, isLoopbackHost, 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 };
|