@patrickdk77/script-defuse 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { analyzeScript } from './analyze';
+export { type InspectScriptOptions, inspectScript } from './engine';
+export { allFindingSpecs } from './findings';
+export { analyzeFormCalc } from './formcalc';
+export { type FormScriptPlugin, formScriptPlugin, type PluginScript } from './plugins';
+export { COMBINATIONS, DEFAULT_BANDS, scoreFindings } from './score';
+export * from './types';
+export { analyzeVba } from './vba';

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeVba = exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.formScriptPlugin = exports.analyzeFormCalc = exports.allFindingSpecs = exports.inspectScript = exports.analyzeScript = void 0;
+var analyze_1 = require("./analyze");
+Object.defineProperty(exports, "analyzeScript", { enumerable: true, get: function () { return analyze_1.analyzeScript; } });
+var engine_1 = require("./engine");
+Object.defineProperty(exports, "inspectScript", { enumerable: true, get: function () { return engine_1.inspectScript; } });
+var findings_1 = require("./findings");
+Object.defineProperty(exports, "allFindingSpecs", { enumerable: true, get: function () { return findings_1.allFindingSpecs; } });
+var formcalc_1 = require("./formcalc");
+Object.defineProperty(exports, "analyzeFormCalc", { enumerable: true, get: function () { return formcalc_1.analyzeFormCalc; } });
+var plugins_1 = require("./plugins");
+Object.defineProperty(exports, "formScriptPlugin", { enumerable: true, get: function () { return plugins_1.formScriptPlugin; } });
+var score_1 = require("./score");
+Object.defineProperty(exports, "COMBINATIONS", { enumerable: true, get: function () { return score_1.COMBINATIONS; } });
+Object.defineProperty(exports, "DEFAULT_BANDS", { enumerable: true, get: function () { return score_1.DEFAULT_BANDS; } });
+Object.defineProperty(exports, "scoreFindings", { enumerable: true, get: function () { return score_1.scoreFindings; } });
+__exportStar(require("./types"), exports);
+var vba_1 = require("./vba");
+Object.defineProperty(exports, "analyzeVba", { enumerable: true, get: function () { return vba_1.analyzeVba; } });

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import cjs from './index.js';
+export const { analyzeScript, inspectScript, allFindingSpecs, analyzeFormCalc, formScriptPlugin, COMBINATIONS, DEFAULT_BANDS, scoreFindings, analyzeVba, ScriptCategory, ScriptDetail, ScriptRisk } = cjs;
+export default cjs;

package/dist/plugins.d.ts

@@ -0,0 +1,28 @@
+import type { ScriptContext, ScriptFinding, ScriptOptions } from './types';
+/** The script a container hands its plugins, as pdf-defuse's ContainedScript gives it. */
+export interface PluginScript extends ScriptContext {
+    text: string;
+}
+/** A script plugin in the shape pdf-defuse's `scriptPlugins` takes. */
+export interface FormScriptPlugin {
+    kind: 'script';
+    name: string;
+    accepts(script: PluginScript): boolean;
+    process(script: PluginScript): Promise<{
+        result: 'passed' | 'removed';
+        findings?: ScriptFinding[];
+    }>;
+    /** Every script this plugin decided, with what it found, in the order it saw them. */
+    readonly decisions: ReadonlyArray<{
+        script: PluginScript;
+        result: 'passed' | 'removed';
+        findings: ScriptFinding[];
+    }>;
+}
+/**
+ * A plugin that keeps a script only when inspectScript calls it a form script, and removes every other one.
+ *
+ * It remembers the globals of the scripts it kept, so a field script may call a helper or read a value a
+ * document-level script defined. pdf-defuse hands document-level scripts over first. Make one plugin per document.
+ */
+export declare function formScriptPlugin(options?: ScriptOptions): FormScriptPlugin;

