@patrickdk77/script-defuse 0.0.0-stage → 0.2.0

package/dist/engine.d.ts

@@ -0,0 +1,12 @@
+import type { ScriptContext, ScriptInspection, ScriptOptions } from './types';
+export interface InspectScriptOptions extends ScriptOptions {
+    /** Where the script runs, for the findings' locations. */
+    context?: ScriptContext;
+    /** Global names scripts that ran before this one defined and kept, which this one may use. */
+    knownGlobals?: Iterable<string>;
+}
+/**
+ * Inspect one script, in JavaScript or, when the context says so, in FormCalc or VBA. The verdict is 'form' when no finding strips it: every call and property a form
+ * script uses formats, checks or calculates form fields, or a VBA module calls nothing known to reach outside its document, and nothing in it hides what it does.
+ */
+export declare function inspectScript(text: string, options?: InspectScriptOptions): ScriptInspection;

package/dist/engine.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectScript = inspectScript;
+const analyze_1 = require("./analyze");
+const formcalc_1 = require("./formcalc");
+const score_1 = require("./score");
+const vba_1 = require("./vba");
+/**
+ * Inspect one script, in JavaScript or, when the context says so, in FormCalc or VBA. The verdict is 'form' when no finding strips it: every call and property a form
+ * script uses formats, checks or calculates form fields, or a VBA module calls nothing known to reach outside its document, and nothing in it hides what it does.
+ */
+function inspectScript(text, options = {}) {
+    const language = options.context?.language;
+    const { findings, definedGlobals } = language === 'formcalc'
+        ? (0, formcalc_1.analyzeFormCalc)({ text, context: options.context, options })
+        : language === 'vba'
+            ? (0, vba_1.analyzeVba)({ text, context: options.context, options })
+            : (0, analyze_1.analyzeScript)({ text, context: options.context, options, known: new Set(options.knownGlobals ?? []) });
+    const counted = findings.filter(f => f.action === 'strip');
+    const { score, risk } = (0, score_1.scoreFindings)(counted, options);
+    return { verdict: counted.length ? 'unsafe' : 'form', score, risk, findings, definedGlobals };
+}

package/dist/findings.d.ts

@@ -0,0 +1,19 @@
+import { ScriptCategory as C, ScriptDetail as D, type ScriptActionOverride, type ScriptFinding, type ScriptFindingAction } from './types';
+interface Spec {
+    action: ScriptFindingAction;
+    /** May contain <key> placeholders filled from data. A filled value has control characters replaced by "?" and is cut to 60 characters. */
+    description: string;
+    weight: number;
+}
+export declare function findingSpec(c: string, d: string): Spec | undefined;
+/** A finding with its default action, after the caller's overrides. */
+export declare function makeFinding(c: C, d: D, overrides?: ScriptActionOverride[], location?: string, data?: Record<string, string | number>): ScriptFinding;
+/** Every finding kind this package can report, with its default action, weight and description. */
+export declare function allFindingSpecs(): Array<{
+    category: C;
+    detail: D;
+    action: ScriptFindingAction;
+    weight: number;
+    description: string;
+}>;
+export {};

