@dailephd/my-dev-kit-lab 0.3.4 → 0.4.1

package/dist/src/mobile/android/advancedSecurity/externalTools/semgrep/checkResult.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+import { sortCandidateEvidence } from "../../ordering.js";
+import { discoverAllowlistedExecutable } from "../discoverExecutable.js";
+import { buildMinimalEnvironment } from "../minimalEnvironment.js";
+import { writeExternalToolArtifact } from "../artifacts.js";
+import { captureTargetSnapshot, buildExternalToolMutationReport } from "../mutation.js";
+import { runBoundedExternalTool, buildCommandSummary, VERSION_PROBE_TIMEOUT_MS } from "../runBoundedExternalTool.js";
+import { serializeSemgrepRulePack } from "./rules.js";
+import { buildSemgrepArgs, parseSemgrepMajorVersion, semgrepCommandFamilyForVersion } from "./command.js";
+import { parseSemgrepJson } from "./parseSemgrepJson.js";
+// ---------------------------------------------------------------------------
+// v0.4.1 Batch 7 — standalone Android Semgrep check. Not called from
+// validateAndroidTarget or any active orchestration; not rendered in
+// reports; no CLI effect. Batch 8 integrates.
+// ---------------------------------------------------------------------------
+export const ANDROID_SEMGREP_AUDIT_CHECK_ID = "android-semgrep-audit";
+const SEMGREP_CANDIDATES = ["semgrep", "semgrep.exe"];
+const SEMGREP_TIMEOUT_MS = 5 * 60_000;
+function skippedCheck(reason, environmentRequirements = []) {
+    return {
+        id: ANDROID_SEMGREP_AUDIT_CHECK_ID,
+        category: "android-semgrep",
+        title: "Android Semgrep audit",
+        status: "skipped",
+        requirementLevel: "optional",
+        ran: false,
+        skipped: true,
+        skipInfo: {
+            checkId: ANDROID_SEMGREP_AUDIT_CHECK_ID,
+            reason,
+            requirementLevel: "optional",
+            missingCapability: "semgrep-executable",
+            verdictImpact: "does not apply until Batch 8 integration",
+            recommendedNextAction: "Install Semgrep locally, or run again after Batch 8 wires optional-tool selection into the CLI.",
+        },
+        evidence: [],
+        findings: [],
+        warnings: [],
+        errors: [],
+        sourcePaths: [],
+        confidence: "unknown",
+        environmentRequirements,
+        candidateEvidence: [],
+    };
+}
+export async function auditAndroidSemgrep(options) {
+    const targetRoot = path.resolve(options.targetRoot);
+    const discovered = (options.discover ?? (() => discoverAllowlistedExecutable(SEMGREP_CANDIDATES, targetRoot)))();
+    if (!discovered.available) {
+        return skippedCheck("Semgrep executable was not found on PATH.", ["Requires a Semgrep executable (semgrep) on PATH."]);
+    }
+    const env = buildMinimalEnvironment();
+    const versionInput = { command: discovered.command, args: ["--version"], cwd: targetRoot, timeoutMs: VERSION_PROBE_TIMEOUT_MS, env };
+    const versionOutcome = await runBoundedExternalTool(options.executor, versionInput);
+    if (versionOutcome.result.timedOut || versionOutcome.result.exitCode === null) {
+        return skippedCheck("Semgrep version probe failed or timed out.");
+    }
+    const rawVersion = versionOutcome.stdout.trim();
+    const majorVersion = parseSemgrepMajorVersion(rawVersion);
+    const family = semgrepCommandFamilyForVersion(majorVersion);
+    if (!family) {
+        return skippedCheck(`Semgrep version "${rawVersion || "(unknown)"}" is not a supported version family.`);
+    }
+    const configArtifact = writeExternalToolArtifact(options.artifactRoot, "semgrep", "android-rules.yaml", serializeSemgrepRulePack(), "text");
+    const configAbsolutePath = path.resolve(options.artifactRoot, configArtifact.relativePath);
+    const args = buildSemgrepArgs(family, configAbsolutePath, targetRoot);
+    const commandSummary = buildCommandSummary(discovered.basename, args, targetRoot, path.resolve(options.artifactRoot));
+    const before = captureTargetSnapshot(targetRoot, true);
+    const analysisOutcome = await runBoundedExternalTool(options.executor, { command: discovered.command, args, cwd: targetRoot, timeoutMs: SEMGREP_TIMEOUT_MS, env });
+    const after = captureTargetSnapshot(targetRoot, true);
+    const mutation = buildExternalToolMutationReport(before, after);
+    const warnings = [];
+    if (analysisOutcome.stdoutTruncated)
+        warnings.push("stdout was truncated; JSON output was not parsed as complete.");
+    if (analysisOutcome.stderrTruncated)
+        warnings.push("stderr was truncated.");
+    if (!mutation.comparable)
+        warnings.push(`Target mutation evidence unavailable: ${mutation.reason ?? "unknown reason"}`);
+    if (mutation.unexpectedChanges.length > 0)
+        warnings.push(`Unexpected target change(s) observed: ${mutation.unexpectedChanges.join(", ")}`);
+    if (analysisOutcome.result.timedOut) {
+        return {
+            id: ANDROID_SEMGREP_AUDIT_CHECK_ID,
+            category: "android-semgrep",
+            title: "Android Semgrep audit",
+            status: "inconclusive",
+            requirementLevel: "optional",
+            ran: true,
+            skipped: false,
+            evidence: [`version=${rawVersion}`, `commandFamily=${family}`],
+            findings: [],
+            warnings: [...warnings, `Semgrep timed out after ${SEMGREP_TIMEOUT_MS}ms.`],
+            errors: [],
+            sourcePaths: [],
+            confidence: "medium",
+            environmentRequirements: [],
+            candidateEvidence: [],
+        };
+    }
+    if (analysisOutcome.stdoutTruncated) {
+        return {
+            id: ANDROID_SEMGREP_AUDIT_CHECK_ID,
+            category: "android-semgrep",
+            title: "Android Semgrep audit",
+            status: "inconclusive",
+            requirementLevel: "optional",
+            ran: true,
+            skipped: false,
+            evidence: [`version=${rawVersion}`, `commandFamily=${family}`],
+            findings: [],
+            warnings,
+            errors: [],
+            sourcePaths: [],
+            confidence: "low",
+            environmentRequirements: [],
+            candidateEvidence: [],
+        };
+    }
+    const parsed = parseSemgrepJson(analysisOutcome.stdout, targetRoot, configArtifact.sha256);
+    const isFindingsExitCode = analysisOutcome.result.exitCode === 0 || analysisOutcome.result.exitCode === 1;
+    if (parsed.malformed) {
+        return {
+            id: ANDROID_SEMGREP_AUDIT_CHECK_ID,
+            category: "android-semgrep",
+            title: "Android Semgrep audit",
+            status: isFindingsExitCode ? "inconclusive" : "failed",
+            requirementLevel: "optional",
+            ran: true,
+            skipped: false,
+            evidence: [`version=${rawVersion}`, `commandFamily=${family}`, `exitCode=${analysisOutcome.result.exitCode}`],
+            findings: [],
+            warnings,
+            errors: isFindingsExitCode ? [] : ["Semgrep exited with a non-findings error and produced no parseable JSON report."],
+            sourcePaths: [],
+            confidence: "low",
+            environmentRequirements: [],
+            candidateEvidence: [],
+        };
+    }
+    for (const parserError of parsed.parserErrors) {
+        warnings.push(`Semgrep reported a parser error: ${parserError}`);
+    }
+    if (parsed.truncated)
+        warnings.push(`Finding count exceeded the bounded limit; results were truncated.`);
+    const findingsById = new Map(parsed.findings.map((f) => [f.id, f]));
+    const candidatesById = new Map(parsed.candidates.map((c) => [c.id, c]));
+    const findings = [...findingsById.values()].sort((a, b) => a.id.localeCompare(b.id));
+    const candidateEvidence = sortCandidateEvidence([...candidatesById.values()]);
+    // A findings exit code (0 or 1) with valid JSON is never treated as a
+    // process crash — Semgrep uses 1 to mean "findings were reported", not
+    // "the tool failed" (agents.txt Batch 7 section 10.11).
+    const status = findings.length > 0 ? "failed" : isFindingsExitCode ? "passed" : "error";
+    return {
+        id: ANDROID_SEMGREP_AUDIT_CHECK_ID,
+        category: "android-semgrep",
+        title: "Android Semgrep audit",
+        status,
+        requirementLevel: "optional",
+        ran: true,
+        skipped: false,
+        evidence: [`version=${rawVersion}`, `commandFamily=${family}`, `scanned=${parsed.scannedCount}`, `command=${commandSummary}`],
+        findings,
+        warnings,
+        errors: status === "error" ? ["Semgrep exited with a non-findings error."] : [],
+        sourcePaths: [],
+        confidence: parsed.parserErrors.length > 0 ? "medium" : "high",
+        environmentRequirements: [],
+        candidateEvidence,
+    };
+}