package/dist/plugins.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formScriptPlugin = formScriptPlugin;
+const engine_1 = require("./engine");
+/**
+ * A plugin that keeps a script only when inspectScript calls it a form script, and removes every other one.
+ *
+ * It remembers the globals of the scripts it kept, so a field script may call a helper or read a value a
+ * document-level script defined. pdf-defuse hands document-level scripts over first. Make one plugin per document.
+ */
+function formScriptPlugin(options = {}) {
+    const known = new Set();
+    const decisions = [];
+    return {
+        kind: 'script',
+        name: 'script-defuse',
+        decisions,
+        accepts: () => true,
+        async process(script) {
+            const r = (0, engine_1.inspectScript)(script.text, { ...options, context: script, knownGlobals: known });
+            const result = r.verdict === 'form' ? 'passed' : 'removed';
+            if (result === 'passed')
+                for (const name of r.definedGlobals)
+                    known.add(name);
+            decisions.push({ script, result, findings: r.findings });
+            return { result, findings: r.findings };
+        },
+    };
+}

package/dist/score.d.ts

@@ -0,0 +1,17 @@
+import { ScriptCategory as C, type DefuseFinding, type ScriptOptions, ScriptRisk, type ScriptScoreBands } from './types';
+export declare const DEFAULT_BANDS: ScriptScoreBands;
+interface Combination {
+    name: string;
+    weight: number;
+    test(has: (c: C) => boolean): boolean;
+}
+export declare const COMBINATIONS: Combination[];
+/** The caller's weights first, then the built-in table. */
+export declare function weightOf(f: DefuseFinding, options: ScriptOptions): number;
+/** Highest weight in full, a quarter of each other kind's weight, plus combinations, capped at 100. */
+export declare function scoreFindings(findings: DefuseFinding[], options: ScriptOptions): {
+    score: number;
+    risk: ScriptRisk;
+};
+export declare function riskFor(score: number, bands: ScriptScoreBands): ScriptRisk;
+export {};

package/dist/score.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMBINATIONS = exports.DEFAULT_BANDS = void 0;
+exports.weightOf = weightOf;
+exports.scoreFindings = scoreFindings;
+exports.riskFor = riskFor;
+const findings_1 = require("./findings");
+const types_1 = require("./types");
+exports.DEFAULT_BANDS = { low: 1, medium: 25, high: 50, critical: 80 };
+exports.COMBINATIONS = [
+    { name: 'obfuscation with a way out of the form', weight: 20, test: has => has(types_1.ScriptCategory.Obfuscation) && (has(types_1.ScriptCategory.External) || has(types_1.ScriptCategory.DynamicCode)) },
+    { name: 'obfuscation with a viewer API known from exploits', weight: 20, test: has => has(types_1.ScriptCategory.Obfuscation) && has(types_1.ScriptCategory.Api) },
+];
+/** The caller's weights first, then the built-in table. */
+function weightOf(f, options) {
+    const w = options.scoreWeights ?? [];
+    const exact = w.find(x => x.category === f.category && x.detail === f.detail);
+    if (exact)
+        return exact.weight;
+    const cat = w.find(x => x.category === f.category && x.detail === undefined);
+    if (cat)
+        return cat.weight;
+    return (0, findings_1.findingSpec)(f.category, f.detail)?.weight ?? f.weight ?? 0;
+}
+/** Highest weight in full, a quarter of each other kind's weight, plus combinations, capped at 100. */
+function scoreFindings(findings, options) {
+    const byKind = new Map();
+    for (const f of findings) {
+        const k = `${f.category}/${f.detail}`;
+        byKind.set(k, Math.max(byKind.get(k) ?? 0, weightOf(f, options)));
+    }
+    const weights = [...byKind.values()].sort((a, b) => b - a);
+    let score = weights.length ? weights[0] + weights.slice(1).reduce((s, w) => s + w / 4, 0) : 0;
+    const has = (c) => findings.some(f => f.category === c && weightOf(f, options) > 0);
+    for (const combo of exports.COMBINATIONS)
+        if (combo.test(has))
+            score += combo.weight;
+    score = Math.min(100, Math.round(score));
+    return { score, risk: riskFor(score, options.scoreBands ?? exports.DEFAULT_BANDS) };
+}
+function riskFor(score, bands) {
+    if (score >= bands.critical)
+        return types_1.ScriptRisk.Critical;
+    if (score >= bands.high)
+        return types_1.ScriptRisk.High;
+    if (score >= bands.medium)
+        return types_1.ScriptRisk.Medium;
+    if (score >= bands.low)
+        return types_1.ScriptRisk.Low;
+    return types_1.ScriptRisk.None;
+}

