@snovon/solast 0.2.0

package/dist/detectors/types.d.ts

@@ -0,0 +1,85 @@
+import type { ScanResult } from '../index';
+import type { SemanticModel } from '../semantic/model';
+import type { TaintTracker } from '../semantic/taint-tracker';
+export type DetectorAstKind = 'parser' | 'solc';
+/**
+ * Optional context passed to detectors that need cross-file information.
+ * Slice 1 of roadmap 3.3 shipped the SemanticModel; Slice 2 (this and
+ * follow-ups) wires detectors to consume it. Detectors that don't read
+ * `semantic` are unaffected — the context is purely additive.
+ *
+ * Detectors that adopt `semantic` MUST keep a per-file fallback so they
+ * still work when the model is absent (single-file tests
+ * that drive a detector directly, etc.). Treat `ctx.semantic === undefined`
+ * as "no cross-file info available", not as an error.
+ */
+export interface DetectorContext {
+    /** The file being scanned. Mirrors what `setFile(file)` would receive. */
+    file: string;
+    /** Optional compiler version supplied by the caller/CLI when a source pragma is unavailable. */
+    solcVersion?: string;
+    /** The SemanticModel built from all parsed source units in this scan. Undefined when unavailable. */
+    semantic?: SemanticModel;
+    /** Shared detector-facing taint tracker built from the analyzed source set. */
+    taint?: TaintTracker;
+}
+export interface Detector {
+    id: string;
+    patternKey?: string;
+    descriptor?: {
+        id: string;
+        shortDescription: string;
+        helpUri: string;
+        defaultSeverity: 'critical' | 'high' | 'medium' | 'low' | 'informational';
+        help?: string;
+    };
+    supportedAstKinds?: DetectorAstKind[];
+    enabledByDefault?: boolean;
+    setFile?(file: string): void;
+    setContext?(ctx: DetectorContext): void;
+    setSourceText?(sourceText?: string): void;
+    /**
+     * Receive the SemanticModel for the current scan (if one is available).
+     * Called by the registry once per file alongside `setFile`. Visitor-style
+     * detectors implement this to gain cross-file context. The model is the
+     * SAME instance for every file in a single scan invocation.
+     */
+    setSemanticModel?(model: SemanticModel | undefined): void;
+    getFindings?(): ScanResult[];
+    /**
+     * Legacy self-traversal entry point. Accepts an optional `ctx` argument
+     * carrying the SemanticModel; older detectors that don't read it are
+     * unaffected (TypeScript optional params are backward-compatible).
+     */
+    scanAst?(ast: any, file: string, sourceText?: string, ctx?: DetectorContext): ScanResult[];
+    [visitorMethod: string]: any;
+}
+export declare const LIFECYCLE_METHOD_NAMES: ReadonlySet<string>;
+export declare const SPECIAL_HOOK_NAMES: ReadonlySet<string>;
+export interface FanoutCacheEntry {
+    visitorDetectors: Detector[];
+    fanout: Record<string, (node: any) => void>;
+}
+/**
+ * Per-detector traversal cost telemetry (roadmap P.2). Active when the
+ * env var `SOLAST_PROFILE=1` is set at registry construction. The
+ * registry tracks two counters per detector:
+ *
+ *   - `visits`: number of fan-out dispatches into a visitor handler
+ *     (or 1 per `scanAst` call for legacy self-traversers).
+ *   - `timeNs`: cumulative wall-clock nanoseconds spent in the
+ *     detector's handlers/scanAst calls.
+ *
+ * Used to confirm Phase 2.A wins are real: a converted visitor-style
+ * detector should have lower `timeNs` per file than its scanAst-style
+ * predecessor on the same fixture corpus, since the shared visitor
+ * pump amortises tree-walking across all subscribed detectors.
+ */
+export interface ProfileStats {
+    visits: number;
+    timeNs: bigint;
+}
+export interface DetectorProfileEntry extends ProfileStats {
+    id: string;
+}
+export declare const PROFILE_ENABLED: boolean;

