v2.2.0

Kastell v2.2.0 — Plugin Ecosystem + Deferred Completion

Added

• Plugin Ecosystem — third-party audit check plugins via kastell-plugin-* npm packages
  • kastell plugin install/remove/list/validate CLI commands
  • server_plugin MCP tool (list + validate actions)
  • Plugin SDK types, manifest validation with Zod + semver compatibility
  • Plugin loader with collision detection, cache, and startup integration
  • Example plugins: kastell-plugin-wordpress (3 checks), kastell-plugin-auditor (2 checks)
• --include-forbidden flag — run FORBIDDEN tier fixes with per-fix confirmation
• --auto-fix --schedule pipeline — doctor + fix on a cron schedule (DOC-04)
• Fix session logging — per-command execution log (AH-03)
• Doctor fix history merge — results persisted to fix-history.json (DOC-02)
• FORBIDDEN rawCommand handler — shows commands with confirmation (DOC-03)

Changed

• CHECK_IDS constants — all 481 audit check IDs migrated to typed const object
• extractReason helper — replaces 18 inline patterns
• compliance/mapper.ts split — category-based sub-modules (DEF-06)
• buildFirewallSetupCommand merge (DEF-07)

Security

• Plugin loader path traversal guard (SEC-08)
• Snapshot path traversal guard (SEC-09)
• server_lock MCP destructiveHint (SEC-10)
• CI expression injection fix (SEC-07)

Stats

• 10401 tests (267 suites), coverage 96.33%
• 6 phases (P124-P129), 100 files changed

---

Full changelog: https://github.com/kastelldev/kastell/blob/main/CHANGELOG.md

v2.1.0

Added

• kastell init 3-way wizard — interactive setup with three paths: provision a new server, register an existing server, or configure defaults (compliance framework, notification channels)
• kastell explain <check-id> — deep-dive into any audit check: why it matters, fix command, fix tier (SAFE/GUARDED/FORBIDDEN), CIS/PCI-DSS/HIPAA compliance references. Supports --format terminal|json|md
• audit --ci flag — CI mode with JSON output, no spinner, requires --threshold for exit code gating
• fleet --categories — shows weakest audit category per server in fleet dashboard
• audit --compare enhancements — --fresh flag for live audit (skip snapshots), --detail for check-level diff instead of category summary
• server_compare MCP tool — side-by-side server comparison with snapshot fallback and detail mode (16th MCP tool)
• Doctor score — computeDoctorScore with severity-weighted findings, wired into CLI and MCP
• Regression gating — pre-fix regression check with --force bypass, conditional baseline save, kastell regression status/reset commands
• Substring fuzzy match — kastell explain ssh-password resolves to SSH-PASSWORD-AUTH (single match returns result, multiple returns suggestions)
• defaults.json support — loadDefaults/saveDefaults with Zod validation for threshold/framework fallback

Changed

• Regression wiring — saveBaseline/checkRegression integrated into all 4 callers (CLI audit, CLI fix, MCP serverAudit, MCP serverFix)
• confirmOrCancel helper — extracted to prompts.ts with DI pattern, replacing inline confirm logic in fix and regression flows
• hasRegression() helper — single source of truth for regression detection, replaces 3 inline copies
• resolveAuditPair extraction — DRY compare logic with exit code bug fix
• formatRegressionSummary — typed DRY helper for consistent regression display across CLI and MCP
• runPostFixReAudit — returns full AuditResult for accurate post-fix baseline
• scoreRegressed removed from interface — derived inline via hasRegression(), 8 test fixtures updated
• Discriminated union for AddServerResult — type-safe success/failure branching in init wizard
• providerConfig.ts rename — utils/defaults.ts renamed for clarity
• formatSuggestions DRY helper — shared between explain command and MCP tool
• Index-based listSnapshots — O(1) read instead of O(N) file parse
• Firewall port deduplication — uses adapter.platformPorts as single source

Security

• Dependency updates — actions/checkout v6, actions/setup-node v6, actions/upload-artifact v7

Tests

• 255 suites, 10265 tests, 12 snapshots (up from 240 suites, 10127 tests in v2.0.0)
• Coverage threshold: 90% global, 95% audit, 90% provider, 90% MCP

v2.0.0

v2.0.0 — Technical Debt + Infrastructure Hardening

Highlights

• Structured error migration — all 9 command files use classifyError with instanceof branching (KastellError hierarchy)
• logSafeModeBlock — structured security logging wired into all SAFE_MODE guard sites
• secureWriteFileSync — platform-aware secure file operations with POSIX permissions
• Config repair — kastell config repair diagnoses and repairs corrupted configs
• MCP audit enhancements — snapshot save/compare, category/severity filter, threshold gate
• Property-based + fuzz tests — fast-check arbitraries, kernel/firewall/filesystem fuzzing
• E2E nightly CI — automated provision→lock→audit→destroy pipeline

