keywarden-ssh 0.3.0__py3-none-any.whl

keywarden/controls.py

@@ -0,0 +1,133 @@
+"""Which framework controls each check gives evidence for.
+
+This is a mapping to help an assessor, not an attestation. Keywarden does not
+claim MFA coverage: turning passwords off is not the same as requiring a second factor. A passing check is
+evidence toward a control on the hosts that were checked; it does not show the
+control is met. Requirement text is paraphrased; read the framework itself.
+"""
+
+from __future__ import annotations
+
+FRAMEWORKS = {
+    "cis": "CIS Controls v8",
+    "nist": "NIST SP 800-53 Rev. 5",
+    "pci": "PCI DSS v4.0",
+    "cip": "NERC CIP",
+}
+
+# Control names, paraphrased so the report reads without the source documents open.
+NAMES = {
+    # CIS Controls v8 safeguards
+    "cis:3.3": "Configure data access control lists",
+    "cis:3.10": "Encrypt sensitive data in transit",
+    "cis:4.1": "Establish and maintain a secure configuration process",
+    "cis:4.7": "Manage default accounts on enterprise assets and software",
+    "cis:5.1": "Establish and maintain an inventory of accounts",
+    "cis:5.2": "Use unique passwords",
+    "cis:5.3": "Disable dormant accounts",
+    "cis:5.4": "Restrict administrator privileges to dedicated administrator accounts",
+    "cis:6.1": "Establish an access granting process",
+    "cis:6.2": "Establish an access revoking process",
+    "cis:6.8": "Define and maintain role-based access control",
+    "cis:8.2": "Collect audit logs",
+    "cis:8.11": "Conduct audit log reviews",
+    # NIST SP 800-53 Rev. 5
+    "nist:AC-2": "Account Management",
+    "nist:AC-2(3)": "Account Management | Disable Accounts",
+    "nist:AC-3": "Access Enforcement",
+    "nist:AC-6": "Least Privilege",
+    "nist:AC-6(5)": "Least Privilege | Privileged Accounts",
+    "nist:AC-17": "Remote Access",
+    "nist:AU-2": "Event Logging",
+    "nist:AU-6": "Audit Record Review, Analysis, and Reporting",
+    "nist:AU-12": "Audit Record Generation",
+    "nist:CM-6": "Configuration Settings",
+    "nist:CM-7": "Least Functionality",
+    "nist:IA-2": "Identification and Authentication (Organizational Users)",
+    "nist:IA-2(5)": "Identification and Authentication | Individual Authentication with Group Authentication",
+    "nist:IA-5": "Authenticator Management",
+    "nist:IA-5(1)": "Authenticator Management | Password-based Authentication",
+    "nist:IA-5(2)": "Authenticator Management | Public Key-based Authentication",
+    "nist:SC-13": "Cryptographic Protection",
+    "nist:SC-17": "Public Key Infrastructure Certificates",
+    # PCI DSS v4.0
+    "pci:2.2.1": "Configuration standards are developed, implemented, and maintained",
+    "pci:2.2.4": "Only necessary services, protocols, and functions are enabled",
+    "pci:2.2.7": "All non-console administrative access is encrypted using strong cryptography",
+    "pci:7.2.1": "Access control model covers appropriate access by role",
+    "pci:7.2.2": "Access is assigned based on job function and least privilege",
+    "pci:7.2.4": "User accounts and access privileges are reviewed at least every six months",
+    "pci:8.2.2": "Group, shared, or generic accounts are used only when necessary and are managed",
+    "pci:8.2.5": "Access for terminated users is immediately revoked",
+    "pci:8.2.6": "Inactive user accounts are removed or disabled within 90 days",
+    "pci:8.3.1": "User access is authenticated with at least one authentication factor",
+    "pci:8.3.6": "Passwords meet minimum complexity",
+    "pci:10.2.1": "Audit logs are enabled and active for all system components",
+    "pci:10.4.1": "Audit logs are reviewed at least once daily",
+    # NERC CIP
+    "cip:CIP-004-7 R4.1": "Authorize electronic access",
+    "cip:CIP-004-7 R4.2": "Verify quarterly that individuals with active electronic access have authorization records",
+    "cip:CIP-004-7 R4.3": "Verify every 15 calendar months that user accounts and privileges are correct and necessary",
+    "cip:CIP-004-7 R5.1": "Remove the ability for unescorted access and Interactive Remote Access on termination",
+    "cip:CIP-005-7 R2.1": "Use an Intermediate System for Interactive Remote Access",
+    "cip:CIP-005-7 R2.2": "Use encryption that terminates at the Intermediate System",
+    "cip:CIP-007-6 R4.1": "Log events, including successful login attempts",
+    "cip:CIP-007-6 R5.1": "Have a method to enforce authentication of interactive user access",
+    "cip:CIP-007-6 R5.2": "Identify and inventory default or generic accounts",
+    "cip:CIP-007-6 R5.3": "Identify individuals who have authorized access to shared accounts",
+    "cip:CIP-007-6 R5.5": "Password-only authentication: length and complexity",
+}
+
+# check code -> control keys
+MAPPING: dict[str, list[str]] = {
+    "permit-root": ["cis:5.4", "nist:AC-6(5)", "nist:IA-2(5)", "pci:8.2.2", "cip:CIP-007-6 R5.2", "cip:CIP-007-6 R5.3"],
+    "root-authorized-key": ["cis:5.4", "nist:AC-6(5)", "nist:IA-2(5)", "pci:8.2.2", "cip:CIP-007-6 R5.3"],
+    "root-account": ["cis:4.7", "cis:5.2", "nist:AC-2", "nist:AC-6(5)", "nist:IA-5(1)", "pci:8.2.2", "cip:CIP-007-6 R5.2"],
+    "password-auth": ["cis:4.1", "nist:IA-2", "nist:IA-5(1)", "pci:8.3.1", "cip:CIP-007-6 R5.1", "cip:CIP-007-6 R5.5"],
+    "keyboard-interactive": ["cis:4.1", "nist:IA-2", "nist:IA-5(1)", "pci:8.3.1", "cip:CIP-007-6 R5.1"],
+    "empty-passwords": ["cis:5.2", "nist:IA-5(1)", "pci:8.3.1", "pci:8.3.6", "cip:CIP-007-6 R5.5"],
+    "auth-methods": ["cis:4.1", "nist:IA-2", "nist:IA-5(1)", "pci:8.3.1", "cip:CIP-007-6 R5.1"],
+    "pubkey-auth": ["nist:IA-5(2)", "pci:8.3.1", "cip:CIP-007-6 R5.1"],
+    "permissions": ["cis:3.3", "cis:4.1", "nist:AC-3", "nist:CM-6", "pci:2.2.1"],
+    "weak-algorithm": ["cis:3.10", "nist:IA-5(2)", "nist:SC-13", "pci:2.2.7", "cip:CIP-005-7 R2.2"],
+    "accepted-algorithms": ["cis:3.10", "nist:SC-13", "pci:2.2.7", "cip:CIP-005-7 R2.2"],
+    "ca-algorithms": ["cis:3.10", "nist:SC-13", "nist:SC-17", "pci:2.2.7"],
+    "outside-push": ["cis:5.1", "cis:6.1", "cis:6.2", "nist:AC-2", "pci:7.2.1", "pci:7.2.4", "pci:8.2.5", "cip:CIP-004-7 R4.1", "cip:CIP-004-7 R4.3"],
+    "cert-authority": ["nist:IA-5(2)", "nist:SC-17", "pci:7.2.2", "cip:CIP-004-7 R4.1"],
+    "ssh-certificate": ["nist:IA-5(2)", "nist:SC-17"],
+    "trusted-user-ca": ["nist:IA-5(2)", "nist:SC-17", "cip:CIP-004-7 R4.1"],
+    "revoked-keys": ["nist:IA-5(2)", "nist:SC-17", "pci:8.2.5", "cip:CIP-004-7 R5.1"],
+    "authorized-keys-command": ["cis:4.1", "nist:AC-2", "nist:CM-6", "pci:2.2.1"],
+    "authorized-keys-file": ["cis:4.1", "nist:CM-6", "pci:2.2.1"],
+    "hostbased-auth": ["cis:4.1", "nist:IA-2", "nist:AC-17", "pci:8.3.1", "cip:CIP-007-6 R5.1"],
+    "sshd-config": ["cis:4.1", "nist:CM-6", "pci:2.2.1"],
+    "match-blocks": ["cis:4.1", "nist:CM-6", "pci:2.2.1"],
+    "key-to-root": ["cis:5.4", "cis:6.8", "nist:AC-6", "nist:AC-6(5)", "pci:7.2.2", "cip:CIP-004-7 R4.3"],
+    "key-source": ["nist:AC-17", "nist:AC-6", "pci:7.2.2", "cip:CIP-005-7 R2.1"],
+    "forced-command-forwarding": ["cis:4.1", "nist:CM-7", "nist:AC-17", "pci:2.2.4"],
+    "key-environment": ["cis:4.1", "nist:CM-6", "nist:CM-7", "pci:2.2.1"],
+    "expired-key": ["nist:IA-5", "pci:8.2.6"],
+    "log-level": ["cis:8.2", "nist:AU-2", "nist:AU-12", "pci:10.2.1", "cip:CIP-007-6 R4.1"],
+    "auth-log": ["cis:8.11", "nist:AU-6", "pci:10.4.1"],
+    "stale-key": ["cis:5.3", "cis:6.2", "nist:AC-2", "nist:AC-2(3)", "nist:IA-5", "pci:7.2.4", "pci:8.2.6", "cip:CIP-004-7 R4.2", "cip:CIP-004-7 R4.3"],
+}
+
+
+def controls_for(code: str) -> list[dict]:
+    result = []
+    for key in MAPPING.get(code, []):
+        framework, control = key.split(":", 1)
+        result.append({"framework": framework, "id": control, "name": NAMES[key]})
+    return result
+
+
+def markdown_table() -> str:
+    """The table in docs/compliance.md, generated so the docs never drift from the code."""
+    lines = ["| Check | " + " | ".join(FRAMEWORKS.values()) + " |", "| --- |" + " --- |" * len(FRAMEWORKS)]
+    for code in sorted(MAPPING):
+        cells = []
+        for framework in FRAMEWORKS:
+            ids = [key.split(":", 1)[1] for key in MAPPING[code] if key.startswith(framework + ":")]
+            cells.append(", ".join(ids) or "–")
+        lines.append(f"| `{code}` | " + " | ".join(cells) + " |")
+    return "\n".join(lines)