package/dist/src/mobile/android/advancedSecurity/externalTools/semgrep/command.js

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// v0.4.1 Batch 7 — fixed Semgrep command planning.
+//
+// Exactly two supported command families, selected only by parsed major
+// version — never by trial-and-error after a failed attempt. No caller-
+// provided flags, config identifiers, or excludes are ever accepted.
+// ---------------------------------------------------------------------------
+export const SEMGREP_FIXED_EXCLUDES = [".git", "node_modules", "build", "dist", "out", "coverage", ".gradle", "reports", "lab-output", ".my-dev-kit", "*.apk", "*.aab"];
+export function semgrepCommandFamilyForVersion(majorVersion) {
+    if (majorVersion === undefined)
+        return undefined;
+    if (majorVersion >= 1)
+        return "modern";
+    if (majorVersion === 0)
+        return "legacy";
+    return undefined;
+}
+export function parseSemgrepMajorVersion(rawVersion) {
+    const match = /(\d+)\.\d+\.\d+/.exec(rawVersion);
+    if (!match)
+        return undefined;
+    return Number.parseInt(match[1], 10);
+}
+export function buildSemgrepArgs(family, configPath, targetRoot) {
+    const excludeArgs = SEMGREP_FIXED_EXCLUDES.flatMap((pattern) => ["--exclude", pattern]);
+    const base = ["--config", configPath, "--json", "--metrics=off", "--disable-version-check", ...excludeArgs, targetRoot];
+    return family === "modern" ? ["scan", ...base] : base;
+}