Security

• secureWrite migration (SEC-06) for all credential files
• TOCTOU fix in auth.ts
• ESLint security plugins, Zod schemas for all 4 providers
• CI hardening with explicit permissions + SHA-pinned actions
• Dependency updates: axios 1.15.0 (CVE-2025-62718), follow-redirects 1.16.0, hono 4.12.14

Stats

• 240 test suites, 10127 tests, 12 snapshots
• 9 phases (P105-P113) completed
• Coverage: 90% global, 95% audit, 90% provider, 90% MCP

Full changelog: https://github.com/kastelldev/kastell/blob/main/CHANGELOG.md

v1.17.1

v1.17.1 — Security Hardening

28 defence-in-depth fixes from 5-skill security audit.

Security

• sshExec type narrowing — accepts SshCommand only, 33 callers wrapped with raw()
• SAFE_MODE typo-safe — accepts "yes"/"1"/"on", warns on unrecognized values
• sanitizedEnv() expanded — 10 secret patterns (up from 4)
• Rollback SHA256 integrity — checksum verified before restore script execution
• MCP error sanitization — all 12 tool handlers route through sanitizeStderr
• Path traversal guard — relPath allowlist regex in rollback
• backupPath Zod regex — format validation prevents injection via tampered history
• SHELL_METACHAR — added & to block && on fallback path
• sedReplace path quoting — POSIX single-quote escape
• DEBIAN_FRONTEND scope — both apt-get commands covered

Changed

• scheduleManager: execSync replaced with spawnSync + DRY helper
• encryption.ts: execSync replaced with spawnSync array args
• Production deps: all 11 pinned to exact versions
• isSafeMode() extracted to src/utils/safeMode.ts
• Platform fallback: "coolify" changed to "bare" (least privileged)
• cmd("") throws, timeoutMs=0 guard, ControlMaster 0o700
• debugLog redaction, getServers() hardened, warnIfPermissionError helper

Full Changelog: v1.17.0...v1.17.1

v1.17.0

v1.17.0 — Fix Advanced + Doctor Integration

Added

• Bulk rollback — kastell fix --rollback-all and --rollback-to <fix-id> for batch fix reversal
• Doctor auto-fix — kastell doctor --auto-fix diagnose-then-fix pipeline with --dry-run and --force options
• Fix scheduling — kastell schedule fix|audit installs local cron for automated fix/audit runs
• SSH ControlMaster — connection multiplexing prevents sshd MaxStartups exhaustion during bulk operations
• Interactive menu full CLI parity — all CLI flags now accessible from interactive menu (schedule, audit extras, fix extras, fleet/doctor/evidence/backup options)
• WAF bot detection checks — NGX-WAF-BOT-DETECT and NGX-WAF-CHALLENGE-MODE audit checks
• Custom fix profiles — user-defined profiles from ~/.kastell/profiles/
• --no-interactive flag for automated fix runs

Fixed

• SSH lockout prevention — NET-HOSTS-DENY moved to GUARDED tier
• Sysctl SSH breakage — all sysctl fixes promoted to GUARDED with SSH probe + rollback
• Session-terminating commands — restart/halt promoted to GUARDED tier
• MCP SAFE_MODE guards — serverLock/Guard/Secure enforce isSafeMode()
• SSH ControlMaster Windows — socket path, stale cleanup, fork detection

Changed

• TOCTOU elimination, KASTELL_DIR consolidation, severityChalk utility
• 9,871 tests across 219 suites (up from 9,611 / 215)

Security

• Tier promotion system — dangerous fixes auto-promoted SAFE to GUARDED
• MCP fail-closed SAFE_MODE default

Full Changelog: v1.16.0...v1.17.0

v1.16.0

Added

• AES-256-GCM token encryption — tokens.json and notify-secrets.json encrypted at rest when OS keychain is unavailable. Per-installation random salt, cross-platform machine key derivation (Linux/macOS/Windows), transparent plaintext auto-migration
• Fix rollback & history — kastell fix --rollback <id> restores from backup, kastell fix --history shows fix log
• Fix prioritization — kastell fix --top N applies highest-impact fixes, kastell fix --target 80 fixes until score reaches target
• Programmatic fix handlers — 4 dedicated handlers (sysctl, file-append, package-install, chmod/chown) replace shell redirect/pipe for SAFE tier fixes
• Fix profiles — kastell fix --profile web-server|database|mail-server applies server-type-specific fix sets
• Fix diff preview — kastell fix --diff shows per-fix before/after changes
• Fix report — kastell fix --report generates markdown fix report with score change and compliance info
• WAF audit deep checks — 5 new WAF pipeline checks (IP ACL, rate limiting, input sanitization, bot detection headers, data masking) expanding nginx category to 14 checks
• Dependabot config — .github/dependabot.yml for automated GitHub Actions SHA updates
• 10 project-specific security audit custom checks (SSH injection, SAFE_MODE bypass, token leak, MCP validation, subprocess env, SSH host key, API sanitization, error disclosure, npm lifecycle)

Fixed

• getServers() fail-closed — corrupt servers.json now throws instead of silently returning empty array
• fileAppend handler shell injection — single-quote escape via shellEscape() on forward path (rollback already escaped)
• Encryption key hardening — per-installation random salt replaces hardcoded "kastell-v1", persistent random UUID fallback replaces low-entropy hostname

Security

• All 13 GitHub Actions references SHA-pinned across 5 workflow files (zero floating tags)
• SECFIX-01 through SECFIX-09 addressed: token encryption, supply chain hardening, fail-closed config, 5 already-closed findings verified
• Security audit: 29 findings (down from 39), 0 critical, 1 high (deferred to v2.0 by design)
• /review skill added to release security gate

Changed

• Test count: 5,522 → 9,611 (4,089 new tests including 3,623 mutation killers)
• Test suites: 207 → 215
• Test helpers: 4 → 5 factory files (encryption-factories.ts added)
• Mutation score: 44.65% → 59.06% nominal / 78.6% effective (Dalga 1-3 complete)

v1.15.1

Added

• kastell changelog command — Parse and display CHANGELOG.md in terminal (kastell changelog, kastell changelog v1.14.0, kastell changelog --all)
• "Why Kastell?" manifesto in README (EN + TR) — problem statement, approach, AI-native positioning
• Kastell vs Alternatives comparison table in README (EN + TR) — Kastell vs Lynis vs OpenSCAP across 12 dimensions
• Zero Telemetry badge in README (EN + TR) — trust signal, no data collection
• CI profile stats dispatch — .github org profile auto-updates on every main push (test/check/category/MCP counts)
• Interactive menu: "View changelog" entry in Configuration section
• CHANGELOG.md included in npm package files

Fixed

• sshExec SSH banner handling — servers with login banners caused non-zero exit codes on Windows, breaking health checks, audit scores (42→11 false drop), and doctor cache writes. Now checks stdout content when stderr is banner-only
• 3 incorrect fix commands — grub2-mkpasswd-pbkdf2 → grub-mkpasswd-pbkdf2 (Ubuntu), dc3dd → sleuthkit (available in repos), vector → rsyslog (no 3rd party repo needed)
• Backup fix command — kastell backup create (local CLI, not available on server) → server-side tar command
• audit-watch test timeout — Windows CI fake timer slowness (jest.setTimeout 15s + extra microtick flushes)
• CI dispatch format — JSON body for repository_dispatch (was form-encoded)

Security

• 10 security audit remediation items applied: SHELL_METACHAR validation, bot middleware fail-closed, clearKnownHostKey IP validation, sendTelegram token validation, unhandled rejection handler, npm publish --provenance, staging token scope, debugLog→KASTELL_DEBUG
• Security audit report: security-audit-report.md (39 findings, 0 critical)

Changed

• Test count: 5,506 → 5,522 (16 new tests: 4 SSH banner + 12 changelog)
• Test suites: 206 → 207

v1.15.0 — Web Security + Auto-Fix + Telegram

What's New

Added

• Edge & WAF Audit (P88): 9 Nginx config checks + WAF detection, 30th audit category
• TCP Stack DDoS Hardening (P89): 8 sysctl DDoS parameter checks, 31st audit category
• kastell fix --safe (P90): SAFE/GUARDED/FORBIDDEN tier classification, mandatory backup, dry-run
• MCP server_fix (P91): 14th MCP tool with dryRun:true default, SAFE_MODE guard
• Telegram Bot Notifications (P92): Guard audit score monitoring, two-tier alerts
• Telegram Bot Commands (P93): grammy bot with /status, /audit, /health, /doctor, /help
• kastell bot start command for foreground Telegram bot
• Interactive menu: Telegram bot entry

Changed

• Audit categories: 29 → 31 (WAF & Reverse Proxy, DDoS Hardening)
• Audit checks: 413 → 442
• Tests: 5,468 → 5,499 (31 new bot module tests)

Security

• Bot allowedChatIds middleware silently blocks unauthorized users
• server_fix FORBIDDEN rejection blocks SSH/Firewall/Docker category fixes via MCP
• Fix tier classification: SSH/Firewall changes always FORBIDDEN

Full Changelog: v1.14.0...v1.15.0

v1.14.0

Added

