devaudit-cli 0.3.0__py3-none-any.whl

dev_audit/__main__.py

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

dev_audit/audit.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+
+def check_devtools(results: dict) -> list[str]:
+    findings: list[str] = []
+
+    devtools = results.get("devtools", {})
+    warnings = devtools.get("warnings", [])
+
+    findings.extend(warnings)
+
+    return findings
+
+
+def check_network(results: dict) -> list[str]:
+    findings: list[str] = []
+
+    network = results.get("network", {})
+    data = network.get("data", {})
+
+    ports = data.get("listening_ports", [])
+
+    for port in ports:
+        protocol = port.get("protocol")
+        address = port.get("local_address", "")
+
+        if protocol == "tcp" and address.startswith("*:22"):
+            findings.append(
+                "SSH is listening on all interfaces."
+            )
+
+        if protocol == "tcp" and address.startswith("0.0.0.0:80"):
+            findings.append(
+                "HTTP service exposed on all IPv4 interfaces."
+            )
+
+        if protocol == "tcp" and address.startswith("[::]:80"):
+            findings.append(
+                "HTTP service exposed on all IPv6 interfaces."
+            )
+
+    return findings
+
+
+def run_audit(results: dict) -> list[str]:
+    findings: list[str] = []
+
+    findings.extend(check_devtools(results))
+    findings.extend(check_network(results))
+
+    return findings

dev_audit/cli.py

@@ -0,0 +1,110 @@
+import argparse
+
+from dev_audit.collectors.devtools import collect_devtools_info
+from dev_audit.collectors.network import collect_network_info
+from dev_audit.collectors.resources import collect_resource_info
+from dev_audit.collectors.system import collect_system_info
+from dev_audit.output import (
+    print_devtools,
+    print_findings,
+    print_json,
+    print_network,
+    print_resources,
+    print_system,
+)
+from dev_audit.audit import run_audit
+from dev_audit.status import determine_exit_code
+
+VALID_SECTIONS = ("system", "resources", "network", "devtools")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="dev-audit",
+        description="Inspect Linux system health and developer environment setup.",
+    )
+
+    parser.add_argument(
+        "section",
+        nargs="?",
+        choices=VALID_SECTIONS,
+        help="Audit section to run. If omitted, all sections run.",
+    )
+
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output results as JSON.",
+    )
+
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed diagnostic information.",
+    )
+
+    return parser
+
+
+def run_full_audit(
+    json_output: bool = False,
+    verbose: bool = False,
+) -> int:
+    results = {
+        "system": collect_system_info(),
+        "resources": collect_resource_info(),
+        "network": collect_network_info(),
+        "devtools": collect_devtools_info(),
+    }
+
+    findings = run_audit(results)
+
+    if json_output:
+        results["findings"] = findings
+        print_json(results)
+        return determine_exit_code(results, findings)
+
+    print_system(results["system"], verbose=verbose)
+    print()
+
+    print_resources(results["resources"], verbose=verbose)
+    print()
+
+    print_network(results["network"], verbose=verbose)
+    print()
+
+    print_devtools(results["devtools"], verbose=verbose)
+
+    print_findings(findings)
+    return determine_exit_code(results, findings)
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.section is None:
+        return run_full_audit(
+            json_output=args.json,
+            verbose=args.verbose,
+        )
+        return
+
+    if args.section == "system":
+        result = collect_system_info()
+        print_json(result) if args.json else print_system(result, verbose=args.verbose)
+        return 0
+
+    if args.section == "resources":
+        result = collect_resource_info()
+        print_json(result) if args.json else print_resources(result, verbose=args.verbose)
+        return 0
+
+    if args.section == "network":
+        result = collect_network_info()
+        print_json(result) if args.json else print_network(result, verbose=args.verbose)
+        return 0
+
+    if args.section == "devtools":
+        result = collect_devtools_info()
+        print_json(result) if args.json else print_devtools(result, verbose=args.verbose)
+        return 0

