Your infrastructure, fortified.
> English | [Türkçe](README.tr.md)  [](https://app.codecov.io/gh/kastelldev/kastell)     [](https://socket.dev/npm/package/kastell) [](https://snyk.io/test/github/kastelldev/kastell) [](https://kastell.dev) [](https://deepwiki.com/kastelldev/kastell)  ## Why Kastell? Server security is fragmented. Lynis scans but doesn't fix. OpenSCAP is powerful but complex. Custom scripts work until they don't -- and nobody maintains them. Each tool has its own output format, its own update cycle, its own learning curve. **Kastell takes a different approach:** one CLI that audits, fixes, hardens, and monitors. Scan your server, apply safe fixes, lock it down to production standards, and keep watching -- all with the same tool. **AI-native from day one.** Kastell ships with a built-in MCP server, so Claude, Cursor, or any MCP-compatible AI agent can manage your servers directly. Go from a prompt to production hardening in seconds. You don't need four separate tools to secure a server. ## Quick Start ```bash # Interactive mode -- no commands to memorize npx kastell ``` Running `kastell` without any arguments launches an **interactive search menu** with a gradient ASCII banner and quick-start examples. Browse actions by emoji-categorized groups, type to filter results instantly, and configure options step by step -- no need to remember any command names or flags. ``` ██╗ ██╗ ██████╗ ███████╗████████╗███████╗██╗ ██╗ ██║ ██╔╝ ██╔══██╗ ██╔════╝╚══██╔══╝██╔════╝██║ ██║ █████╔╝ ███████║ ███████╗ ██║ █████╗ ██║ ██║ ██╔═██╗ ██╔══██║ ╚════██║ ██║ ██╔══╝ ██║ ██║ ██║ ██╗ ██║ ██║ ███████║ ██║ ███████╗███████╗███████╗ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚═╝ ╚══════╝╚══════╝╚══════╝ KASTELL v2.3.1 · Your infrastructure, fortified. $ kastell init --template production → deploy a new server $ kastell status --all → check all servers $ kastell secure setup → harden SSH + fail2ban $ kastell maintain --all → full maintenance cycle ? What would you like to do? Server Management ❯ Deploy a new server Add an existing server List all servers ... Security Harden SSH & fail2ban Manage firewall (UFW) ... ``` Each action includes sub-options (server mode, template, log source, port number, etc.) and a **<- Back** option to return to the main menu at any point. If you already know the commands, you can still use them directly: ```bash kastell init # Deploy a new server kastell status my-server # Check server status kastell backup --all # Backup all servers ``` Kastell handles server provisioning, SSH key setup, firewall configuration, and platform installation automatically. ## What Makes Kastell Different? | Problem | Solution | |---------|----------| | Broke your server with an update? | Pre-update snapshot protection via `maintain` | | No idea if your server is healthy? | Built-in monitoring, health checks, and `doctor` diagnostics | | Security is an afterthought? | Firewall, SSH hardening, SSL, and security audits built-in | | Backups? Maybe someday... | One-command backup & restore with manifest tracking | | Managing multiple servers? | `--all` flag across backup, maintain, status, and health | | Existing server not tracked? | `kastell add` brings any server under management | | Don't want to memorize commands? | Just run `kastell` -- interactive menu guides you | ## Kastell vs Alternatives | Feature | Kastell | Lynis | OpenSCAP | |---------|---------|-------|----------| | Installation | `npm i -g kastell` | Package manager | Package manager | | Language | TypeScript | Shell | C/Python | | Security Checks | 449 | 300+ | Varies by profile | | Auto-Fix | Safe tier | Suggest only | Suggest only | | MCP (AI Agent) | 17 tools | -- | -- | | Compliance | CIS, PCI-DSS, HIPAA | CIS, HIPAA | CIS, STIG, PCI-DSS | | Cloud Provision | 4 providers | -- | -- | | Hardening (Lock) | 24-step | -- | -- | | Remote Monitoring | Guard daemon | -- | -- | | Telegram Bot | Built-in | -- | -- | | Platform Support | Linux (SSH) | Linux/macOS/BSD | Linux | | License | Apache 2.0 | GPL-3.0 | LGPL-2.1 | ## What Can You Do? ### Deploy ```bash kastell # Interactive menu (recommended) kastell init # Interactive setup (direct) kastell init --provider hetzner # Non-interactive kastell init --config kastell.yml # From YAML config kastell init --template production # Use a template kastell init --mode bare # Generic VPS (no platform) kastell init --mode dokploy # Dokploy (Docker Swarm PaaS) ``` ### Manage ```bash kastell list # List all servers kastell status my-server # Check server status kastell status --all # Check all servers kastell ssh my-server # SSH into server kastell restart my-server # Restart server kastell destroy my-server # Destroy cloud server entirely kastell add # Add existing server kastell remove my-server # Remove from local config kastell config set key value # Manage default configuration kastell config validate # Validate servers.yaml structure and types kastell export # Export server list to JSON kastell import servers.json # Import servers from JSON ``` ### Update & Maintain ```bash kastell update my-server # Update platform (Coolify or Dokploy, auto-detected) kastell update my-server --dry-run # Preview update without executing kastell maintain my-server # Full maintenance (snapshot + update + health + reboot) kastell maintain my-server --dry-run # Preview maintenance steps kastell maintain --all # Maintain all servers ``` ### Back Up & Restore ```bash kastell backup my-server # Backup DB + config kastell backup --all # Backup all servers kastell restore my-server # Restore from backup ``` ### Snapshots ```bash kastell snapshot create my-server # Create VPS snapshot (with cost estimate) kastell snapshot list my-server # List snapshots kastell snapshot list --all # List all snapshots across servers kastell snapshot delete my-server # Delete a snapshot ``` ### Security ```bash kastell firewall status my-server # Check firewall kastell firewall setup my-server # Configure UFW kastell secure audit my-server # Security audit kastell secure setup my-server # SSH hardening + fail2ban kastell domain add my-server --domain example.com # Set domain + SSL ``` ### Security Audit ```bash kastell audit my-server # Full security audit (31 categories, 449 checks) kastell audit my-server --json # JSON output for automation kastell audit my-server --threshold 70 # Exit code 1 if score below threshold kastell audit my-server --fix # Interactive fix mode (prompts per severity) kastell audit my-server --fix --dry-run # Preview fixes without executing kastell audit my-server --watch # Re-audit every 5 min, show only changes kastell audit my-server --watch 60 # Custom interval (60 seconds) kastell audit --host root@1.2.3.4 # Audit unregistered server kastell audit my-server --badge # SVG badge output kastell audit my-server --report html # Full HTML report kastell audit my-server --score-only # Just the score (CI-friendly) kastell audit my-server --summary # Compact dashboard view kastell audit my-server --explain # Explain failed checks with remediation guidance kastell audit my-server --compliance cis # Filter by compliance framework (cis-level1, cis-level2, pci-dss, hipaa) ``` ### Security Hardening ```bash kastell lock my-server # 24-step production hardening (SSH + UFW + sysctl + auditd + AIDE + Docker) kastell lock my-server --dry-run # Preview hardening steps without applying ``` ### Monitor & Debug ```bash kastell monitor my-server # CPU, RAM, disk usage kastell logs my-server # View platform logs (Coolify or Dokploy) kastell logs my-server -f # Follow logs kastell health # Health check all servers kastell doctor # Check local environment ``` ## Supported Providers | Provider | Status | Regions | Starting Price | |----------|--------|---------|---------------| | [Hetzner Cloud](https://hetzner.cloud) | Stable | EU, US | ~€4/mo | | [DigitalOcean](https://digitalocean.com) | Stable | Global | ~$18/mo | | [Vultr](https://vultr.com) | Stable | Global | ~$12/mo | | [Linode (Akamai)](https://linode.com) | Beta | Global | ~$12/mo | > Prices reflect the cheapest plan with at least 2 GB RAM (required by Coolify and Dokploy). Bare mode has no minimum requirements -- plans start from ~$2.50/mo depending on provider. You can choose a different size during setup. Linode support is in beta -- community testing welcome. ## Supported Platforms | Platform | Mode Flag | Min RAM | Min CPU | Description | |----------|-----------|---------|---------|-------------| | Coolify | `--mode coolify` (default) | 2 GB | 2 vCPU | Docker-based PaaS (port 8000) | | Dokploy | `--mode dokploy` | 2 GB | 2 vCPU | Docker Swarm-based PaaS (port 3000) | | Bare | `--mode bare` | — | — | Generic VPS, no platform overhead | Kastell uses a **PlatformAdapter** architecture -- the same commands (`update`, `maintain`, `logs`, `health`) work across all platforms. The platform is stored in your server record and auto-detected on each command. ## Developer Experience | Feature | Command / Flag | Description | |---------|---------------|-------------| | Dry Run | `--dry-run` | Preview destructive commands without executing. Available on: destroy, update, restart, remove, maintain, restore, firewall, domain, backup, snapshot, secure. | | Shell Completions | `kastell completions bash\|zsh\|fish` | Generate shell completion scripts for tab-completion of commands and options. | | Config Validation | `kastell config validate` | Check `servers.yaml` for structural and type errors using Zod strict schemas. | | Version Check | `kastell --version` | Shows current version and notifies if a newer version is available on npm. | ## YAML Config Deploy with a single config file: ```yaml # kastell.yml provider: hetzner region: nbg1 size: cax11 name: my-coolify fullSetup: true domain: coolify.example.com ``` ```bash kastell init --config kastell.yml ``` ## Templates | Template | Best For | Includes | |----------|----------|----------| | `starter` | Testing, side projects | 1-2 vCPU, 2-4 GB RAM | | `production` | Live applications | 2-4 vCPU, 4-8 GB RAM, full hardening | | `dev` | Development & CI/CD | Same as starter, no hardening | ```bash kastell init --template production --provider hetzner ``` ## Security Kastell is built with security as a priority -- **12,132 tests** across 380 suites, including dedicated security test suites. - API tokens are never stored on disk -- prompted at runtime or via environment variables - SSH keys are auto-generated if needed (Ed25519) - All SSH connections use `StrictHostKeyChecking=accept-new` with IP validation (octet range) and environment filtering - Shell injection protection on all user-facing inputs (`spawn`/`spawnSync`, no `execSync`) - Provider error messages are sanitized to prevent token leakage - stderr sanitization redacts IPs, home paths, tokens, and secrets from error output - Config file token detection (22+ key patterns, case-insensitive, nested) - Import/export operations strip sensitive fields and enforce strict file permissions (`0o600`) - `--full-setup` enables UFW firewall and SSH hardening automatically - MCP: SAFE_MODE (default: on) blocks all destructive operations, Zod schema validation on all inputs, path traversal protection on backup restore - Claude Code hooks: destroy-block prevents accidental `kastell destroy` without `--force`, pre-commit audit guard warns on score drops - **Zero Telemetry** — Kastell collects no usage data, analytics, or telemetry. Your server data never leaves your machine. ## Security behavior (v2.3.1) This section documents security contracts shipped in v2.3.1. Future work is described elsewhere (see `CHANGELOG.md` for upcoming entries). - **`KASTELL_STRICT_HOST_KEY=true`** — when set, Kastell rejects unknown SSH host keys outright. Direct SSH connections (i.e. those that go through `accept-new`) emit a one-time Trust-On-First-Use (TOFU) warning so operators see the risk; combined with `KASTELL_STRICT_HOST_KEY=true`, the warning is promoted to a hard error. - **Non-TTY destructive commands** — in non-interactive environments (CI, scripts, automation), destructive operations require an explicit `--force` flag or the command's documented opt-in flag. Without one, the command exits with a non-zero status and a clear error. - **Structured skipped checks** — checks that are skipped (e.g. VPS-irrelevant, platform-mismatch, missing prerequisite) appear in audit output as a neutral, visible result rather than being silently dropped. Operators can see exactly which checks did not run and why. - **Windows secret files** — secret-bearing files written by Kastell on Windows receive restrictive ACLs (owner-only access). `0o600` POSIX permissions remain the source of truth on Linux/macOS; Windows uses the equivalent DACL. - **QuickWin JSON shape** — `audit --json` QuickWin entries now include a stable `id` (check ID) and `severity` field, in addition to the existing `description` and `commands`. This makes QuickWins programmatically consumable without parsing the human-readable description. - **FORBIDDEN previews include reasons** — when previewing fixes with `--dry-run` (or via `server_fix` MCP dry-run), each FORBIDDEN-tier fix now renders a short reason explaining why the fix is classified FORBIDDEN (e.g. "requires reboot", "disrupts active SSH sessions"). The reason is sourced from the check's `forbiddenReason` field. ## Installation ```bash # Run directly (recommended) npx kastell