package/dist/src/mobile/android/advancedSecurity/externalTools/semgrep/index.js

@@ -0,0 +1,2 @@
+export { auditAndroidSemgrep, ANDROID_SEMGREP_AUDIT_CHECK_ID } from "./checkResult.js";
+export { ANDROID_SEMGREP_RULE_PACK, assertUniqueSemgrepRuleIds, serializeSemgrepRulePack } from "./rules.js";

package/dist/src/mobile/android/advancedSecurity/externalTools/semgrep/parseSemgrepJson.js

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { makeAndroidFinding } from "../../../audit/androidFinding.js";
+import { makeCandidateEvidence } from "../../candidateEvidence.js";
+import { buildAndroidSourceLocation } from "../../sourceLocation.js";
+import { safeJsonParse, DEFAULT_MAX_MESSAGE_LENGTH } from "../boundedOutput.js";
+// ---------------------------------------------------------------------------
+// v0.4.1 Batch 7 — bounded Semgrep JSON normalization.
+//
+// Only the one Batch 1 Semgrep rule id (android-optional-tool-semgrep-
+// evidence) is used internally; the external Semgrep rule id is preserved
+// separately as `externalRuleId`. Full source snippets (extra.lines) and
+// complete metavariable values are never retained.
+// ---------------------------------------------------------------------------
+const MAX_RESULTS = 5_000;
+const MAX_SKIPPED_PATHS = 200;
+function severityToProjectSeverity(severity) {
+    switch (severity) {
+        case "ERROR":
+            return "major";
+        case "WARNING":
+            return "minor";
+        default:
+            return "informational";
+    }
+}
+function boundedMessage(message) {
+    const text = typeof message === "string" ? message : "";
+    return text.length > DEFAULT_MAX_MESSAGE_LENGTH ? `${text.slice(0, DEFAULT_MAX_MESSAGE_LENGTH)}...` : text;
+}
+export function parseSemgrepJson(rawStdout, targetRoot, configFingerprint) {
+    const parsed = safeJsonParse(rawStdout);
+    if (!parsed.ok) {
+        return { malformed: true, findings: [], candidates: [], scannedCount: 0, skippedPaths: [], parserErrors: [], truncated: parsed.truncated };
+    }
+    const doc = parsed.value;
+    const toolVersion = typeof doc.version === "string" ? doc.version : undefined;
+    const results = Array.isArray(doc.results) ? doc.results : [];
+    const errors = Array.isArray(doc.errors) ? doc.errors : [];
+    const pathsSection = doc.paths;
+    const scanned = Array.isArray(pathsSection?.scanned) ? pathsSection.scanned : [];
+    const skipped = Array.isArray(pathsSection?.skipped) ? pathsSection.skipped : [];
+    const findings = [];
+    const candidates = [];
+    let truncated = false;
+    for (const rawResult of results.slice(0, MAX_RESULTS)) {
+        if (results.length > MAX_RESULTS)
+            truncated = true;
+        const result = rawResult;
+        const checkId = typeof result.check_id === "string" ? result.check_id : "(unknown-rule)";
+        const relativePath = typeof result.path === "string" ? result.path : undefined;
+        const start = result.start;
+        const line = typeof start?.line === "number" ? start.line : undefined;
+        const extra = result.extra ?? {};
+        const severity = typeof extra.severity === "string" ? extra.severity : undefined;
+        const message = boundedMessage(extra.message);
+        const projectSeverity = severityToProjectSeverity(severity);
+        if (!relativePath) {
+            candidates.push(makeCandidateEvidence({
+                ruleId: "android-optional-tool-semgrep-evidence",
+                category: "android-semgrep",
+                confidence: "low",
+                location: { path: "(unknown)" },
+                summary: `Semgrep result "${checkId}" had no reportable path`,
+                rawValue: undefined,
+                resolutionState: "unresolved",
+                staticAnalysisLimitations: ["Semgrep static analysis only; does not prove runtime exploitability."],
+            }));
+            continue;
+        }
+        const absolutePath = path.resolve(targetRoot, relativePath);
+        let location;
+        try {
+            location = buildAndroidSourceLocation(targetRoot, absolutePath, { line });
+        }
+        catch {
+            candidates.push(makeCandidateEvidence({
+                ruleId: "android-optional-tool-semgrep-evidence",
+                category: "android-semgrep",
+                confidence: "low",
+                location: { path: relativePath },
+                summary: `Semgrep result "${checkId}" reported a path outside the target`,
+                rawValue: relativePath,
+                resolutionState: "unresolved",
+                staticAnalysisLimitations: ["Semgrep static analysis only; does not prove runtime exploitability."],
+            }));
+            continue;
+        }
+        if (projectSeverity === "informational" || severity === undefined) {
+            candidates.push(makeCandidateEvidence({
+                ruleId: "android-optional-tool-semgrep-evidence",
+                category: "android-semgrep",
+                confidence: "medium",
+                location,
+                summary: `Semgrep ${severity ?? "unknown-severity"} result: ${checkId} — ${message}`,
+                rawValue: message,
+                resolutionState: "resolved",
+                staticAnalysisLimitations: [`External rule: ${checkId}`, "Semgrep static analysis only; does not prove runtime exploitability."],
+            }));
+            continue;
+        }
+        findings.push(makeAndroidFinding({
+            ruleId: "android-optional-tool-semgrep-evidence",
+            title: `Semgrep finding: ${checkId}`,
+            severity: projectSeverity,
+            confidence: "medium",
+            description: message || "Semgrep reported a finding for this rule.",
+            manifestPath: relativePath,
+            identity: `semgrep:${checkId}:${configFingerprint.slice(0, 16)}`,
+            location: { line },
+            evidenceDetails: [`externalRuleId=${checkId}`, `toolSeverity=${severity}`],
+            recommendation: "Review the Semgrep rule pack entry and remediate the matched pattern.",
+        }));
+    }
+    for (const rawSkip of skipped.slice(0, MAX_SKIPPED_PATHS)) {
+        const skip = rawSkip;
+        const skippedPath = typeof skip === "string" ? skip : typeof skip.path === "string" ? skip.path : undefined;
+        if (skippedPath) {
+            candidates.push(makeCandidateEvidence({
+                ruleId: "android-optional-tool-semgrep-evidence",
+                category: "android-semgrep",
+                confidence: "low",
+                location: { path: skippedPath },
+                summary: "Semgrep skipped this path during the scan",
+                rawValue: undefined,
+                resolutionState: "not-applicable",
+                staticAnalysisLimitations: ["Semgrep static analysis only."],
+            }));
+        }
+    }
+    const parserErrors = errors.slice(0, 50).map((e) => (typeof e === "object" && e !== null && "message" in e ? boundedMessage(e.message) : "Semgrep reported an error."));
+    return {
+        malformed: false,
+        toolVersion,
+        findings,
+        candidates,
+        scannedCount: scanned.length,
+        skippedPaths: skipped.map((s) => (typeof s === "string" ? s : typeof s?.path === "string" ? s.path : "")).filter(Boolean),
+        parserErrors,
+        truncated,
+    };
+}

