kastell 2.2.3 → 2.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/.claude-plugin/marketplace.json +18 -18
  2. package/.claude-plugin/plugin.json +45 -39
  3. package/CHANGELOG.md +1294 -1266
  4. package/LICENSE +201 -201
  5. package/NOTICE +5 -5
  6. package/README.md +1 -1
  7. package/README.tr.md +1 -1
  8. package/bin/kastell +2 -2
  9. package/bin/kastell-mcp +5 -5
  10. package/dist/adapters/coolify.js +92 -92
  11. package/dist/adapters/dokploy.js +99 -99
  12. package/dist/core/audit/formatters/badge.js +20 -20
  13. package/dist/core/completions.js +631 -631
  14. package/dist/mcp/server.d.ts.map +1 -1
  15. package/dist/mcp/server.js +25 -31
  16. package/dist/mcp/server.js.map +1 -1
  17. package/dist/mcp/tools/serverExplain.d.ts.map +1 -1
  18. package/dist/mcp/tools/serverExplain.js.map +1 -1
  19. package/dist/mcp/tools/serverFleet.d.ts.map +1 -1
  20. package/dist/mcp/tools/serverFleet.js.map +1 -1
  21. package/dist/mcp/tools/serverInfo.d.ts +1 -1
  22. package/dist/mcp/tools/serverInfo.js +1 -1
  23. package/dist/mcp/tools/serverPlugin.d.ts.map +1 -1
  24. package/dist/mcp/tools/serverPlugin.js.map +1 -1
  25. package/dist/mcp-bundle.mjs +101015 -0
  26. package/dist/utils/cloudInit.js +58 -58
  27. package/dist/utils/version.d.ts.map +1 -1
  28. package/dist/utils/version.js +19 -4
  29. package/dist/utils/version.js.map +1 -1
  30. package/kastell-plugin/.claude-plugin/plugin.json +20 -20
  31. package/kastell-plugin/.mcp.json +15 -8
  32. package/kastell-plugin/README.md +113 -113
  33. package/kastell-plugin/agents/kastell-auditor.md +77 -77
  34. package/kastell-plugin/agents/scripts/bucket_mapper.sh +101 -101
  35. package/kastell-plugin/agents/scripts/trend_report.sh +91 -91
  36. package/kastell-plugin/hooks/destroy-block.cjs +31 -31
  37. package/kastell-plugin/hooks/hooks.json +57 -57
  38. package/kastell-plugin/hooks/pre-commit-audit-guard.cjs +75 -75
  39. package/kastell-plugin/hooks/session-audit.cjs +86 -86
  40. package/kastell-plugin/hooks/session-log.cjs +56 -56
  41. package/kastell-plugin/hooks/stop-quality-check.cjs +72 -72
  42. package/kastell-plugin/skills/kastell-careful/SKILL.md +64 -64
  43. package/kastell-plugin/skills/kastell-ops/SKILL.md +139 -139
  44. package/kastell-plugin/skills/kastell-ops/references/commands.md +45 -45
  45. package/kastell-plugin/skills/kastell-ops/references/mcp-tools.md +50 -50
  46. package/kastell-plugin/skills/kastell-ops/references/patterns.md +145 -145
  47. package/kastell-plugin/skills/kastell-ops/references/pitfalls.md +136 -136
  48. package/kastell-plugin/skills/kastell-ops/scripts/check_coverage.sh +101 -101
  49. package/kastell-plugin/skills/kastell-ops/scripts/fleet_report.sh +73 -73
  50. package/kastell-plugin/skills/kastell-ops/scripts/parse_audit.sh +76 -76
  51. package/kastell-plugin/skills/kastell-research/SKILL.md +90 -90
  52. package/kastell-plugin/skills/kastell-scaffold/SKILL.md +104 -104
  53. package/kastell-plugin/skills/kastell-scaffold/references/template-audit-check.md +150 -150
  54. package/kastell-plugin/skills/kastell-scaffold/references/template-command.md +80 -80
  55. package/kastell-plugin/skills/kastell-scaffold/references/template-mcp-tool.md +72 -72
  56. package/kastell-plugin/skills/kastell-scaffold/references/template-provider.md +67 -67
  57. package/kastell-plugin/skills/kastell-scaffold/scripts/scaffold.sh +180 -180
  58. package/kastell-plugin/skills/kastell-scaffold/templates/check-test.ts.tpl +27 -27
  59. package/kastell-plugin/skills/kastell-scaffold/templates/check.ts.tpl +50 -50
  60. package/kastell-plugin/skills/kastell-scaffold/templates/command-core.ts.tpl +18 -18
  61. package/kastell-plugin/skills/kastell-scaffold/templates/command-test.ts.tpl +17 -17
  62. package/kastell-plugin/skills/kastell-scaffold/templates/command.ts.tpl +25 -25
  63. package/kastell-plugin/skills/kastell-scaffold/templates/mcp-tool-test.ts.tpl +30 -30
  64. package/kastell-plugin/skills/kastell-scaffold/templates/mcp-tool.ts.tpl +29 -29
  65. package/kastell-plugin/skills/kastell-scaffold/templates/provider-test.ts.tpl +34 -34
  66. package/kastell-plugin/skills/kastell-scaffold/templates/provider.ts.tpl +32 -32
  67. package/package.json +125 -122
  68. package/dist/commands/interactive.d.ts +0 -11
  69. package/dist/commands/interactive.d.ts.map +0 -1
  70. package/dist/commands/interactive.js +0 -1079
  71. package/dist/commands/interactive.js.map +0 -1
  72. package/dist/core/lock.d.ts +0 -66
  73. package/dist/core/lock.d.ts.map +0 -1
  74. package/dist/core/lock.js +0 -556
  75. package/dist/core/lock.js.map +0 -1
