Skip to content

Instantly share code, notes, and snippets.

@ocodo
Created October 12, 2026 01:25
Show Gist options
  • Select an option

  • Save ocodo/32036d07c188fcf04ffb29f117ffde5c to your computer and use it in GitHub Desktop.

Select an option

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]
#!/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