package/dist/src/mobile/android/advancedSecurity/externalTools/semgrep/rules.js

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// v0.4.1 Batch 7 — package-owned, bounded Android-focused Semgrep rule pack.
+//
+// Small, stable supplement to the internal checks — NOT a replacement.
+// Deliberately excludes hardcoded-secret rules (owned by Batch 4's
+// secretCandidates analyzer) and manifest-attribute rules (owned by the
+// internal manifest parser); covers source-level patterns those analyzers
+// do not reach. Caller-provided configuration is never accepted — this is
+// the only rule pack Semgrep is ever invoked with.
+// ---------------------------------------------------------------------------
+export const ANDROID_SEMGREP_RULE_PACK = [
+    {
+        id: "android-semgrep-trust-all-hostname-verifier",
+        languages: ["java", "kotlin"],
+        message: "A HostnameVerifier implementation unconditionally returns true, disabling TLS hostname verification.",
+        severity: "ERROR",
+        cwe: ["CWE-297"],
+        owasp: ["A02:2021"],
+        patterns: ["new HostnameVerifier() { ... boolean verify(...) { return true; } ... }"],
+    },
+    {
+        id: "android-semgrep-permissive-x509-trust-manager",
+        languages: ["java", "kotlin"],
+        message: "An X509TrustManager implementation has an empty or no-op certificate validation method, accepting any certificate chain.",
+        severity: "ERROR",
+        cwe: ["CWE-295"],
+        owasp: ["A02:2021"],
+        patterns: [
+            "class $T : X509TrustManager { ... override fun checkServerTrusted(...) { } ... }",
+            "new X509TrustManager() { ... public void checkServerTrusted(...) { } ... }",
+        ],
+    },
+    {
+        id: "android-semgrep-ssl-error-handler-proceed",
+        languages: ["java", "kotlin"],
+        message: "onReceivedSslError calls handler.proceed(), ignoring the certificate error and continuing the connection.",
+        severity: "ERROR",
+        cwe: ["CWE-295"],
+        patterns: ["... onReceivedSslError(...) { ... $HANDLER.proceed() ... }"],
+    },
+    {
+        id: "android-semgrep-webview-universal-file-url-access",
+        languages: ["java", "kotlin"],
+        message: "setAllowUniversalAccessFromFileURLs(true) allows file:// content to access any origin.",
+        severity: "WARNING",
+        cwe: ["CWE-668"],
+        patterns: ["$WEBVIEW.settings.allowUniversalAccessFromFileURLs = true", "$SETTINGS.setAllowUniversalAccessFromFileURLs(true)"],
+    },
+    {
+        id: "android-semgrep-webview-debugging-enabled",
+        languages: ["java", "kotlin"],
+        message: "WebView.setWebContentsDebuggingEnabled(true) is set unconditionally, which may ship to release builds.",
+        severity: "INFO",
+        patterns: ["WebView.setWebContentsDebuggingEnabled(true)"],
+    },
+    {
+        id: "android-semgrep-world-readable-writable-mode",
+        languages: ["java", "kotlin"],
+        message: "A file or preferences API is opened with MODE_WORLD_READABLE or MODE_WORLD_WRITEABLE.",
+        severity: "ERROR",
+        cwe: ["CWE-732"],
+        patterns: ["$CTX.getSharedPreferences($NAME, Context.MODE_WORLD_READABLE)", "$CTX.getSharedPreferences($NAME, Context.MODE_WORLD_WRITEABLE)", "$CTX.openFileOutput($NAME, Context.MODE_WORLD_READABLE)", "$CTX.openFileOutput($NAME, Context.MODE_WORLD_WRITEABLE)"],
+    },
+    {
+        id: "android-semgrep-weak-digest-md5-sha1",
+        languages: ["java", "kotlin"],
+        message: "MessageDigest.getInstance uses a weak digest algorithm (MD5 or SHA-1) for security-sensitive hashing.",
+        severity: "WARNING",
+        cwe: ["CWE-327"],
+        patterns: ['MessageDigest.getInstance("MD5")', 'MessageDigest.getInstance("SHA-1")', 'MessageDigest.getInstance("SHA1")'],
+    },
+    {
+        id: "android-semgrep-insecure-cipher-transformation",
+        languages: ["java", "kotlin"],
+        message: "Cipher.getInstance uses an insecure transformation (ECB mode, DES, or RC4).",
+        severity: "ERROR",
+        cwe: ["CWE-327"],
+        patterns: ['Cipher.getInstance("...ECB...")', 'Cipher.getInstance("DES")', 'Cipher.getInstance("RC4")'],
+    },
+];
+export function assertUniqueSemgrepRuleIds() {
+    const ids = ANDROID_SEMGREP_RULE_PACK.map((rule) => rule.id);
+    const unique = new Set(ids);
+    if (unique.size !== ids.length) {
+        throw new Error("Duplicate Semgrep rule id detected in ANDROID_SEMGREP_RULE_PACK.");
+    }
+}
+// Deterministic YAML-compatible serialization (JSON is valid YAML; Semgrep
+// accepts a .yaml/.yml config file). Key order is fixed so repeated calls
+// produce byte-identical output (config fingerprinting depends on this).
+export function serializeSemgrepRulePack() {
+    const rules = ANDROID_SEMGREP_RULE_PACK.map((rule) => ({
+        id: rule.id,
+        languages: [...rule.languages],
+        message: rule.message,
+        severity: rule.severity,
+        metadata: {
+            ...(rule.cwe ? { cwe: [...rule.cwe] } : {}),
+            ...(rule.owasp ? { owasp: [...rule.owasp] } : {}),
+            "android-package-owned": true,
+        },
+        "pattern-either": rule.patterns.map((pattern) => ({ pattern })),
+    }));
+    return JSON.stringify({ rules }, null, 2);
+}