package/dist/types.d.ts

@@ -0,0 +1,149 @@
+/** Prefixed with SCRIPT_, so they never read as another package's kinds in a shared report, such as pdf-defuse's FORM. */
+export declare enum ScriptCategory {
+    /** The script only formats, checks or calculates form fields, or a macro calls nothing known to reach outside its document. */
+    Form = "SCRIPT_FORM",
+    /** The script reaches outside the form or document: a URL, mail, a submit, another file, the network, a program, a library. */
+    External = "SCRIPT_EXTERNAL",
+    /** The script runs code it builds at run time, installs scripts, or reaches the language's own machinery. */
+    DynamicCode = "SCRIPT_DYNAMIC_CODE",
+    /** The script hides what it does: decoded strings, character codes, long concatenations, escapes. */
+    Obfuscation = "SCRIPT_OBFUSCATION",
+    /** The script uses a viewer API that is not form computation. */
+    Api = "SCRIPT_API",
+    Syntax = "SCRIPT_SYNTAX",
+    Limit = "SCRIPT_LIMIT"
+}
+export declare enum ScriptDetail {
+    Computation = "COMPUTATION",
+    DocumentMacro = "DOCUMENT_MACRO",
+    Url = "URL",
+    Submit = "SUBMIT",
+    Mail = "MAIL",
+    OpenDocument = "OPEN_DOCUMENT",
+    DataObject = "DATA_OBJECT",
+    ImportExport = "IMPORT_EXPORT",
+    Network = "NETWORK",
+    MenuCommand = "MENU_COMMAND",
+    Print = "PRINT",
+    Save = "SAVE",
+    FileSystem = "FILE_SYSTEM",
+    Process = "PROCESS",
+    Registry = "REGISTRY",
+    Dde = "DDE",
+    ComObject = "COM_OBJECT",
+    NativeCode = "NATIVE_CODE",
+    Environment = "ENVIRONMENT",
+    Reference = "REFERENCE",
+    Eval = "EVAL",
+    Timer = "TIMER",
+    InstallScript = "INSTALL_SCRIPT",
+    Privilege = "PRIVILEGE",
+    ComputedAccess = "COMPUTED_ACCESS",
+    Prototype = "PROTOTYPE",
+    With = "WITH",
+    SelfReference = "SELF_REFERENCE",
+    LegacyMacro = "LEGACY_MACRO",
+    CharCodes = "CHAR_CODES",
+    Decode = "DECODE",
+    Concatenation = "CONCATENATION",
+    Escapes = "ESCAPES",
+    EncodedString = "ENCODED_STRING",
+    LongString = "LONG_STRING",
+    BracketName = "BRACKET_NAME",
+    NumberExpression = "NUMBER_EXPRESSION",
+    Exploited = "EXPLOITED",
+    Unknown = "UNKNOWN",
+    PasswordPrompt = "PASSWORD_PROMPT",
+    Unparseable = "UNPARSEABLE",
+    Size = "SIZE",
+    Depth = "DEPTH"
+}
+export type ScriptFindingAction = 'strip' | 'info';
+export declare enum ScriptRisk {
+    None = "NONE",
+    Low = "LOW",
+    Medium = "MEDIUM",
+    High = "HIGH",
+    Critical = "CRITICAL"
+}
+/** The finding shape every package of the defuse family shares. */
+export interface DefuseFinding {
+    category: string;
+    detail: string;
+    /** Plain sentence, safe to show the uploader. */
+    description: string;
+    /** Default action after any caller override. */
+    action: 'reject' | 'strip' | 'info';
+    /** Where in the script: "line 3", with the trigger and field when the caller gave them. */
+    location?: string;
+    /** Extra values: the API name, the count, the length. */
+    data?: Record<string, string | number>;
+    /** Set when the finding comes from inside a contained file. */
+    attachment?: string;
+    /** How much the finding adds to a score. */
+    weight?: number;
+}
+export interface ScriptFinding extends DefuseFinding {
+    category: ScriptCategory;
+    detail: ScriptDetail;
+    action: ScriptFindingAction;
+}
+export interface ScriptActionOverride {
+    category: ScriptCategory;
+    detail?: ScriptDetail;
+    action: ScriptFindingAction;
+}
+export interface ScriptScoreWeight {
+    category: ScriptCategory;
+    detail?: ScriptDetail;
+    weight: number;
+}
+/** Lower bound of each band. */
+export interface ScriptScoreBands {
+    low: number;
+    medium: number;
+    high: number;
+    critical: number;
+}
+export interface ScriptLimits {
+    /** Characters in one script. A script past it is LIMIT/SIZE and is not parsed. */
+    scriptSize?: number;
+    /** Nesting of the syntax tree. A script past it is LIMIT/DEPTH. */
+    depth?: number;
+}
+export interface ScriptOptions {
+    /** A limit left out is not enforced. */
+    limits?: ScriptLimits;
+    actionOverrides?: ScriptActionOverride[];
+    scoreWeights?: ScriptScoreWeight[];
+    scoreBands?: ScriptScoreBands;
+}
+/** A type library or another VBA project a VBA project refers to, as office-defuse reads it from the dir stream. */
+export interface ScriptReference {
+    name: string;
+    kind: 'registered' | 'control' | 'project';
+    /** A type library's LibidReference, such as `*\G{...}#2.0#0#path#description`, or a project's path. */
+    libid: string;
+}
+/** Where a script runs, as a container reports it. pdf-defuse's and office-defuse's ContainedScript fit. */
+export interface ScriptContext {
+    /** "document", "open", "field-format", "field-calculate", "click", ...; for a VBA module "vba-" and its kind. */
+    trigger?: string;
+    location?: string;
+    fieldName?: string;
+    /** 'javascript' unless the script is FormCalc, which only XFA forms carry, or a VBA module. */
+    language?: 'javascript' | 'formcalc' | 'vba';
+    /** 'xfa' for a script in an XFA form, which runs against the XFA object model; 'office' for a VBA module. */
+    form?: 'acroform' | 'xfa' | 'office';
+    /** For a VBA module, the references of its project. office-defuse gives them with the project's first module. */
+    references?: ScriptReference[];
+}
+export interface ScriptInspection {
+    /** 'form' when no finding strips the script: it only formats, checks or calculates form fields, or a VBA module calls nothing known to reach outside its document. */
+    verdict: 'form' | 'unsafe';
+    score: number;
+    risk: ScriptRisk;
+    findings: ScriptFinding[];
+    /** Global names the script defines, for scripts that run after it and use them. */
+    definedGlobals: string[];
+}