keywarden/evidence.py

@@ -0,0 +1,207 @@
+"""An evidence report: one self-contained HTML file to hand an assessor.
+
+It records scope, who ran the check and with what visibility, each finding
+with the framework controls it bears on, the access review table, accepted
+risks, and a SHA-256 of the JSON report it was built from. No key bodies.
+"""
+
+from __future__ import annotations
+
+import getpass
+import hashlib
+import json
+import socket
+from html import escape
+
+from keywarden.controls import FRAMEWORKS, MAPPING, NAMES
+
+_RANK = {"fail": 3, "warn": 2, "accepted": 1, "pass": 0}
+_STATUS = {3: ("fail", "Checks failed"), 2: ("warn", "Checks to review"), 1: ("accepted", "Accepted risk"), 0: ("pass", "Checks passed")}
+
+
+def _hosts(document: dict) -> list[dict]:
+    return document.get("hosts") or ([document["host"]] if document.get("host") else [])
+
+
+def _operator() -> str:
+    try:
+        return f"{getpass.getuser()}@{socket.gethostname()}"
+    except Exception:
+        return "unknown"
+
+
+def control_matrix(document: dict) -> dict[str, list[dict]]:
+    """framework -> rows of {id, name, status, codes, hosts}."""
+    seen: dict[str, dict] = {}
+    for host in _hosts(document):
+        for item in host.get("findings", []):
+            for key in MAPPING.get(item.get("code", ""), []):
+                entry = seen.setdefault(key, {"rank": -1, "codes": set(), "hosts": set()})
+                rank = _RANK.get(item.get("severity"), 0)
+                entry["codes"].add(item["code"])
+                if rank > 0:
+                    entry["hosts"].add(host.get("name", "?"))
+                entry["rank"] = max(entry["rank"], rank)
+    matrix: dict[str, list[dict]] = {}
+    for framework in FRAMEWORKS:
+        rows = []
+        for key in sorted({k for codes in MAPPING.values() for k in codes if k.startswith(framework + ":")}, key=_sort_key):
+            entry = seen.get(key)
+            if entry is None:
+                status, label = "none", "Not assessed in this run"
+                codes, hosts = [], []
+            else:
+                status, label = _STATUS[entry["rank"]]
+                codes, hosts = sorted(entry["codes"]), sorted(entry["hosts"])
+            rows.append({"id": key.split(":", 1)[1], "name": NAMES[key], "status": status, "label": label, "codes": codes, "hosts": hosts})
+        matrix[framework] = rows
+    return matrix
+
+
+def _sort_key(key: str):
+    control = key.split(":", 1)[1]
+    parts = []
+    for token in control.replace("(", ".").replace(")", "").replace("-", ".").replace(" ", ".").split("."):
+        parts.append((0, int(token), "") if token.isdigit() else (1, 0, token))
+    return parts
+
+
+def render_evidence(document: dict) -> str:
+    canonical = json.dumps(document, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    digest = hashlib.sha256(canonical).hexdigest()
+    hosts = _hosts(document)
+    keys = [row for host in hosts for row in host.get("keys", [])]
+    counts = {name: sum(1 for host in hosts if host.get("posture") == name) for name in ("fail", "warn", "pass")}
+    failed_checks = sum(1 for host in hosts for item in host.get("findings", []) if item.get("severity") == "fail")
+    waivers = [(host.get("name"), item) for host in hosts for item in host.get("findings", []) if item.get("severity") == "accepted"]
+    matrix = control_matrix(document)
+    out: list[str] = []
+    add = out.append
+    add("<!doctype html><html lang='en'><head><meta charset='utf-8'><meta name='viewport' content='width=device-width, initial-scale=1'>")
+    add("<title>Keywarden evidence report</title><style>")
+    add(_CSS)
+    add("</style></head><body><main>")
+    add("<header><p class='eyebrow'>Keywarden evidence report</p><h1>SSH access and configuration</h1>")
+    add(f"<p class='lede'>{len(hosts)} host{'s' if len(hosts) != 1 else ''} checked. Generated {escape(document.get('generatedAt', ''))} by Keywarden {escape(str(document.get('version', '')))}.</p></header>")
+    add("<section><h2>Run</h2><dl class='facts'>")
+    for label, value in (
+        ("Run by", _operator()),
+        ("Generated", document.get("generatedAt", "")),
+        ("Keywarden version", document.get("version", "")),
+        ("Keys compared against", f"{len(document.get('push', []))} pushed public key fingerprint(s)"),
+        ("Key material", "Omitted. Fingerprints identify keys; no key bodies are in this report."),
+        ("Report SHA-256", digest),
+    ):
+        add(f"<dt>{escape(label)}</dt><dd>{escape(str(value))}</dd>")
+    add("</dl><p class='note'>The SHA-256 is computed over the JSON report embedded at the end of this file (keys sorted, no whitespace). Recompute it to show the findings were not edited.</p></section>")
+
+    add("<section><h2>Summary</h2><div class='tiles'>")
+    for label, value, cls in (
+        ("Hosts", len(hosts), ""),
+        ("Failing hosts", counts["fail"], "fail"),
+        ("Hosts to review", counts["warn"], "warn"),
+        ("Failed checks", failed_checks, "fail"),
+        ("Keys reaching root", sum(1 for row in keys if row.get("reach") in ("root", "root-nopasswd")), "warn"),
+        ("Stale keys", sum(1 for row in keys if row.get("usage") == "stale"), "warn"),
+    ):
+        add(f"<div class='tile {cls}'><span>{escape(label)}</span><b>{value}</b></div>")
+    add("</div></section>")
+
+    add("<section><h2>Scope</h2><table><thead><tr><th>Host</th><th>Address</th><th>Result</th><th>Read as</th><th>sshd -T</th><th>Login log</th><th>Observed</th></tr></thead><tbody>")
+    for host in hosts:
+        posture = host.get("posture", "")
+        add(
+            f"<tr><td>{escape(host.get('name', ''))}</td><td class='mono'>{escape(str(host.get('address', '')))}</td>"
+            f"<td><span class='pill {escape(posture)}'>{escape(posture)}</span></td><td>{escape(str(host.get('privilege', '–')))}</td>"
+            f"<td>{escape(str(host.get('sshdRead', '–')))}</td><td>{escape(str(host.get('authLog', '–')))}</td><td class='mono'>{escape(str(host.get('observedAt', '')))}</td></tr>"
+        )
+    add("</tbody></table><p class='note'>Read as: root, sudo, or none. Checks that could not see something are reported as warnings, never as passes.</p></section>")
+
+    add("<section><h2>Control coverage</h2><p class='note'>Each control lists the Keywarden checks that bear on it for the hosts above. A passing check is evidence toward a control, not proof that the control is met; controls also cover process and people that a host scan cannot see. Requirement names are paraphrased.</p>")
+    for framework, title in FRAMEWORKS.items():
+        add(f"<h3>{escape(title)}</h3><table><thead><tr><th>Control</th><th>Requirement</th><th>Status</th><th>Checks</th><th>Hosts with issues</th></tr></thead><tbody>")
+        for row in matrix[framework]:
+            add(
+                f"<tr><td class='mono'>{escape(row['id'])}</td><td>{escape(row['name'])}</td><td><span class='pill {row['status']}'>{escape(row['label'])}</span></td>"
+                f"<td class='mono'>{escape(', '.join(row['codes']) or '–')}</td><td>{escape(', '.join(row['hosts']) or '–')}</td></tr>"
+            )
+        add("</tbody></table>")
+    add("</section>")
+
+    add("<section><h2>Findings</h2>")
+    order = {"fail": 0, "warn": 1, "accepted": 2, "pass": 3}
+    for host in hosts:
+        items = sorted(host.get("findings", []), key=lambda item: order.get(item.get("severity"), 4))
+        add(f"<h3>{escape(host.get('name', ''))} <span class='pill {escape(host.get('posture', ''))}'>{escape(host.get('posture', ''))}</span></h3>")
+        add("<table class='findings'><thead><tr><th>Result</th><th>Check</th><th>Detail</th><th>Controls</th></tr></thead><tbody>")
+        for item in items:
+            controls = ", ".join(f"{FRAMEWORKS[c['framework']].split()[0]} {c['id']}" for c in item.get("controls", []))
+            badge = f" <span class='pill warn'>{escape(item['drift'])}</span>" if item.get("drift") else ""
+            add(
+                f"<tr><td><span class='pill {escape(item.get('severity', ''))}'>{escape(item.get('severity', ''))}</span></td>"
+                f"<td><b>{escape(item.get('title', ''))}</b>{badge}<br><span class='mono dim'>{escape(item.get('code', ''))}</span></td>"
+                f"<td class='detail'>{escape(item.get('detail', ''))}</td><td class='small'>{escape(controls or '–')}</td></tr>"
+            )
+        add("</tbody></table>")
+    add("</section>")
+
+    add("<section><h2>Access review</h2>")
+    if keys:
+        add("<table><thead><tr><th>Host</th><th>Account</th><th>Fingerprint</th><th>Reach</th><th>Usage</th><th>Last used</th><th>From</th><th>In push</th><th>Comment</th></tr></thead><tbody>")
+        for row in keys:
+            in_push = "–" if row.get("inAllow") is None else ("yes" if row["inAllow"] else "no")
+            add(
+                f"<tr><td>{escape(row['host'])}</td><td>{escape(row['account'])}</td><td class='mono'>{escape(row['fingerprint'])}</td>"
+                f"<td>{escape(row['reach'])}</td><td>{escape(row['usage'])}</td><td class='mono'>{escape((row.get('lastUsed') or '–')[:10])}</td>"
+                f"<td class='mono'>{escape(', '.join(row['options'].get('from', [])) or 'any')}</td><td>{in_push}</td><td>{escape(row.get('comment') or '–')}</td></tr>"
+            )
+        add("</tbody></table>")
+    else:
+        add("<p>No authorized keys were readable.</p>")
+    add("</section>")
+
+    add("<section><h2>Accepted risks</h2>")
+    if waivers:
+        add("<table><thead><tr><th>Host</th><th>Check</th><th>Was</th><th>Owner / ticket</th><th>Until</th><th>Reason</th></tr></thead><tbody>")
+        for name, item in waivers:
+            for waiver in item.get("waivers", []):
+                owner = " / ".join(filter(None, [waiver.get("owner"), waiver.get("ticket")]))
+                add(
+                    f"<tr><td>{escape(str(name))}</td><td class='mono'>{escape(item['code'])}</td><td>{escape(str(item.get('was', '')))}</td>"
+                    f"<td>{escape(owner)}</td><td class='mono'>{escape(waiver.get('expires', ''))}</td><td>{escape(waiver.get('reason', ''))}</td></tr>"
+                )
+        add("</tbody></table>")
+    else:
+        add("<p>No findings were accepted under a waiver in this run.</p>")
+    add("</section>")
+
+    payload = json.dumps(document, indent=1).replace("</", "<\\/")
+    add(f"<section><h2>Report data</h2><p class='note'>The JSON report this page was built from. Its SHA-256 is above.</p><script type='application/json' id='keywarden-report'>{payload}</script></section>")
+    add("<footer>Generated by Keywarden, an open-source SSH access review tool. This report maps findings to controls to help an assessment; it is not a certification.</footer>")
+    add("</main></body></html>")
+    return "".join(out)
+
+
+_CSS = """
+:root { --ink:#111827; --muted:#4b5563; --line:#e5e7eb; --bg:#f8fafc; --card:#fff; --fail:#c4001a; --warn:#b54700; --pass:#1f7a35; --acpt:#3634a3; --none:#6b7280;
+  font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; color: var(--ink); background: var(--bg); }
+body { margin: 0; } main { max-width: 1100px; margin: 0 auto; padding: 32px 20px 48px; }
+.eyebrow { text-transform: uppercase; letter-spacing: .08em; font-size: 12px; color: #0a6cff; font-weight: 600; margin: 0; }
+h1 { font-size: 28px; margin: 4px 0 6px; letter-spacing: -.02em; } h2 { font-size: 19px; margin: 32px 0 10px; } h3 { font-size: 15px; margin: 22px 0 8px; }
+.lede { color: var(--muted); margin: 0; } .note { color: var(--muted); font-size: 12.5px; max-width: 80ch; }
+section { break-inside: auto; }
+.facts { display: grid; grid-template-columns: 200px 1fr; gap: 6px 16px; background: var(--card); border: 1px solid var(--line); border-radius: 12px; padding: 14px 16px; margin: 0; }
+.facts dt { color: var(--muted); } .facts dd { margin: 0; overflow-wrap: anywhere; font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 12.5px; }
+.tiles { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 10px; }
+.tile { background: var(--card); border: 1px solid var(--line); border-radius: 12px; padding: 10px 14px; } .tile span { color: var(--muted); font-size: 12px; display: block; }
+.tile b { font-size: 24px; font-variant-numeric: tabular-nums; } .tile.fail b { color: var(--fail); } .tile.warn b { color: var(--warn); }
+table { width: 100%; border-collapse: collapse; background: var(--card); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; font-size: 12.5px; }
+th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+th { background: #f1f5f9; font-weight: 600; color: var(--muted); font-size: 12px; }
+.mono { font-family: ui-monospace, Menlo, Consolas, monospace; font-size: 12px; overflow-wrap: anywhere; } .dim { color: var(--muted); } .small { font-size: 11.5px; color: var(--muted); }
+.detail { overflow-wrap: anywhere; max-width: 520px; }
+.pill { display: inline-block; font-size: 11px; font-weight: 600; padding: 1px 8px; border-radius: 999px; border: 1px solid currentColor; white-space: nowrap; }
+.pill.fail { color: var(--fail); } .pill.warn { color: var(--warn); } .pill.pass { color: var(--pass); } .pill.accepted { color: var(--acpt); } .pill.none { color: var(--none); }
+footer { margin-top: 36px; color: var(--muted); font-size: 12px; }
+@media print { :root { background: #fff; } main { padding: 0; } table, .facts, .tile { border-color: #cbd5e1; } h2 { break-after: avoid; } tr { break-inside: avoid; } }
+"""

keywarden/inventory.py

@@ -0,0 +1,199 @@
+"""Ansible INI inventory, enough to know where to SSH. Passwords in the file are ignored."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_RANGE = re.compile(r"\[(\d+):(\d+)\]")
+_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,253}$")
+_GROUP = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.-]*$")
+_USER = re.compile(r"^[a-z_][-a-z0-9_.]*\$?$", re.IGNORECASE)
+
+# Only connection fields are kept. Passwords, become settings, and everything
+# else in the inventory are dropped as the line is read.
+_ALIASES = {
+    "ansible_host": "host",
+    "ansible_ssh_host": "host",
+    "ansible_user": "user",
+    "ansible_ssh_user": "user",
+    "ansible_port": "port",
+    "ansible_ssh_port": "port",
+    "ansible_ssh_private_key_file": "key",
+    "ansible_private_key_file": "key",
+}
+
+
+@dataclass(frozen=True)
+class InventoryHost:
+    name: str
+    address: str
+    user: str | None
+    port: int | None
+    identity_file: str | None = None
+
+    @property
+    def destination(self) -> str:
+        if self.user:
+            return f"{self.user}@{self.address}"
+        return self.address
+
+
+def _expand(token: str) -> list[str]:
+    match = _RANGE.search(token)
+    if not match:
+        return [token]
+    start, end = match.group(1), match.group(2)
+    first, last = int(start), int(end)
+    if last < first or last - first > 256:
+        raise ValueError(f"inventory range is too large: {token}")
+    width = len(start)
+    prefix, suffix = token[: match.start()], token[match.end() :]
+    return [f"{prefix}{index:0{width}d}{suffix}" for index in range(first, last + 1)]
+
+
+def _port(value: str, name: str) -> int:
+    if not value.isdigit() or not 1 <= int(value) <= 65535:
+        raise ValueError(f"{name} has a port that is not 1-65535")
+    return int(value)
+
+
+def _unquote(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+        return value[1:-1]
+    return value
+
+
+def _keep(key: str, value: str, into: dict[str, str]) -> None:
+    field = _ALIASES.get(key.strip())
+    if field:
+        into[field] = _unquote(value)
+
+
+def _looks_like_yaml(text: str, source: str | None) -> bool:
+    if source and source.lower().endswith((".yml", ".yaml", ".json")):
+        return True
+    for raw in text.splitlines():
+        line = raw.split("#", 1)[0].rstrip()
+        if not line.strip():
+            continue
+        stripped = line.strip()
+        return stripped.startswith("{") or stripped == "---" or (stripped.endswith(":") and "=" not in stripped)
+    return False
+
+
+def _ancestors(group: str, parents: dict[str, list[str]]) -> list[str]:
+    """Parent groups, farthest first, so nearer groups override them like Ansible does."""
+    levels: dict[str, int] = {}
+    frontier = [(group, 0)]
+    while frontier:
+        current, depth = frontier.pop()
+        for parent in parents.get(current, []):
+            if parent == group or levels.get(parent, -1) >= depth + 1:
+                continue
+            if depth + 1 > 64:
+                raise ValueError("inventory group nesting is too deep or circular")
+            levels[parent] = depth + 1
+            frontier.append((parent, depth + 1))
+    return sorted(levels, key=lambda name: (-levels[name], name))
+
+
+def parse_inventory(text: str, source: str | None = None) -> list[InventoryHost]:
+    if _looks_like_yaml(text, source):
+        raise ValueError(
+            "only INI inventories are supported in this release. For a YAML inventory, write an INI copy; "
+            "'ansible-inventory -i <file> --list' shows each host and its ansible_* connection vars"
+        )
+    group = "ungrouped"
+    kind = "hosts"
+    group_vars: dict[str, dict[str, str]] = {"all": {}}
+    parents: dict[str, list[str]] = {}
+    membership: dict[str, list[str]] = {}
+    inline_vars: dict[str, dict[str, str]] = {}
+    order: list[str] = []
+
+    for raw in text.splitlines():
+        line = raw.split("#", 1)[0].split(";", 1)[0].strip()
+        if not line:
+            continue
+        if line.startswith("[") and line.endswith("]"):
+            header = line[1:-1].strip()
+            if header.endswith(":vars"):
+                group = header[: -len(":vars")] or "all"
+                kind = "vars"
+                group_vars.setdefault(group, {})
+            elif header.endswith(":children"):
+                group = header[: -len(":children")]
+                kind = "children"
+                group_vars.setdefault(group, {})
+            elif ":" in header:
+                kind = "skip"
+            else:
+                group = header or "ungrouped"
+                kind = "hosts"
+                group_vars.setdefault(group, {})
+            continue
+        if kind == "skip":
+            continue
+        if kind == "vars":
+            if "=" in line:
+                key, value = line.split("=", 1)
+                _keep(key, value, group_vars.setdefault(group, {}))
+            continue
+        if kind == "children":
+            child = line.split()[0]
+            if not _GROUP.fullmatch(child):
+                raise ValueError(f"not a group name: {child}")
+            if group not in parents.setdefault(child, []):
+                parents[child].append(group)
+            continue
+        parts = line.split()
+        names = _expand(parts[0])
+        chosen: dict[str, str] = {}
+        for part in parts[1:]:
+            if "=" in part:
+                key, value = part.split("=", 1)
+                _keep(key, value, chosen)
+        for name in names:
+            if not _NAME.fullmatch(name):
+                raise ValueError(f"not a hostname: {name}")
+            if name not in inline_vars:
+                order.append(name)
+                inline_vars[name] = {}
+                membership[name] = []
+            if group not in membership[name] and group != "ungrouped":
+                membership[name].append(group)
+            inline_vars[name].update(chosen)
+
+    hosts: list[InventoryHost] = []
+    for name in order:
+        merged: dict[str, str] = dict(group_vars.get("all", {}))
+        applied: list[str] = []
+        for owned in membership[name]:
+            for parent in _ancestors(owned, parents):
+                if parent not in applied and parent != "all":
+                    applied.append(parent)
+        for owned in membership[name]:
+            if owned not in applied:
+                applied.append(owned)
+            else:
+                # A direct group beats the same group reached as a parent.
+                applied.remove(owned)
+                applied.append(owned)
+        for owned in applied:
+            merged.update(group_vars.get(owned, {}))
+        merged.update(inline_vars[name])
+        user = merged.get("user") or None
+        if user is not None and not _USER.fullmatch(user):
+            raise ValueError(f"{name} has a username that is not usable")
+        address = merged.get("host", name)
+        if not _NAME.fullmatch(address):
+            raise ValueError(f"{name} has an address that is not usable")
+        port_text = merged.get("port")
+        port = _port(port_text, name) if port_text else None
+        identity = merged.get("key") or None
+        if identity is not None and (identity.startswith("-") or "{{" in identity):
+            raise ValueError(f"{name} has a private-key path Keywarden cannot pass to ssh")
+        hosts.append(InventoryHost(name, address, user, port, identity))
+    return hosts