@@ -1,63 +1,63 @@
1
1
  export function getBareCloudInit(serverName) {
2
2
  const safeName = serverName.toLowerCase().replace(/[^a-z0-9-]/g, "");
3
- return `#!/bin/bash
4
- set +e
5
- touch /var/log/kastell-install.log
6
- chmod 600 /var/log/kastell-install.log
7
- exec > >(tee /var/log/kastell-install.log) 2>&1
8
-
9
- echo "=================================="
10
- echo "Kastell Bare Server Setup"
11
- echo "Server: ${safeName}"
12
- echo "=================================="
13
-
14
- # Wait for network connectivity
15
- echo "Waiting for network connectivity..."
16
- MAX_ATTEMPTS=30
17
- ATTEMPTS=0
18
- while [ $ATTEMPTS -lt $MAX_ATTEMPTS ]; do
19
- if curl -s --max-time 5 https://apt.releases.hashicorp.com > /dev/null 2>&1 || curl -s --max-time 5 https://archive.ubuntu.com > /dev/null 2>&1; then
20
- echo "Network is ready!"
21
- break
22
- fi
23
- ATTEMPTS=$((ATTEMPTS + 1))
24
- echo "Network not ready (attempt $ATTEMPTS/$MAX_ATTEMPTS)..."
25
- sleep 2
26
- done
27
-
28
- # Update system packages
29
- echo "Updating system packages..."
30
- apt-get update -y
31
- DEBIAN_FRONTEND=noninteractive apt-get upgrade -y
32
-
33
- # Install hardening packages
34
- echo "Installing hardening packages (fail2ban, ufw, unattended-upgrades)..."
35
- DEBIAN_FRONTEND=noninteractive apt-get install -y fail2ban ufw unattended-upgrades
36
-
37
- # Configure UFW firewall
38
- echo "Configuring UFW firewall..."
39
- ufw allow 22/tcp
40
- ufw allow 80/tcp
41
- ufw allow 443/tcp
42
- echo "y" | ufw enable || true
43
- ufw status
44
-
45
- # Configure unattended-upgrades for automatic security updates
46
- echo "Configuring unattended-upgrades..."
47
- dpkg-reconfigure -f noninteractive unattended-upgrades
48
-
49
- # Enable and start fail2ban
50
- echo "Enabling fail2ban..."
51
- systemctl enable fail2ban || true
52
- systemctl start fail2ban || true
53
-
54
- echo "=================================="
55
- echo "Bare server setup completed!"
56
- echo "Server: ${safeName}"
57
- echo "=================================="
58
- echo ""
59
- echo "Your server is ready. Connect via SSH:"
60
- echo " ssh root@YOUR_SERVER_IP"
3
+ return `#!/bin/bash
4
+ set +e
5
+ touch /var/log/kastell-install.log
6
+ chmod 600 /var/log/kastell-install.log
7
+ exec > >(tee /var/log/kastell-install.log) 2>&1
8
+
9
+ echo "=================================="
10
+ echo "Kastell Bare Server Setup"
11
+ echo "Server: ${safeName}"
12
+ echo "=================================="
13
+
14
+ # Wait for network connectivity
15
+ echo "Waiting for network connectivity..."
16
+ MAX_ATTEMPTS=30
17
+ ATTEMPTS=0
18
+ while [ $ATTEMPTS -lt $MAX_ATTEMPTS ]; do
19
+ if curl -s --max-time 5 https://apt.releases.hashicorp.com > /dev/null 2>&1 || curl -s --max-time 5 https://archive.ubuntu.com > /dev/null 2>&1; then
20
+ echo "Network is ready!"
21
+ break
22
+ fi
23
+ ATTEMPTS=$((ATTEMPTS + 1))
24
+ echo "Network not ready (attempt $ATTEMPTS/$MAX_ATTEMPTS)..."
25
+ sleep 2
26
+ done
27
+
28
+ # Update system packages
29
+ echo "Updating system packages..."
30
+ apt-get update -y
31
+ DEBIAN_FRONTEND=noninteractive apt-get upgrade -y
32
+
33
+ # Install hardening packages
34
+ echo "Installing hardening packages (fail2ban, ufw, unattended-upgrades)..."
35
+ DEBIAN_FRONTEND=noninteractive apt-get install -y fail2ban ufw unattended-upgrades
36
+
37
+ # Configure UFW firewall
38
+ echo "Configuring UFW firewall..."
39
+ ufw allow 22/tcp
40
+ ufw allow 80/tcp
41
+ ufw allow 443/tcp
42
+ echo "y" | ufw enable || true
43
+ ufw status
44
+
45
+ # Configure unattended-upgrades for automatic security updates
46
+ echo "Configuring unattended-upgrades..."
47
+ dpkg-reconfigure -f noninteractive unattended-upgrades
48
+
49
+ # Enable and start fail2ban
50
+ echo "Enabling fail2ban..."
51
+ systemctl enable fail2ban || true
52
+ systemctl start fail2ban || true
53
+
54
+ echo "=================================="
55
+ echo "Bare server setup completed!"
56
+ echo "Server: ${safeName}"
57
+ echo "=================================="
58
+ echo ""
59
+ echo "Your server is ready. Connect via SSH:"
60
+ echo " ssh root@YOUR_SERVER_IP"
61
61
  `;
62
62
  }
63
63
  //# sourceMappingURL=cloudInit.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAMA,wBAAgB,iBAAiB,IAAI,MAAM,CAU1C;AAED,eAAO,MAAM,eAAe,QAAsB,CAAC;AAEnD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
1
+ {"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAkBA,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C;AAED,eAAO,MAAM,eAAe,QAAsB,CAAC;AAEnD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
@@ -1,13 +1,28 @@
1
- import { readFileSync } from "fs";
2
- import { join } from "path";
1
+ import { readFileSync, existsSync } from "fs";
2
+ import { join, dirname } from "path";
3
3
  import { fileURLToPath } from "url";
4
4
  let cachedVersion = null;
5
+ function findPackageJson() {
6
+ let dir = fileURLToPath(new URL(".", import.meta.url));
7
+ for (let i = 0; i < 5; i++) {
8
+ const candidate = join(dir, "package.json");
9
+ if (existsSync(candidate))
10
+ return candidate;
11
+ const parent = dirname(dir);
12
+ if (parent === dir)
13
+ break;
14
+ dir = parent;
15
+ }
16
+ return null;
17
+ }
5
18
  export function getKastellVersion() {
6
19
  if (cachedVersion !== null)
7
20
  return cachedVersion;
8
21
  try {
9
- const __dirname = fileURLToPath(new URL(".", import.meta.url));
10
- const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
22
+ const pkgPath = findPackageJson();
23
+ if (!pkgPath)
24
+ return "0.0.0";
25
+ const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
11
26
  cachedVersion = pkg.version;
12
27
  return cachedVersion;
13
28
  }
@@ -1 +1 @@
1
- {"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,IAAI,aAAa,GAAkB,IAAI,CAAC;AAExC,MAAM,UAAU,iBAAiB;IAC/B,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,aAAa,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,EAAE,OAAO,CAAC,CAAwB,CAAC;QAC5G,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC;QAC5B,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,EAAE,CAAC;AAEnD,MAAM,UAAU,iBAAiB;IAC/B,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC"}
1
+ {"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,IAAI,aAAa,GAAkB,IAAI,CAAC;AAExC,SAAS,eAAe;IACtB,IAAI,GAAG,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC5C,IAAI,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,aAAa,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC;QAClC,IAAI,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC;QAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAwB,CAAC;QAC9E,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC;QAC5B,OAAO,aAAa,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,EAAE,CAAC;AAEnD,MAAM,UAAU,iBAAiB;IAC/B,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC"}
@@ -1,20 +1,20 @@
1
- {
2
- "name": "kastell",
3
- "version": "2.2.0",
4
- "description": "Autonomous server security and infrastructure management. Provides 13 MCP tools for cloud server provisioning, security auditing (457 checks), hardening, backup, and fleet management across Hetzner, DigitalOcean, Vultr, and Linode.",
5
- "author": {
6
- "name": "kastelldev"
7
- },
8
- "homepage": "https://kastell.dev",
9
- "repository": "https://github.com/kastelldev/kastell",
10
- "keywords": [
11
- "server",
12
- "security",
13
- "infrastructure",
14
- "mcp",
15
- "audit",
16
- "hardening",
17
- "vps",
18
- "cloud"
19
- ]
20
- }
1
+ {
2
+ "name": "kastell",
3
+ "version": "2.2.5",
4
+ "description": "Autonomous server security and infrastructure management. Provides 17 MCP tools for cloud server provisioning, security auditing (457 checks), hardening, backup, and fleet management across Hetzner, DigitalOcean, Vultr, and Linode.",
5
+ "author": {
6
+ "name": "kastelldev"
7
+ },
8
+ "homepage": "https://kastell.dev",
9
+ "repository": "https://github.com/kastelldev/kastell",
10
+ "keywords": [
11
+ "server",
12
+ "security",
13
+ "infrastructure",
14
+ "mcp",
15
+ "audit",
16
+ "hardening",
17
+ "vps",
18
+ "cloud"
19
+ ]
20
+ }
@@ -1,8 +1,15 @@
1
- {
2
- "mcpServers": {
3
- "kastell": {
4
- "command": "node",
5
- "args": ["${CLAUDE_PLUGIN_ROOT}/../../bin/kastell-mcp"]
6
- }
7
- }
8
- }
1
+ {
2
+ "mcpServers": {
3
+ "kastell": {
4
+ "command": "node",
5
+ "args": ["${CLAUDE_PLUGIN_ROOT}/../../dist/mcp-bundle.mjs"],
6
+ "env": {
7
+ "HETZNER_TOKEN": "${HETZNER_TOKEN}",
8
+ "DIGITALOCEAN_TOKEN": "${DIGITALOCEAN_TOKEN}",
9
+ "VULTR_TOKEN": "${VULTR_TOKEN}",
10
+ "LINODE_TOKEN": "${LINODE_TOKEN}",
11
+ "KASTELL_SAFE_MODE": "true"
12
+ }
13
+ }
14
+ }
15
+ }
@@ -1,113 +1,113 @@
1
- # Kastell
2
-
3
- Autonomous server security and infrastructure management for Claude Code.
4
-
5
- ## What You Get
6
-
7
- The Kastell plugin bundles 13 MCP tools, 4 skills, 1 agent, and 5 hooks that give Claude Code
8
- full control over your self-hosted server infrastructure. Use it to provision cloud servers,
9
- run 457-check security audits across 30 categories, apply 24-step hardening, manage backups,
10
- and operate entire fleets — all from natural language in Claude Code.
11
-
12
- Supported providers: Hetzner Cloud, DigitalOcean, Vultr, Linode.
13
- Supported platforms: Coolify, Dokploy.
14
-
15
- ## Prerequisites
16
-
17
- - `npm install -g kastell` — the Kastell CLI must be installed globally
18
- - At least one cloud provider API token (Hetzner, DigitalOcean, Vultr, or Linode)
19
- - `kastell setup` — run once to configure your API tokens and default provider
20
-
21
- ## Skills
22
-
23
- | Skill | Invocation | Purpose |
24
- |-------|------------|---------|
25
- | kastell-ops | Auto-loaded (background) | Architecture reference, patterns, anti-patterns, and decision trees for working in the Kastell codebase or managing Kastell-provisioned servers |
26
- | kastell-scaffold | `/kastell:scaffold` | Generate new CLI commands, MCP tools, cloud providers, and audit checks following Kastell conventions |
27
- | kastell-careful | `/kastell:careful` | Intercepts `kastell destroy` and `kastell restore` commands and requires explicit confirmation before proceeding |
28
- | kastell-research | `/kastell:research` | Read-only codebase exploration with full architecture context — for understanding behavior without making changes |
29
-
30
- **kastell-ops** loads automatically as background context whenever you work with the Kastell
31
- codebase or ask about server provisioning, audit, hardening, or provider management. It does
32
- not appear in the slash-command menu.
33
-
34
- ## Agents
35
-
36
- **`/agent:kastell-auditor`** — Parallel audit analyzer that groups all 30 audit categories into
37
- five analysis buckets (critical config, network exposure, access control, monitoring, compliance),
38
- produces structured findings with severity ratings, and remembers previous audit context across
39
- sessions using user-scoped memory.
40
-
41
- Invoke it with: "Analyze my last audit report" or "Which findings should I fix first?"
42
-
43
- Note: `kastell-fixer` is a project-scope agent, not bundled in this plugin. It requires
44
- `isolation: worktree` which only works when installed at project scope (`.claude/agents/`).
45
- Install kastell-fixer separately inside your Kastell project directory.
46
-
47
- ## Hooks
48
-
49
- | Hook | Trigger | What It Does |
50
- |------|---------|--------------|
51
- | stop-quality-check | Stop | Checks for TypeScript compilation errors, missing CHANGELOG entries, and stale README before ending the session |
52
- | session-log | PostToolUse (Bash) | Records Bash command outputs to `session.log` for audit trail |
53
- | session-audit | SessionStart | Runs `kastell audit --silent` on session start and surfaces the current security score |
54
- | pre-commit-audit-guard | PreToolUse (git commit) | Blocks the commit if the current audit score has dropped below the recorded baseline |
55
- | destroy-block | PreToolUse (Bash) | Blocks `kastell destroy` and `kastell restore` operations through Claude Code |
56
-
57
- ## MCP Tools
58
-
59
- All 13 tools are available in Claude Code once the plugin is installed. The MCP server starts
60
- automatically via the bundled `.mcp.json` configuration.
61
-
62
- | Tool | Description |
63
- |------|-------------|
64
- | server_info | List servers, check status, health, and available sizes |
65
- | server_logs | Fetch logs and system metrics from servers via SSH |
66
- | server_manage | Add, remove, or destroy servers |
67
- | server_maintain | Update platform, restart, or run full maintenance |
68
- | server_secure | SSH hardening, firewall management, and domain configuration |
69
- | server_backup | Create backups and manage cloud snapshots |
70
- | server_provision | Provision new cloud servers on Hetzner, DigitalOcean, Vultr, or Linode |
71
- | server_audit | Run the full 457-check security audit across 30 categories |
72
- | server_evidence | Collect forensic evidence packages from servers |
73
- | server_guard | Manage the autonomous security monitoring daemon |
74
- | server_doctor | Proactive health analysis with remediation recommendations |
75
- | server_lock | Apply the 24-step production hardening sequence |
76
- | server_fleet | Fleet-wide health and security posture overview |
77
-
78
- ## Quick Start
79
-
80
- ```bash
81
- # Install kastell globally
82
- npm install -g kastell
83
-
84
- # Configure your cloud provider
85
- kastell setup
86
-
87
- # In Claude Code, the plugin auto-starts the MCP server.
88
- # Try natural language commands like:
89
- # "Provision a new Hetzner server in Nuremberg with 2 CPUs"
90
- # "Run a security audit on my server at 1.2.3.4"
91
- # "Apply full hardening to my production server"
92
- # "Show me all my servers"
93
- ```
94
-
95
- After installation, the `kastell-ops` skill loads automatically in any session where you
96
- work with Kastell. Use `/kastell:scaffold` to generate new CLI commands or MCP tools,
97
- and `/agent:kastell-auditor` to get prioritized remediation guidance from audit results.
98
-
99
- ## Supported Providers
100
-
101
- | Provider | Regions | Notes |
102
- |----------|---------|-------|
103
- | Hetzner Cloud | EU (FSN, NBG, HEL), US (ASH, HIL) | Default recommended provider |
104
- | DigitalOcean | Global (NYC, SFO, AMS, SGP, LON, FRA, TOR, BLR, SYD) | |
105
- | Vultr | 25+ global locations | |
106
- | Linode (Akamai) | 11 global locations | |
107
-
108
- ## Links
109
-
110
- - Website: https://kastell.dev
111
- - GitHub: https://github.com/kastelldev/kastell
112
- - npm: https://www.npmjs.com/package/kastell
113
- - Docs: https://kastell.dev/docs
1
+ # Kastell
2
+
3
+ Autonomous server security and infrastructure management for Claude Code.
4
+
5
+ ## What You Get
6
+
7
+ The Kastell plugin bundles 13 MCP tools, 4 skills, 1 agent, and 5 hooks that give Claude Code
8
+ full control over your self-hosted server infrastructure. Use it to provision cloud servers,
9
+ run 457-check security audits across 30 categories, apply 24-step hardening, manage backups,
10
+ and operate entire fleets — all from natural language in Claude Code.
11
+
12
+ Supported providers: Hetzner Cloud, DigitalOcean, Vultr, Linode.
13
+ Supported platforms: Coolify, Dokploy.
14
+
15
+ ## Prerequisites
16
+
17
+ - `npm install -g kastell` — the Kastell CLI must be installed globally
18
+ - At least one cloud provider API token (Hetzner, DigitalOcean, Vultr, or Linode)
19
+ - `kastell setup` — run once to configure your API tokens and default provider
20
+
21
+ ## Skills
22
+
23
+ | Skill | Invocation | Purpose |
24
+ |-------|------------|---------|
25
+ | kastell-ops | Auto-loaded (background) | Architecture reference, patterns, anti-patterns, and decision trees for working in the Kastell codebase or managing Kastell-provisioned servers |
26
+ | kastell-scaffold | `/kastell:scaffold` | Generate new CLI commands, MCP tools, cloud providers, and audit checks following Kastell conventions |
27
+ | kastell-careful | `/kastell:careful` | Intercepts `kastell destroy` and `kastell restore` commands and requires explicit confirmation before proceeding |
28
+ | kastell-research | `/kastell:research` | Read-only codebase exploration with full architecture context — for understanding behavior without making changes |
29
+
30
+ **kastell-ops** loads automatically as background context whenever you work with the Kastell
31
+ codebase or ask about server provisioning, audit, hardening, or provider management. It does
32
+ not appear in the slash-command menu.
33
+
34
+ ## Agents
35
+
36
+ **`/agent:kastell-auditor`** — Parallel audit analyzer that groups all 30 audit categories into
37
+ five analysis buckets (critical config, network exposure, access control, monitoring, compliance),
38
+ produces structured findings with severity ratings, and remembers previous audit context across
39
+ sessions using user-scoped memory.
40
+
41
+ Invoke it with: "Analyze my last audit report" or "Which findings should I fix first?"
42
+
43
+ Note: `kastell-fixer` is a project-scope agent, not bundled in this plugin. It requires
44
+ `isolation: worktree` which only works when installed at project scope (`.claude/agents/`).
45
+ Install kastell-fixer separately inside your Kastell project directory.
46
+
47
+ ## Hooks
48
+
49
+ | Hook | Trigger | What It Does |
50
+ |------|---------|--------------|
51
+ | stop-quality-check | Stop | Checks for TypeScript compilation errors, missing CHANGELOG entries, and stale README before ending the session |
52
+ | session-log | PostToolUse (Bash) | Records Bash command outputs to `session.log` for audit trail |
53
+ | session-audit | SessionStart | Runs `kastell audit --silent` on session start and surfaces the current security score |
54
+ | pre-commit-audit-guard | PreToolUse (git commit) | Blocks the commit if the current audit score has dropped below the recorded baseline |
55
+ | destroy-block | PreToolUse (Bash) | Blocks `kastell destroy` and `kastell restore` operations through Claude Code |
56
+
57
+ ## MCP Tools
58
+
59
+ All 13 tools are available in Claude Code once the plugin is installed. The MCP server starts
60
+ automatically via the bundled `.mcp.json` configuration.
61
+
62
+ | Tool | Description |
63
+ |------|-------------|
64
+ | server_info | List servers, check status, health, and available sizes |
65
+ | server_logs | Fetch logs and system metrics from servers via SSH |
66
+ | server_manage | Add, remove, or destroy servers |
67
+ | server_maintain | Update platform, restart, or run full maintenance |
68
+ | server_secure | SSH hardening, firewall management, and domain configuration |
69
+ | server_backup | Create backups and manage cloud snapshots |
70
+ | server_provision | Provision new cloud servers on Hetzner, DigitalOcean, Vultr, or Linode |
71
+ | server_audit | Run the full 457-check security audit across 30 categories |
72
+ | server_evidence | Collect forensic evidence packages from servers |
73
+ | server_guard | Manage the autonomous security monitoring daemon |
74
+ | server_doctor | Proactive health analysis with remediation recommendations |
75
+ | server_lock | Apply the 24-step production hardening sequence |
76
+ | server_fleet | Fleet-wide health and security posture overview |
77
+
78
+ ## Quick Start
79
+
80
+ ```bash
81
+ # Install kastell globally
82
+ npm install -g kastell
83
+
84
+ # Configure your cloud provider
85
+ kastell setup
86
+
87
+ # In Claude Code, the plugin auto-starts the MCP server.
88
+ # Try natural language commands like:
89
+ # "Provision a new Hetzner server in Nuremberg with 2 CPUs"
90
+ # "Run a security audit on my server at 1.2.3.4"
91
+ # "Apply full hardening to my production server"
92
+ # "Show me all my servers"
93
+ ```
94
+
95
+ After installation, the `kastell-ops` skill loads automatically in any session where you
96
+ work with Kastell. Use `/kastell:scaffold` to generate new CLI commands or MCP tools,
97
+ and `/agent:kastell-auditor` to get prioritized remediation guidance from audit results.
98
+
99
+ ## Supported Providers
100
+
101
+ | Provider | Regions | Notes |
102
+ |----------|---------|-------|
103
+ | Hetzner Cloud | EU (FSN, NBG, HEL), US (ASH, HIL) | Default recommended provider |
104
+ | DigitalOcean | Global (NYC, SFO, AMS, SGP, LON, FRA, TOR, BLR, SYD) | |
105
+ | Vultr | 25+ global locations | |
106
+ | Linode (Akamai) | 11 global locations | |
107
+
108
+ ## Links
109
+
110
+ - Website: https://kastell.dev
111
+ - GitHub: https://github.com/kastelldev/kastell
112
+ - npm: https://www.npmjs.com/package/kastell
113
+ - Docs: https://kastell.dev/docs
@@ -1,77 +1,77 @@
1
- ---
2
- name: kastell-auditor
3
- description: "Security audit analyzer for Kastell servers. Runs kastell audit, maps results across 5 security domains (perimeter, authentication, runtime, internals, compliance), tracks score trends across sessions. Use when running kastell audit, analyzing server security posture, investigating audit findings, or generating security reports."
4
- tools: Read, Grep, Glob, Bash
5
- model: inherit
6
- effort: high
7
- memory: user
8
- maxTurns: 25
9
- skills:
10
- - kastell-ops
11
- ---
12
-
13
- # Role
14
-
15
- ## Live Context
16
-
17
- **Last audit score:** !`node -e "import('fs').then(f=>{try{const h=JSON.parse(f.readFileSync(process.env.HOME+'/.kastell/audit-history.json','utf8'));const last=h.sort((a,b)=>new Date(b.timestamp)-new Date(a.timestamp))[0];if(last)console.log(last.overallScore+'/100 ('+last.serverName+', '+last.timestamp.split('T')[0]+')');else console.log('No audit history yet')}catch(e){console.log('No audit history yet')}}).catch(()=>console.log('No audit history yet'))" 2>/dev/null || echo "No audit history yet"`
18
-
19
- You are a security audit analyst for Kastell-managed servers. Your purpose is to run `kastell audit`, organize findings into 5 security domains, identify critical failures and quick wins, and track score trends across sessions.
20
-
21
- # Workflow
22
-
23
- 1. **Identify target server** — ask user if not provided; verify with `kastell list`
24
- 2. **Run audit** — `kastell audit <server> --json` to get structured output
25
- 3. **Analyze by bucket** — pipe JSON through `bash scripts/bucket_mapper.sh` for instant 5-domain mapping
26
- 4. **Check memory** — run `bash scripts/trend_report.sh <server>` for score history; or load `audit-history.json` directly
27
- 5. **Report** — per-bucket summary + overall score + trend (if memory available)
28
-
29
- ## Scripts (Deterministic)
30
-
31
- ```bash
32
- # Map audit JSON to 5 security buckets
33
- kastell audit --server <name> --json | bash scripts/bucket_mapper.sh
34
-
35
- # Show audit score trend for a server
36
- bash scripts/trend_report.sh <server-name>
37
- bash scripts/trend_report.sh --all
38
- ```
39
-
40
- # Bucket Map
41
-
42
- | Bucket | Categories | Focus |
43
- |--------|-----------|-------|
44
- | 1 Perimeter | Network, Firewall, DNS Security | External attack surface |
45
- | 2 Authentication | SSH, Auth, Crypto, Accounts | Identity controls |
46
- | 3 Runtime | Docker, Services, Boot, Scheduling | Service exposure |
47
- | 4 Internals | Filesystem, Logging, Kernel, Memory | System hardening |
48
- | 5 Compliance | Updates, File Integrity, Malware, MAC, Secrets, Cloud Metadata, Supply Chain, Backup Hygiene, Resource Limits, Incident Readiness, Banners, Time | Hygiene and compliance |
49
-
50
- # Output Format
51
-
52
- For each bucket:
53
- - **Score:** X/Y checks passed
54
- - **Critical findings** (up to 3): `[FAIL] check-name -- one-line impact`
55
- - **Quick win:** one actionable fix
56
-
57
- After all buckets:
58
- - **Overall score:** X/100
59
- - **Trend** (when memory has prior data): "Last audit: Y -- Delta: +/-Z -- [N] new failures in [bucket]"
60
-
61
- # Memory
62
-
63
- Manage a single file `audit-history.json` in your agent memory directory. Store per server:
64
-
65
- ```json
66
- { "server": "string", "date": "string", "score": 0, "bucketScores": { "perimeter": 0, "authentication": 0, "runtime": 0, "internals": 0, "compliance": 0 }, "failedChecks": [] }
67
- ```
68
-
69
- On each run: load prior record, compute delta, store new record. Discard entries for servers no longer in `kastell list` output.
70
-
71
- # Rules
72
-
73
- - Read-only operations only: `server_audit`, `server_doctor`, `server_fleet`
74
- - Never run `kastell lock`, `kastell secure`, or any write operation
75
- - Recommend fixes but do not apply them — suggest `/agent:kastell-fixer` for implementation
76
- - If multiple servers requested, analyze each sequentially
77
- - English output for analysis structure; follow user's language for explanatory text
1
+ ---
2
+ name: kastell-auditor
3
+ description: "Security audit analyzer for Kastell servers. Runs kastell audit, maps results across 5 security domains (perimeter, authentication, runtime, internals, compliance), tracks score trends across sessions. Use when running kastell audit, analyzing server security posture, investigating audit findings, or generating security reports."
4
+ tools: Read, Grep, Glob, Bash
5
+ model: inherit
6
+ effort: high
7
+ memory: user
8
+ maxTurns: 25
9
+ skills:
10
+ - kastell-ops
11
+ ---
12
+
13
+ # Role
14
+
15
+ ## Live Context
16
+
17
+ **Last audit score:** !`node -e "import('fs').then(f=>{try{const h=JSON.parse(f.readFileSync(process.env.HOME+'/.kastell/audit-history.json','utf8'));const last=h.sort((a,b)=>new Date(b.timestamp)-new Date(a.timestamp))[0];if(last)console.log(last.overallScore+'/100 ('+last.serverName+', '+last.timestamp.split('T')[0]+')');else console.log('No audit history yet')}catch(e){console.log('No audit history yet')}}).catch(()=>console.log('No audit history yet'))" 2>/dev/null || echo "No audit history yet"`
18
+
19
+ You are a security audit analyst for Kastell-managed servers. Your purpose is to run `kastell audit`, organize findings into 5 security domains, identify critical failures and quick wins, and track score trends across sessions.
20
+
21
+ # Workflow
22
+
23
+ 1. **Identify target server** — ask user if not provided; verify with `kastell list`
24
+ 2. **Run audit** — `kastell audit <server> --json` to get structured output
25
+ 3. **Analyze by bucket** — pipe JSON through `bash scripts/bucket_mapper.sh` for instant 5-domain mapping
26
+ 4. **Check memory** — run `bash scripts/trend_report.sh <server>` for score history; or load `audit-history.json` directly
27
+ 5. **Report** — per-bucket summary + overall score + trend (if memory available)
28
+
29
+ ## Scripts (Deterministic)
30
+
31
+ ```bash
32
+ # Map audit JSON to 5 security buckets
33
+ kastell audit --server <name> --json | bash scripts/bucket_mapper.sh
34
+
35
+ # Show audit score trend for a server
36
+ bash scripts/trend_report.sh <server-name>
37
+ bash scripts/trend_report.sh --all
38
+ ```
39
+
40
+ # Bucket Map
41
+
42
+ | Bucket | Categories | Focus |
43
+ |--------|-----------|-------|
44
+ | 1 Perimeter | Network, Firewall, DNS Security | External attack surface |
45
+ | 2 Authentication | SSH, Auth, Crypto, Accounts | Identity controls |
46
+ | 3 Runtime | Docker, Services, Boot, Scheduling | Service exposure |
47
+ | 4 Internals | Filesystem, Logging, Kernel, Memory | System hardening |
48
+ | 5 Compliance | Updates, File Integrity, Malware, MAC, Secrets, Cloud Metadata, Supply Chain, Backup Hygiene, Resource Limits, Incident Readiness, Banners, Time | Hygiene and compliance |
49
+
50
+ # Output Format
51
+
52
+ For each bucket:
53
+ - **Score:** X/Y checks passed
54
+ - **Critical findings** (up to 3): `[FAIL] check-name -- one-line impact`
55
+ - **Quick win:** one actionable fix
56
+
57
+ After all buckets:
58
+ - **Overall score:** X/100
59
+ - **Trend** (when memory has prior data): "Last audit: Y -- Delta: +/-Z -- [N] new failures in [bucket]"
60
+
61
+ # Memory
62
+
63
+ Manage a single file `audit-history.json` in your agent memory directory. Store per server:
64
+
65
+ ```json
66
+ { "server": "string", "date": "string", "score": 0, "bucketScores": { "perimeter": 0, "authentication": 0, "runtime": 0, "internals": 0, "compliance": 0 }, "failedChecks": [] }
67
+ ```
68
+
69
+ On each run: load prior record, compute delta, store new record. Discard entries for servers no longer in `kastell list` output.
70
+
71
+ # Rules
72
+
73
+ - Read-only operations only: `server_audit`, `server_doctor`, `server_fleet`
74
+ - Never run `kastell lock`, `kastell secure`, or any write operation
75
+ - Recommend fixes but do not apply them — suggest `/agent:kastell-fixer` for implementation
76
+ - If multiple servers requested, analyze each sequentially
77
+ - English output for analysis structure; follow user's language for explanatory text