kubesift 2.0.0__py3-none-any.whl

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 (63) hide show
  1. kubesift/__init__.py +3 -0
  2. kubesift/analysis/__init__.py +3 -0
  3. kubesift/analysis/changes.py +165 -0
  4. kubesift/analysis/correlate.py +160 -0
  5. kubesift/analysis/describe.py +83 -0
  6. kubesift/analysis/engine.py +362 -0
  7. kubesift/analysis/llm.py +152 -0
  8. kubesift/checks/__init__.py +17 -0
  9. kubesift/checks/base.py +150 -0
  10. kubesift/checks/config_refs.py +84 -0
  11. kubesift/checks/events.py +77 -0
  12. kubesift/checks/hygiene.py +264 -0
  13. kubesift/checks/lifecycle.py +202 -0
  14. kubesift/checks/network.py +325 -0
  15. kubesift/checks/nodes.py +183 -0
  16. kubesift/checks/operations.py +319 -0
  17. kubesift/checks/pods.py +485 -0
  18. kubesift/checks/storage.py +72 -0
  19. kubesift/checks/workloads.py +201 -0
  20. kubesift/cli.py +874 -0
  21. kubesift/cluster/__init__.py +4 -0
  22. kubesift/cluster/client.py +141 -0
  23. kubesift/cluster/snapshot.py +513 -0
  24. kubesift/config.py +134 -0
  25. kubesift/cost.py +150 -0
  26. kubesift/drill_scenarios/01-crashloop-missing-env.yaml +24 -0
  27. kubesift/drill_scenarios/02-imagepull-wrong-tag.yaml +23 -0
  28. kubesift/drill_scenarios/03-oomkilled-low-memory.yaml +24 -0
  29. kubesift/drill_scenarios/04-service-selector-mismatch.yaml +34 -0
  30. kubesift/drill_scenarios/05-missing-probe-crashloop.yaml +24 -0
  31. kubesift/drill_scenarios/06-pending-insufficient-resources.yaml +26 -0
  32. kubesift/drill_scenarios/07-missing-secret.yaml +28 -0
  33. kubesift/drill_scenarios/08-pvc-missing-storageclass.yaml +38 -0
  34. kubesift/drill_scenarios/09-netpol-blocks-dns.yaml +14 -0
  35. kubesift/drill_scenarios/10a-rollout-good.yaml +27 -0
  36. kubesift/drill_scenarios/10b-rollout-bad.yaml +25 -0
  37. kubesift/drill_scenarios/__init__.py +1 -0
  38. kubesift/drills.py +122 -0
  39. kubesift/knowledge.py +51 -0
  40. kubesift/leader.py +145 -0
  41. kubesift/lint.py +89 -0
  42. kubesift/mcp_server.py +193 -0
  43. kubesift/models.py +144 -0
  44. kubesift/notify.py +71 -0
  45. kubesift/postmortem.py +152 -0
  46. kubesift/preflight.py +435 -0
  47. kubesift/redact.py +38 -0
  48. kubesift/remediate.py +99 -0
  49. kubesift/report.py +193 -0
  50. kubesift/runbooks.py +58 -0
  51. kubesift/server/__init__.py +0 -0
  52. kubesift/server/app.py +480 -0
  53. kubesift/server/static/index.html +152 -0
  54. kubesift/slack.py +106 -0
  55. kubesift/store.py +219 -0
  56. kubesift/timetravel.py +156 -0
  57. kubesift/upgrade.py +51 -0
  58. kubesift/util.py +174 -0
  59. kubesift-2.0.0.dist-info/METADATA +192 -0
  60. kubesift-2.0.0.dist-info/RECORD +63 -0
  61. kubesift-2.0.0.dist-info/WHEEL +4 -0
  62. kubesift-2.0.0.dist-info/entry_points.txt +3 -0
  63. kubesift-2.0.0.dist-info/licenses/LICENSE +202 -0