package/dist/detectors/types.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROFILE_ENABLED = exports.SPECIAL_HOOK_NAMES = exports.LIFECYCLE_METHOD_NAMES = void 0;
+// Methods on a detector that are part of the registry lifecycle, not
+// visitor handlers. These are excluded from the fan-out visitor.
+exports.LIFECYCLE_METHOD_NAMES = new Set([
+    'constructor', 'setFile', 'setContext', 'setSourceText', 'setSemanticModel', 'getFindings', 'scanAst',
+]);
+// Special hooks the solc walker fires that are NOT named after AST node
+// types. The access-control detector uses these to track when the walker
+// enters or leaves a nested statement body (if/for/while/etc.). They are
+// preserved by the fan-out so multi-detector runs still see them.
+exports.SPECIAL_HOOK_NAMES = new Set([
+    'enterNestedStatementBody', 'exitNestedStatementBody',
+]);
+// Captured at module load — not constructor time — so test harnesses that
+// load this module under a temporary `withEnv` block see the value they
+// set, even if they construct the registry after restoring the env.
+exports.PROFILE_ENABLED = process.env.SOLAST_PROFILE === '1';
+//# sourceMappingURL=types.js.map

package/dist/detectors/unauthorized-payer-transferfrom.d.ts

@@ -0,0 +1,66 @@
+import type { ScanResult } from '../index';
+/**
+ * Flags externally-callable functions that move a *caller-supplied* party's
+ * ERC-20 allowance — `transferFrom(payer, ...)` / `safeTransferFrom(token,
+ * payer, ...)` where `payer` is (or derives from) a function parameter —
+ * without any guard tying `msg.sender` to that payer.
+ *
+ * This is the Ekubo EVM swap-router shape (#2768): a payment callback that
+ * accepts `payer` / `token` / `amount` from attacker-controlled payload and
+ * drains the payer's outstanding approval. Heuristic and FP-prone — see
+ * `docs/detectors/unauthorized-payer-transferfrom.md` — so emitted at low
+ * confidence.
+ */
+export declare class UnauthorizedPayerTransferfromDetector {
+    readonly id = "unauthorized-payer-transferfrom";
+    readonly patternKey = "unauthorized-payer-transferfrom";
+    readonly supportedAstKinds: "parser"[];
+    readonly descriptor: {
+        id: string;
+        shortDescription: string;
+        helpUri: string;
+        defaultSeverity: "high";
+        help: string;
+    };
+    private findings;
+    private currentFile;
+    private currentContract;
+    private hasSafeErc20ForErc20;
+    private contractErc20Names;
+    private contractNonErc20Names;
+    setFile(file: string): void;
+    getFindings(): ScanResult[];
+    ContractDefinition(node: any): void;
+    ContractDefinition_post(): void;
+    FunctionDefinition(node: any): void;
+    /** Walk the body; emit at most one finding per function. */
+    private reportFirstVulnerableCall;
+    private emit;
+    private isExternallyCallable;
+    private isFunctionGuarded;
+    /** Map locals to the parameter name they are a straight copy of. */
+    private collectAliases;
+    private collectTokenTypes;
+    /**
+     * Resolve an expression back to the parameter name it derives from.
+     * Handles a bare identifier, a struct-field access of a parameter
+     * (`payment.payer`), and a local alias of either. Returns null for
+     * anything else (a deeper `abi.decode(bytes)` flow is a documented miss).
+     */
+    private getBaseParamName;
+    /**
+     * The `from` argument of a `transferFrom` / `safeTransferFrom` call, or
+     * null if the call is neither. ERC-20 `transferFrom(from, to, amount)`
+     * and SafeERC20 shapes: static `SafeERC20.safeTransferFrom(token, from,
+     * to, amount)` plus extension-style `IERC20(token).safeTransferFrom(from,
+     * to, amount)` / `token.safeTransferFrom(from, to, amount)` when there is
+     * SafeERC20-for-IERC20 evidence. ERC-721's 3-arg
+     * `safeTransferFrom(from, to, tokenId)` is intentionally out of scope.
+     */
+    private getFromArgument;
+    private recordUsingFor;
+    private recordTypedVariable;
+    private hasErc20SafeTransferFromEvidence;
+    private getDirectCallName;
+    private childNodes;
+}

package/dist/detectors/unauthorized-payer-transferfrom.js

