defense-mcp-server 0.8.4 → 0.9.1

package/README.md

@@ -1,13 +1,44 @@
 # Defense MCP Server
 
-A Model Context Protocol (MCP) server that gives AI assistants access to **31 defensive security tools** (with 150+ actions) on Linux. Connect it to Claude Desktop, Cursor, or any MCP-compatible client to harden systems, manage firewalls, scan for vulnerabilities, and enforce compliance — all through natural language conversation.
+[![Smithery](https://smithery.ai/badge/@bottobot/defense-mcp-server)](https://smithery.ai/server/@bottobot/defense-mcp-server)
+[![npm version](https://img.shields.io/npm/v/defense-mcp-server)](https://www.npmjs.com/package/defense-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?logo=github)](https://github.com/sponsors/bottobot)
+[![Support on Ko-fi](https://img.shields.io/badge/Support-Ko--fi-FF5E5B?logo=ko-fi)](https://ko-fi.com/bottobot)
 
-## Why I Made This
-Basically I'm a total noob when it comes to really serious system hardening so I thought I'd test the latest LLM models and see how far I could get. Turns out they're pretty helpful! I got tired of hardening my new systems by hand every time I spun up a new one so I made this MCP server to make it pretty easy. I jam packed as many security tools as I could into this thing so be prepared to burn tokens using it. Hopefully it helps you about half as much as its helped me. 
+**31 defensive security tools. 250+ actions. One MCP server.**
 
+A Model Context Protocol (MCP) server that gives AI assistants access to **31 defensive security tools** (with 250+ actions) on Linux. Connect it to Claude Desktop, Cursor, Smithery, or any MCP-compatible client to harden systems, manage firewalls, scan for vulnerabilities, and enforce compliance — all through natural language conversation.
+
+### TLDR ###
+It's an all-in-one easy to use MCP server that will help you secure your Linux OS and harden it to external attackers. It's not perfect by any stretch but if you need something that'll take the pain out of hardening a fresh OS install then give it a try. It's as simple as saying "give me a full security audit using the Defense MCP Server" to your favourite LLM agent.  
+
+## **The Story Of This Thing** ##
+I started experimenting with Kali and I had a weird thought that if someone ever gained control of that system they could do some damage in my network. I found it came with all sorts of interesting defensive tools besides the obvious offensive ones and so I started messing around with automating the hardening process. Eventually I left Kali to the hackers and just switched to a Debian 13 vanilla type setup on my daily driver. All those hacker tools just made me nervous! However I have spent an incredible amount of time learning about system security on Linux building this thing and I think its ready to see the light of day for others to use. 
+
+Please don't hesitate to leave feedback or if you think there's a good tool I should include. 
+
+## Testing So Far ##
+So my stack for this that I've tested is VS Codium on Kali and Debian 13 using Roo Code and Claude Code using Anthropic Models. I gotta say I'm pretty happy with how well it does. I've really tried to get it to be a simple all-in-one hardening tool that'll at least plug the major gaps in anyones system. If you're using API's then its really gonna chug down some tokens so be warned. It did go through a few rounds of token efficiency optimisation but it'll eat em up like their Girl Guides Thin Mint cookies. 
+
+---
+
+## Install
+
+```bash
+npm install -g defense-mcp-server
+```
+
+Or via Smithery:
+
+```bash
+npx -y @smithery/cli install @bottobot/defense-mcp-server --client claude
+```
+
+---
 ## So What It Does
 
-This server exposes Linux security tools as MCP tools that an AI assistant can invoke on your behalf. Instead of memorizing command syntax for dozens of security utilities, you describe what you want in plain English and the assistant calls the right tool with the right parameters. Sounds pretty good right!
+This server exposes Linux security tools as MCP tools that an AI assistant can invoke on your behalf. Instead of memorizing command syntax for dozens of security utilities, you describe what you want in plain English and the assistant calls the right tool with the right parameters. Sounds pretty good right?
 
 Here are the tools:
 
@@ -46,7 +77,10 @@ Here are the tools:
 | **Deception/Honeypots** | Canary token deployment, honeyport listeners, trigger monitoring |
 | **Wireless Security** | Bluetooth/WiFi auditing, rogue AP detection, interface disabling |
 
-Every tool runs with safety guardrails:
+### Safety Guardrails
+
+Every tool runs with safety guardrails — you won't blow up your box:
+
 - **Dry-run by default** — tools preview what they would do before making changes
 - **Command allowlist** — only pre-approved binaries can execute (no shell interpreters)
 - **Input sanitization** — all parameters validated against injection attacks
@@ -81,7 +115,7 @@ DEFENSE_MCP_AUTO_INSTALL=false node build/index.js
 ## Requirements
 
 - **Linux** (Kali, Debian, Ubuntu, RHEL, Arch, or any systemd-based distro)
-- **Node.js 18+**
+- **Node.js 22+**
 - **npm 9+**
 
 ## System Dependencies
@@ -101,17 +135,105 @@ sudo apt-get install -y \
 
 ### Third-Party Tools
 
-These are **not available** in standard Debian/Ubuntu repos and require manual installation:
+These are **not available** in standard Debian/Ubuntu repos. The instructions below avoid piping remote scripts into a shell (`curl | sh`) — each binary is downloaded, verified, and installed as a discrete step.
+
+> **Note:** The MCP server can auto-install these tools for you when `DEFENSE_MCP_AUTO_INSTALL=true` (the default). It uses GPG fingerprint and SHA256 verification internally. The manual steps below are for pre-installation or air-gapped environments.
+
+#### Falco (eBPF runtime security)
+
+```bash
+# Import GPG key and verify fingerprint
+curl -fsSL https://falco.org/repo/falcosecurity-packages.asc -o /tmp/falco.asc
+gpg --show-keys /tmp/falco.asc  # Verify: 478B 2FBB C75F 4237 B731 DA43 6510 6822 B35B 1B1F
+sudo gpg --dearmor -o /usr/share/keyrings/falco-archive-keyring.gpg /tmp/falco.asc
+rm /tmp/falco.asc
+
+# Add signed repo and install
+echo "deb [signed-by=/usr/share/keyrings/falco-archive-keyring.gpg] https://download.falco.org/packages/deb stable main" \
+  | sudo tee /etc/apt/sources.list.d/falcosecurity.list
+sudo apt-get update && sudo apt-get install -y falco
+```
+
+#### Trivy (container image scanning)
+
+```bash
+# Import GPG key and verify fingerprint
+curl -fsSL https://aquasecurity.github.io/trivy-repo/deb/public.key -o /tmp/trivy.asc
+gpg --show-keys /tmp/trivy.asc  # Verify: 2E2D 3567 4616 32C8 4BB6 CD6F E9D0 A361 6276 FA6C
+sudo gpg --dearmor -o /usr/share/keyrings/trivy-archive-keyring.gpg /tmp/trivy.asc
+rm /tmp/trivy.asc
+
+# Add signed repo and install
+echo "deb [signed-by=/usr/share/keyrings/trivy-archive-keyring.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" \
+  | sudo tee /etc/apt/sources.list.d/trivy.list
+sudo apt-get update && sudo apt-get install -y trivy
+```
+
+#### Grype (vulnerability scanning)
+
+```bash
+VERSION=v0.110.0
+curl -fsSL -o /tmp/grype.tar.gz \
+  "https://github.com/anchore/grype/releases/download/${VERSION}/grype_${VERSION#v}_linux_amd64.tar.gz"
+curl -fsSL -o /tmp/grype.tar.gz.sha256 \
+  "https://github.com/anchore/grype/releases/download/${VERSION}/grype_${VERSION#v}_checksums.txt"
+
+# Verify checksum
+cd /tmp && grep "linux_amd64.tar.gz" grype.tar.gz.sha256 | sha256sum -c -
+tar xzf grype.tar.gz grype && sudo install grype /usr/local/bin/grype
+rm -f /tmp/grype /tmp/grype.tar.gz /tmp/grype.tar.gz.sha256
+```
+
+#### Syft (SBOM generation)
+
+```bash
+VERSION=v1.42.3
+curl -fsSL -o /tmp/syft.tar.gz \
+  "https://github.com/anchore/syft/releases/download/${VERSION}/syft_${VERSION#v}_linux_amd64.tar.gz"
+curl -fsSL -o /tmp/syft_checksums.txt \
+  "https://github.com/anchore/syft/releases/download/${VERSION}/syft_${VERSION#v}_checksums.txt"
+
+# Verify checksum
+cd /tmp && grep "linux_amd64.tar.gz" syft_checksums.txt | sha256sum -c -
+tar xzf syft.tar.gz syft && sudo install syft /usr/local/bin/syft
+rm -f /tmp/syft /tmp/syft.tar.gz /tmp/syft_checksums.txt
+```
+
+#### TruffleHog (secret scanning)
+
+```bash
+VERSION=v3.94.1
+curl -fsSL -o /tmp/trufflehog.tar.gz \
+  "https://github.com/trufflesecurity/trufflehog/releases/download/${VERSION}/trufflehog_${VERSION#v}_linux_amd64.tar.gz"
+curl -fsSL -o /tmp/trufflehog_checksums.txt \
+  "https://github.com/trufflesecurity/trufflehog/releases/download/${VERSION}/trufflehog_${VERSION#v}_checksums.txt"
+
+# Verify checksum
+cd /tmp && grep "linux_amd64.tar.gz" trufflehog_checksums.txt | sha256sum -c -
+tar xzf trufflehog.tar.gz trufflehog && sudo install trufflehog /usr/local/bin/trufflehog
+rm -f /tmp/trufflehog /tmp/trufflehog.tar.gz /tmp/trufflehog_checksums.txt
+```
+
+#### slsa-verifier (supply chain verification)
 
-| Tool | Purpose | Install Command |
-|------|---------|----------------|
-| **Falco** | eBPF runtime security | `curl -fsSL https://falco.org/repo/falcosecurity-packages.asc \| sudo gpg --dearmor -o /usr/share/keyrings/falco-archive-keyring.gpg && echo "deb [signed-by=/usr/share/keyrings/falco-archive-keyring.gpg] https://download.falco.org/packages/deb stable main" \| sudo tee /etc/apt/sources.list.d/falcosecurity.list && sudo apt-get update && sudo apt-get install -y falco` |
-| **Trivy** | Container image scanning | `curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh \| sh -s -- -b /usr/local/bin` |
-| **Grype** | Vulnerability scanning | `curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh \| sh -s -- -b /usr/local/bin` |
-| **Syft** | SBOM generation | `curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh \| sh -s -- -b /usr/local/bin` |
-| **TruffleHog** | Secret scanning | `curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh \| sh -s -- -b /usr/local/bin` |
-| **slsa-verifier** | Supply chain verification | Download from [GitHub releases](https://github.com/slsa-framework/slsa-verifier/releases) |
-| **cdxgen** | CycloneDX SBOM generation | `npm install -g @cyclonedx/cdxgen` |
+```bash
+VERSION=v2.7.1
+curl -fsSL -o /tmp/slsa-verifier \
+  "https://github.com/slsa-framework/slsa-verifier/releases/download/${VERSION}/slsa-verifier-linux-amd64"
+curl -fsSL -o /tmp/slsa-verifier.sha256 \
+  "https://github.com/slsa-framework/slsa-verifier/releases/download/${VERSION}/slsa-verifier-linux-amd64.sha256"
+
+# Verify checksum
+cd /tmp && echo "$(cat slsa-verifier.sha256)  slsa-verifier" | sha256sum -c -
+sudo install slsa-verifier /usr/local/bin/slsa-verifier
+rm -f /tmp/slsa-verifier /tmp/slsa-verifier.sha256
+```
+
+#### cdxgen (CycloneDX SBOM generation)
+
+```bash
+npm install -g @cyclonedx/cdxgen
+```
 
 ### Important Notes
 
@@ -120,37 +242,48 @@ These are **not available** in standard Debian/Ubuntu repos and require manual i
 - **`bpftool`**: On Debian Trixie, install the `bpftool` package directly (NOT `linux-tools-generic` which is Ubuntu-specific).
 - **`pam_pwquality`**: This is a PAM module (`libpam-pwquality`), not a standalone binary. Install via `apt-get install libpam-pwquality`.
 
-## Installation
+## Quick Start
+
+### Step 1: Install the server
 
-### Option A: npm (recommended)
+Pick one method:
 
+**npm (recommended):**
 ```bash
 npm install -g defense-mcp-server
 ```
 
-### Option B: Clone and build
+**Or clone and build from source:**
+```bash
+git clone https://github.com/bottobot/defense-mcp-server.git
+cd defense-mcp-server
+npm install && npm run build
+```
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/bottobot/defense-mcp-server.git
-   cd defense-mcp-server
-   ```
+### Step 2: Connect to your AI client
 
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
+The server supports any MCP client. Pick your client below and add the configuration:
 
-3. Build:
-   ```bash
-   npm run build
-   ```
+**Claude Code (CLI / VS Code / JetBrains):**
 
-## Connecting to Claude Desktop
+Create a `.mcp.json` file in your project root (or `~/.claude/` for global):
+```json
+{
+  "mcpServers": {
+    "defense-mcp-server": {
+      "command": "defense-mcp-server",
+      "env": {
+        "DEFENSE_MCP_DRY_RUN": "true",
+        "DEFENSE_MCP_ALLOWED_DIRS": "/tmp,/home,/var/log"
+      }
+    }
+  }
+}
+```
 
-Add this to your Claude Desktop configuration file (`~/.config/claude/claude_desktop_config.json` on Linux):
+**Claude Desktop:**
 
-**If installed globally via npm:**
+Edit `~/.config/claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 ```json
 {
   "mcpServers": {
@@ -160,30 +293,50 @@ Add this to your Claude Desktop configuration file (`~/.config/claude/claude_des
   }
 }
 ```
+Restart Claude Desktop. The server will appear in the MCP tools panel.
 
-**If cloned and built locally:**
+**Cursor / Other MCP clients:**
 ```json
 {
   "mcpServers": {
     "defense-mcp-server": {
-      "command": "node",
-      "args": ["/path/to/defense-mcp-server/build/index.js"]
+      "command": "defense-mcp-server"
     }
   }
 }
 ```
 
-Replace `/path/to/` with the actual path where you cloned the repo.
+**If you cloned and built from source**, replace `"defense-mcp-server"` in the command field with:
+```json
+"command": "node",
+"args": ["/path/to/defense-mcp-server/build/index.js"]
+```
 
-Restart Claude Desktop. The server will appear in the MCP tools panel.
+### Step 3: Verify it works
 
-## Connecting to Other MCP Clients
+Open your AI client and ask:
 
-Any MCP client that supports stdio transport can connect. The server communicates over stdin/stdout using the MCP protocol. Launch it with:
+> "Check my firewall status"
 
-```bash
-node build/index.js
-```
+The assistant should call the `firewall` tool and return your iptables/UFW rules. If it does, you're all set.
+
+### Step 4: Elevate when needed
+
+Most audit tools (listing firewall rules, checking patches, reading logs) work without sudo. When a tool needs elevated privileges, the server will tell you. Elevate securely:
+
+> "Elevate sudo with GUI dialog"
+
+This opens a native password dialog (zenity/kdialog) — your password never passes through the AI conversation. The session auto-expires after 15 minutes, or you can drop it anytime:
+
+> "Drop sudo privileges"
+
+### What happens on first run
+
+1. **Dry-run mode is on by default** — tools preview what they would do without changing anything
+2. **Missing tools are auto-installed** — if you ask for a malware scan but ClamAV isn't installed, the server installs it via apt/dnf automatically
+3. **All file access is restricted** — only `/tmp`, `/home`, and `/var/log` are accessible by default
+
+To enable live changes (not just previews), set `DEFENSE_MCP_DRY_RUN=false` in the env config above.
 
 ## Usage Examples
 
@@ -227,6 +380,8 @@ Configuration is via environment variables. All have secure defaults:
 | `DEFENSE_MCP_AUTO_INSTALL` | `true` | Auto-install missing tool dependencies |
 | `DEFENSE_MCP_PREFLIGHT` | `true` | Enable pre-flight dependency checks |
 | `DEFENSE_MCP_PREFLIGHT_BANNERS` | `true` | Show pre-flight status in tool output |
+| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
+| `MCP_PORT` | `3100` | HTTP server port (when `MCP_TRANSPORT=http`) |
 
 To apply changes for real (not just preview), set:
 ```bash
@@ -235,16 +390,125 @@ DEFENSE_MCP_DRY_RUN=false node build/index.js
 
 ## Security
 
-This server is designed to be safe by default:
+A security tool that isn't secure itself is worse than useless. This server implements defense-in-depth across 10 layers, from configuration defaults down to cryptographic verification.
+
+### MCP Specification Compliance
+
+The [MCP spec](https://modelcontextprotocol.io/) defines security requirements for servers. Here's how this project meets them:
+
+| MCP Requirement | Implementation |
+|----------------|---------------|
+| **Validate all tool inputs** | Zod schemas on every parameter + 15 specialized validators (paths, IPs, ports, service names, etc.) |
+| **Implement access controls** | 200+ entry command allowlist, `shell: false` enforced, sudo session management |
+| **Rate limit tool invocations** | 30/tool/min, 100 global/min, auth failure throttling (5 attempts per 5 minutes) |
+| **Sanitize tool outputs** | Error sanitization strips paths, stack traces, and truncates to 500 chars |
+
+### Layer 1: Safe Defaults
+
+Everything is locked down out of the box. You have to explicitly opt in to making changes:
+
+- **Dry-run mode on by default** — every tool previews what it would do before touching anything
+- **Backups before changes** — system state is backed up automatically before any modification
+- **Confirmation required** — destructive actions need explicit confirmation
+- **Restricted directories** — the server can only access explicitly allowed paths; root `/`, `/etc`, `/usr`, `/bin`, `/sbin` are blocked by default
+- **Protected paths** — system-critical files are blocked from modification regardless of directory config
+
+### Layer 2: Command Execution
+
+No tool can run arbitrary commands. Every command goes through multiple gates:
+
+- **Binary allowlist** — 200+ pre-approved binaries across 18 categories. If a binary isn't on the list, it doesn't run. Period.
+- **Absolute path resolution** — binaries are resolved to absolute paths at startup via `fs.existsSync()`, never through `which` or PATH
+- **`shell: false` enforced** — hardcoded, cannot be overridden. Shell metacharacters (`;`, `|`, `&`, `` ` ``, `$`, etc.) have no effect
+- **TOCTOU detection** — binary inodes are recorded at startup and verified before execution to detect replacement
+- **No fallback** — if a binary can't be resolved to a known path, execution is refused entirely
+
+### Layer 3: Input Validation
+
+Every parameter is validated before it reaches any tool handler:
+
+- **Zod schemas** — runtime type checking with string length limits, enum constraints, numeric ranges, array bounds
+- **Path traversal protection** — `../` sequences rejected, null bytes blocked, symlinks resolved and re-validated
+- **Shell metacharacter blocking** — `[;|&$\`(){}<>!\\\n\r]` stripped from all inputs
+- **Control character rejection** — `[\x00-\x08\x0e-\x1f\x7f]` blocked
+- **Specialized validators** for: targets (hostname/IP/CIDR), ports, service names, sysctl keys, package names, iptables chains, network interfaces, usernames, YARA rules, certificate paths, firewall zones, auditd keys
+- **ReDoS protection** — regex patterns limited to 200 characters, nested quantifiers and excessive alternation rejected
+
+### Layer 4: Sudo & Privilege Management
+
+The server never asks for your password in a way an AI can see:
+
+- **GUI elevation** — `sudo_elevate_gui` opens a native zenity/kdialog dialog. The password goes directly to sudo, never through the AI conversation
+- **Buffer storage** — passwords are stored as Node.js Buffers (not V8 strings), which can be explicitly zeroed from memory
+- **Auto-zeroing** — password buffer is zeroed on session drop, timeout expiry, and process exit
+- **Credential validation** — password is tested with `sudo -S -k -v` before being accepted
+- **Auth rate limiting** — 5 failed attempts per 5 minutes, then locked out
+- **Session UID guard** — session is dropped immediately if the OS user ID changes
+- **NOPASSWD:ALL rejection** — the sudoers management tool explicitly refuses to write `NOPASSWD: ALL` rules
+- **`sudo -S` stdin piping** — passwords are piped via stdin, never passed as command-line arguments (which would be visible in `ps`)
+- **40+ permission error patterns** — detected and surfaced with clear elevation prompts instead of cryptic failures
+
+### Layer 5: Secure File Operations
+
+Every file write is atomic and permission-hardened:
+
+- **Atomic writes** — write to temp file, then rename. No partial writes, no corruption on crash
+- **Owner-only permissions** — files created with `0o600`, directories with `0o700`
+- **Explicit chmod** — permissions enforced independently of umask
+- **Symlink protection** — real paths resolved and re-validated against allowed directories
+- **Backup before modify** — timestamped backups with manifest tracking under `~/.defense-mcp/backups/`
+
+### Layer 6: Encrypted State Storage
+
+Sensitive runtime data is encrypted at rest:
+
+- **Algorithm**: AES-256-GCM (authenticated encryption)
+- **Key derivation**: PBKDF2 with 100,000 iterations, SHA-512
+- **IV**: 96-bit (GCM-recommended)
+- **Auth tag**: 128-bit
+- **Salt**: 128-bit per file
+- **Fallback**: plaintext JSON with warning when no key is configured (`DEFENSE_MCP_STATE_KEY`)
+
+### Layer 7: Supply Chain Security
+
+Auto-installed tools are verified, not blindly trusted:
+
+- **System packages** — installed only via official package manager (apt/dnf/pacman)
+- **pip allowlist** — only 9 pre-approved packages (yara-python, python-nmap, etc.)
+- **npm allowlist** — only 2 pre-approved packages (cdxgen, snyk)
+- **Third-party tools** (Falco, Trivy, Grype, Syft, TruffleHog, slsa-verifier):
+  - Never uses `curl | sh` — all downloads verified before execution
+  - SHA256 checksums hardcoded in manifest
+  - GPG fingerprints verified against known-good values
+  - Cosign verification where available
+  - Requires explicit `DEFENSE_MCP_THIRD_PARTY_INSTALL=true` to enable
+
+### Layer 8: Rate Limiting & Safeguards
+
+Protection against runaway or abusive tool invocations:
+
+- **Per-tool limit**: 30 invocations per 60 seconds
+- **Global limit**: 100 invocations per 60 seconds
+- **Running service detection** — detects VS Code, Docker, databases, web servers, MCP servers, SSH sessions before operations that could affect them
+- **Pre-flight validation** — every tool checks dependencies, privileges, and safeguards before executing
+
+### Layer 9: Audit Trail & Rollback
+
+Every change is recorded and reversible:
+
+- **Structured changelog** — JSON entries with tool name, action, target, before/after values, timestamp
+- **Rollback commands** — stored with each change, validated against command allowlist
+- **Structured logging** — JSON-formatted security events to stderr with file rotation (10 MB, 5 files)
+- **Security log level** — critical events always logged regardless of log level setting
+
+### Layer 10: Policy Engine
+
+Hardening policies are enforced safely:
 
-- Commands execute with `shell: false` — no shell interpretation
-- All binaries resolved against a 190-entry allowlist at startup
-- Input validated with Zod schemas before execution
-- Passwords handled as Buffers (zeroed after use, never logged)
-- Rate limited to prevent abuse (30/tool/min, 100 global/min)
-- All file writes go through secure-fs with audit trail
-- Encrypted state storage (AES-256-GCM) for sensitive runtime data
-- Atomic file writes (write-to-temp-then-rename) to prevent corruption
+- **No shell interpreters** — policy check and remediation commands use direct binary invocation only
+- **Regex safety** — pattern length limits (200 chars), nested quantifier rejection
+- **Severity classification** — critical, high, medium, low, info
+- **Secure policy storage** — policy files created with `0o700` directory permissions
 
 For the full security architecture, see [ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
@@ -269,7 +533,7 @@ npm run audit:security
 
 ## Test Coverage
 
-- **1,801+ tests** across 60+ test files
+- **2,048+ tests** across 62 test files
 - Every source module (core + tools) has a corresponding test file
 - Coverage enforced in CI pipeline
 

package/build/core/auto-installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-installer.d.ts","sourceRoot":"","sources":["../../src/core/auto-installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;IACtE,MAAM,EACF,gBAAgB,GAChB,KAAK,GACL,KAAK,GACL,OAAO,GACP,YAAY,GACZ,iBAAiB,GACjB,mBAAmB,GACnB,UAAU,GACV,SAAS,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC;AA0FD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAoOD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA8B;IACtD,OAAO,CAAC,WAAW,CAA2B;IAE9C,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,IAAI,aAAa;IAahC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B,mDAAmD;IACnD,SAAS,IAAI,OAAO;IAIpB;;;;;OAKG;IACG,UAAU,CACd,QAAQ,EAAE,YAAY,EACtB,eAAe,EAAE,MAAM,EAAE,EACzB,aAAa,CAAC,EAAE,MAAM,EAAE,EACxB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAC1B,OAAO,CAAC,iBAAiB,CAAC;IA6G7B;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuP5D;;;;;;;OAOG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAiHlE;;;;;;OAMG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8G7D;;;;;;OAMG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAyG1D;;OAEG;YACW,SAAS;IAOvB;;OAEG;IACH,OAAO,CAAC,aAAa;CAmBtB"}
+{"version":3,"file":"auto-installer.d.ts","sourceRoot":"","sources":["../../src/core/auto-installer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,aAAa,GAAG,SAAS,GAAG,MAAM,CAAC;IACtE,MAAM,EACF,gBAAgB,GAChB,KAAK,GACL,KAAK,GACL,OAAO,GACP,YAAY,GACZ,iBAAiB,GACjB,mBAAmB,GACnB,UAAU,GACV,SAAS,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,EAAE,OAAO,CAAC;IACrB,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC;AA0FD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAoOD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,SAAS,CAA8B;IACtD,OAAO,CAAC,WAAW,CAA2B;IAE9C,4CAA4C;IAC5C,MAAM,CAAC,QAAQ,IAAI,aAAa;IAahC;;;OAGG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B,mDAAmD;IACnD,SAAS,IAAI,OAAO;IAIpB;;;;;OAKG;IACG,UAAU,CACd,QAAQ,EAAE,YAAY,EACtB,eAAe,EAAE,MAAM,EAAE,EACzB,aAAa,CAAC,EAAE,MAAM,EAAE,EACxB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAC1B,OAAO,CAAC,iBAAiB,CAAC;IA6G7B;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAsP5D;;;;;;;OAOG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAgHlE;;;;;;OAMG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8G7D;;;;;;OAMG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAwG1D;;OAEG;YACW,SAAS;IAOvB;;OAEG;IACH,OAAO,CAAC,aAAa;CAmBtB"}

package/build/core/auto-installer.js

@@ -589,7 +589,6 @@ export class AutoInstaller {
         const useSudo = distro.packageManager !== "brew";
         const result = execWithSudo(installArgs, { useSudo, timeoutMs: 300_000 });
         if (!result.success) {
-            const elapsed = ((Date.now() - start) / 1000).toFixed(1);
             console.error(`[auto-installer] ✗ Failed to install '${binary}' (package: ${packageName}): ${result.stderr.slice(0, 200)}`);
             return {
                 dependency: binary,
@@ -695,7 +694,6 @@ export class AutoInstaller {
             result = execWithSudo([pip, "install", module], { timeoutMs: 120_000 });
         }
         if (!result.success) {
-            const elapsed = ((Date.now() - start) / 1000).toFixed(1);
             console.error(`[auto-installer] ✗ Failed to install Python module '${module}': ${result.stderr.slice(0, 200)}`);
             return {
                 dependency: module,
@@ -888,7 +886,6 @@ export class AutoInstaller {
             lastError = result.stderr.slice(0, 200);
         }
         if (!installed) {
-            const elapsed = ((Date.now() - start) / 1000).toFixed(1);
             console.error(`[auto-installer] ✗ Failed to install library '${lib}': ${lastError}`);
             return {
                 dependency: lib,

package/build/core/backup-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup-manager.d.ts","sourceRoot":"","sources":["../../src/core/backup-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAmC1E;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,SAAS,CAAC,EAAE,MAAM;IAK9B,sCAAsC;IACtC,OAAO,CAAC,SAAS;IAIjB,8DAA8D;IAC9D,OAAO,CAAC,YAAY;IAgBpB,8BAA8B;IAC9B,OAAO,CAAC,aAAa;IAKrB;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAqCzC;;;OAGG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAO3C;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA+BtD"}
+{"version":3,"file":"backup-manager.d.ts","sourceRoot":"","sources":["../../src/core/backup-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAiC1E;AAID,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,SAAS,CAAC,EAAE,MAAM;IAK9B,sCAAsC;IACtC,OAAO,CAAC,SAAS;IAIjB,8DAA8D;IAC9D,OAAO,CAAC,YAAY;IAepB,8BAA8B;IAC9B,OAAO,CAAC,aAAa;IAKrB;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW;IAyCzC;;;OAGG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK/C;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB9C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAO3C;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAiCtD"}

package/build/core/backup-manager.js

@@ -4,7 +4,7 @@
  * Backups are stored under ~/.defense-mcp/backups/ with timestamped filenames.
  * A manifest.json tracks all backups for listing and restore operations.
  */
-import { existsSync, readFileSync, unlinkSync, statSync, lstatSync, } from "node:fs";
+import { readFileSync, unlinkSync, statSync, lstatSync, } from "node:fs";
 import { join, basename, dirname, resolve as pathResolve } from "node:path";
 import { secureWriteFileSync, secureMkdirSync, secureCopyFileSync } from "./secure-fs.js";
 import { homedir } from "node:os";
@@ -38,20 +38,18 @@ export function validateBackupPath(filePath, baseDir) {
     if (!resolved.startsWith(resolvedBase + "/") && resolved !== resolvedBase) {
         throw new Error(`SECURITY: Backup path '${resolved}' escapes base directory '${resolvedBase}'`);
     }
-    // 4. Reject symlinks (if the path exists)
-    if (existsSync(filePath)) {
-        try {
-            const lstats = lstatSync(filePath);
-            if (lstats.isSymbolicLink()) {
-                throw new Error(`SECURITY: Backup path '${filePath}' is a symlink. Refusing to use.`);
-            }
+    // 4. Reject symlinks — use lstatSync directly to avoid TOCTOU
+    try {
+        const lstats = lstatSync(filePath);
+        if (lstats.isSymbolicLink()) {
+            throw new Error(`SECURITY: Backup path '${filePath}' is a symlink. Refusing to use.`);
         }
-        catch (err) {
-            if (err instanceof Error && err.message.startsWith("SECURITY:")) {
-                throw err;
-            }
-            // lstat failure on existing path is suspicious but non-fatal for validation
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("SECURITY:")) {
+            throw err;
         }
+        // ENOENT (path doesn't exist yet) is fine for validation; other errors are non-fatal
     }
 }
 // ── BackupManager ────────────────────────────────────────────────────────────
@@ -69,17 +67,16 @@ export class BackupManager {
     /** Read manifest from disk with migration from old format. */
     readManifest() {
         try {
-            if (existsSync(this.manifestPath)) {
-                const raw = readFileSync(this.manifestPath, "utf-8");
-                const parsed = JSON.parse(raw);
-                if (parsed && Array.isArray(parsed.backups)) {
-                    // Migrate: ensure version field is present (old format may lack it)
-                    return { version: 1, backups: parsed.backups };
-                }
+            // Read directly — avoids TOCTOU between existsSync and readFileSync
+            const raw = readFileSync(this.manifestPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed && Array.isArray(parsed.backups)) {
+                // Migrate: ensure version field is present (old format may lack it)
+                return { version: 1, backups: parsed.backups };
             }
         }
         catch {
-            // Corrupt or missing manifest — start fresh
+            // Missing, unreadable, or corrupt manifest — start fresh
         }
         return { version: 1, backups: [] };
     }
@@ -95,9 +92,6 @@ export class BackupManager {
     backupSync(filePath) {
         const validated = FilePathSchema.parse(filePath);
         this.ensureDir();
-        if (!existsSync(validated)) {
-            throw new Error(`Source file does not exist: ${validated}`);
-        }
         const id = randomUUID();
         const now = new Date();
         const ts = now.toISOString().replace(/[:.]/g, "-");
@@ -106,7 +100,16 @@ export class BackupManager {
         const backupPath = join(this.backupDir, backupName);
         // SECURITY (CORE-015): Validate the backup destination path
         validateBackupPath(backupPath, this.backupDir);
-        secureCopyFileSync(validated, backupPath);
+        // Copy atomically — no prior existsSync to avoid TOCTOU
+        try {
+            secureCopyFileSync(validated, backupPath);
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                throw new Error(`Source file does not exist: ${validated}`);
+            }
+            throw err;
+        }
         const stat = statSync(backupPath);
         const entry = {
             id,
@@ -139,13 +142,19 @@ export class BackupManager {
         if (!entry) {
             throw new Error(`Backup not found: ${validated}`);
         }
-        if (!existsSync(entry.backupPath)) {
-            throw new Error(`Backup file missing on disk: ${entry.backupPath}`);
-        }
         // SECURITY (CORE-015): Validate the backup source path before restore
         validateBackupPath(entry.backupPath, this.backupDir);
         secureMkdirSync(dirname(entry.originalPath));
-        secureCopyFileSync(entry.backupPath, entry.originalPath);
+        // Copy atomically — no prior existsSync to avoid TOCTOU
+        try {
+            secureCopyFileSync(entry.backupPath, entry.originalPath);
+        }
+        catch (err) {
+            if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+                throw new Error(`Backup file missing on disk: ${entry.backupPath}`);
+            }
+            throw err;
+        }
         console.error(`[backup-manager] Restored ${entry.backupPath} → ${entry.originalPath}`);
     }
     /**
@@ -174,12 +183,14 @@ export class BackupManager {
         }
         for (const entry of remove) {
             try {
-                if (existsSync(entry.backupPath)) {
-                    unlinkSync(entry.backupPath);
-                }
+                // Unlink directly — no prior existsSync to avoid TOCTOU
+                unlinkSync(entry.backupPath);
             }
             catch (err) {
-                console.error(`[backup-manager] Failed to delete ${entry.backupPath}: ${err instanceof Error ? err.message : String(err)}`);
+                // ENOENT is fine (already gone); log other errors
+                if (!(err instanceof Error && "code" in err && err.code === "ENOENT")) {
+                    console.error(`[backup-manager] Failed to delete ${entry.backupPath}: ${err instanceof Error ? err.message : String(err)}`);
+                }
             }
         }
         manifest.backups = keep;