defense-mcp-server 0.6.0

package/build/core/logger.d.ts

@@ -0,0 +1,102 @@
+/**
+ * logger.ts — Structured logging module for security event correlation.
+ *
+ * Outputs JSON-formatted log entries with consistent fields for easy parsing
+ * by log aggregation systems (ELK, Splunk, Loki, etc.).
+ *
+ * Supports standard log levels plus a `security` level for security-relevant
+ * events (authentication, privilege escalation, policy violations).
+ *
+ * @module logger
+ * @see CICD-027
+ */
+/** Supported log levels, ordered by severity (lowest to highest). */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "security";
+/** A structured log entry written as JSON to stderr. */
+export interface LogEntry {
+    /** ISO 8601 UTC timestamp */
+    timestamp: string;
+    /** Log severity level */
+    level: LogLevel;
+    /** Module or subsystem that produced the log (e.g., "preflight", "executor") */
+    component: string;
+    /** Action being performed (e.g., "tool_invoked", "sudo_elevated") */
+    action: string;
+    /** Human-readable message */
+    message: string;
+    /** Optional structured details (tool params, error info, metrics, etc.) */
+    details?: Record<string, unknown>;
+}
+/**
+ * Structured logger that outputs JSON to stderr.
+ *
+ * Uses stderr so log output doesn't interfere with MCP protocol messages
+ * on stdout (StdioServerTransport).
+ *
+ * Usage:
+ * ```typescript
+ * import { logger } from './logger.js';
+ *
+ * logger.info('preflight', 'cache_hit', 'Pre-flight cache hit for tool', { toolName: 'firewall_iptables' });
+ * logger.security('sudo-guard', 'elevation_requested', 'Sudo elevation requested', { tool: 'harden_sysctl' });
+ * ```
+ */
+export declare class Logger {
+    private minLevel;
+    constructor(minLevel?: LogLevel);
+    /**
+     * Read the minimum log level from `KALI_DEFENSE_LOG_LEVEL` env var.
+     * Falls back to `"info"` if unset or invalid.
+     */
+    private parseEnvLevel;
+    /** Check whether a message at `level` should be emitted. */
+    private shouldLog;
+    /**
+     * Emit a structured log entry as a single JSON line to stderr.
+     *
+     * @param level     - Severity level
+     * @param component - Subsystem name (e.g., "executor", "preflight")
+     * @param action    - Action identifier (e.g., "command_executed", "cache_miss")
+     * @param message   - Human-readable description
+     * @param details   - Optional structured metadata
+     */
+    log(level: LogLevel, component: string, action: string, message: string, details?: Record<string, unknown>): void;
+    /** Log a debug-level message. */
+    debug(component: string, action: string, message: string, details?: Record<string, unknown>): void;
+    /** Log an info-level message. */
+    info(component: string, action: string, message: string, details?: Record<string, unknown>): void;
+    /** Log a warning-level message. */
+    warn(component: string, action: string, message: string, details?: Record<string, unknown>): void;
+    /** Log an error-level message. */
+    error(component: string, action: string, message: string, details?: Record<string, unknown>): void;
+    /**
+     * Log a security-relevant event.
+     *
+     * Security events are **always** emitted regardless of the configured
+     * minimum log level. Use for:
+     * - Authentication / privilege escalation events
+     * - Policy violations
+     * - Rate limit breaches
+     * - Suspicious input patterns
+     * - Configuration changes with security impact
+     */
+    security(component: string, action: string, message: string, details?: Record<string, unknown>): void;
+    /**
+     * Update the minimum log level at runtime.
+     * Useful for tests or dynamic configuration changes.
+     */
+    setLevel(level: LogLevel): void;
+    /** Get the current minimum log level. */
+    getLevel(): LogLevel;
+}
+/**
+ * Default singleton logger instance.
+ *
+ * Import and use directly:
+ * ```typescript
+ * import { logger } from '../core/logger.js';
+ * logger.info('my-module', 'action', 'Something happened');
+ * ```
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAYxE,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,yBAAyB;IACzB,KAAK,EAAE,QAAQ,CAAC;IAChB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAW;gBAEf,QAAQ,CAAC,EAAE,QAAQ;IAI/B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAQrB,4DAA4D;IAC5D,OAAO,CAAC,SAAS;IAIjB;;;;;;;;OAQG;IACH,GAAG,CACD,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAgBP,iCAAiC;IACjC,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAIP,iCAAiC;IACjC,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAIP,mCAAmC;IACnC,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAIP,kCAAkC;IAClC,KAAK,CACH,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAIP;;;;;;;;;;OAUG;IACH,QAAQ,CACN,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI;IAIP;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B,yCAAyC;IACzC,QAAQ,IAAI,QAAQ;CAGrB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC"}

package/build/core/logger.js

@@ -0,0 +1,132 @@
+/**
+ * logger.ts — Structured logging module for security event correlation.
+ *
+ * Outputs JSON-formatted log entries with consistent fields for easy parsing
+ * by log aggregation systems (ELK, Splunk, Loki, etc.).
+ *
+ * Supports standard log levels plus a `security` level for security-relevant
+ * events (authentication, privilege escalation, policy violations).
+ *
+ * @module logger
+ * @see CICD-027
+ */
+/** Numeric severity for each log level (used for filtering). */
+const LOG_LEVEL_SEVERITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    /** Security events always log regardless of level (severity 999). */
+    security: 999,
+};
+// ── Logger Class ─────────────────────────────────────────────────────────────
+/**
+ * Structured logger that outputs JSON to stderr.
+ *
+ * Uses stderr so log output doesn't interfere with MCP protocol messages
+ * on stdout (StdioServerTransport).
+ *
+ * Usage:
+ * ```typescript
+ * import { logger } from './logger.js';
+ *
+ * logger.info('preflight', 'cache_hit', 'Pre-flight cache hit for tool', { toolName: 'firewall_iptables' });
+ * logger.security('sudo-guard', 'elevation_requested', 'Sudo elevation requested', { tool: 'harden_sysctl' });
+ * ```
+ */
+export class Logger {
+    minLevel;
+    constructor(minLevel) {
+        this.minLevel = minLevel ?? this.parseEnvLevel();
+    }
+    /**
+     * Read the minimum log level from `KALI_DEFENSE_LOG_LEVEL` env var.
+     * Falls back to `"info"` if unset or invalid.
+     */
+    parseEnvLevel() {
+        const raw = process.env.KALI_DEFENSE_LOG_LEVEL?.toLowerCase();
+        if (raw && raw in LOG_LEVEL_SEVERITY) {
+            return raw;
+        }
+        return "info";
+    }
+    /** Check whether a message at `level` should be emitted. */
+    shouldLog(level) {
+        return LOG_LEVEL_SEVERITY[level] >= LOG_LEVEL_SEVERITY[this.minLevel];
+    }
+    /**
+     * Emit a structured log entry as a single JSON line to stderr.
+     *
+     * @param level     - Severity level
+     * @param component - Subsystem name (e.g., "executor", "preflight")
+     * @param action    - Action identifier (e.g., "command_executed", "cache_miss")
+     * @param message   - Human-readable description
+     * @param details   - Optional structured metadata
+     */
+    log(level, component, action, message, details) {
+        if (!this.shouldLog(level))
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            component,
+            action,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        };
+        // Single-line JSON to stderr — safe for MCP stdio transport
+        process.stderr.write(JSON.stringify(entry) + "\n");
+    }
+    /** Log a debug-level message. */
+    debug(component, action, message, details) {
+        this.log("debug", component, action, message, details);
+    }
+    /** Log an info-level message. */
+    info(component, action, message, details) {
+        this.log("info", component, action, message, details);
+    }
+    /** Log a warning-level message. */
+    warn(component, action, message, details) {
+        this.log("warn", component, action, message, details);
+    }
+    /** Log an error-level message. */
+    error(component, action, message, details) {
+        this.log("error", component, action, message, details);
+    }
+    /**
+     * Log a security-relevant event.
+     *
+     * Security events are **always** emitted regardless of the configured
+     * minimum log level. Use for:
+     * - Authentication / privilege escalation events
+     * - Policy violations
+     * - Rate limit breaches
+     * - Suspicious input patterns
+     * - Configuration changes with security impact
+     */
+    security(component, action, message, details) {
+        this.log("security", component, action, message, details);
+    }
+    /**
+     * Update the minimum log level at runtime.
+     * Useful for tests or dynamic configuration changes.
+     */
+    setLevel(level) {
+        this.minLevel = level;
+    }
+    /** Get the current minimum log level. */
+    getLevel() {
+        return this.minLevel;
+    }
+}
+// ── Singleton Export ─────────────────────────────────────────────────────────
+/**
+ * Default singleton logger instance.
+ *
+ * Import and use directly:
+ * ```typescript
+ * import { logger } from '../core/logger.js';
+ * logger.info('my-module', 'action', 'Something happened');
+ * ```
+ */
+export const logger = new Logger();