package/dist/src/mobile/android/advancedSecurity/externalTools/types.js

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// v0.4.1 Batch 7 — common contract for optional external Android
+// security-tool evidence (Semgrep, OSV-Scanner, Android Lint,
+// OWASP Dependency-Check).
+//
+// This module defines identities and request/result shapes only. No process
+// ever executes because a type exists here. Every tool remains disconnected
+// from validateAndroidTarget, the CLI, verdict calculation, and active
+// reports until Batch 8 — see each adapter's checkResult.ts for the
+// standalone AndroidCheckResult-compatible builder.
+// ---------------------------------------------------------------------------
+export const ANDROID_EXTERNAL_TOOL_IDS = ["semgrep", "osv", "android-lint", "dependency-check"];
+export function isAndroidExternalSecurityToolId(value) {
+    return ANDROID_EXTERNAL_TOOL_IDS.includes(value);
+}
+// Deterministic dispatch order — never concurrent, never caller-controlled.
+export const ANDROID_EXTERNAL_TOOL_ORDER = ["semgrep", "osv", "android-lint", "dependency-check"];
+export const ANDROID_EXTERNAL_TOOL_NETWORK_POLICIES = ["deny", "allow-for-requested-tool"];
+const MIN_TIMEOUT_OVERRIDE_MS = 5_000;
+const MAX_TIMEOUT_OVERRIDE_MS = 30 * 60_000;
+// Deduplicates and orders requested tool ids deterministically, and rejects
+// any id outside the closed ANDROID_EXTERNAL_TOOL_IDS union at this single
+// contract boundary — no caller can smuggle an arbitrary tool identity past
+// this point.
+export function normalizeAndroidExternalToolRequest(request) {
+    if (!request || !Array.isArray(request.requestedTools) || request.requestedTools.length === 0) {
+        return {
+            ok: true,
+            value: {
+                tools: [],
+                targetRoot: request?.targetRoot ?? "",
+                artifactRoot: request?.artifactRoot ?? "",
+                networkPolicy: request?.networkPolicy ?? "deny",
+                timeoutOverrideMs: request?.timeoutOverrideMs,
+            },
+        };
+    }
+    const unknown = request.requestedTools.filter((id) => !isAndroidExternalSecurityToolId(id));
+    if (unknown.length > 0) {
+        return { ok: false, error: `Unknown external security tool id(s): ${unknown.join(", ")}` };
+    }
+    if (!request.targetRoot)
+        return { ok: false, error: "targetRoot is required." };
+    if (!request.artifactRoot)
+        return { ok: false, error: "artifactRoot is required." };
+    if (request.timeoutOverrideMs !== undefined) {
+        if (request.timeoutOverrideMs < MIN_TIMEOUT_OVERRIDE_MS || request.timeoutOverrideMs > MAX_TIMEOUT_OVERRIDE_MS) {
+            return { ok: false, error: `timeoutOverrideMs must be between ${MIN_TIMEOUT_OVERRIDE_MS} and ${MAX_TIMEOUT_OVERRIDE_MS}.` };
+        }
+    }
+    const requestedSet = new Set(request.requestedTools);
+    const tools = ANDROID_EXTERNAL_TOOL_ORDER.filter((id) => requestedSet.has(id));
+    return {
+        ok: true,
+        value: {
+            tools,
+            targetRoot: request.targetRoot,
+            artifactRoot: request.artifactRoot,
+            networkPolicy: request.networkPolicy ?? "deny",
+            timeoutOverrideMs: request.timeoutOverrideMs,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Artifact references — Batch 7 introduces this concept new (no existing
+// owner copies/hashes generated tool output); Batch 8 decides where active
+// reports place these.
+// ---------------------------------------------------------------------------
+export const ANDROID_EXTERNAL_TOOL_ARTIFACT_KINDS = ["json", "xml", "sarif", "text"];
+export const ANDROID_EXTERNAL_TOOL_PARSE_STATUSES = ["parsed", "malformed", "truncated", "not-attempted"];
+// ---------------------------------------------------------------------------
+// Common per-tool execution result — every adapter's checkResult.ts folds
+// this (plus tool-specific findings/candidates) into a standalone
+// AndroidCheckResult, exactly as the existing Gradle operations fold a
+// CommandExecutionResult via buildGradleOperationCheckResult.
+// ---------------------------------------------------------------------------
+export const ANDROID_EXTERNAL_TOOL_STATUSES = [
+    "not-requested",
+    "skipped",
+    "completed-without-findings",
+    "completed-with-findings",
+    "inconclusive",
+    "failed",
+];
+export function notRequestedResult(toolId, targetRoot, networkPolicy) {
+    return {
+        toolId,
+        requested: false,
+        available: false,
+        executed: false,
+        status: "not-requested",
+        commandSummary: "(not requested)",
+        workingDirectory: targetRoot,
+        networkPolicy,
+        durationMs: 0,
+        exitCode: null,
+        timedOut: false,
+        stdoutTruncated: false,
+        stderrTruncated: false,
+        artifacts: [],
+        warnings: [],
+        errors: [],
+        skips: [],
+        mutationEvidence: { comparable: true, expectedGeneratedChanges: [], unexpectedChanges: [] },
+        limitations: [],
+    };
+}