dev_audit/collectors/devtools.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import shutil
+
+from dev_audit.command import run_command
+
+
+def inspect_tool(
+    name: str,
+    executable: str,
+    version_command: list[str],
+) -> dict[str, object]:
+    path = shutil.which(executable)
+
+    if path is None:
+        return {
+            "name": name,
+            "installed": False,
+            "version": None,
+            "path": None,
+        }
+
+    version_output = run_command(version_command)
+
+    version = None
+
+    if version_output["ok"]:
+        version = (
+            version_output.get("stdout")
+            or version_output.get("stderr")
+        )
+
+        if version:
+            version = version.strip()
+
+    return {
+        "name": name,
+        "installed": True,
+        "version": version,
+        "path": path,
+    }
+
+
+def collect_devtools_info() -> dict[str, object]:
+    tools = [
+        inspect_tool(
+            name="Python",
+            executable="python3",
+            version_command=["python3", "--version"],
+        ),
+        inspect_tool(
+            name="pip",
+            executable="pip",
+            version_command=["pip", "--version"],
+        ),
+        inspect_tool(
+            name="Git",
+            executable="git",
+            version_command=["git", "--version"],
+        ),
+        inspect_tool(
+            name="Docker",
+            executable="docker",
+            version_command=["docker", "--version"],
+        ),
+        inspect_tool(
+            name="Docker Compose",
+            executable="docker",
+            version_command=["docker", "compose", "version"],
+        ),
+        inspect_tool(
+            name="Node.js",
+            executable="node",
+            version_command=["node", "--version"],
+        ),
+        inspect_tool(
+            name="npm",
+            executable="npm",
+            version_command=["npm", "--version"],
+        ),
+    ]
+
+    warnings: list[str] = []
+
+    node_installed = False
+    npm_installed = False
+
+    for tool in tools:
+        if tool["name"] == "Node.js":
+            node_installed = bool(tool["installed"])
+
+        if tool["name"] == "npm":
+            npm_installed = bool(tool["installed"])
+
+            path = tool.get("path")
+
+            if isinstance(path, str) and path.startswith("/mnt/c/"):
+                warnings.append(
+                    "npm is being resolved from a Windows installation."
+                )
+
+    if npm_installed and not node_installed:
+        warnings.append(
+            "npm detected but Node.js executable not found."
+        )
+
+    return {
+        "success": True,
+        "data": {
+            "tools": tools,
+        },
+        "warnings": warnings,
+    }

