enroll 0.0.1__tar.gz

enroll-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

enroll-0.0.1/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: enroll
+Version: 0.0.1
+Summary: Enroll a server's running state retrospectively into Ansible
+Home-page: https://git.mig5.net/mig5/enroll
+License: GPL-3.0-or-later
+Author: Miguel Jacq
+Author-email: mig@mig5.net
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Project-URL: Repository, https://git.mig5.net/mig5/enroll
+Description-Content-Type: text/markdown
+
+# Enroll 
+
+**enroll** inspects a Linux machine (currently Debian-only) and generates Ansible roles for things it finds running on the machine.
+
+It aims to be **optimistic and noninteractive**:
+- Detects packages that have been installed
+- Detects Debian package ownership of `/etc` files using dpkg’s local database.
+- Captures config that has **changed from packaged defaults** (dpkg conffile hashes + package md5sums when available).
+- Also captures **service-relevant custom/unowned files** under `/etc/<service>/...` (e.g. drop-in config includes).
+- Defensively excludes likely secrets (path denylist + content sniff + size caps).
+- Captures non-system users that exist on the system, and their SSH public keys
+
+## Install (Poetry)
+
+```bash
+poetry install
+poetry run enroll --help
+```
+
+## Usage
+
+On the host (root recommended):
+
+### 1. Generate a bundle of state/information about the host
+
+```bash
+sudo poetry run enroll harvest --out /tmp/enroll-bundle
+```
+
+### 2. Generate Ansible manifests (roles/playbook) from that bundle
+
+```bash
+sudo poetry run enroll manifest --bundle /tmp/enroll-bundle --out /tmp/enroll-ansible
+```
+
+### Alternatively, do both steps in one shot:
+
+```bash
+sudo poetry run enroll export --bundle /tmp/enroll-bundle --out /tmp/enroll-ansible
+```
+
+Then run:
+
+```bash
+ansible-playbook -i "localhost," -c local /tmp/enroll-ansible/playbook.yml
+```
+
+
+## Notes / Safety
+
+- enroll **skips** common sensitive locations like `/etc/ssl/private/*`, `/etc/ssh/ssh_host_*`, and files that look like private keys/tokens.
+- It also skips symlinks, binary-ish files, and large files by default.
+- Review each generated role’s README before committing it anywhere.
+- It only stores the raw config files. If you want to turn these into Jinja2 templates with dynamic inventory, see my other tool https://git.mig5.net/mig5/jinjaturtle .
+
+
+## Troubleshooting
+
+- Run as root for the most complete harvest (`sudo ...`).
+

enroll-0.0.1/README.md

@@ -0,0 +1,59 @@
+# Enroll 
+
+**enroll** inspects a Linux machine (currently Debian-only) and generates Ansible roles for things it finds running on the machine.
+
+It aims to be **optimistic and noninteractive**:
+- Detects packages that have been installed
+- Detects Debian package ownership of `/etc` files using dpkg’s local database.
+- Captures config that has **changed from packaged defaults** (dpkg conffile hashes + package md5sums when available).
+- Also captures **service-relevant custom/unowned files** under `/etc/<service>/...` (e.g. drop-in config includes).
+- Defensively excludes likely secrets (path denylist + content sniff + size caps).
+- Captures non-system users that exist on the system, and their SSH public keys
+
+## Install (Poetry)
+
+```bash
+poetry install
+poetry run enroll --help
+```
+
+## Usage
+
+On the host (root recommended):
+
+### 1. Generate a bundle of state/information about the host
+
+```bash
+sudo poetry run enroll harvest --out /tmp/enroll-bundle
+```
+
+### 2. Generate Ansible manifests (roles/playbook) from that bundle
+
+```bash
+sudo poetry run enroll manifest --bundle /tmp/enroll-bundle --out /tmp/enroll-ansible
+```
+
+### Alternatively, do both steps in one shot:
+
+```bash
+sudo poetry run enroll export --bundle /tmp/enroll-bundle --out /tmp/enroll-ansible
+```
+
+Then run:
+
+```bash
+ansible-playbook -i "localhost," -c local /tmp/enroll-ansible/playbook.yml
+```
+
+
+## Notes / Safety
+
+- enroll **skips** common sensitive locations like `/etc/ssl/private/*`, `/etc/ssh/ssh_host_*`, and files that look like private keys/tokens.
+- It also skips symlinks, binary-ish files, and large files by default.
+- Review each generated role’s README before committing it anywhere.
+- It only stores the raw config files. If you want to turn these into Jinja2 templates with dynamic inventory, see my other tool https://git.mig5.net/mig5/jinjaturtle .
+
+
+## Troubleshooting
+
+- Run as root for the most complete harvest (`sudo ...`).