kubesift/cli.py ADDED
@@ -0,0 +1,874 @@
1
+ """Command line interface. Also installed as `kubectl-sift`, so `kubectl sift ...` works."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import json
7
+ import sys
8
+ from pathlib import Path
9
+ from typing import Any, NoReturn
10
+
11
+ import typer
12
+ from rich.console import Console
13
+ from rich.table import Table
14
+ from rich.text import Text
15
+
16
+ from kubesift import __version__
17
+ from kubesift.config import Settings, load_settings
18
+ from kubesift.models import Report, Severity
19
+
20
+ app = typer.Typer(no_args_is_help=True, rich_markup_mode="rich", add_completion=True,
21
+ help="KubeSift: find out what is broken in Kubernetes, why, and what changed.")
22
+ note_app = typer.Typer(help="Team notes: record what fixed a problem so the next person sees it.")
23
+ snapshot_app = typer.Typer(help="Save a redacted cluster snapshot to analyse offline or attach to a bug report.")
24
+ drill_app = typer.Typer(help="Fire drills: break a dedicated namespace on purpose to practise on-call.")
25
+ knowledge_app = typer.Typer(help="Knowledge packs: share what fixed past incidents between teams and clusters.")
26
+ app.add_typer(note_app, name="note")
27
+ app.add_typer(snapshot_app, name="snapshot")
28
+ app.add_typer(drill_app, name="drill")
29
+ app.add_typer(knowledge_app, name="knowledge")
30
+
31
+ console = Console()
32
+ err = Console(stderr=True)
33
+
34
+
35
+ class State:
36
+ settings: Settings
37
+
38
+
39
+ state = State()
40
+
41
+
42
+ @app.callback()
43
+ def main_options(
44
+ kubeconfig: str | None = typer.Option(None, "--kubeconfig", envvar="KUBECONFIG_PATH", help="Path to kubeconfig."),
45
+ context: str | None = typer.Option(None, "--context", help="Kubeconfig context to use."),
46
+ llm: str | None = typer.Option(None, "--llm-provider", help="anthropic | openai | openrouter | ollama | none"),
47
+ model: str | None = typer.Option(None, "--model", help="LLM model name."),
48
+ prometheus: str | None = typer.Option(None, "--prometheus", help="Prometheus URL for usage history."),
49
+ ) -> None:
50
+ state.settings = load_settings(kubeconfig=kubeconfig, context=context, llm_provider=llm, llm_model=model,
51
+ prometheus_url=prometheus)
52
+
53
+
54
+ def _fail(msg: str, code: int = 1) -> NoReturn:
55
+ err.print(Text(f"error: {msg}", style="bold red"))
56
+ raise typer.Exit(code)
57
+
58
+
59
+ def _snapshot(namespace: str | None, from_file: str | None = None, with_logs: bool = True):
60
+ from kubesift.cluster.snapshot import Snapshot
61
+
62
+ if from_file:
63
+ data = json.loads(Path(from_file).read_text(encoding="utf-8"))
64
+ snap = Snapshot.from_dict(data)
65
+ if namespace:
66
+ snap.namespace = namespace
67
+ return snap
68
+ from kubesift.analysis.engine import snapshot_for
69
+
70
+ try:
71
+ with err.status("Reading cluster state…"):
72
+ return snapshot_for(state.settings, namespace, with_logs=with_logs)
73
+ except Exception as exc: # kubeconfig missing, cluster unreachable
74
+ _fail(f"cannot connect to the cluster: {exc}")
75
+
76
+
77
+ def _store():
78
+ from kubesift.store import open_store
79
+
80
+ try:
81
+ return open_store(state.settings)
82
+ except Exception:
83
+ return None
84
+
85
+
86
+ def _exit_on(report_findings: list, fail_on: str | None) -> None:
87
+ if not fail_on:
88
+ return
89
+ threshold = Severity.parse(fail_on).rank
90
+ if any(f.severity.rank >= threshold for f in report_findings):
91
+ raise typer.Exit(2)
92
+
93
+
94
+ def _emit(report: Report, output: str, risks: bool, verbose: bool) -> None:
95
+ from kubesift.report import print_report, to_markdown
96
+
97
+ if output == "json":
98
+ print(report.model_dump_json(indent=2))
99
+ elif output in ("md", "markdown"):
100
+ print(to_markdown(report))
101
+ else:
102
+ print_report(console, report, show_risks=risks, verbose=verbose)
103
+
104
+
105
+ NS = typer.Option(None, "--namespace", "-n", help="Only this namespace (default: all namespaces).")
106
+ OUT = typer.Option("text", "--output", "-o", help="text | json | markdown")
107
+ LLM = typer.Option(True, "--llm/--no-llm", help="Use the configured LLM to explain findings.")
108
+ FAIL = typer.Option(None, "--fail-on", help="Exit 2 if a finding at this severity or above exists.")
109
+ FROM = typer.Option(None, "--from", help="Analyse a saved snapshot file instead of the live cluster.")
110
+
111
+
112
+ @app.command()
113
+ def diagnose(
114
+ namespace: str | None = NS,
115
+ output: str = OUT,
116
+ llm: bool = LLM,
117
+ risks: bool = typer.Option(False, "--risks", help="List configuration risks, not just a count."),
118
+ verbose: bool = typer.Option(False, "--verbose", "-v", help="Show evidence, fixes and recent changes."),
119
+ since: str = typer.Option("6h", "--since", help="How far back to look for changes."),
120
+ fail_on: str | None = FAIL,
121
+ from_file: str | None = FROM,
122
+ ) -> None:
123
+ """Scan the cluster, group problems into incidents and explain the most likely causes."""
124
+ from kubesift.analysis.engine import investigate
125
+ from kubesift.util import parse_duration
126
+
127
+ snap = _snapshot(namespace, from_file)
128
+ store = _store()
129
+ with err.status("Analysing…"):
130
+ report = investigate(state.settings, snap, use_llm=llm, window=parse_duration(since), store=store)
131
+ if store:
132
+ store.save_report(report, retention_days=state.settings.history_days)
133
+ _emit(report, output, risks, verbose)
134
+ _exit_on(report.findings, fail_on)
135
+
136
+
137
+ @app.command()
138
+ def audit(
139
+ namespace: str | None = NS,
140
+ output: str = OUT,
141
+ fail_on: str | None = FAIL,
142
+ from_file: str | None = FROM,
143
+ ) -> None:
144
+ """Production-readiness review: reliability, security, resources and upgrade risks."""
145
+ from kubesift.analysis.engine import investigate
146
+
147
+ snap = _snapshot(namespace, from_file, with_logs=False)
148
+ report = investigate(state.settings, snap, use_llm=False)
149
+ report.findings = [f for f in report.findings if f.kind == "risk"]
150
+ report.incidents = []
151
+ report.diagnosis = None
152
+ if output == "text":
153
+ from kubesift.report import print_findings
154
+ print_findings(console, report.findings, title=f"Audit: {report.cluster}")
155
+ else:
156
+ _emit(report, output, True, False)
157
+ _exit_on(report.findings, fail_on)
158
+
159
+
160
+ @app.command()
161
+ def ask(
162
+ question: list[str] = typer.Argument(..., help="Your question in plain English."),
163
+ namespace: str | None = NS,
164
+ output: str = OUT,
165
+ llm: bool = LLM,
166
+ from_file: str | None = FROM,
167
+ ) -> None:
168
+ """Ask a question: "why is checkout failing?", "is payments ready for production?"."""
169
+ from kubesift.analysis.engine import ask as do_ask
170
+ from kubesift.analysis.engine import mentioned_namespace
171
+
172
+ q = " ".join(question)
173
+ snap = _snapshot(namespace, from_file)
174
+ if not namespace:
175
+ ns = mentioned_namespace(q, [n.get("metadata", {}).get("name", "") for n in snap.all("namespaces")])
176
+ if ns:
177
+ snap.namespace = ns
178
+ with err.status("Thinking…"):
179
+ report, answer = do_ask(state.settings, snap, q, use_llm=llm, store=_store())
180
+ if output == "json":
181
+ print(json.dumps({"answer": answer, "report": report.model_dump(mode="json")}, indent=2, default=str))
182
+ return
183
+ console.print(Text(f"Q: {q}", style="bold"))
184
+ console.print(Text(answer["answer"]))
185
+ console.print(Text(f"confidence {answer['confidence']}% · {answer.get('generated_by')}", style="dim"))
186
+ for c in answer.get("commands") or []:
187
+ console.print(Text(f"$ {c}", style="cyan"))
188
+ for fu in answer.get("follow_up") or []:
189
+ console.print(Text(f"→ {fu}", style="green"))
190
+ if report.findings:
191
+ from kubesift.report import print_findings
192
+ print_findings(console, report.findings, title="Supporting findings")
193
+
194
+
195
+ @app.command()
196
+ def changes(
197
+ namespace: str | None = NS,
198
+ since: str = typer.Option("24h", "--since", help="Window, e.g. 30m, 6h, 2d."),
199
+ output: str = OUT,
200
+ from_file: str | None = FROM,
201
+ ) -> None:
202
+ """What changed recently: rollouts, config edits, Helm upgrades, Argo CD syncs, scaling, nodes."""
203
+ from kubesift.analysis.changes import detect_changes
204
+ from kubesift.report import print_changes
205
+ from kubesift.util import parse_duration
206
+
207
+ snap = _snapshot(namespace, from_file, with_logs=False)
208
+ items = detect_changes(snap, parse_duration(since))
209
+ if output == "json":
210
+ print(json.dumps([c.model_dump(mode="json") for c in items], indent=2))
211
+ else:
212
+ print_changes(console, items, title=f"Changes in the last {since}")
213
+
214
+
215
+ @app.command()
216
+ def explain(
217
+ resource: str = typer.Argument(..., help="kind/name, e.g. deploy/checkout or pod/web-abc"),
218
+ namespace: str = typer.Option("default", "--namespace", "-n"),
219
+ output: str = OUT,
220
+ from_file: str | None = FROM,
221
+ ) -> None:
222
+ """Everything about one resource: status, pods, events, logs, findings and changes."""
223
+ from kubesift.analysis.engine import explain_resource
224
+
225
+ if "/" not in resource:
226
+ _fail("use kind/name, e.g. deploy/checkout")
227
+ kind, name = resource.split("/", 1)
228
+ snap = _snapshot(namespace, from_file)
229
+ data = explain_resource(state.settings, snap, kind, None if kind.lower() in ("node", "no") else namespace, name)
230
+ if output == "json" or "error" in data:
231
+ print(json.dumps(data, indent=2, default=str))
232
+ if "error" in data:
233
+ raise typer.Exit(1)
234
+ return
235
+ import yaml
236
+ r = data["resource"]
237
+ console.rule(f"{r['kind']}/{r['name']}" + (f" ({r['namespace']})" if r.get("namespace") else ""))
238
+ console.print(yaml.safe_dump({k: v for k, v in r.items() if k not in ("events", "logs")}, sort_keys=False))
239
+ for e in r.get("events") or []:
240
+ console.print(Text(e, style="yellow" if "Warning" in e else "dim"))
241
+ for p in data["pods"]:
242
+ console.print(Text(f"pod {p['name']}: {p.get('phase')} " + ", ".join(
243
+ f"{c['name']}={c['state']}{'/' + c['reason'] if c.get('reason') else ''} restarts={c['restarts']}"
244
+ for c in p.get("containers") or []), style="bold"))
245
+ from kubesift.models import Finding
246
+ from kubesift.report import print_findings
247
+ print_findings(console, [Finding.model_validate(f) for f in data["findings"]], title="Findings")
248
+
249
+
250
+ @app.command()
251
+ def lint(
252
+ paths: list[str] = typer.Argument(..., help="Files, directories, Helm charts, Kustomize dirs, or - for stdin."),
253
+ target_version: str | None = typer.Option(None, "--target-version", "-t", help="Kubernetes version to check against, e.g. 1.36"),
254
+ values: list[str] = typer.Option([], "--values", "-f", help="Helm values files."),
255
+ output: str = typer.Option("text", "--output", "-o", help="text | json | sarif | markdown"),
256
+ fail_on: str | None = typer.Option("high", "--fail-on", help="Exit 2 at or above this severity (none to disable)."),
257
+ ) -> None:
258
+ """Check manifests before they ship (CI / pre-commit). No cluster needed."""
259
+ from kubesift.lint import LintError
260
+ from kubesift.lint import lint as do_lint
261
+ from kubesift.report import print_findings, to_sarif
262
+
263
+ try:
264
+ findings = do_lint(paths, state.settings, target_version=target_version, values=values)
265
+ except LintError as exc:
266
+ _fail(str(exc))
267
+ if output == "sarif":
268
+ print(to_sarif(findings))
269
+ elif output == "json":
270
+ print(json.dumps([f.model_dump(mode="json") for f in findings], indent=2))
271
+ elif output in ("md", "markdown"):
272
+ print("| Severity | Check | Resource | Source | Detail |\n|---|---|---|---|---|")
273
+ for f in findings:
274
+ print(f"| {f.severity.value} | {f.check} | `{f.resource}` | {f.source or ''} | {f.message} |")
275
+ else:
276
+ print_findings(console, findings, title="Lint results")
277
+ _exit_on(findings, None if (fail_on or "").lower() == "none" else fail_on)
278
+
279
+
280
+ @app.command()
281
+ def cost(
282
+ namespace: str | None = NS,
283
+ output: str = OUT,
284
+ from_file: str | None = FROM,
285
+ ) -> None:
286
+ """Right-sizing and waste: over-requested CPU/memory, idle GPUs, unused volumes and load balancers."""
287
+ from kubesift.cost import cost_report
288
+
289
+ snap = _snapshot(namespace, from_file, with_logs=False)
290
+ data = cost_report(snap, state.settings)
291
+ if output == "json":
292
+ print(json.dumps(data, indent=2))
293
+ return
294
+ c = data["cluster"]
295
+ console.print(Text(f"{c['nodes']} nodes · {c['cpu']} CPU · {c['memory']} memory · "
296
+ f"~${c['monthly_compute_estimate']:,.0f}/month compute (list prices)", style="bold"))
297
+ console.print(Text(f"usage source: {data['source']}", style="dim"))
298
+ t = Table(title="Right-sizing", expand=True)
299
+ for col in ("Workload", "Container", "CPU req → used → suggest", "Memory req → used → suggest", "$/month saved"):
300
+ t.add_column(col)
301
+ for i in data["rightsizing"][:25]:
302
+ t.add_row(i["workload"], i["container"], f"{i['cpu_request_h']} → {i['cpu_used_h']} → {i['recommend_cpu']}",
303
+ f"{i['mem_request_h']} → {i['mem_used_h']} → {i['recommend_memory']}" + (f"\n{i['note']}" if i["note"] else ""),
304
+ f"{i['monthly_savings']:,.2f}")
305
+ console.print(t)
306
+ if data["waste"]:
307
+ w = Table(title="Waste", expand=True)
308
+ for col in ("Type", "Resource", "Detail", "$/month"):
309
+ w.add_column(col)
310
+ for x in data["waste"]:
311
+ w.add_row(x["type"], x["resource"], x["detail"], f"{x['monthly_cost']:,.2f}")
312
+ console.print(w)
313
+ console.print(Text(f"Potential savings: ~${data['totals']['monthly_savings']:,.0f}/month", style="bold green"))
314
+ for warning in data["warnings"]:
315
+ console.print(Text(f"! {warning}", style="yellow"))
316
+
317
+
318
+ @app.command("upgrade-check")
319
+ def upgrade_check(
320
+ target: str = typer.Option(..., "--target", "-t", help="Target Kubernetes version, e.g. 1.36"),
321
+ output: str = OUT,
322
+ from_file: str | None = FROM,
323
+ ) -> None:
324
+ """What will break when you upgrade: removed APIs, blocking PDBs, node skew, retired components."""
325
+ from kubesift.upgrade import upgrade_report
326
+
327
+ snap = _snapshot(None, from_file, with_logs=False)
328
+ try:
329
+ data = upgrade_report(snap, state.settings, target)
330
+ except ValueError as exc:
331
+ _fail(str(exc))
332
+ if output == "json":
333
+ print(json.dumps(data, indent=2, default=str))
334
+ return
335
+ ok = data["ready"]
336
+ console.print(Text(f"{data['current']} → {data['target']}: " + ("no blockers found" if ok else
337
+ f"{len(data['blockers'])} blocker(s)"),
338
+ style="bold green" if ok else "bold red"))
339
+ from kubesift.models import Finding
340
+ from kubesift.report import print_findings
341
+ if data["blockers"]:
342
+ print_findings(console, [Finding.model_validate(f) for f in data["blockers"]], title="Blockers")
343
+ if data["warnings"]:
344
+ print_findings(console, [Finding.model_validate(f) for f in data["warnings"]], title="Warnings")
345
+ for n in data["notes"]:
346
+ console.print(Text(f"• {n}", style="yellow"))
347
+ for s in data["steps"]:
348
+ console.print(Text(f"→ {s}", style="dim"))
349
+ if not ok:
350
+ raise typer.Exit(2)
351
+
352
+
353
+ @app.command()
354
+ def fix(
355
+ action: str = typer.Argument(..., help="restart | rollback | scale | delete-pod"),
356
+ resource: str = typer.Argument(..., help="kind/name, e.g. deployment/checkout or pod/web-abc"),
357
+ namespace: str = typer.Option("default", "--namespace", "-n"),
358
+ replicas: int | None = typer.Option(None, "--replicas"),
359
+ yes: bool = typer.Option(False, "--yes", "-y", help="Apply after a successful dry run without asking."),
360
+ dry_run: bool = typer.Option(False, "--dry-run", help="Only run the server-side dry run."),
361
+ ) -> None:
362
+ """Apply a guarded fix: shows the plan, runs a server-side dry run, then asks before changing anything."""
363
+ from kubesift.cluster.client import KubeClient, KubeError
364
+ from kubesift.remediate import execute, plan
365
+
366
+ if "/" not in resource:
367
+ _fail("use kind/name")
368
+ kind, name = resource.split("/", 1)
369
+ if action == "delete-pod":
370
+ kind = "pod"
371
+ s = state.settings
372
+ try:
373
+ client = KubeClient(kubeconfig=s.kubeconfig, context=s.context, timeout=s.request_timeout)
374
+ p = plan(client, action, kind, namespace, name, replicas)
375
+ except (ValueError, KubeError) as exc:
376
+ _fail(str(exc))
377
+ except Exception as exc:
378
+ _fail(f"cannot connect to the cluster: {exc}")
379
+ store = _store()
380
+ console.print(Text(f"Plan: {p.description}", style="bold"))
381
+ console.print(Text(f"Equivalent: {p.kubectl}", style="cyan"))
382
+ console.print(Text(f"Cluster context: {client.context_name}", style="dim"))
383
+ try:
384
+ console.print(Text(f"Dry run: {execute(client, p, True, store)}", style="green"))
385
+ except KubeError as exc:
386
+ _fail(f"dry run failed: {exc.message}")
387
+ if dry_run:
388
+ return
389
+ if not yes and not typer.confirm("Apply this change to the cluster?", default=False):
390
+ console.print("Cancelled.")
391
+ raise typer.Exit(1)
392
+ try:
393
+ console.print(Text(f"Result: {execute(client, p, False, store)}", style="bold green"))
394
+ except KubeError as exc:
395
+ _fail(exc.message)
396
+
397
+
398
+ @snapshot_app.command("save")
399
+ def snapshot_save(
400
+ output_file: str = typer.Option("kubesift-snapshot.json", "--output", "-o"),
401
+ namespace: str | None = NS,
402
+ logs: bool = typer.Option(True, "--logs/--no-logs", help="Include redacted error lines from failing pods."),
403
+ ) -> None:
404
+ """Write a redacted snapshot (no Secret values, ConfigMap values or credentials)."""
405
+ snap = _snapshot(namespace, with_logs=logs)
406
+ Path(output_file).write_text(json.dumps(snap.to_dict(), default=str), encoding="utf-8")
407
+ console.print(f"Saved {sum(len(v) for v in snap.objects.values())} objects to {output_file}")
408
+
409
+
410
+ @app.command()
411
+ def history(report_id: str | None = typer.Argument(None), limit: int = 20, output: str = OUT) -> None:
412
+ """Past investigations, newest first. Pass an id to show one."""
413
+ store = _store()
414
+ if store is None:
415
+ _fail("history store unavailable")
416
+ if report_id:
417
+ report = store.get_report(report_id)
418
+ if report is None:
419
+ _fail(f"no report {report_id}")
420
+ _emit(report, output, True, True)
421
+ return
422
+ rows = store.list_reports(limit)
423
+ if output == "json":
424
+ print(json.dumps(rows, indent=2))
425
+ return
426
+ t = Table(title="History")
427
+ for col in ("ID", "When (UTC)", "Cluster", "Namespace", "Crit/High", "Summary"):
428
+ t.add_column(col)
429
+ for r in rows:
430
+ c = r["counts"]
431
+ t.add_row(r["id"], r["created"][:16].replace("T", " "), r["cluster"] or "", r["namespace"] or "all",
432
+ f"{c.get('critical', 0)}/{c.get('high', 0)}", (r["question"] or r["summary"] or "")[:80])
433
+ console.print(t)
434
+
435
+
436
+ @note_app.command("add")
437
+ def note_add(
438
+ check_id: str = typer.Argument(..., help="Check id, e.g. pod-oomkilled"),
439
+ note: str = typer.Argument(..., help="What fixed it / what to know"),
440
+ target: str | None = typer.Option(None, "--target", help="Limit to a resource, e.g. Deployment/shop/checkout"),
441
+ author: str | None = typer.Option(None, "--author"),
442
+ ) -> None:
443
+ """Record a fix. It is shown next to matching findings from now on."""
444
+ from kubesift.checks import REGISTRY
445
+
446
+ if check_id not in REGISTRY:
447
+ _fail(f"unknown check {check_id}; see `kubesift checks`")
448
+ store = _store()
449
+ if store is None:
450
+ _fail("store unavailable")
451
+ store.add_note(check_id, note, target, author)
452
+ console.print("Saved.")
453
+
454
+
455
+ @note_app.command("list")
456
+ def note_list(check_id: str | None = typer.Argument(None)) -> None:
457
+ store = _store()
458
+ for n in (store.list_notes(check_id) if store else []):
459
+ console.print(f"[{n['id']}] {n['created'][:10]} {n['check_id']} {n['target'] or ''}: {n['note']}")
460
+
461
+
462
+ @app.command("checks")
463
+ def list_checks(output: str = OUT) -> None:
464
+ """List every check with its severity and what it detects."""
465
+ from kubesift.checks import REGISTRY
466
+
467
+ if output == "json":
468
+ print(json.dumps([{"id": c.id, "title": c.title, "category": c.category.value, "severity": c.severity.value,
469
+ "type": "risk" if c.risk else "problem", "works_offline": not c.live_only,
470
+ "description": c.description} for c in REGISTRY.values()], indent=2))
471
+ return
472
+ t = Table(title=f"{len(REGISTRY)} checks", expand=True)
473
+ for col in ("ID", "Category", "Severity", "Type", "Lint", "Detects"):
474
+ t.add_column(col)
475
+ for c in sorted(REGISTRY.values(), key=lambda c: (c.category.value, c.id)):
476
+ t.add_row(c.id, c.category.value, c.severity.value, "risk" if c.risk else "problem",
477
+ "" if c.live_only else "✓", c.description)
478
+ console.print(t)
479
+
480
+
481
+ @app.command()
482
+ def contexts() -> None:
483
+ """List kubeconfig contexts."""
484
+ from kubesift.cluster.client import list_contexts
485
+
486
+ try:
487
+ items, current = list_contexts(state.settings.kubeconfig)
488
+ except Exception as exc:
489
+ _fail(f"cannot read kubeconfig: {exc}")
490
+ for c in items:
491
+ mark = "*" if c["name"] == current else " "
492
+ console.print(f"{mark} {c['name']} (cluster {c['cluster']})")
493
+
494
+
495
+ @app.command()
496
+ def doctor() -> None:
497
+ """Check connectivity, permissions, metrics and LLM configuration."""
498
+ from kubesift.cluster.client import KubeClient
499
+ from kubesift.cluster.snapshot import KINDS
500
+
501
+ s = state.settings
502
+ ok = True
503
+
504
+ def line(good: bool | None, text: str) -> None:
505
+ mark = {True: "[green]✓[/]", False: "[red]✗[/]", None: "[yellow]![/]"}[good]
506
+ console.print(f"{mark} {text}")
507
+
508
+ try:
509
+ client = KubeClient(kubeconfig=s.kubeconfig, context=s.context, timeout=s.request_timeout)
510
+ version = client.server_version()
511
+ line(bool(version), f"cluster {client.context_name}: Kubernetes {version or 'unreachable'}")
512
+ ok &= bool(version)
513
+ except Exception as exc:
514
+ line(False, f"kubeconfig/cluster: {exc}")
515
+ raise typer.Exit(1) from None
516
+ if version:
517
+ missing = []
518
+ for key, _, prefix, plural, _, optional in KINDS:
519
+ if optional and key != "secrets":
520
+ continue
521
+ try:
522
+ review = client.request("POST", "/apis/authorization.k8s.io/v1/selfsubjectaccessreviews", body={
523
+ "apiVersion": "authorization.k8s.io/v1", "kind": "SelfSubjectAccessReview",
524
+ "spec": {"resourceAttributes": {"verb": "list", "resource": plural,
525
+ "group": "" if prefix == "/api/v1" else prefix.split("/")[2]}}})
526
+ if not (review.get("status") or {}).get("allowed"):
527
+ missing.append(plural)
528
+ except Exception:
529
+ missing.append(plural)
530
+ line(not missing or None, "read permissions" + (f": cannot list {', '.join(missing)}" if missing else ": complete"))
531
+ try:
532
+ client.get("/apis/metrics.k8s.io/v1beta1/nodes")
533
+ line(True, "metrics-server available (cost and HPA checks)")
534
+ except Exception:
535
+ line(None, "metrics-server not found: cost report and right-sizing will be limited")
536
+ provider = s.resolved_provider()
537
+ if provider == "none":
538
+ line(None, "no LLM configured: rule-based diagnosis only (set ANTHROPIC_API_KEY, OPENAI_API_KEY, "
539
+ "OPENROUTER_API_KEY or KUBESIFT_LLM_PROVIDER=ollama)")
540
+ else:
541
+ line(True, f"LLM: {provider} / {s.resolved_model()}")
542
+ line(True if s.prometheus_url else None, f"Prometheus: {s.prometheus_url or 'not configured (optional)'}")
543
+ if not ok:
544
+ raise typer.Exit(1)
545
+
546
+
547
+ @app.command()
548
+ def serve(
549
+ host: str = typer.Option("127.0.0.1", "--host"),
550
+ port: int = typer.Option(8080, "--port"),
551
+ ) -> None:
552
+ """Run the web dashboard and REST API (set KUBESIFT_API_TOKEN when exposing it)."""
553
+ try:
554
+ import uvicorn
555
+
556
+ from kubesift.server.app import create_app
557
+ except ImportError:
558
+ _fail("install the server extra: pip install 'kubesift[server]'")
559
+ s = state.settings
560
+ if host not in ("127.0.0.1", "localhost") and not s.api_token:
561
+ _fail("refusing to listen on a non-local address without KUBESIFT_API_TOKEN")
562
+ import logging
563
+ logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
564
+ uvicorn.run(create_app(s), host=host, port=port, log_level="info")
565
+
566
+
567
+ @app.command()
568
+ def mcp(
569
+ transport: str = typer.Option("stdio", "--transport", help="stdio | streamable-http"),
570
+ host: str = typer.Option("127.0.0.1", "--host"),
571
+ port: int = typer.Option(8765, "--port"),
572
+ ) -> None:
573
+ """Run as an MCP server so AI assistants (Claude, Cursor, VS Code…) can investigate the cluster."""
574
+ try:
575
+ from kubesift.mcp_server import build_server
576
+ except ImportError:
577
+ _fail("install the MCP extra: pip install 'kubesift[mcp]'")
578
+ s = state.settings
579
+ if transport == "stdio":
580
+ build_server(s).run("stdio")
581
+ return
582
+ if host not in ("127.0.0.1", "localhost") and not s.api_token:
583
+ _fail("refusing to serve MCP on a non-local address without KUBESIFT_API_TOKEN")
584
+ import uvicorn
585
+
586
+ from kubesift.mcp_server import build_http_app
587
+ _, http_app = build_http_app(s)
588
+ err.print(f"MCP endpoint: http://{host}:{port}/mcp" + (" (bearer token required)" if s.api_token else ""))
589
+ uvicorn.run(http_app, host=host, port=port, log_level="warning")
590
+
591
+
592
+ @app.command()
593
+ def version() -> None:
594
+ """Print the version."""
595
+ console.print(f"kubesift {__version__}")
596
+
597
+
598
+ @app.command()
599
+ def preflight(
600
+ paths: list[str] = typer.Argument(..., help="Manifests, Helm chart or Kustomize dir, or - for stdin."),
601
+ namespace: str = typer.Option("default", "--namespace", "-n", help="Namespace for objects without one."),
602
+ values: list[str] = typer.Option([], "--values", "-f", help="Helm values files."),
603
+ server_dry_run: bool = typer.Option(False, "--server-dry-run", help="Also ask the API server (webhooks, Pod Security, quota)."),
604
+ check_images: bool = typer.Option(False, "--check-images", help="Check that image tags exist in their registries."),
605
+ output: str = typer.Option("text", "--output", "-o", help="text | json | markdown"),
606
+ fail_on: str | None = typer.Option("high", "--fail-on", help="Exit 2 at or above this severity (none to disable)."),
607
+ from_file: str | None = FROM,
608
+ ) -> None:
609
+ """Check a change against the LIVE cluster before deploying: missing secrets, capacity, risky diffs, OOM risk."""
610
+ from kubesift.cluster.client import KubeClient
611
+ from kubesift.lint import LintError, load_documents
612
+ from kubesift.preflight import preflight as run_preflight
613
+
614
+ try:
615
+ docs = load_documents(paths, values)
616
+ except LintError as exc:
617
+ _fail(str(exc))
618
+ snap = _snapshot(None, from_file, with_logs=False)
619
+ s = state.settings
620
+ client = KubeClient(kubeconfig=s.kubeconfig, context=s.context, timeout=s.request_timeout) if server_dry_run else None
621
+ with err.status("Comparing with the live cluster…"):
622
+ res = run_preflight(docs, snap, s, default_namespace=namespace, client=client,
623
+ server_dry_run=server_dry_run, check_images=check_images)
624
+ if output == "json":
625
+ print(json.dumps(res.to_dict(), indent=2, default=str))
626
+ elif output in ("md", "markdown"):
627
+ print(_preflight_markdown(res))
628
+ else:
629
+ from kubesift.report import print_findings
630
+ console.print(Text(f"Preflight against {res.target} ({res.server_version or '?'})", style="bold"))
631
+ for c in res.changes:
632
+ if c["action"] != "unchanged":
633
+ detail = f": {'; '.join(c['details'][:4])}" if c["details"] else ""
634
+ console.print(Text(f" {c['action']:7} {c['resource']}{detail}",
635
+ style="cyan" if c["action"] == "create" else "magenta"))
636
+ print_findings(console, res.findings, title="Preflight findings")
637
+ _exit_on(res.findings, None if (fail_on or "").lower() == "none" else fail_on)
638
+
639
+
640
+ def _preflight_markdown(res: Any) -> str:
641
+ blockers = [f for f in res.findings if f.severity.rank >= 3]
642
+ verdict = f"❌ {len(blockers)} blocker(s)" if blockers else "✅ no blockers"
643
+ lines = [f"### KubeSift preflight: {verdict}",
644
+ f"Target cluster `{res.target}` ({res.server_version or 'unknown version'})", ""]
645
+ changed = [c for c in res.changes if c["action"] != "unchanged"]
646
+ if changed:
647
+ lines += ["**Changes**", ""]
648
+ for c in changed:
649
+ detail = f" — {'; '.join(c['details'][:4])}" if c["details"] else ""
650
+ lines.append(f"- `{c['action']}` {c['resource']}{detail}")
651
+ lines.append("")
652
+ if res.findings:
653
+ lines += ["| Severity | Check | Resource | Finding |", "|---|---|---|---|"]
654
+ lines += [f"| {f.severity.value} | {f.check} | `{f.resource}` | {f.message.replace('|', '/')} |"
655
+ for f in res.findings]
656
+ return "\n".join(lines)
657
+
658
+
659
+ @app.command()
660
+ def diff(
661
+ since: str | None = typer.Option(None, "--since", help="Compare now with the cluster as it was this long ago (e.g. 2h)."),
662
+ from_file: str | None = typer.Option(None, "--from", help="Earlier snapshot file (from `snapshot save`)."),
663
+ to_file: str | None = typer.Option(None, "--to", help="Later snapshot file (default: live cluster)."),
664
+ namespace: str | None = NS,
665
+ output: str = OUT,
666
+ ) -> None:
667
+ """Time travel: what is different between two moments (stored history or snapshot files)."""
668
+ from kubesift.cluster.snapshot import Snapshot
669
+ from kubesift.timetravel import diff as do_diff
670
+ from kubesift.timetravel import digest
671
+ from kubesift.util import now, parse_duration
672
+
673
+ if to_file:
674
+ later = Snapshot.from_dict(json.loads(Path(to_file).read_text(encoding="utf-8")))
675
+ else:
676
+ later = _snapshot(namespace, with_logs=False)
677
+ if from_file:
678
+ earlier = digest(Snapshot.from_dict(json.loads(Path(from_file).read_text(encoding="utf-8"))))
679
+ elif since:
680
+ store = _store()
681
+ earlier = store.digest_before(later.context, now() - parse_duration(since)) if store else None
682
+ if earlier is None:
683
+ _fail(f"no stored history for {later.context} from {since} ago. History is recorded by "
684
+ "`kubesift snapshot record` and by the in-cluster service's background scans.")
685
+ else:
686
+ _fail("use --since 2h (stored history) or --from snapshot.json")
687
+ current = digest(later)
688
+ items = do_diff(earlier, current)
689
+ if namespace:
690
+ items = [i for i in items if f"/{namespace}/" in i["resource"] or i["kind"] == "Node"]
691
+ if output == "json":
692
+ print(json.dumps({"from": earlier.get("time"), "to": current.get("time"), "changes": items}, indent=2))
693
+ return
694
+ console.print(Text(f"{str(earlier.get('time', '?'))[:16]} → {str(current.get('time', '?'))[:16]} UTC · "
695
+ f"{len(items)} difference(s)", style="bold"))
696
+ style = {"added": "green", "removed": "red", "changed": "yellow"}
697
+ for i in items:
698
+ console.print(Text(f" {i['change']:8} {i['resource']}", style=style[i["change"]]))
699
+ for d in i["details"][:6]:
700
+ console.print(Text(f" {d}", style="dim"))
701
+
702
+
703
+ @snapshot_app.command("record")
704
+ def snapshot_record(namespace: str | None = NS) -> None:
705
+ """Store a compact digest of the cluster now, for `kubesift diff --since` later."""
706
+ from kubesift.timetravel import digest
707
+
708
+ snap = _snapshot(namespace, with_logs=False)
709
+ store = _store()
710
+ if store is None:
711
+ _fail("history store unavailable")
712
+ stored = store.save_digest(digest(snap))
713
+ console.print("Recorded." if stored else "Nothing changed since the last record.")
714
+
715
+
716
+ @app.command()
717
+ def postmortem(
718
+ namespace: str | None = NS,
719
+ since: str = typer.Option("24h", "--since", help="How far back the incident window goes."),
720
+ report_id: str | None = typer.Option(None, "--report", help="Build from a stored investigation instead of now."),
721
+ output: str = typer.Option("markdown", "--output", "-o", help="markdown | json"),
722
+ llm: bool = LLM,
723
+ from_file: str | None = FROM,
724
+ ) -> None:
725
+ """Draft a blameless postmortem: impact, timeline, root cause, triggering change, action items."""
726
+ from kubesift.analysis.engine import investigate
727
+ from kubesift.postmortem import build, to_markdown
728
+ from kubesift.util import parse_duration
729
+
730
+ store = _store()
731
+ snap = None
732
+ if report_id:
733
+ report = store.get_report(report_id) if store else None
734
+ if report is None:
735
+ _fail(f"no report {report_id}")
736
+ else:
737
+ snap = _snapshot(namespace, from_file)
738
+ report = investigate(state.settings, snap, use_llm=llm, window=parse_duration(since), store=store)
739
+ pm = build(report, snap, store.list_audit(200) if store else [], state.settings if llm else None)
740
+ print(json.dumps(pm, indent=2) if output == "json" else to_markdown(pm))
741
+
742
+
743
+ @drill_app.command("list")
744
+ def drill_list() -> None:
745
+ """Available drills."""
746
+ from kubesift.drills import DRILLS
747
+
748
+ t = Table(title="Drills")
749
+ for col in ("ID", "Scenario", "What the on-call engineer sees"):
750
+ t.add_column(col)
751
+ for d in DRILLS.values():
752
+ t.add_row(d.id, d.title, d.story)
753
+ console.print(t)
754
+
755
+
756
+ @drill_app.command("start")
757
+ def drill_start(
758
+ drill_id: str = typer.Argument(..., help="Drill id from `kubesift drill list`."),
759
+ namespace: str = typer.Option("kubesift-drill", "--namespace", "-n"),
760
+ yes: bool = typer.Option(False, "--yes", "-y"),
761
+ ) -> None:
762
+ """Break a drill namespace on purpose. Only touches namespaces labelled kubesift.dev/drill=true."""
763
+ from kubesift.cluster.client import KubeClient, KubeError
764
+ from kubesift.drills import DRILLS, start
765
+
766
+ if drill_id not in DRILLS:
767
+ _fail(f"unknown drill {drill_id}; see `kubesift drill list`")
768
+ s = state.settings
769
+ client = KubeClient(kubeconfig=s.kubeconfig, context=s.context, timeout=s.request_timeout)
770
+ if not yes and not typer.confirm(f"Create broken workloads in namespace '{namespace}' on {client.context_name}?"):
771
+ raise typer.Exit(1)
772
+ try:
773
+ with err.status("Setting up the incident…"):
774
+ d = start(client, drill_id, namespace)
775
+ except (KubeError, ValueError) as exc:
776
+ _fail(str(exc))
777
+ console.print(Text(f"Incident started: {d.title}", style="bold red"))
778
+ console.print(d.story)
779
+ console.print(Text(f"Investigate it yourself first. Hint: `kubesift drill hint {d.id}`. Answer: "
780
+ f"`kubesift drill reveal {d.id} -n {namespace}`. Clean up: `kubesift drill stop -n {namespace}`.",
781
+ style="dim"))
782
+
783
+
784
+ @drill_app.command("hint")
785
+ def drill_hint(drill_id: str) -> None:
786
+ """A nudge without giving the answer away."""
787
+ from kubesift.drills import DRILLS
788
+
789
+ console.print(DRILLS[drill_id].hint if drill_id in DRILLS else "unknown drill")
790
+
791
+
792
+ @drill_app.command("reveal")
793
+ def drill_reveal(drill_id: str, namespace: str = typer.Option("kubesift-drill", "--namespace", "-n")) -> None:
794
+ """Show the answer and whether KubeSift caught it."""
795
+ from kubesift.analysis.engine import investigate
796
+ from kubesift.drills import DRILLS
797
+
798
+ d = DRILLS.get(drill_id)
799
+ if d is None:
800
+ _fail("unknown drill")
801
+ report = investigate(state.settings, _snapshot(namespace), use_llm=False)
802
+ caught = [f for f in report.findings if f.check in d.expect]
803
+ console.print(Text(f"Answer: {d.answer}", style="bold green"))
804
+ if caught:
805
+ console.print(Text(f"KubeSift caught it: {caught[0].message}", style="green"))
806
+ if caught[0].related_changes:
807
+ console.print(Text(f"Triggered by: {caught[0].related_changes[0].summary}", style="magenta"))
808
+ else:
809
+ console.print(Text("KubeSift has not detected it yet (some failures take a minute or two to appear).",
810
+ style="yellow"))
811
+
812
+
813
+ @drill_app.command("stop")
814
+ def drill_stop(namespace: str = typer.Option("kubesift-drill", "--namespace", "-n")) -> None:
815
+ """Delete the drill namespace (refuses any namespace not created for drills)."""
816
+ from kubesift.cluster.client import KubeClient, KubeError
817
+ from kubesift.drills import stop
818
+
819
+ s = state.settings
820
+ try:
821
+ stop(KubeClient(kubeconfig=s.kubeconfig, context=s.context, timeout=s.request_timeout), namespace)
822
+ except (KubeError, ValueError) as exc:
823
+ _fail(str(exc))
824
+ console.print(f"Deleted drill namespace {namespace}.")
825
+
826
+
827
+ @knowledge_app.command("export")
828
+ def knowledge_export(output_file: str = typer.Option("kubesift-knowledge.yaml", "--output", "-o"),
829
+ check_id: str | None = typer.Option(None, "--check")) -> None:
830
+ """Write team notes and runbooks to a YAML pack you can review and share."""
831
+ import yaml
832
+
833
+ from kubesift.knowledge import export_pack
834
+
835
+ store = _store()
836
+ if store is None:
837
+ _fail("store unavailable")
838
+ pack = export_pack(store, state.settings.runbooks_dir, check_id)
839
+ Path(output_file).write_text(yaml.safe_dump(pack, sort_keys=False, allow_unicode=True), encoding="utf-8")
840
+ console.print(f"Exported {len(pack['notes'])} notes and {len(pack['runbooks'])} runbooks to {output_file}")
841
+
842
+
843
+ @knowledge_app.command("import")
844
+ def knowledge_import(pack_file: str) -> None:
845
+ """Add notes (and runbooks, if runbooks_dir is set) from a knowledge pack. Duplicates are skipped."""
846
+ import yaml
847
+
848
+ from kubesift.knowledge import import_pack
849
+
850
+ store = _store()
851
+ if store is None:
852
+ _fail("store unavailable")
853
+ try:
854
+ pack = yaml.safe_load(Path(pack_file).read_text(encoding="utf-8")) or {}
855
+ result = import_pack(store, pack, state.settings.runbooks_dir)
856
+ except ValueError as exc:
857
+ _fail(str(exc))
858
+ console.print(f"Added {result['notes_added']} notes, skipped {result['notes_skipped']}, "
859
+ f"wrote {result['runbooks_written']} runbooks.")
860
+
861
+
862
+ def main() -> Any:
863
+ for stream in (sys.stdout, sys.stderr): # Windows consoles default to cp1252
864
+ if (getattr(stream, "encoding", "") or "").lower().replace("-", "") != "utf8":
865
+ with contextlib.suppress(AttributeError, ValueError):
866
+ stream.reconfigure(encoding="utf-8", errors="replace") # type: ignore[attr-defined]
867
+ try:
868
+ return app()
869
+ except KeyboardInterrupt:
870
+ sys.exit(130)
871
+
872
+
873
+ if __name__ == "__main__":
874
+ main()