package/dist/findings.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findingSpec = findingSpec;
+exports.makeFinding = makeFinding;
+exports.allFindingSpecs = allFindingSpecs;
+const types_1 = require("./types");
+const specs = new Map();
+function def(c, d, action, weight, description) {
+    specs.set(`${c}/${d}`, { action, weight, description });
+}
+// FORM
+def(types_1.ScriptCategory.Form, types_1.ScriptDetail.Computation, 'info', 0, 'The script only formats, checks or calculates form fields');
+def(types_1.ScriptCategory.Form, types_1.ScriptDetail.DocumentMacro, 'info', 0, 'The macro calls nothing script-defuse knows to reach outside its document');
+// EXTERNAL
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Url, 'strip', 60, '<api> opens a web address');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Submit, 'strip', 50, '<api> sends the form data somewhere');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Mail, 'strip', 50, '<api> sends mail');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.OpenDocument, 'strip', 60, '<api> opens or creates another document');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.DataObject, 'strip', 70, '<api> reads, writes or opens a file attached to the document');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.ImportExport, 'strip', 50, '<api> reads or writes form data or files outside the document');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Network, 'strip', 70, '<api> talks to a network service');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.MenuCommand, 'strip', 60, '<api> runs a viewer menu command');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Print, 'strip', 20, '<api> prints');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Save, 'strip', 30, '<api> saves or closes the document');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.FileSystem, 'strip', 70, '<api> reads, writes or lists files and folders');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Process, 'strip', 90, '<api> starts a program or sends keystrokes to one');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Registry, 'strip', 60, '<api> reads or writes the registry or settings files');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Dde, 'strip', 80, '<api> talks to another program over DDE');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.ComObject, 'strip', 80, '<api> creates or gets an object from outside the document, such as a shell or a web request');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.NativeCode, 'strip', 90, '<api> calls native code in a library');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Environment, 'strip', 30, '<api> reads the environment of the computer it runs on');
+def(types_1.ScriptCategory.External, types_1.ScriptDetail.Reference, 'strip', 60, 'The project refers to <api>, a library or project from outside the document');
+// DYNAMIC_CODE
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.Eval, 'strip', 80, '<api> runs code built from a string');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.Timer, 'strip', 70, '<api> runs code later, from a string');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.InstallScript, 'strip', 70, '<api> installs another script or action');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.Privilege, 'strip', 80, '<api> asks for privileged execution');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.ComputedAccess, 'strip', 40, 'A property is read by a name computed at run time, so what it reaches cannot be told');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.Prototype, 'strip', 60, '<api> reaches the language machinery behind objects and functions');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.With, 'strip', 40, 'A with statement changes what names refer to');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.SelfReference, 'strip', 60, '<api> reads the source of the running code, the way self-decrypting scripts do');
+def(types_1.ScriptCategory.DynamicCode, types_1.ScriptDetail.LegacyMacro, 'strip', 80, '<api> runs a command of an older macro language, which reaches outside the document');
+// OBFUSCATION
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.CharCodes, 'strip', 50, 'Text is built from character codes');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.Decode, 'strip', 60, '<api> decodes hidden text');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.Concatenation, 'strip', 40, 'A string is joined from many short pieces');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.Escapes, 'strip', 40, 'A string writes ordinary letters as escape sequences');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.EncodedString, 'strip', 50, 'A string holds encoded data');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.LongString, 'strip', 40, 'A string far longer than form text');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.NumberExpression, 'strip', 30, 'A number is written as arithmetic on hex constants');
+def(types_1.ScriptCategory.Obfuscation, types_1.ScriptDetail.BracketName, 'strip', 30, '<api> is reached by a quoted name where a form script names it plainly');
+// API
+def(types_1.ScriptCategory.Api, types_1.ScriptDetail.Exploited, 'strip', 80, '<api> is a viewer API known from exploits');
+def(types_1.ScriptCategory.Api, types_1.ScriptDetail.Unknown, 'strip', 30, '<api> is not a form calculation, format or check');
+def(types_1.ScriptCategory.Api, types_1.ScriptDetail.PasswordPrompt, 'strip', 50, '<api> asks for a password in a prompt, as a fake sign-in does. A form takes a password in a field of its own');
+// SYNTAX
+def(types_1.ScriptCategory.Syntax, types_1.ScriptDetail.Unparseable, 'strip', 50, 'The script does not parse, so what it does cannot be told');
+// LIMIT
+def(types_1.ScriptCategory.Limit, types_1.ScriptDetail.Size, 'strip', 30, 'The script is longer than limits.scriptSize');
+def(types_1.ScriptCategory.Limit, types_1.ScriptDetail.Depth, 'strip', 30, 'The script nests deeper than limits.depth');
+function findingSpec(c, d) {
+    return specs.get(`${c}/${d}`);
+}
+const clip = (v) => String(v)
+    .replace(/[\p{Cc}\p{Cf}]/gu, '?')
+    .slice(0, 60);
+/** A finding with its default action, after the caller's overrides. */
+function makeFinding(c, d, overrides = [], location, data) {
+    const spec = specs.get(`${c}/${d}`);
+    if (!spec)
+        throw new Error(`no finding spec for ${c}/${d}`);
+    const exact = overrides.find(o => o.category === c && o.detail === d);
+    const byCategory = overrides.find(o => o.category === c && o.detail === undefined);
+    const action = exact?.action ?? byCategory?.action ?? spec.action;
+    const description = spec.description.replace(/<(\w+)>/g, (_m, key) => (data?.[key] === undefined ? key : clip(data[key])));
+    const f = { category: c, detail: d, description, action, weight: spec.weight };
+    if (location)
+        f.location = location;
+    if (data)
+        f.data = data;
+    return f;
+}
+/** Every finding kind this package can report, with its default action, weight and description. */
+function allFindingSpecs() {
+    return [...specs].map(([key, spec]) => {
+        const [category, detail] = key.split('/');
+        return { category, detail, ...spec };
+    });
+}

package/dist/formcalc.d.ts

@@ -0,0 +1,10 @@
+import { type ScriptContext, type ScriptFinding, type ScriptOptions } from './types';
+export interface FormCalcInput {
+    text: string;
+    context?: ScriptContext;
+    options?: ScriptOptions;
+}
+export declare function analyzeFormCalc(input: FormCalcInput): {
+    findings: ScriptFinding[];
+    definedGlobals: string[];
+};