enroll-0.0.1/enroll/__init__.py

@@ -0,0 +1 @@
+__all__ = []

enroll-0.0.1/enroll/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

enroll-0.0.1/enroll/accounts.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Set, Tuple
+
+
+@dataclass
+class UserRecord:
+    name: str
+    uid: int
+    gid: int
+    gecos: str
+    home: str
+    shell: str
+    primary_group: str
+    supplementary_groups: List[str]
+    ssh_files: List[str]
+
+
+def parse_login_defs(path: str = "/etc/login.defs") -> Dict[str, int]:
+    vals: Dict[str, int] = {}
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                parts = line.split()
+                if len(parts) >= 2 and parts[0] in {"UID_MIN", "UID_MAX", "SYS_UID_MIN", "SYS_UID_MAX"}:
+                    try:
+                        vals[parts[0]] = int(parts[1])
+                    except ValueError:
+                        continue
+    except FileNotFoundError:
+        pass
+    return vals
+
+
+def parse_passwd(path: str = "/etc/passwd") -> List[Tuple[str, int, int, str, str, str]]:
+    rows: List[Tuple[str, int, int, str, str, str]] = []
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.rstrip("\n")
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split(":")
+            if len(parts) < 7:
+                continue
+            name = parts[0]
+            try:
+                uid = int(parts[2])
+                gid = int(parts[3])
+            except ValueError:
+                continue
+            gecos = parts[4]
+            home = parts[5]
+            shell = parts[6]
+            rows.append((name, uid, gid, gecos, home, shell))
+    return rows
+
+
+def parse_group(path: str = "/etc/group") -> Tuple[Dict[int, str], Dict[str, int], Dict[str, Set[str]]]:
+    gid_to_name: Dict[int, str] = {}
+    name_to_gid: Dict[str, int] = {}
+    members: Dict[str, Set[str]] = {}
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.rstrip("\n")
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split(":")
+            if len(parts) < 4:
+                continue
+            name = parts[0]
+            try:
+                gid = int(parts[2])
+            except ValueError:
+                continue
+            mem = set([m for m in parts[3].split(",") if m])
+            gid_to_name[gid] = name
+            name_to_gid[name] = gid
+            members[name] = mem
+    return gid_to_name, name_to_gid, members
+
+
+def is_human_user(uid: int, shell: str, uid_min: int) -> bool:
+    if uid < uid_min:
+        return False
+    shell = (shell or "").strip()
+    if shell in {"/usr/sbin/nologin", "/usr/bin/nologin", "/bin/false"}:
+        return False
+    return True
+
+
+def find_user_ssh_files(home: str) -> List[str]:
+    sshdir = os.path.join(home, ".ssh")
+    out: List[str] = []
+    if not os.path.isdir(sshdir):
+        return out
+
+    ak = os.path.join(sshdir, "authorized_keys")
+    if os.path.isfile(ak) and not os.path.islink(ak):
+        out.append(ak)
+
+    return sorted(set(out))
+
+
+def collect_non_system_users() -> List[UserRecord]:
+    defs = parse_login_defs()
+    uid_min = defs.get("UID_MIN", 1000)
+
+    passwd_rows = parse_passwd()
+    gid_to_name, _, group_members = parse_group()
+
+    users: List[UserRecord] = []
+    for name, uid, gid, gecos, home, shell in passwd_rows:
+        if name in {"root", "nobody"}:
+            continue
+        if not is_human_user(uid, shell, uid_min):
+            continue
+
+        primary_group = gid_to_name.get(gid, str(gid))
+
+        supp: List[str] = []
+        for gname, mem in group_members.items():
+            if name in mem and gname != primary_group:
+                supp.append(gname)
+        supp = sorted(set(supp))
+
+        ssh_files = find_user_ssh_files(home) if home and home.startswith("/") else []
+
+        users.append(UserRecord(
+            name=name,
+            uid=uid,
+            gid=gid,
+            gecos=gecos,
+            home=home,
+            shell=shell,
+            primary_group=primary_group,
+            supplementary_groups=supp,
+            ssh_files=ssh_files,
+        ))
+
+    return users

enroll-0.0.1/enroll/cli.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import argparse
+from .harvest import harvest
+from .manifest import manifest
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(prog="enroll")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    h = sub.add_parser("harvest", help="Harvest service/package/config state into a bundle")
+    h.add_argument("--out", required=True, help="Bundle output directory")
+
+    r = sub.add_parser("manifest", help="Render Ansible roles from a harvested bundle")
+    r.add_argument("--bundle", required=True, help="Path to the bundle directory created by the harvest command")
+    r.add_argument("--out", required=True, help="Output directory for generated roles/playbook Ansible manifest")
+
+    e = sub.add_parser("export", help="Harvest then manifest in one shot")
+    e.add_argument("--bundle", required=True, help="Path to the directory to place the bundle in")
+    e.add_argument("--out", required=True, help="Output directory for generated roles/playbook Ansible manifest")
+
+    args = ap.parse_args()
+
+    if args.cmd == "harvest":
+        path = harvest(args.out)
+        print(path)
+    elif args.cmd == "manifest":
+        manifest(args.bundle, args.out)
+    elif args.cmd == "export":
+        harvest(args.bundle)
+        manifest(args.bundle, args.out)

enroll-0.0.1/enroll/debian.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import glob
+import hashlib
+import os
+import subprocess
+from typing import Dict, List, Optional, Set, Tuple
+
+
+def _run(cmd: list[str]) -> str:
+    p = subprocess.run(cmd, check=False, text=True, capture_output=True)
+    if p.returncode != 0:
+        raise RuntimeError(f"Command failed: {cmd}\n{p.stderr}")
+    return p.stdout
+
+
+def dpkg_owner(path: str) -> Optional[str]:
+    p = subprocess.run(["dpkg", "-S", path], text=True, capture_output=True)
+    if p.returncode != 0:
+        return None
+    left = p.stdout.split(":", 1)[0].strip()
+    pkg = left.split(":", 1)[0].strip()
+    return pkg or None
+
+
+
+def list_manual_packages() -> List[str]:
+    """Return packages marked as manually installed (apt-mark showmanual)."""
+    p = subprocess.run(["apt-mark", "showmanual"], text=True, capture_output=True)
+    if p.returncode != 0:
+        return []
+    pkgs: List[str] = []
+    for line in (p.stdout or "").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        pkgs.append(line)
+    return sorted(set(pkgs))
+
+def build_dpkg_etc_index(
+    info_dir: str = "/var/lib/dpkg/info",
+) -> Tuple[Set[str], Dict[str, str], Dict[str, Set[str]], Dict[str, List[str]]]:
+    """
+    Returns:
+      owned_etc_paths: set of /etc paths owned by dpkg
+      etc_owner_map: /etc/path -> pkg
+      topdir_to_pkgs: "nginx" -> {"nginx-common", ...} based on /etc/<topdir>/...
+      pkg_to_etc_paths: pkg -> list of /etc paths it installs
+    """
+    owned: Set[str] = set()
+    owner: Dict[str, str] = {}
+    topdir_to_pkgs: Dict[str, Set[str]] = {}
+    pkg_to_etc: Dict[str, List[str]] = {}
+
+    for list_path in glob.glob(os.path.join(info_dir, "*.list")):
+        pkg_raw = os.path.basename(list_path)[:-5]  # strip ".list"
+        pkg = pkg_raw.split(":", 1)[0]  # drop arch suffix if present
+
+        etc_paths: List[str] = []
+        try:
+            with open(list_path, "r", encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    p = line.rstrip("\n")
+                    if not p.startswith("/etc/"):
+                        continue
+                    owned.add(p)
+                    owner.setdefault(p, pkg)
+                    etc_paths.append(p)
+
+                    parts = p.split("/", 3)
+                    if len(parts) >= 3 and parts[2]:
+                        top = parts[2]
+                        topdir_to_pkgs.setdefault(top, set()).add(pkg)
+        except FileNotFoundError:
+            continue
+
+        if etc_paths:
+            pkg_to_etc.setdefault(pkg, []).extend(etc_paths)
+
+    for k, v in list(pkg_to_etc.items()):
+        pkg_to_etc[k] = sorted(set(v))
+
+    return owned, owner, topdir_to_pkgs, pkg_to_etc
+
+
+def parse_status_conffiles(status_path: str = "/var/lib/dpkg/status") -> Dict[str, Dict[str, str]]:
+    """
+    pkg -> { "/etc/foo": md5hex, ... } based on dpkg status "Conffiles" field.
+    This md5 is the packaged baseline for the conffile.
+    """
+    out: Dict[str, Dict[str, str]] = {}
+
+    cur: Dict[str, str] = {}
+    key: Optional[str] = None
+
+    def flush() -> None:
+        pkg = cur.get("Package")
+        if not pkg:
+            return
+        raw = cur.get("Conffiles")
+        if not raw:
+            return
+        m: Dict[str, str] = {}
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split()
+            if len(parts) >= 2 and parts[0].startswith("/"):
+                m[parts[0]] = parts[1]
+        if m:
+            out[pkg] = m
+
+    with open(status_path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            if line.strip() == "":
+                if cur:
+                    flush()
+                cur = {}
+                key = None
+                continue
+            if line[0].isspace() and key:
+                cur[key] += line
+            else:
+                if ":" in line:
+                    k, v = line.split(":", 1)
+                    key = k
+                    cur[key] = v.lstrip()
+
+    if cur:
+        flush()
+    return out
+
+
+def read_pkg_md5sums(pkg: str) -> Dict[str, str]:
+    """
+    relpath -> md5hex from /var/lib/dpkg/info/<pkg>.md5sums
+    relpath has no leading slash, e.g. 'etc/nginx/nginx.conf'
+    """
+    path = f"/var/lib/dpkg/info/{pkg}.md5sums"
+    if not os.path.exists(path):
+        return {}
+    m: Dict[str, str] = {}
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            md5, rel = line.split(None, 1)
+            m[rel.strip()] = md5.strip()
+    return m
+
+
+def file_md5(path: str) -> str:
+    h = hashlib.md5()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def stat_triplet(path: str) -> Tuple[str, str, str]:
+    st = os.stat(path, follow_symlinks=True)
+    mode = oct(st.st_mode & 0o777)[2:].zfill(4)
+
+    import pwd, grp
+    try:
+        owner = pwd.getpwuid(st.st_uid).pw_name
+    except KeyError:
+        owner = str(st.st_uid)
+    try:
+        group = grp.getgrgid(st.st_gid).gr_name
+    except KeyError:
+        group = str(st.st_gid)
+    return owner, group, mode