Created
October 12, 2026 01:25
-
-
Save ocodo/32036d07c188fcf04ffb29f117ffde5c to your computer and use it in GitHub Desktop.
Run from Live USB Audit a Linux Mint for migration to Cachy-OS without reinstall (WIP) uv run mine-audit.py <audit dit> <mint src root> [output dir]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/usr/bin/env python3 | |
| """mine-audit.py AUDIT_DIR MINT_ROOT [OUTPUT_DIR] | |
| Read-only Mint -> CachyOS audit miner. | |
| Requires: uv, Python 3, ripgrep (rg), dpkg-query from the host. | |
| Does not execute commands inside the mounted source root. | |
| """ | |
| import json | |
| import re | |
| import subprocess | |
| import sys | |
| from collections import defaultdict | |
| from pathlib import Path | |
| if len(sys.argv) < 3: | |
| sys.exit(f"Usage: {sys.argv[0]} AUDIT_DIR MINT_ROOT [OUTPUT_DIR]") | |
| AUDIT = Path(sys.argv[1]).resolve() | |
| ROOT = Path(sys.argv[2]).resolve() | |
| OUT = Path(sys.argv[3] if len(sys.argv) > 3 else "migration-review").resolve() | |
| OUT.mkdir(parents=True, exist_ok=True) | |
| if not (ROOT / "etc/os-release").is_file(): | |
| sys.exit(f"Not a Linux root: {ROOT}") | |
| def read(path): | |
| p = Path(path) | |
| try: | |
| return p.read_text(errors="replace") | |
| except OSError: | |
| return "" | |
| def audit(name): | |
| return read(AUDIT / name) | |
| def run(argv): | |
| p = subprocess.run(argv, text=True, capture_output=True) | |
| return p.stdout, p.stderr, p.returncode | |
| def rg(pattern, *paths): | |
| paths = [str(p) for p in paths if p.exists()] | |
| if not paths: | |
| return [] | |
| stdout, _, _ = run(["rg", "-n", "--no-heading", pattern, *paths]) | |
| return stdout.splitlines() | |
| def source_files(*dirs, suffixes=None): | |
| result = [] | |
| for d in dirs: | |
| base = ROOT / d | |
| if not base.is_dir(): | |
| continue | |
| stdout, _, rc = run([ | |
| "rg", "--files", "--hidden", "--no-ignore", | |
| "--follow", str(base) | |
| ]) | |
| if rc not in (0, 1): | |
| continue | |
| for line in stdout.splitlines(): | |
| p = Path(line) | |
| if suffixes and p.suffix not in suffixes: | |
| continue | |
| result.append(p) | |
| return sorted(set(result)) | |
| def rel(p): | |
| try: | |
| return str(p.relative_to(ROOT)) | |
| except ValueError: | |
| return str(p) | |
| def parse_colon(name): | |
| return [x.split(":") for x in audit(name).splitlines() | |
| if x and not x.startswith("#")] | |
| def unit_name(path): | |
| # Account for systemd drop-ins, e.g. foo.service.d/override.conf | |
| parts = path.parts | |
| for i in range(len(parts) - 1, -1, -1): | |
| if parts[i].endswith((".service", ".timer", ".socket", | |
| ".path", ".mount", ".automount", ".target")): | |
| return parts[i] | |
| return Path(path).name | |
| # ---------- Users and groups ---------- | |
| users, groups = [], [] | |
| for f in parse_colon("passwd.txt"): | |
| if len(f) >= 7: | |
| try: | |
| uid, gid = int(f[2]), int(f[3]) | |
| except ValueError: | |
| continue | |
| users.append(dict(name=f[0], uid=uid, gid=gid, | |
| home=f[5], shell=f[6])) | |
| for f in parse_colon("groups.txt"): | |
| if len(f) >= 4: | |
| try: | |
| gid = int(f[2]) | |
| except ValueError: | |
| continue | |
| groups.append(dict(name=f[0], gid=gid, | |
| members=f[3].split(",") if f[3] else [])) | |
| # Supplement the original audit with subordinate IDs and account policy. | |
| identity_files = {} | |
| for name in ("etc/subuid", "etc/subgid", "etc/login.defs", | |
| "etc/security/limits.conf", "etc/security/limits.d"): | |
| p = ROOT / name | |
| if p.is_file(): | |
| identity_files[name] = read(p) | |
| elif p.is_dir(): | |
| identity_files[name] = { | |
| rel(f): read(f) for f in source_files(name) | |
| } | |
| # ---------- Packages ---------- | |
| packages = {} | |
| for line in audit("packages.txt").splitlines(): | |
| f = line.split("\t") | |
| if len(f) >= 2 and (len(f) < 3 or f[2].startswith("ii")): | |
| packages[f[0]] = f[1] | |
| # dpkg status gives package metadata, dependencies and descriptions. | |
| status = read(ROOT / "var/lib/dpkg/status") | |
| pkg_meta = {} | |
| for block in status.split("\n\n"): | |
| fields = {} | |
| key = None | |
| for line in block.splitlines(): | |
| if line[:1].isspace() and key: | |
| fields[key] += "\n" + line | |
| elif ":" in line: | |
| key, value = line.split(":", 1) | |
| fields[key] = value.strip() | |
| if fields.get("Status", "").endswith(" installed"): | |
| name = fields.get("Package") | |
| if name: | |
| pkg_meta[name] = { | |
| k: fields[k] for k in ( | |
| "Version", "Architecture", "Essential", | |
| "Priority", "Depends", "Pre-Depends", | |
| "Recommends", "Description" | |
| ) if k in fields | |
| } | |
| # Build dpkg file ownership index directly from source package lists. | |
| # This avoids running dpkg tools against the host's package database. | |
| owners = defaultdict(set) | |
| info = ROOT / "var/lib/dpkg/info" | |
| if info.is_dir(): | |
| for listing in info.glob("*.list"): | |
| package = listing.name[:-5] | |
| for item in read(listing).splitlines(): | |
| if item.startswith("/"): | |
| owners[item].add(package) | |
| def owner_of(path): | |
| # Exact match first; Debian package listings generally use absolute paths. | |
| return sorted(owners.get(path, ())) | |
| # ---------- systemd units and overrides ---------- | |
| unit_suffixes = (".service", ".timer", ".socket", ".path", | |
| ".mount", ".automount", ".target", ".slice") | |
| unit_dirs = ( | |
| "etc/systemd/system", | |
| "usr/local/lib/systemd/system", | |
| "lib/systemd/system", | |
| "usr/lib/systemd/system", | |
| "etc/systemd/user", | |
| "usr/local/lib/systemd/user", | |
| "usr/lib/systemd/user", | |
| ) | |
| unit_paths = [] | |
| for d in unit_dirs: | |
| unit_paths.extend(source_files(d, suffixes=unit_suffixes + (".conf",))) | |
| # Include user unit files beneath each home. | |
| home_paths = source_files( | |
| "home", suffixes=unit_suffixes + (".conf",) | |
| ) | |
| home_paths = [ | |
| p for p in home_paths | |
| if "/.config/systemd/user/" in str(p) | |
| or "/.local/share/systemd/user/" in str(p) | |
| ] | |
| unit_paths.extend(home_paths) | |
| unit_records = {} | |
| directives = defaultdict(list) | |
| for p in sorted(set(unit_paths)): | |
| path = rel(p) | |
| content = read(p) | |
| name = unit_name(p) | |
| is_user = "/systemd/user/" in path | |
| unit_records[path] = { | |
| "unit": name, | |
| "scope": "user" if is_user else "system", | |
| "content": content, | |
| "packages": owner_of("/" + path.split("/", 1)[-1]) | |
| if path.startswith(("etc/", "usr/", "lib/")) else [], | |
| } | |
| for lineno, line in enumerate(content.splitlines(), 1): | |
| s = line.strip() | |
| if not s or s.startswith(("#", ";")) or "=" not in s: | |
| continue | |
| key, value = s.split("=", 1) | |
| if key in { | |
| "ExecStart", "ExecStartPre", "ExecStartPost", "ExecStop", | |
| "User", "Group", "SupplementaryGroups", "WorkingDirectory", | |
| "RootDirectory", "EnvironmentFile", "Requires", "Wants", | |
| "BindsTo", "After", "Before", "PartOf", "WantedBy", | |
| "RequiredBy", "ConditionPathExists", "BindPaths", | |
| "ReadWritePaths", "ReadOnlyPaths", "StateDirectory", | |
| "CacheDirectory", "RuntimeDirectory", "LoadCredential", | |
| }: | |
| directives[name].append({ | |
| "file": path, "line": lineno, | |
| "key": key, "value": value | |
| }) | |
| # Enablement links are evidence of enablement, not proof of necessity. | |
| enablement = {} | |
| for d in ("etc/systemd/system", "etc/systemd/user"): | |
| base = ROOT / d | |
| if not base.exists(): | |
| continue | |
| stdout, _, _ = run(["rg", "--files", "--hidden", "--no-ignore", | |
| "--follow", str(base)]) | |
| links = [] | |
| for s in stdout.splitlines(): | |
| p = Path(s) | |
| if p.is_symlink(): | |
| links.append({"path": rel(p), "target": str(p.readlink())}) | |
| enablement[d] = links | |
| def unit_list(filename, suffixes): | |
| found = set() | |
| for line in audit(filename).splitlines(): | |
| f = line.split() | |
| if f and f[0].endswith(suffixes): | |
| found.add(f[0]) | |
| return found | |
| enabled = unit_list("enabled-services.txt", (".service",)) | |
| running = unit_list("running-services.txt", (".service",)) | |
| failed = unit_list("failed-units.txt", unit_suffixes) | |
| timers = unit_list("system-timers.txt", (".timer",)) | |
| user_units = unit_list("user-units.txt", unit_suffixes) | |
| user_timers = unit_list("user-timers.txt", (".timer",)) | |
| # ---------- Package ownership for units and executables ---------- | |
| # Unit file ownership comes from dpkg .list files. Executable ownership is | |
| # resolved by interpreting common absolute Exec* paths against the source root. | |
| def executable_candidates(value): | |
| # Strip systemd prefixes and arguments. Do not attempt shell evaluation. | |
| value = value.strip() | |
| value = re.sub(r"^[+-!:@]+", "", value) | |
| if not value.startswith("/"): | |
| return [] | |
| return [value.split()[0]] | |
| for rec in unit_records.values(): | |
| for entry in directives[rec["unit"]]: | |
| if entry["key"].startswith("Exec"): | |
| paths = executable_candidates(entry["value"]) | |
| entry["executables"] = [ | |
| {"path": x, "packages": owner_of(x)} for x in paths | |
| ] | |
| # Find scripts referenced by units, and read their package ownership. | |
| for rec in unit_records.values(): | |
| for entry in directives[rec["unit"]]: | |
| if entry["key"].startswith("Exec"): | |
| for exe in entry.get("executables", []): | |
| p = ROOT / exe["path"].lstrip("/") | |
| if p.is_file(): | |
| exe["exists_in_source"] = True | |
| exe["source_path"] = rel(p) | |
| else: | |
| exe["exists_in_source"] = False | |
| # ---------- Mounts and scheduled jobs ---------- | |
| fstab = [] | |
| for line in audit("fstab.txt").splitlines(): | |
| s = line.strip() | |
| if not s or s.startswith("#"): | |
| continue | |
| f = s.split() | |
| if len(f) >= 4: | |
| fstab.append(dict(source=f[0], mountpoint=f[1], | |
| fstype=f[2], options=f[3], | |
| dump=f[4] if len(f) > 4 else "", | |
| passno=f[5] if len(f) > 5 else "")) | |
| cron = {} | |
| for d in ("etc/cron.d", "etc/cron.daily", "etc/cron.hourly", | |
| "etc/cron.weekly", "etc/cron.monthly", "etc/cron.yearly", | |
| "var/spool/cron/crontabs"): | |
| for p in source_files(d): | |
| cron[rel(p)] = read(p) | |
| # ---------- Source distro package / service classification ---------- | |
| mint_specific = re.compile( | |
| r"(mint|ubuntu|apport|apt-|dpkg|packagekit|" | |
| r"unattended-upgrades|update-notifier|needrestart)", | |
| re.I | |
| ) | |
| service_report = [] | |
| all_service_names = sorted(enabled | running | failed | timers | | |
| user_units | user_timers | | |
| {r["unit"] for r in unit_records.values()}) | |
| for name in all_service_names: | |
| records = [r for r in unit_records.values() if r["unit"] == name] | |
| local = any( | |
| r["scope"] == "system" and | |
| (r["file"].startswith(("etc/systemd/system/", | |
| "usr/local/lib/systemd/")) | |
| or "/.config/systemd/" in r["file"]) | |
| for r in records | |
| ) | |
| referenced_packages = set() | |
| for r in records: | |
| referenced_packages.update(r["packages"]) | |
| for entry in directives[name]: | |
| for exe in entry.get("executables", []): | |
| referenced_packages.update(exe["packages"]) | |
| service_report.append({ | |
| "unit": name, | |
| "enabled": name in enabled, | |
| "running_in_source_audit": name in running, | |
| "failed_in_source_audit": name in failed, | |
| "timer": name in timers or name in user_timers, | |
| "user_unit": name in user_units or name in user_timers, | |
| "local_or_user_definition": local, | |
| "source_unit_files": [r["file"] for r in records], | |
| "package_candidates": sorted(referenced_packages), | |
| "directives": directives[name], | |
| "initial_classification": ( | |
| "review-distro-specific" if mint_specific.search(name) | |
| else "review-custom-unit" if local | |
| else "resolve-package-and-target" | |
| ), | |
| }) | |
| # ---------- LLM input: compact, structured, secret-aware ---------- | |
| # Unit contents can contain credentials. Keep them in the local report but | |
| # exclude obvious secret-bearing values from the default LLM payload. | |
| SECRET = re.compile(r"(password|passwd|token|secret|credential|api[_-]?key)", re.I) | |
| def redact_unit_content(content): | |
| out = [] | |
| for line in content.splitlines(): | |
| if SECRET.search(line) and "=" in line: | |
| k, _ = line.split("=", 1) | |
| out.append(k + "=<REDACTED>") | |
| else: | |
| out.append(line) | |
| return "\n".join(out) | |
| llm_units = [] | |
| for path, rec in unit_records.items(): | |
| llm_units.append({ | |
| "path": path, | |
| "unit": rec["unit"], | |
| "scope": rec["scope"], | |
| "package_candidates": rec["packages"], | |
| "content": redact_unit_content(rec["content"]), | |
| }) | |
| data = { | |
| "source": { | |
| "root": str(ROOT), | |
| "os_release": read(ROOT / "etc/os-release"), | |
| "hostname": read(ROOT / "etc/hostname").strip(), | |
| }, | |
| "users": users, | |
| "groups": groups, | |
| "identity_policy_files": identity_files, | |
| "packages": packages, | |
| "package_metadata": pkg_meta, | |
| "unit_files": llm_units, | |
| "unit_records": service_report, | |
| "systemd_enablement_symlinks": enablement, | |
| "fstab": fstab, | |
| "cron_files": cron, | |
| "audit_state": { | |
| "enabled_services": sorted(enabled), | |
| "running_services": sorted(running), | |
| "failed_units": sorted(failed), | |
| "system_timers": sorted(timers), | |
| "user_units": sorted(user_units), | |
| "user_timers": sorted(user_timers), | |
| }, | |
| } | |
| (OUT / "migration-data.json").write_text( | |
| json.dumps(data, indent=2) + "\n" | |
| ) | |
| # Static prompt template. The JSON payload is supplied separately; don't | |
| # interpolate untrusted system data into executable Python or shell code. | |
| prompt = r""" | |
| You are analysing a read-only Linux Mint -> CachyOS migration audit. | |
| Use the supplied migration-data.json as evidence. Do not assume a package | |
| name match proves functional equivalence. Do not propose copying Debian | |
| package databases, system accounts, or distro-specific service defaults. | |
| For each relevant system service, timer, mount, and user/group, return: | |
| - decision: preserve, translate, omit, or unresolved | |
| - evidence: source file/unit/package/identity | |
| - target requirement: CachyOS package, configuration, or account | |
| - dependencies and ordering | |
| - risks and validation test | |
| - confidence: high, medium, low | |
| Prioritise locally defined services, their Exec* binaries, User/Group, | |
| WorkingDirectory, EnvironmentFile, mount dependencies, timers, and service | |
| accounts. Keep user home content separate from system package installation. | |
| Preserve user-owned files by default; never print secrets. | |
| Treat the audit's enabled/running states as observations, not proof that a | |
| service is required. Flag any missing evidence instead of guessing. | |
| Output a concise proposed migration manifest. Make no system changes. | |
| """ | |
| (OUT / "LLM-INSTRUCTIONS.txt").write_text(prompt.strip() + "\n") | |
| # Template for an API/client integration using static template + parameters. | |
| # Keep prompt and JSON data separate. Avoid f-string interpolation of data. | |
| template = ( | |
| "SYSTEM_INSTRUCTIONS:\n{instructions}\n\n" | |
| "MIGRATION_DATA_JSON:\n{migration_data}\n" | |
| ) | |
| (OUT / "llm-template.txt").write_text(template) | |
| print(f"Wrote {OUT / 'migration-data.json'}") | |
| print(f"Wrote {OUT / 'LLM-INSTRUCTIONS.txt'}") | |
| print(f"Wrote {OUT / 'llm-template.txt'}") | |
| print(f"Units analysed: {len(service_report)}; " | |
| f"users: {len(users)}; packages: {len(packages)}") |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment