devaudit-cli 0.3.0__py3-none-any.whl

dev_audit/command.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+def command_exists(command: str) -> bool:
+    return shutil.which(command) is not None
+
+
+def run_command(
+    command: list[str],
+    timeout: int = 5,
+) -> dict:
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+
+        return {
+            "ok": result.returncode == 0,
+            "command": " ".join(command),
+            "returncode": result.returncode,
+            "stdout": result.stdout.strip(),
+            "stderr": result.stderr.strip(),
+            "error": None,
+        }
+
+    except FileNotFoundError:
+        return {
+            "ok": False,
+            "command": " ".join(command),
+            "returncode": None,
+            "stdout": "",
+            "stderr": "",
+            "error": f"Command not found: {command[0]}",
+        }
+
+    except subprocess.TimeoutExpired:
+        return {
+            "ok": False,
+            "command": " ".join(command),
+            "returncode": None,
+            "stdout": "",
+            "stderr": "",
+            "error": f"Command timed out after {timeout}s",
+        }

dev_audit/output.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import json
+
+
+def format_duration(seconds: float | None) -> str:
+    if seconds is None:
+        return "unknown"
+
+    total_seconds = int(seconds)
+    days, remainder = divmod(total_seconds, 86400)
+    hours, remainder = divmod(remainder, 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    parts = []
+
+    if days:
+        parts.append(f"{days}d")
+    if hours:
+        parts.append(f"{hours}h")
+    if minutes:
+        parts.append(f"{minutes}m")
+    if seconds or not parts:
+        parts.append(f"{seconds}s")
+
+    return " ".join(parts)
+
+
+def print_json(result: dict[str, object]) -> None:
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+def print_system(result: dict[str, object], verbose: bool = False) -> None:
+    data = result["data"]
+
+    print("System Information")
+    print("────────────────────────")
+    print(f"Hostname      : {data['hostname']}")
+    print(f"OS            : {data['os_name']} {data['os_version']}")
+    print(f"Kernel        : {data['kernel']}")
+    print(f"Architecture  : {data['architecture']}")
+    print(f"User          : {data['user']}")
+    print(f"Shell         : {data['shell']}")
+    print(f"Uptime        : {format_duration(data['uptime_seconds'])}")
+
+    warnings = result.get("warnings", [])
+
+    if warnings:
+        print()
+        print("Warnings")
+        print("────────")
+        for warning in warnings:
+            print(f"⚠ {warning}")
+
+    if verbose:
+        print()
+        print("Raw Result")
+        print("──────────")
+        print_json(result)
+
+def print_resources(result: dict[str, object], verbose: bool = False) -> None:
+    data = result["data"]
+
+    print("Resource Usage")
+    print("────────────────────────")
+    print(f"CPU Cores      : {data['cpu_count']}")
+
+    load_average = data["load_average"]
+    if load_average:
+        print(
+            "Load Average   : "
+            f"{load_average['1_min']} "
+            f"{load_average['5_min']} "
+            f"{load_average['15_min']}"
+        )
+    else:
+        print("Load Average   : unknown")
+
+    memory = data["memory"]
+    print()
+    print("Memory")
+    print("──────")
+    print(f"Total          : {memory['total_gib']} GiB")
+    print(f"Used           : {memory['used_gib']} GiB")
+    print(f"Available      : {memory['available_gib']} GiB")
+    print(f"Used Percent   : {memory['used_percent']}%")
+
+    swap = data["swap"]
+    print()
+    print("Swap")
+    print("────")
+    print(f"Total          : {swap['total_gib']} GiB")
+    print(f"Used           : {swap['used_gib']} GiB")
+    print(f"Free           : {swap['free_gib']} GiB")
+    print(f"Used Percent   : {swap['used_percent']}%")
+
+    root_disk = data["root_disk"]
+    print()
+    print("Root Disk")
+    print("─────────")
+    print(f"Total          : {root_disk['total_gib']} GiB")
+    print(f"Used           : {root_disk['used_gib']} GiB")
+    print(f"Free           : {root_disk['free_gib']} GiB")
+    print(f"Used Percent   : {root_disk['used_percent']}%")
+
+    warnings = result.get("warnings", [])
+
+    if warnings:
+        print()
+        print("Warnings")
+        print("────────")
+        for warning in warnings:
+            print(f"⚠ {warning}")
+
+    if verbose:
+        print()
+        print("Mounts")
+        print("──────")
+        for mount in data["mounts"]:
+            print(
+                f"{mount['mount_point']} "
+                f"({mount['filesystem']}) "
+                f"← {mount['device']}"
+            )
+
+        print()
+        print("Raw Result")
+        print("──────────")
+        print_json(result)
+
+def print_network(result: dict[str, object], verbose: bool = False) -> None:
+    data = result["data"]
+
+    print("Network Information")
+    print("────────────────────────")
+
+    print("Interfaces")
+    print("──────────")
+
+    interfaces = data["interfaces"]
+
+    if interfaces:
+        for interface in interfaces:
+            print(
+                f"{interface['name']:<20} "
+                f"{interface['ipv4'] or 'No IPv4'}"
+            )
+    else:
+        print("No interfaces found")
+
+    print()
+
+    print("Default Route")
+    print("─────────────")
+
+    route = data["default_route"]
+
+    if route:
+        print(f"Gateway   : {route['gateway']}")
+        print(f"Interface : {route['interface']}")
+    else:
+        print("No default route found")
+
+    print()
+
+    print("DNS Servers")
+    print("───────────")
+
+    dns_servers = data["dns_servers"]
+
+    if dns_servers:
+        for server in dns_servers:
+            print(f"- {server}")
+    else:
+        print("No DNS servers found")
+
+    print()
+
+    print("Listening Ports")
+    print("───────────────")
+
+    ports = data["listening_ports"]
+
+    if ports:
+        for port in ports[:10]:
+            print(
+                f"{port['protocol'].upper():<5} "
+                f"{port['local_address']}"
+            )
+
+        if len(ports) > 10:
+            print(
+                f"... {len(ports) - 10} more ports hidden. "
+                f"Use --verbose to see all."
+            )
+    else:
+        print("No listening ports found")
+
+    warnings = result.get("warnings", [])
+
+    if warnings:
+        print()
+        print("Warnings")
+        print("────────")
+
+        for warning in warnings:
+            print(f"⚠ {warning}")
+
+    if verbose:
+        print()
+
+        print("All Listening Ports")
+        print("──────────────────")
+
+        for port in ports:
+            print(
+                f"{port['protocol'].upper():<5} "
+                f"{port['local_address']}"
+            )
+
+        print()
+
+        print("Raw Result")
+        print("──────────")
+
+        print_json(result)
+
+def print_devtools(result: dict[str, object], verbose: bool = False) -> None:
+    tools = result["data"]["tools"]
+
+    print("Developer Tools")
+    print("────────────────────────")
+
+    for tool in tools:
+        print()
+        print(tool["name"])
+
+        if tool["installed"]:
+            print("✓ Installed")
+
+            if tool["version"]:
+                print(f"Version : {tool['version']}")
+
+            if verbose and tool["path"]:
+                print(f"Path    : {tool['path']}")
+
+        else:
+            print("✗ Not Installed")
+
+    warnings = result.get("warnings", [])
+
+    if warnings:
+        print()
+        print("Warnings")
+        print("────────")
+
+        for warning in warnings:
+            print(f"⚠ {warning}")
+
+def print_findings(findings: list[str]) -> None:
+    if not findings:
+        print()
+        print("Audit Findings")
+        print("──────────────")
+        print("No findings detected.")
+        return
+
+    print()
+    print("Audit Findings")
+    print("──────────────")
+
+    for finding in findings:
+        print(f"⚠ {finding}")

dev_audit/status.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_COLLECTOR_FAILURE = 2
+
+
+def has_collector_failure(results: dict[str, object]) -> bool:
+    for section_result in results.values():
+        if not isinstance(section_result, dict):
+            continue
+
+        if section_result.get("success") is False:
+            return True
+
+    return False
+
+
+def determine_exit_code(
+    results: dict[str, object],
+    findings: list[str],
+) -> int:
+    if has_collector_failure(results):
+        return EXIT_COLLECTOR_FAILURE
+
+    if findings:
+        return EXIT_FINDINGS
+
+    return EXIT_OK

devaudit_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,347 @@
+Metadata-Version: 2.4
+Name: devaudit-cli
+Version: 0.3.0
+Summary: Linux system inspection and developer environment audit tool
+Author-email: Brenda Bonareri <bonarerijb24@gmail.com>
+Keywords: linux,audit,cli,diagnostics,system-monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dev-audit
+
+![CI](https://github.com/Bonbonjb/dev-audit/actions/workflows/ci.yml/badge.svg)
+
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
+![Version](https://img.shields.io/badge/version-0.3.0-green)
+![Tests](https://img.shields.io/badge/tests-44%20passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-50%25-yellow)
+
+## Project Status
+
+**Current Release:** v0.3.0
+
+### Features
+
+* Linux system inspection
+* Resource monitoring
+* Network auditing
+* Developer tool validation
+* Audit findings engine
+* JSON output support
+* Verbose output support
+* Exit code support for automation
+* GitHub Actions CI/CD
+
+### Quality Metrics
+
+* 44 passing tests
+* 50% code coverage
+* Automated CI validation
+* Semantic versioning
+* Tagged releases
+
+
+A Linux system inspection and diagnostic CLI built for Ubuntu environments.
+
+`dev-audit` collects system information, resource metrics, network configuration, and developer environment details, then evaluates the results against audit rules to identify potential issues.
+
+---
+
+## Features
+
+### System Audit
+
+* Operating system information
+* Kernel version
+* Hostname
+* Architecture
+* User and shell
+* System uptime
+
+### Resource Audit
+
+* CPU core count
+* Load averages
+* Memory utilization
+* Swap utilization
+* Root filesystem usage
+
+### Network Audit
+
+* Network interfaces
+* Default route
+* DNS configuration
+* Listening TCP and UDP ports
+
+### Developer Environment Audit
+
+* Python
+* pip
+* Git
+* Docker
+* Docker Compose
+* Node.js
+* npm
+
+### Audit Engine
+
+Detects:
+
+* Exposed SSH services
+* HTTP services listening on all interfaces
+* Inconsistent development tool installations
+* WSL-specific tool resolution issues
+
+### Output Modes
+
+* Human-readable terminal output
+* JSON output
+* Verbose diagnostics
+
+### Exit Codes
+
+| Exit Code | Meaning           |
+| --------- | ----------------- |
+| 0         | Healthy audit     |
+| 1         | Findings detected |
+| 2         | Collector failure |
+
+---
+
+## Architecture
+
+dev-audit follows a modular collector-based architecture.
+
+```text
+CLI
+ │
+ ├── System Collector
+ │      ├── OS Information
+ │      ├── Kernel Information
+ │      └── Uptime
+ │
+ ├── Resource Collector
+ │      ├── CPU Usage
+ │      ├── Memory Usage
+ │      ├── Swap Usage
+ │      └── Disk Usage
+ │
+ ├── Network Collector
+ │      ├── Interfaces
+ │      ├── DNS Servers
+ │      ├── Default Route
+ │      └── Listening Ports
+ │
+ ├── DevTools Collector
+ │      ├── Python
+ │      ├── pip
+ │      ├── Git
+ │      ├── Docker
+ │      ├── Docker Compose
+ │      ├── Node.js
+ │      └── npm
+ │
+ └── Audit Engine
+        ├── Resource Checks
+        ├── Network Checks
+        └── Environment Checks
+
+Output Layer
+ ├── Human Readable Output
+ ├── JSON Output
+ └── Exit Codes
+```
+
+### Design Goals
+
+* Modular collector architecture
+* Linux-first implementation
+* Machine-readable JSON output
+* Human-readable terminal output
+* CI/CD validated
+* Test-driven development
+* Suitable for automation and scripting
+
+## Example Output
+
+```bash
+$ dev-audit
+
+System Information
+────────────────────────
+Hostname      : ubuntu-server
+OS            : Ubuntu 24.04 LTS
+Kernel        : 6.8.0
+Architecture  : x86_64
+User          : ubuntu
+
+Resource Usage
+────────────────────────
+CPU Cores      : 8
+Load Average   : 0.10 0.12 0.08
+
+Memory
+──────
+Total          : 16.0 GiB
+Used           : 4.2 GiB
+Available      : 11.8 GiB
+
+Audit Findings
+──────────────
+⚠ SSH is listening on all interfaces.
+⚠ HTTP service exposed on all IPv4 interfaces.
+```
+
+### JSON Output
+
+```bash
+$ dev-audit --json
+```
+
+```json
+{
+  "system": {
+    "hostname": "ubuntu-server",
+    "kernel": "6.8.0"
+  },
+  "findings": [
+    "SSH is listening on all interfaces."
+  ]
+}
+```
+
+## Use Cases
+
+`dev-audit` can be used to:
+
+* Quickly inspect Linux development environments
+* Validate workstation setup before software development
+* Audit servers for exposed services and configuration issues
+* Generate machine-readable JSON reports for automation
+* Troubleshoot networking and developer tool installations
+* Perform lightweight health checks on Ubuntu systems
+
+## Installation
+
+### Clone Repository
+
+```bash
+git clone https://github.com/Bonbonjb/dev-audit.git
+cd dev-audit
+```
+
+### Create Virtual Environment
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+### Install Package
+
+```bash
+pip install -e .
+```
+
+---
+
+## Usage
+
+### Full Audit
+
+```bash
+dev-audit
+```
+
+### Run Individual Sections
+
+```bash
+dev-audit system
+dev-audit resources
+dev-audit network
+dev-audit devtools
+```
+
+### JSON Output
+
+```bash
+dev-audit --json
+```
+
+### Verbose Output
+
+```bash
+dev-audit --verbose
+```
+
+---
+
+## Example Audit Findings
+
+```text
+⚠ SSH is listening on all interfaces.
+⚠ HTTP service exposed on all IPv4 interfaces.
+⚠ npm detected but Node.js executable not found.
+```
+
+---
+
+## Running Tests
+
+```bash
+pytest
+```
+
+Current test suite:
+
+```text
+44 passing tests
+```
+
+---
+
+## Project Structure
+
+```text
+src/dev_audit/
+├── audit.py
+├── cli.py
+├── command.py
+├── output.py
+├── status.py
+└── collectors/
+    ├── system.py
+    ├── resources.py
+    ├── network.py
+    └── devtools.py
+
+tests/
+├── test_audit.py
+├── test_command.py
+├── test_network.py
+├── test_output.py
+├── test_resources.py
+├── test_status.py
+└── test_system.py
+```
+
+---
+
+## Roadmap
+
+* GitHub Actions CI
+* Coverage reporting
+* Additional audit rules
+* Package publishing
+* Extended Linux distribution support

devaudit_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+dev_audit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dev_audit/__main__.py,sha256=NMzkhEt4JrPnvOKaIX-PS41GmT7WtA8wdimlZJYB4Ro,88
+dev_audit/audit.py,sha256=6Oi2QCETVvZuA1yfyvJ0-RgiwxdAv5szDKK4BSdrO9s,1276
+dev_audit/cli.py,sha256=mBGVVT_ufyKmy88SECDiiVxroqrAO1D8TcW63RDeM68,2985
+dev_audit/command.py,sha256=ZBqdolTIUgWLWmHEeZrHPw_Td9p-umQxl6uKFeq3ivw,1233
+dev_audit/output.py,sha256=1LGoiRWbCsuupz3vI8B9H3VdHb1rcT3qclFYTaFbk3A,7297
+dev_audit/status.py,sha256=cdbbDP7aSyL4j7G28wzlweKTvEd1nlPRf9v-IC0fKvQ,605
+dev_audit/collectors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dev_audit/collectors/devtools.py,sha256=nNkRV6lCuJ5aS86V8ltCcT7NMFLRFGRF2SKXjx_NHoA,2671
+dev_audit/collectors/network.py,sha256=LrBvQNmHJ5eF1Zz0nTYwyBWo7Yw2ghg6HDkEnDLXmWo,4020
+dev_audit/collectors/resources.py,sha256=5Gc3cpaJVxF2b-a1E70y35d1FYypZL_D3jiJGw7Ixic,3706
+dev_audit/collectors/system.py,sha256=J2bzNOtI4eVGkhzEll498iGNq6maTglmixkxnEeJm68,1739
+devaudit_cli-0.3.0.dist-info/licenses/LICENSE,sha256=-7gN4WoZV6NAULFetK8ovhVGWD7_BkEt1qcTFryzWDw,1092
+devaudit_cli-0.3.0.dist-info/METADATA,sha256=xvqqCiql_fIOITr4ffThGiQ36BH6iPQDVCvnzADNX80,6631
+devaudit_cli-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+devaudit_cli-0.3.0.dist-info/entry_points.txt,sha256=3ONwyrlQeBsW4d3u6QG6NYrzSxgsDVS3kt6txVBtOu4,49
+devaudit_cli-0.3.0.dist-info/top_level.txt,sha256=RApWYjNVDZXVB3dwjgw7UHrD8ujDknaeP8T12QBA0nk,10
+devaudit_cli-0.3.0.dist-info/RECORD,,