io.github.kastelldev/kastell
Server security audit (413 checks), hardening, and fleet management across 4 cloud providers.
Open source Open in the app JSON README (API)
About
Server security audit (413 checks), hardening, and fleet management across 4 cloud providers.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- kastelldev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.14.0
- Stars
- 60
- Forks
- 2
- Open pull requests
- 17
- Last push
- 2026-09-07T14:21:33Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 04:00:20
- Updated
- 2026-08-29 04:00:20
- Origin id
io.github.kastelldev/kastell
README
<p align="center">
<img src="assets/logo.png" alt="Kastell" width="120" />
</p>
<h1 align="center">Kastell</h1>
<p align="center">Your infrastructure, fortified.</p>
> 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 <command>
# Or install globally
npm install -g kastell
kastell <command>
```
Requires Node.js 20 or later.
## Safety Modes
`KASTELL_SAFE_MODE` environment variable controls destructive operations:
- **MCP default:** `true` — `provision`, `destroy`, `restore` are blocked
- **CLI default:** `false` — all operations are enabled
- **Override:** `KASTELL_SAFE_MODE=true kastell destroy <server>` → rejected
Affected commands: `init`, `destroy`, `backup-restore`, `snapshot-restore`, `snapshot-delete`, `restart`, `maintain`.
## Troubleshooting
**Server creation fails?**
Run `kastell doctor --check-tokens` to verify your API token and local environment.
**Server not responding?**
Use `kastell status my-server --autostart` to check platform status and auto-restart if needed, or `kastell health` to check all servers at once.
**Need to start fresh?**
`kastell destroy my-server` removes the cloud server entirely.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.
Kastell uses **11,206 tests** across 344 suites. Run `npm test` before submitting PRs.
## MCP Server (AI Integration)
Kastell includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server for AI-powered server management. Works with Claude Code, Cursor, Windsurf, and other MCP-compatible clients.
```json
{
"mcpServers": {
"kastell": {
"command": "npx",
"args": ["-y", "-p", "kastell", "kastell-mcp"],
"env": {
"HETZNER_TOKEN": "your-token",
"DIGITALOCEAN_TOKEN": "your-token",
"VULTR_TOKEN": "your-token",
"LINODE_TOKEN": "your-token"
}
}
}
}
```
Available tools:
| Tool | Actions | Description |
|------|---------|-------------|
| `server_info` | list, status, health, sizes | Query server information, check cloud provider and platform status |
| `server_logs` | logs, monitor | Fetch platform/Docker logs and system metrics via SSH |
| `server_manage` | add, remove, destroy | Register, unregister, or destroy cloud servers |
| `server_maintain` | update, restart, maintain | Update platform, restart servers, run full maintenance |
| `server_secure` | secure, firewall, domain | SSH hardening, firewall rules, domain/SSL management (10 subcommands) |
| `server_backup` | backup, snapshot | Backup/restore databases and create/manage VPS snapshots |
| `server_provision` | create | Provision new servers on cloud providers |
| `server_audit` | audit | 449-check security audit with compliance framework filtering; use `--explain` for remediation guidance |
| `server_evidence` | collect | Collect forensic evidence package with checksums |
| `server_guard` | start, stop, status | Manage autonomous security monitoring daemon |
| `server_doctor` | diagnose | Proactive health analysis with remediation commands |
| `server_lock` | harden | 24-step production hardening (SSH, UFW, sysctl, auditd, AIDE, Docker) |
| `server_fleet` | overview | Fleet-wide health and security posture dashboard |
| `server_fix` | fix --safe | Apply safe auto-fixes with backup (SAFE tier only, dryRun default) |
> All destructive operations (destroy, restore, snapshot-delete, provision, restart, maintain, snapshot-create) require `SAFE_MODE=false` to execute.
### Claude Code Plugin
Kastell is available as a [Claude Code plugin](kastell-plugin/) for the Anthropic marketplace. The plugin bundles:
- **4 skills**: kastell-ops (architecture reference), kastell-scaffold (component generation), kastell-careful (destructive op guard), kastell-research (codebase exploration)
- **2 agents**: kastell-auditor (parallel audit analyzer), kastell-fixer (worktree-isolated auto-fix)
- **5 hooks**: destroy-block, session-audit, session-log, pre-commit-audit-guard, stop-quality-check
Install via Claude Code plugin manager or use directly with `claude --plugin-dir kastell-plugin`.
### MCP Platform Setup
| Platform | Config Location | Guide |
|----------|----------------|-------|
| Claude Code | `claude mcp add` or `.mcp.json` | [Setup Guide](docs/mcp-platforms/claude-code.md) |
| Claude Desktop | `claude_desktop_config.json` | [Setup Guide](docs/mcp-platforms/claude-desktop.md) |
| VS Code / Copilot | `.vscode/mcp.json` | [Setup Guide](docs/mcp-platforms/vscode.md) |
| Cursor | `.cursor/mcp.json` | [Setup Guide](docs/mcp-platforms/cursor.md) |
> More platforms (JetBrains, Windsurf, Gemini, and others) coming in v2.0.
### AI Discoverability
Kastell provides [`llms.txt`](llms.txt) for AI crawlers and is listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.kastelldev/kastell`.
## v2.3 Reliability Contracts
These contracts apply to the CLI and the MCP server.
### Provisioning behavior
`server_provision` returns after the provider creates the server and Kastell
durably registers it. `readiness.status` may be `pending`; follow with
`server_info status` or `server_info health`. The interactive `kastell init`
command continues waiting through its existing readiness checks.
### Automation contracts
- Unsupported and failed CLI operations return exit code `1`.
- Valid empty results and user cancellation return `0`.
- Mixed `--all` failures return `1`.
- `audit --json` and `audit --ci` reserve stdout for one JSON payload.
## CI/CD Integration
Use `kastell audit` in your CI pipeline to enforce security baselines:
```yaml
# .github/workflows/security-audit.yml
name: Security Audit
on:
schedule:
- cron: '0 6 * * 1' # Weekly Monday 6 AM
workflow_dispatch:
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install -g kastell
- run: kastell audit --host root@${{ secrets.SERVER_IP }} --threshold 70 --json > audit-result.json
- uses: actions/upload-artifact@v4
with:
name: audit-report
path: audit-result.json
```
The `--threshold` flag causes a non-zero exit code when the score falls below the target, failing the CI job automatically.
## What's Next
- Test Excellence: Mutation testing, coverage gaps, integration tests (v1.14)
- Plugin ecosystem with marketplace distribution (v2.0)
- Dashboard and managed service (v3.0)
## Philosophy
> Infrastructure should be boring, predictable, and safe.
Kastell is not a script. It's your DevOps safety layer for self-hosted infrastructure.
## License
Apache 2.0 -- see [LICENSE](LICENSE)
## Support
- [GitHub Issues](https://github.com/kastelldev/kastell/issues) -- Bug reports and feature requests
- [Changelog](CHANGELOG.md) -- Version history
---
Built by [@omrfc](https://github.com/omrfc)