dev_audit/collectors/network.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from dev_audit.command import command_exists, run_command
+
+
+def read_dns_servers() -> list[str]:
+    path = Path("/etc/resolv.conf")
+    servers: list[str] = []
+
+    try:
+        for line in path.read_text().splitlines():
+            line = line.strip()
+
+            if line.startswith("nameserver"):
+                parts = line.split()
+                if len(parts) >= 2:
+                    servers.append(parts[1])
+
+    except OSError:
+        return []
+
+    return servers
+
+
+def parse_interfaces(ip_addr_output: str) -> list[dict[str, str]]:
+    interfaces: list[dict[str, str]] = []
+    current_interface: dict[str, str] | None = None
+
+    for line in ip_addr_output.splitlines():
+        line = line.strip()
+
+        if not line:
+            continue
+
+        if ": " in line and line[0].isdigit():
+            parts = line.split(":", 2)
+
+            if len(parts) < 2:
+                continue
+
+            name = parts[1].strip()
+
+            current_interface = {
+                "name": name,
+                "ipv4": "",
+            }
+
+            interfaces.append(current_interface)
+
+        elif line.startswith("inet ") and current_interface is not None:
+            ip = line.split()[1].split("/")[0]
+            current_interface["ipv4"] = ip
+
+    return interfaces
+
+
+def parse_default_route(route_output: str) -> dict[str, str] | None:
+    for line in route_output.splitlines():
+        if not line.startswith("default"):
+            continue
+
+        parts = line.split()
+
+        try:
+            gateway = parts[2]
+            interface = parts[4]
+        except IndexError:
+            return None
+
+        return {
+            "gateway": gateway,
+            "interface": interface,
+        }
+
+    return None
+
+
+def parse_listening_ports(ss_output: str) -> list[dict[str, str]]:
+    ports: list[dict[str, str]] = []
+
+    for line in ss_output.splitlines():
+        line = line.strip()
+
+        if not line:
+            continue
+
+        if line.startswith("Netid"):
+            continue
+
+        parts = line.split()
+
+        if len(parts) < 5:
+            continue
+
+        ports.append(
+            {
+                "protocol": parts[0],
+                "local_address": parts[4],
+            }
+        )
+
+    return ports
+
+def collect_network_info() -> dict[str, object]:
+    warnings: list[str] = []
+
+    ip_addr = None
+    ip_route = None
+    listening_ports = None
+
+    if not command_exists("ip"):
+        warnings.append("Missing required command: ip")
+    else:
+        ip_addr = run_command(["ip", "addr"])
+        ip_route = run_command(["ip", "route"])
+
+        if not ip_addr["ok"]:
+            warnings.append("Failed to run: ip addr")
+
+        if not ip_route["ok"]:
+            warnings.append("Failed to run: ip route")
+
+    if not command_exists("ss"):
+        warnings.append("Missing required command: ss")
+    else:
+        listening_ports = run_command(["ss", "-tuln"])
+
+        if not listening_ports["ok"]:
+            warnings.append("Failed to run: ss -tuln")
+
+    dns_servers = read_dns_servers()
+
+    if not dns_servers:
+        warnings.append("Could not read DNS servers from /etc/resolv.conf")
+
+    interfaces = (
+        parse_interfaces(ip_addr["stdout"])
+        if ip_addr and ip_addr["stdout"]
+        else []
+    )
+
+    default_route = (
+        parse_default_route(ip_route["stdout"])
+        if ip_route and ip_route["stdout"]
+        else None
+    )
+
+    parsed_ports = (
+        parse_listening_ports(listening_ports["stdout"])
+        if listening_ports and listening_ports["stdout"]
+        else []
+    )
+
+    data = {
+        "interfaces": interfaces,
+        "default_route": default_route,
+        "dns_servers": dns_servers,
+        "listening_ports": parsed_ports,
+    }
+
+    return {
+        "success": bool(
+            interfaces
+            or default_route
+            or dns_servers
+            or parsed_ports
+        ),
+        "data": data,
+        "warnings": warnings,
+    }