@@ -0,0 +1,339 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnauthorizedPayerTransferfromDetector = void 0;
+const access_control_1 = require("./_common/access-control");
+const ast_1 = require("./_common/ast");
+const RULE_ID = 'unauthorized-payer-transferfrom';
+/**
+ * Keyword vocabulary for recognising a caller-authorisation predicate. The
+ * canonical privileged set plus the auth/allowlist-style names that gate a
+ * router (`authorized[msg.sender]`, `whitelist`, `manager`, ...). Kept local
+ * per `_common/access-control.ts`'s policy-as-parameter guidance rather than
+ * widening the shared default set.
+ */
+const GUARD_KEYWORDS = Object.freeze([
+    ...access_control_1.DEFAULT_PRIVILEGED_KEYWORDS,
+    'auth', 'authority', 'manager', 'whitelist', 'allowlist', 'allowed', 'caller',
+]);
+/**
+ * Flags externally-callable functions that move a *caller-supplied* party's
+ * ERC-20 allowance — `transferFrom(payer, ...)` / `safeTransferFrom(token,
+ * payer, ...)` where `payer` is (or derives from) a function parameter —
+ * without any guard tying `msg.sender` to that payer.
+ *
+ * This is the Ekubo EVM swap-router shape (#2768): a payment callback that
+ * accepts `payer` / `token` / `amount` from attacker-controlled payload and
+ * drains the payer's outstanding approval. Heuristic and FP-prone — see
+ * `docs/detectors/unauthorized-payer-transferfrom.md` — so emitted at low
+ * confidence.
+ */
+class UnauthorizedPayerTransferfromDetector {
+    id = RULE_ID;
+    patternKey = RULE_ID;
+    supportedAstKinds = ['parser'];
+    descriptor = {
+        id: RULE_ID,
+        shortDescription: 'External transferFrom consumes a caller-supplied payer without an access-control guard.',
+        helpUri: 'https://snovon.com/',
+        defaultSeverity: 'high',
+        help: 'Bind the payer to msg.sender (require(msg.sender == payer)), or gate the function with recognized access control.',
+    };
+    findings = [];
+    currentFile = '';
+    currentContract = '';
+    hasSafeErc20ForErc20 = false;
+    contractErc20Names = new Set();
+    contractNonErc20Names = new Set();
+    setFile(file) {
+        this.currentFile = file;
+        this.findings = [];
+        this.currentContract = '';
+        this.hasSafeErc20ForErc20 = false;
+        this.contractErc20Names.clear();
+        this.contractNonErc20Names.clear();
+    }
+    getFindings() {
+        return this.findings;
+    }
+    ContractDefinition(node) {
+        this.currentContract = String(node?.name || '<anonymous>');
+        this.hasSafeErc20ForErc20 = false;
+        this.contractErc20Names.clear();
+        this.contractNonErc20Names.clear();
+        for (const child of node?.subNodes || node?.nodes || []) {
+            if ((0, ast_1.isNode)(child, 'UsingForDeclaration'))
+                this.recordUsingFor(child);
+            if ((0, ast_1.isNode)(child, 'StateVariableDeclaration')) {
+                for (const variable of child.variables || [])
+                    this.recordTypedVariable(variable, this.contractErc20Names, this.contractNonErc20Names);
+            }
+        }
+    }
+    ContractDefinition_post() {
+        this.currentContract = '';
+        this.hasSafeErc20ForErc20 = false;
+        this.contractErc20Names.clear();
+        this.contractNonErc20Names.clear();
+    }
+    FunctionDefinition(node) {
+        if (!node || !node.body)
+            return;
+        if (node.isConstructor)
+            return;
+        if (!this.isExternallyCallable(node))
+            return;
+        const params = new Set();
+        for (const p of node.parameters || []) {
+            if (p?.name)
+                params.add(String(p.name));
+        }
+        if (params.size === 0)
+            return;
+        // A guard relating msg.sender to the payer (or any recognised access
+        // control) means the caller is authorised to spend the payer's tokens.
+        if (this.isFunctionGuarded(node, params))
+            return;
+        const aliases = this.collectAliases(node.body);
+        const tokenTypes = this.collectTokenTypes(node, node.body);
+        this.reportFirstVulnerableCall(node, node.body, params, aliases, tokenTypes);
+    }
+    /** Walk the body; emit at most one finding per function. */
+    reportFirstVulnerableCall(fnNode, node, params, aliases, tokenTypes) {
+        if (!node || typeof node !== 'object')
+            return false;
+        if ((0, ast_1.isNode)(node, 'FunctionCall')) {
+            const fromArg = this.getFromArgument(node, tokenTypes);
+            if (fromArg) {
+                const baseName = this.getBaseParamName(fromArg, aliases);
+                if (baseName && params.has(baseName)) {
+                    this.emit(fnNode, node);
+                    return true;
+                }
+            }
+        }
+        for (const child of this.childNodes(node)) {
+            if (this.reportFirstVulnerableCall(fnNode, child, params, aliases, tokenTypes))
+                return true;
+        }
+        return false;
+    }
+    emit(fnNode, callNode) {
+        const { line, endLine, column, endColumn } = (0, ast_1.assertLoc)(callNode, fnNode);
+        const functionName = String(fnNode?.name || '<anonymous>');
+        this.findings.push({
+            file: this.currentFile,
+            contract: this.currentContract,
+            'function': functionName,
+            line,
+            endLine,
+            column,
+            endColumn,
+            pattern: RULE_ID,
+            confidence: 'low',
+            category: 'access-control',
+            ruleId: RULE_ID,
+            severity: 'high',
+            message: `External function '${functionName}' calls transferFrom with a caller-supplied payer and no access-control guard — an outstanding ERC-20 approval can be drained by an arbitrary caller.`,
+            rationale: "transferFrom moves the `from` party's tokens on the strength of an existing allowance; when `from` is a function parameter the caller, not the payer, decides whose approval is spent.",
+            suggestedFix: 'Require the caller to equal the payer (require(msg.sender == payer)), derive the payer from msg.sender, or gate the function with recognized access control.',
+            contractName: this.currentContract,
+            functionName,
+            sourceLocation: { line, column },
+            findingId: '',
+            contractHash: '',
+        });
+    }
+    isExternallyCallable(node) {
+        const visibility = String(node.visibility || '').toLowerCase();
+        return visibility === 'public' || visibility === 'external' || visibility === 'default';
+    }
+    isFunctionGuarded(fn, payerParams) {
+        if ((0, access_control_1.hasRecognisedAccessControlModifier)(fn))
+            return true;
+        // A caller-authorisation predicate counts the payer parameter itself as
+        // "privileged": `require(msg.sender == payer)` proves the caller is the
+        // payer. Auth/allowlist-style names cover mapping-gated routers.
+        const isPrivileged = (name) => {
+            if (payerParams.has(name))
+                return true;
+            return (0, access_control_1.isPrivilegedIdentifier)(name, { keywords: GUARD_KEYWORDS });
+        };
+        let guarded = false;
+        const walk = (node) => {
+            if (guarded || !node || typeof node !== 'object')
+                return;
+            if ((0, ast_1.isNode)(node, 'FunctionCall')) {
+                const calleeName = this.getDirectCallName(node.expression);
+                if (calleeName === 'require' || calleeName === 'assert') {
+                    const condition = (node.arguments || [])[0];
+                    if ((0, access_control_1.requireExpressesAccessControl)(condition, isPrivileged))
+                        guarded = true;
+                }
+            }
+            for (const child of this.childNodes(node))
+                walk(child);
+        };
+        walk(fn.body);
+        return guarded;
+    }
+    /** Map locals to the parameter name they are a straight copy of. */
+    collectAliases(body) {
+        const aliases = new Map();
+        const walk = (node) => {
+            if (!node || typeof node !== 'object')
+                return;
+            if ((0, ast_1.isNode)(node, 'VariableDeclarationStatement') && node.initialValue) {
+                const baseName = this.getBaseParamName(node.initialValue, aliases);
+                if (baseName) {
+                    for (const v of node.variables || []) {
+                        if (v?.name)
+                            aliases.set(String(v.name), baseName);
+                    }
+                }
+            }
+            for (const child of this.childNodes(node))
+                walk(child);
+        };
+        walk(body);
+        return aliases;
+    }
+    collectTokenTypes(fn, body) {
+        const names = {
+            erc20: new Set(this.contractErc20Names),
+            nonErc20: new Set(this.contractNonErc20Names),
+        };
+        for (const param of fn.parameters || [])
+            this.recordTypedVariable(param, names.erc20, names.nonErc20);
+        const walk = (node) => {
+            if (!node || typeof node !== 'object')
+                return;
+            if ((0, ast_1.isNode)(node, 'VariableDeclarationStatement')) {
+                for (const variable of node.variables || node.declarations || []) {
+                    this.recordTypedVariable(variable, names.erc20, names.nonErc20);
+                }
+            }
+            for (const child of this.childNodes(node))
+                walk(child);
+        };
+        walk(body);
+        return names;
+    }
+    /**
+     * Resolve an expression back to the parameter name it derives from.
+     * Handles a bare identifier, a struct-field access of a parameter
+     * (`payment.payer`), and a local alias of either. Returns null for
+     * anything else (a deeper `abi.decode(bytes)` flow is a documented miss).
+     */
+    getBaseParamName(expr, aliases) {
+        if (!expr || typeof expr !== 'object')
+            return null;
+        if ((0, ast_1.isNode)(expr, 'Identifier')) {
+            const name = String(expr.name || '');
+            return aliases.has(name) ? aliases.get(name) || null : name;
+        }
+        if ((0, ast_1.isNode)(expr, 'MemberAccess')) {
+            return this.getBaseParamName(expr.expression, aliases);
+        }
+        return null;
+    }
+    /**
+     * The `from` argument of a `transferFrom` / `safeTransferFrom` call, or
+     * null if the call is neither. ERC-20 `transferFrom(from, to, amount)`
+     * and SafeERC20 shapes: static `SafeERC20.safeTransferFrom(token, from,
+     * to, amount)` plus extension-style `IERC20(token).safeTransferFrom(from,
+     * to, amount)` / `token.safeTransferFrom(from, to, amount)` when there is
+     * SafeERC20-for-IERC20 evidence. ERC-721's 3-arg
+     * `safeTransferFrom(from, to, tokenId)` is intentionally out of scope.
+     */
+    getFromArgument(node, tokenTypes) {
+        const expr = node.expression;
+        if (!(0, ast_1.isNode)(expr, 'MemberAccess'))
+            return null;
+        const memberName = String(expr.memberName || '');
+        const args = node.arguments || [];
+        if (memberName === 'transferFrom' && args.length === 3)
+            return args[0];
+        if (memberName === 'safeTransferFrom' && args.length === 4)
+            return args[1];
+        if (memberName === 'safeTransferFrom' && args.length === 3 && this.hasErc20SafeTransferFromEvidence(expr, tokenTypes)) {
+            return args[0];
+        }
+        return null;
+    }
+    recordUsingFor(node) {
+        const libraryName = String(node?.libraryName || node?.library?.name || '');
+        if (libraryName !== 'SafeERC20')
+            return;
+        const typeName = typeNameText(node.typeName || node.type);
+        if (isErc20TypeName(typeName))
+            this.hasSafeErc20ForErc20 = true;
+    }
+    recordTypedVariable(node, erc20Target, nonErc20Target) {
+        const name = String(node?.name || node?.identifier?.name || '');
+        if (!name)
+            return;
+        const typeName = typeNameText(node.typeName);
+        if (!typeName)
+            return;
+        if (isErc20TypeName(typeName))
+            erc20Target.add(name);
+        else
+            nonErc20Target.add(name);
+    }
+    hasErc20SafeTransferFromEvidence(expr, tokenTypes) {
+        const receiver = expr.expression;
+        if (isErc20Cast(receiver))
+            return true;
+        if ((0, ast_1.isNode)(receiver, 'Identifier')) {
+            const name = String(receiver.name || '');
+            if (tokenTypes.nonErc20.has(name))
+                return false;
+            if (tokenTypes.erc20.has(name))
+                return true;
+        }
+        return this.hasSafeErc20ForErc20;
+    }
+    getDirectCallName(expr) {
+        return (0, ast_1.isNode)(expr, 'Identifier') ? String(expr.name || '') : '';
+    }
+    childNodes(node) {
+        const out = [];
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'loc' || key === 'range' || key === 'typeName')
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value) {
+                    if (item && typeof item === 'object')
+                        out.push(item);
+                }
+            }
+            else if (value && typeof value === 'object') {
+                out.push(value);
+            }
+        }
+        return out;
+    }
+}
+exports.UnauthorizedPayerTransferfromDetector = UnauthorizedPayerTransferfromDetector;
+function typeNameText(typeName) {
+    if (!typeName || typeof typeName !== 'object')
+        return '';
+    if (typeof typeName.namePath === 'string')
+        return typeName.namePath;
+    if (typeof typeName.name === 'string')
+        return typeName.name;
+    if (typeName.typeName)
+        return typeNameText(typeName.typeName);
+    return '';
+}
+function isErc20TypeName(typeName) {
+    const tail = typeName.split('.').pop() || typeName;
+    return tail === 'IERC20' || tail === 'ERC20';
+}
+function isErc20Cast(expr) {
+    if (!expr || !(0, ast_1.isNode)(expr, 'FunctionCall'))
+        return false;
+    const callee = expr.expression;
+    return (0, ast_1.isNode)(callee, 'Identifier') && isErc20TypeName(String(callee.name || ''));
+}
+//# sourceMappingURL=unauthorized-payer-transferfrom.js.map

package/dist/detectors/unauthorized-transferfrom-shell.d.ts

@@ -0,0 +1,7 @@
+import type { ScanResult } from '../index';
+export declare class UnauthorizedTransferfromShellDetector {
+    readonly id = "unauthorized-transferfrom";
+    readonly patternKey = "unauthorized-transferfrom";
+    readonly supportedAstKinds: ("parser" | "solc")[];
+    scanAst(ast: any, file: string, sourceText?: string): ScanResult[];
+}