defense-mcp-server 0.6.0

package/build/core/preflight.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Pre-flight Validation Engine — orchestrates the complete pre-flight
+ * validation pipeline for MCP tools.
+ *
+ * Before each tool invocation this module:
+ * 1. Resolves the tool's manifest from the {@link ToolRegistry}
+ * 2. Checks binary, Python, npm, library, and file dependencies
+ * 3. Attempts auto-installation of missing deps when enabled
+ * 4. Validates privilege requirements via {@link PrivilegeManager}
+ * 5. Returns a structured {@link PreflightResult} with pass/fail, actionable
+ *    messages, and a human-readable summary
+ *
+ * Results are cached for 60 seconds to avoid redundant checks when multiple
+ * tools from the same category are invoked in sequence.
+ *
+ * @module preflight
+ */
+import { type ToolManifest } from "./tool-registry.js";
+import { type PrivilegeIssue } from "./privilege-manager.js";
+export interface PreflightResult {
+    toolName: string;
+    /** Overall pass/fail */
+    passed: boolean;
+    timestamp: number;
+    /** Total pre-flight time in ms */
+    duration: number;
+    dependencies: {
+        /** Everything that was checked */
+        checked: DependencyCheck[];
+        /** Still missing after install attempts */
+        missing: DependencyCheck[];
+        /** Successfully auto-installed */
+        installed: DependencyCheck[];
+        /** Non-fatal dependency issues */
+        warnings: string[];
+    };
+    privileges: {
+        satisfied: boolean;
+        issues: PrivilegeIssue[];
+        recommendations: string[];
+    };
+    safeguards?: {
+        /** Whether the operation is safe */
+        safe: boolean;
+        /** Blocking safety issues (prevent execution) */
+        blockers: string[];
+        /** Non-blocking safety warnings */
+        warnings: string[];
+        /** Applications impacted by the operation */
+        impactedApps: string[];
+    };
+    /** Human-readable summary */
+    summary: string;
+    /** Fatal blocking errors */
+    errors: string[];
+    /** Non-fatal warnings */
+    warnings: string[];
+}
+export interface DependencyCheck {
+    name: string;
+    type: "binary" | "python-module" | "npm-package" | "library" | "file";
+    /** true = required, false = optional */
+    required: boolean;
+    found: boolean;
+    autoInstalled?: boolean;
+    installMessage?: string;
+}
+/**
+ * Central orchestration engine for the pre-flight validation pipeline.
+ *
+ * Singleton — obtain via {@link PreflightEngine.instance}.
+ *
+ * The main entry point is {@link runPreflight}, which executes the full
+ * dependency → auto-install → privilege check pipeline and returns a
+ * structured {@link PreflightResult}.
+ */
+export declare class PreflightEngine {
+    private registry;
+    private privilegeManager;
+    private autoInstaller;
+    /**
+     * Dependency cache — keyed by tool name only, 60s TTL.
+     * Covers: binary existence, privilege checks, auto-install results.
+     * Cached regardless of params (dependency results don't depend on runtime params).
+     */
+    private resultCache;
+    private static readonly CACHE_TTL;
+    private static _instance;
+    private constructor();
+    /** Get or create the singleton instance. */
+    static instance(): PreflightEngine;
+    /**
+     * Run the full pre-flight validation pipeline for a tool.
+     *
+     * 1. Check cache — return early for valid passing results
+     * 2. Resolve the tool's manifest from the registry
+     * 3. Check all dependency types (binary, Python, npm, library, file)
+     * 4. Auto-install missing required deps when enabled
+     * 5. Validate privilege requirements (sudo, capabilities)
+     * 6. Determine overall pass/fail and generate summary
+     * 7. Cache and return the result
+     */
+    runPreflight(toolName: string, params?: Record<string, unknown>): Promise<PreflightResult>;
+    /**
+     * Check all dependency types for a tool manifest.
+     *
+     * Checks binaries, Python modules, npm packages, system libraries,
+     * and required files. If any required dependency is missing and
+     * auto-install is enabled, attempts installation via {@link AutoInstaller}.
+     */
+    checkDependencies(manifest: ToolManifest): Promise<PreflightResult["dependencies"]>;
+    /**
+     * Check privilege requirements for a tool manifest.
+     * Delegates to {@link PrivilegeManager.checkForTool}.
+     */
+    checkPrivileges(manifest: ToolManifest): Promise<PreflightResult["privileges"]>;
+    /**
+     * Generate a human-readable summary of the pre-flight result.
+     *
+     * @example Passing
+     * ```
+     * ✅ Pre-flight passed for 'firewall_iptables_list'
+     *   Dependencies: 2/2 available (iptables, ip6tables)
+     *   Privileges: sudo session active
+     *   Ready to execute.
+     * ```
+     *
+     * @example Failing
+     * ```
+     * ❌ Pre-flight FAILED for 'compliance_oscap_scan'
+     *   Missing dependencies:
+     *     • oscap (binary) — Install with: sudo apt-get install -y libopenscap8
+     *   Privilege issues:
+     *     • Root access required for OpenSCAP scanning
+     *     → Run 'sudo_elevate' tool first to provide credentials
+     *   Cannot proceed until issues are resolved.
+     * ```
+     */
+    formatSummary(result: PreflightResult): string;
+    /**
+     * Generate a shorter status message for prepending to tool output.
+     *
+     * - Passed (no issues): `"[pre-flight ✓] All checks passed (2 deps, sudo active)"`
+     * - Passed (warnings): `"[pre-flight ✓] Passed with warnings: optional dep 'nmap' not found"`
+     * - Failed: returns the full error summary from {@link formatSummary}
+     */
+    formatStatusMessage(result: PreflightResult): string;
+    /**
+     * Clear the result cache.
+     * Call after installs, privilege changes, or any event that invalidates
+     * previous pre-flight results.
+     */
+    clearCache(): void;
+    /** Store a result in the cache with TTL. */
+    private cacheResult;
+}
+//# sourceMappingURL=preflight.d.ts.map

package/build/core/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/core/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAehC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IAGjB,YAAY,EAAE;QACZ,kCAAkC;QAClC,OAAO,EAAE,eAAe,EAAE,CAAC;QAC3B,2CAA2C;QAC3C,OAAO,EAAE,eAAe,EAAE,CAAC;QAC3B,kCAAkC;QAClC,SAAS,EAAE,eAAe,EAAE,CAAC;QAC7B,kCAAkC;QAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IAGF,UAAU,EAAE;QACV,SAAS,EAAE,OAAO,CAAC;QACnB,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,eAAe,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;IAGF,UAAU,CAAC,EAAE;QACX,oCAAoC;QACpC,IAAI,EAAE,OAAO,CAAC;QACd,iDAAiD;QACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,mCAAmC;QACnC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,6CAA6C;QAC7C,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;IAEF,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;IACtE,wCAAwC;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA6ID;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,aAAa,CAAgB;IAErC;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAA2D;IAC9E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAU;IAE3C,OAAO,CAAC,MAAM,CAAC,SAAS,CAAgC;IAExD,OAAO;IAOP,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,IAAI,eAAe;IASlC;;;;;;;;;;OAUG;IACG,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,eAAe,CAAC;IAmM3B;;;;;;OAMG;IACG,iBAAiB,CACrB,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IA0J3C;;;OAGG;IACG,eAAe,CACnB,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAWzC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IAoG9C;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IAiCpD;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAMlB,4CAA4C;IAC5C,OAAO,CAAC,WAAW;CAMpB"}