package/dist/types.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScriptRisk = exports.ScriptDetail = exports.ScriptCategory = void 0;
+/** Prefixed with SCRIPT_, so they never read as another package's kinds in a shared report, such as pdf-defuse's FORM. */
+var ScriptCategory;
+(function (ScriptCategory) {
+    /** The script only formats, checks or calculates form fields, or a macro calls nothing known to reach outside its document. */
+    ScriptCategory["Form"] = "SCRIPT_FORM";
+    /** The script reaches outside the form or document: a URL, mail, a submit, another file, the network, a program, a library. */
+    ScriptCategory["External"] = "SCRIPT_EXTERNAL";
+    /** The script runs code it builds at run time, installs scripts, or reaches the language's own machinery. */
+    ScriptCategory["DynamicCode"] = "SCRIPT_DYNAMIC_CODE";
+    /** The script hides what it does: decoded strings, character codes, long concatenations, escapes. */
+    ScriptCategory["Obfuscation"] = "SCRIPT_OBFUSCATION";
+    /** The script uses a viewer API that is not form computation. */
+    ScriptCategory["Api"] = "SCRIPT_API";
+    ScriptCategory["Syntax"] = "SCRIPT_SYNTAX";
+    ScriptCategory["Limit"] = "SCRIPT_LIMIT";
+})(ScriptCategory || (exports.ScriptCategory = ScriptCategory = {}));
+var ScriptDetail;
+(function (ScriptDetail) {
+    // FORM
+    ScriptDetail["Computation"] = "COMPUTATION";
+    ScriptDetail["DocumentMacro"] = "DOCUMENT_MACRO";
+    // EXTERNAL
+    ScriptDetail["Url"] = "URL";
+    ScriptDetail["Submit"] = "SUBMIT";
+    ScriptDetail["Mail"] = "MAIL";
+    ScriptDetail["OpenDocument"] = "OPEN_DOCUMENT";
+    ScriptDetail["DataObject"] = "DATA_OBJECT";
+    ScriptDetail["ImportExport"] = "IMPORT_EXPORT";
+    ScriptDetail["Network"] = "NETWORK";
+    ScriptDetail["MenuCommand"] = "MENU_COMMAND";
+    ScriptDetail["Print"] = "PRINT";
+    ScriptDetail["Save"] = "SAVE";
+    ScriptDetail["FileSystem"] = "FILE_SYSTEM";
+    ScriptDetail["Process"] = "PROCESS";
+    ScriptDetail["Registry"] = "REGISTRY";
+    ScriptDetail["Dde"] = "DDE";
+    ScriptDetail["ComObject"] = "COM_OBJECT";
+    ScriptDetail["NativeCode"] = "NATIVE_CODE";
+    ScriptDetail["Environment"] = "ENVIRONMENT";
+    ScriptDetail["Reference"] = "REFERENCE";
+    // DYNAMIC_CODE
+    ScriptDetail["Eval"] = "EVAL";
+    ScriptDetail["Timer"] = "TIMER";
+    ScriptDetail["InstallScript"] = "INSTALL_SCRIPT";
+    ScriptDetail["Privilege"] = "PRIVILEGE";
+    ScriptDetail["ComputedAccess"] = "COMPUTED_ACCESS";
+    ScriptDetail["Prototype"] = "PROTOTYPE";
+    ScriptDetail["With"] = "WITH";
+    ScriptDetail["SelfReference"] = "SELF_REFERENCE";
+    ScriptDetail["LegacyMacro"] = "LEGACY_MACRO";
+    // OBFUSCATION
+    ScriptDetail["CharCodes"] = "CHAR_CODES";
+    ScriptDetail["Decode"] = "DECODE";
+    ScriptDetail["Concatenation"] = "CONCATENATION";
+    ScriptDetail["Escapes"] = "ESCAPES";
+    ScriptDetail["EncodedString"] = "ENCODED_STRING";
+    ScriptDetail["LongString"] = "LONG_STRING";
+    ScriptDetail["BracketName"] = "BRACKET_NAME";
+    ScriptDetail["NumberExpression"] = "NUMBER_EXPRESSION";
+    // API
+    ScriptDetail["Exploited"] = "EXPLOITED";
+    ScriptDetail["Unknown"] = "UNKNOWN";
+    ScriptDetail["PasswordPrompt"] = "PASSWORD_PROMPT";
+    // SYNTAX
+    ScriptDetail["Unparseable"] = "UNPARSEABLE";
+    // LIMIT
+    ScriptDetail["Size"] = "SIZE";
+    ScriptDetail["Depth"] = "DEPTH";
+})(ScriptDetail || (exports.ScriptDetail = ScriptDetail = {}));
+var ScriptRisk;
+(function (ScriptRisk) {
+    ScriptRisk["None"] = "NONE";
+    ScriptRisk["Low"] = "LOW";
+    ScriptRisk["Medium"] = "MEDIUM";
+    ScriptRisk["High"] = "HIGH";
+    ScriptRisk["Critical"] = "CRITICAL";
+})(ScriptRisk || (exports.ScriptRisk = ScriptRisk = {}));

package/dist/vba.d.ts

@@ -0,0 +1,11 @@
+import { type ScriptContext, type ScriptFinding, type ScriptOptions } from './types';
+export interface VbaInput {
+    text: string;
+    context?: ScriptContext;
+    options?: ScriptOptions;
+}
+/** Inspects one VBA module. Its findings say what it calls that reaches outside the document, and what it hides. */
+export declare function analyzeVba(input: VbaInput): {
+    findings: ScriptFinding[];
+    definedGlobals: string[];
+};