dev_audit/collectors/resources.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def read_load_average() -> dict[str, float] | None:
+    path = Path("/proc/loadavg")
+
+    try:
+        values = path.read_text().split()
+        return {
+            "1_min": float(values[0]),
+            "5_min": float(values[1]),
+            "15_min": float(values[2]),
+        }
+    except (OSError, IndexError, ValueError):
+        return None
+
+
+def read_meminfo() -> dict[str, int]:
+    path = Path("/proc/meminfo")
+    data: dict[str, int] = {}
+
+    try:
+        for line in path.read_text().splitlines():
+            key, value = line.split(":", 1)
+            parts = value.strip().split()
+
+            if not parts:
+                continue
+
+            data[key] = int(parts[0]) * 1024
+
+    except (OSError, ValueError):
+        return {}
+
+    return data
+
+
+def bytes_to_gib(value: int | None) -> float | None:
+    if value is None:
+        return None
+
+    return round(value / (1024**3), 2)
+
+
+def get_memory_usage(meminfo: dict[str, int]) -> dict[str, float | None]:
+    total = meminfo.get("MemTotal")
+    available = meminfo.get("MemAvailable")
+
+    used = None
+    percent = None
+
+    if total is not None and available is not None:
+        used = total - available
+        percent = round((used / total) * 100, 1)
+
+    return {
+        "total_gib": bytes_to_gib(total),
+        "available_gib": bytes_to_gib(available),
+        "used_gib": bytes_to_gib(used),
+        "used_percent": percent,
+    }
+
+
+def get_swap_usage(meminfo: dict[str, int]) -> dict[str, float | None]:
+    total = meminfo.get("SwapTotal")
+    free = meminfo.get("SwapFree")
+
+    used = None
+    percent = None
+
+    if total is not None and free is not None:
+        used = total - free
+        percent = round((used / total) * 100, 1) if total else 0.0
+
+    return {
+        "total_gib": bytes_to_gib(total),
+        "free_gib": bytes_to_gib(free),
+        "used_gib": bytes_to_gib(used),
+        "used_percent": percent,
+    }
+
+
+def get_root_disk_usage() -> dict[str, float]:
+    usage = shutil.disk_usage("/")
+
+    return {
+        "total_gib": bytes_to_gib(usage.total),
+        "used_gib": bytes_to_gib(usage.used),
+        "free_gib": bytes_to_gib(usage.free),
+        "used_percent": round((usage.used / usage.total) * 100, 1),
+    }
+
+
+def read_mounts() -> list[dict[str, str]]:
+    path = Path("/proc/mounts")
+    mounts: list[dict[str, str]] = []
+
+    try:
+        for line in path.read_text().splitlines():
+            parts = line.split()
+
+            if len(parts) < 3:
+                continue
+
+            device, mount_point, filesystem = parts[:3]
+
+            mounts.append(
+                {
+                    "device": device,
+                    "mount_point": mount_point,
+                    "filesystem": filesystem,
+                }
+            )
+
+    except OSError:
+        return []
+
+    return mounts
+
+
+def collect_resource_info() -> dict[str, object]:
+    warnings: list[str] = []
+
+    load_average = read_load_average()
+    meminfo = read_meminfo()
+    mounts = read_mounts()
+
+    if load_average is None:
+        warnings.append("Could not read /proc/loadavg")
+
+    if not meminfo:
+        warnings.append("Could not read /proc/meminfo")
+
+    if not mounts:
+        warnings.append("Could not read /proc/mounts")
+
+    data = {
+        "cpu_count": os.cpu_count(),
+        "load_average": load_average,
+        "memory": get_memory_usage(meminfo),
+        "swap": get_swap_usage(meminfo),
+        "root_disk": get_root_disk_usage(),
+        "mounts": mounts,
+    }
+
+    return {
+        "success": bool(meminfo) and load_average is not None,
+        "data": data,
+        "warnings": warnings,
+    }

dev_audit/collectors/system.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import getpass
+import os
+import platform
+import socket
+from pathlib import Path
+
+
+def read_os_release() -> dict[str, str]:
+    os_release_path = Path("/etc/os-release")
+
+    if not os_release_path.exists():
+        return {}
+
+    data: dict[str, str] = {}
+
+    try:
+        for line in os_release_path.read_text().splitlines():
+            if "=" not in line:
+                continue
+
+            key, value = line.split("=", 1)
+            data[key] = value.strip().strip('"')
+
+    except OSError:
+        return {}
+
+    return data
+
+
+def read_uptime_seconds() -> float | None:
+    uptime_path = Path("/proc/uptime")
+
+    if not uptime_path.exists():
+        return None
+
+    try:
+        uptime_text = uptime_path.read_text().split()[0]
+        return float(uptime_text)
+    except (IndexError, ValueError, OSError):
+        return None
+
+
+def collect_system_info() -> dict[str, object]:
+    warnings: list[str] = []
+
+    os_release = read_os_release()
+    uptime_seconds = read_uptime_seconds()
+
+    if not os_release:
+        warnings.append("Could not read /etc/os-release")
+
+    if uptime_seconds is None:
+        warnings.append("Could not read /proc/uptime")
+
+    data = {
+        "hostname": socket.gethostname(),
+        "os_name": os_release.get("NAME", platform.system()),
+        "os_version": os_release.get("VERSION", "unknown"),
+        "kernel": platform.release(),
+        "architecture": platform.machine(),
+        "user": getpass.getuser(),
+        "shell": os.environ.get("SHELL", "unknown"),
+        "uptime_seconds": uptime_seconds,
+    }
+
+    return {
+        "success": uptime_seconds is not None and bool(os_release),
+        "data": data,
+        "warnings": warnings,
+    }