• Snapshot Restore — kastell snapshot restore CLI + MCP snapshot-restore action with SAFE_MODE guard, double confirmation, and 4-provider support (Hetzner, DigitalOcean, Vultr, Linode)
• Cloud ID Lookup — findServerByIp() across all 4 providers; kastell add now displays Cloud ID automatically
• TLS Hardening Audit — 8 checks (min version, weak ciphers, HSTS with max-age validation, OCSP stapling, cert expiry, DH params, compression, cert chain) with PCI-DSS/CIS/HIPAA compliance mappings
• HTTP Security Headers Audit — 6 checks (X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, CORS wildcard, CSP) with PCI-DSS v4.0 mappings
• Lock Score Boost — 4 new lock steps (SSH fine-tuning with 15 directives, login.defs hardening, pam_faillock, sudo logging/requiretty) + 2 extended steps (banners +/etc/motd, cronAccess +at.allow); 24-step orchestrator
• Interactive menu — Added snapshot restore, audit --explain/--diff/--fix, doctor --fix options
• Stryker Mutation Testing — Baseline 40.74% across 19,726 mutants

Fixed

• Lock-audit alignment — 5 misalignments fixed (AIDE cron path, auditd restart, logrotate install+timer, cronAccess step, Docker mkdir)
• snapshotId MCP validation — Added regex validation for defense-in-depth
• CERT_NOT_FOUND sentinel — Properly emits when certificate file is missing instead of false CERT_EXPIRING_SOON
• HTTPS-only audit gap — HTTP header audit now tries HTTPS before HTTP for HTTPS-only servers
• CLI snapshotCreate SAFE_MODE — Added guard for consistency with MCP handler
• Vultr/Linode snapshotId validation — Added assertValidServerId for defense-in-depth
• Hetzner findServerByIp pagination — Changed per_page from 50 to 100 for consistency
• Faillock idempotency — Each directive independently checked/updated instead of batch
• fileLock ENOENT — Ensure parent directory exists before creating lock file

Changed

• Test suite — 4178→5087 tests (909 new), 197 suites, 11 snapshots; branch coverage: global 93.25%, audit 95.96%, providers 91.22%, MCP 90.25%
• Audit categories — 27→29 (TLS Hardening + HTTP Security Headers); 421+ total checks
• CI hardening — Codecov integration, 4 typed test factory helpers, zero as any casts (231→0)
• CI release gate — release.yml now depends on CI success via workflow_run (prevents releasing when CI fails)
• CI tag support — CI workflow now runs on tag pushes for release/publish chain
• TLS weak cipher detection — Added SEED and IDEA to pattern
• HSTS validation — Now checks max-age >= 31536000
• Compliance mappings — Added HIPAA for TLS, updated PCI-DSS HDR-005 to v4.0 (6.2.4)
• Skill consolidation — 5 global security skills delegated to single kastell-security-check.md

Removed

• Stryker from CI — Mutation testing removed from GitHub Actions (exceeds 6h limit); moved to dedicated infrastructure with scheduled nightly incremental runs

Security

• Comprehensive v1.14 review — 5-agent parallel audit (OWASP, token/secret, audit system, code quality, test coverage); 13 findings resolved (3 MEDIUM + 10 LOW)
• Release workflow injection fix — Prevented shell injection via head_branch interpolation; added strict semver validation before checkout
• Zero token leakage — 5-layer sanitization verified across all new code paths

v1.13.0

Added

• Claude Code Plugin — kastell-plugin/ marketplace-ready package with plugin.json manifest, .mcp.json, and hooks.json
• 4 Skills — kastell-ops (background server management), kastell-research (Explore agent + architecture map), kastell-careful (skill-scoped LLM prompt hook), kastell-scaffold (4 fork-friendly templates)
• 2 Agents — kastell-auditor (security review) and kastell-fixer (bug diagnosis) project-scope agents
• 5 Hooks — session-log, stop-quality-check, session-audit, pre-commit-audit-guard, destroy-block with ESM-compatible .cjs scripts
• MCP Discoverability — server.instructions, MCP Logging, llms.txt, SUBMISSIONS.md, 4 platform setup guides, mcp-server keyword
• Dynamic Content Injection — !command syntax in 4 skill files for live codebase context

Fixed

• CLI↔MCP parity — 3 bugs fixed: logs default service (Dokploy), health host-key-mismatch detection, maintain update validation
• DO Coolify SSH key loss — Re-inject SSH public key after platform installer in cloud-init
• Docker crash after lock — SSH host key resolution in MCP health checks
• Plugin hook ESM compatibility — Renamed .js → .cjs for ESM project compatibility

Changed

• Commands→Core extraction — backup, status, update business logic moved from commands/ to core/ (thin command pattern)
• Adapter bypass elimination — 9 commands now use adapter properties (port, defaultLogService, platformPorts) instead of hardcoded values
• Shared createMockAdapter() — Test mock factory in tests/helpers/mockAdapter.ts; deduplicated across all test files
• Test coverage — 4156→4178 tests (adapter contract, core extraction, hook tests)