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