package/build/core/parsers.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Output parsing utilities for defensive security tool output.
+ * Converts raw command output into structured data for MCP responses.
+ */
+/** MCP text content type */
+export interface McpTextContent {
+    type: "text";
+    text: string;
+    [key: string]: unknown;
+}
+/**
+ * Parses key:value pair output into a Record.
+ * Lines without the separator are skipped.
+ */
+export declare function parseKeyValue(output: string, separator?: string): Record<string, string>;
+/**
+ * Parses whitespace-delimited table output into an array of Records.
+ * First non-empty line is treated as the header row.
+ */
+export declare function parseTable(output: string): Record<string, string>[];
+/**
+ * Safely parses JSON text. Returns null on parse failure.
+ */
+export declare function parseJsonSafe(text: string): unknown | null;
+/**
+ * Formats any data into MCP text content.
+ * Objects are JSON-stringified with indentation.
+ */
+export declare function formatToolOutput(data: unknown): McpTextContent;
+/**
+ * Creates a simple MCP text content object.
+ */
+export declare function createTextContent(text: string): McpTextContent;
+/**
+ * Creates an MCP text content object with an error prefix.
+ */
+export declare function createErrorContent(msg: string): McpTextContent;
+/** Structured iptables rule */
+export interface IptablesRule {
+    chain: string;
+    policy?: string;
+    packets: string;
+    bytes: string;
+    target: string;
+    protocol: string;
+    opt: string;
+    in: string;
+    out: string;
+    source: string;
+    destination: string;
+    extra: string;
+}
+/**
+ * Parses `iptables -L -n -v` output into structured rules.
+ */
+export declare function parseIptablesOutput(output: string): IptablesRule[];
+/**
+ * Parses `nft list ruleset` output into structured sections.
+ */
+export declare function parseNftOutput(output: string): Record<string, string[]>;
+/** Structured sysctl entry */
+export interface SysctlEntry {
+    key: string;
+    value: string;
+}
+/**
+ * Parses `sysctl -a` output into structured entries.
+ */
+export declare function parseSysctlOutput(output: string): SysctlEntry[];
+/** Structured audit log entry */
+export interface AuditEntry {
+    type: string;
+    timestamp: string;
+    fields: Record<string, string>;
+}
+/**
+ * Parses `ausearch` output into structured audit entries.
+ */
+export declare function parseAuditdOutput(output: string): AuditEntry[];
+/** Lynis finding */
+export interface LynisFinding {
+    severity: string;
+    testId: string;
+    description: string;
+}
+/**
+ * Parses Lynis audit output for findings/warnings/suggestions.
+ */
+export declare function parseLynisOutput(output: string): LynisFinding[];
+/** OpenSCAP result entry */
+export interface OscapResult {
+    ruleId: string;
+    result: string;
+    severity: string;
+    title: string;
+}
+/**
+ * Parses OpenSCAP text/XML results output.
+ * Handles the common text report format.
+ */
+export declare function parseOscapOutput(output: string): OscapResult[];
+/** ClamAV scan result */
+export interface ClamavResult {
+    file: string;
+    status: "OK" | "FOUND" | "ERROR";
+    virus?: string;
+}
+/**
+ * Parses `clamscan` output into structured results.
+ */
+export declare function parseClamavOutput(output: string): ClamavResult[];
+/** Structured socket entry from ss */
+export interface SsEntry {
+    state: string;
+    recv: string;
+    send: string;
+    local: string;
+    peer: string;
+    process: string;
+}
+/**
+ * Parses `ss -tulnp` output into structured entries.
+ */
+export declare function parseSsOutput(output: string): SsEntry[];
+/** Structured fail2ban jail status */
+export interface Fail2banJail {
+    name: string;
+    status: string;
+    currentlyFailed: number;
+    totalFailed: number;
+    currentlyBanned: number;
+    totalBanned: number;
+    bannedIPs: string[];
+}
+/**
+ * Parses `fail2ban-client status` output.
+ */
+export declare function parseFail2banOutput(output: string): Fail2banJail[];
+/** Structured systemctl unit entry */
+export interface SystemctlUnit {
+    unit: string;
+    load: string;
+    active: string;
+    sub: string;
+    description: string;
+}
+/**
+ * Parses `systemctl list-units` output into structured entries.
+ */
+export declare function parseSystemctlOutput(output: string): SystemctlUnit[];
+//# sourceMappingURL=parsers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parsers.d.ts","sourceRoot":"","sources":["../../src/core/parsers.ts"],"names":[],"mappings":"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"}