Metadata-Version: 2.4
Name: sentinel-linux
Version: 0.1.0
Summary: A production-ready Linux security auditing toolkit with a Typer CLI.
Author: Sentinel Maintainers
License-Expression: MIT
Keywords: linux,security,audit,cli,hardening
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1.0,>=0.12
Dynamic: license-file

# Sentinel

**Sentinel** is a local-first Linux security auditing and hardening toolkit designed to give developers and system administrators clear, actionable insight into their system’s security posture.

It combines a CLI with a lightweight local dashboard to make Linux security simple, visible, and actionable without relying on cloud services or telemetry.

---

## Features

* **Security Scanning**

  * Open ports and exposed services
  * SSH configuration auditing
  * Firewall status and rules
  * File permission checks
  * Authentication log analysis

* **System Hardening (WIP)**

  * Safe, reversible security configurations
  * SSH hardening (disable root login, password auth)
  * Firewall setup and defaults
  * Secure system recommendations

* **Security Scoring**

  * Simple, understandable score (0–100)
  * Severity-based issue classification
  * Clear recommendations for improvement

* **Auth Log Monitoring**

  * Failed login detection
  * Brute-force attempt indicators

* **Permission Auditing**

  * World-writable file detection
  * Sensitive file misconfigurations

* **Local Dashboard (Planned)**

  * Visualize system security in real-time
  * Track trends and historical data
  * Fully local — no external connections

* **JSON Reporting**

  * Machine-readable reports
  * Easy integration with other tools

* **Privacy First**

  * No telemetry
  * No cloud dependency
  * Runs entirely on your machine

---

## Philosophy

Sentinel is built around a few core principles:

* **Local-first security** — your data stays on your system
* **Transparency over automation** — nothing changes without your consent
* **Secure defaults** — highlight real risks, not noise
* **Developer-friendly** — simple CLI, clean output, easy to extend

---

## Installation

```bash
python3 -m pip install -e .
```

## Install as a CLI

From the project root:

```bash
python3 -m pip install -e .
sentinel scan
```

## Install (Recommended)

### Using pipx

After publishing to PyPI:

```bash
sudo apt install pipx -y
pipx ensurepath
pipx install sentinel-linux
sentinel scan
```

### Local development with pipx

From the project root:

```bash
pipx install --editable .
sentinel scan
```

---

## Usage

### Run a full security scan

```bash
sentinel scan
```

### Show detailed per-module results

```bash
sentinel scan --verbose
```

### Emit JSON for automation

```bash
sentinel scan --json
```

### View system security status

```bash
sentinel status
```

### Output full JSON report

```bash
sentinel report
```

### Run in module mode

```bash
python3 -m sentinel scan
python3 -m sentinel status
python3 -m sentinel report
```

### Report storage

Sentinel writes the latest JSON report to a user-writable location:

```text
$XDG_DATA_HOME/sentinel/latest_report.json
```

If `XDG_DATA_HOME` is unset, Sentinel falls back to:

```text
~/.local/share/sentinel/latest_report.json
```

---

## Example Output

```text
[+] Checking firewall...
[+] Checking SSH configuration...
[+] Checking open ports...
[+] Checking auth logs...
[+] Checking file permissions...

Security Score: 72/100

Warnings:
- Firewall is disabled
- SSH password authentication is enabled
- Port 3306 is exposed

Recommendations:
- Enable UFW
- Disable SSH password authentication
- Restrict database ports to localhost
```

---

## Project Structure

```
sentinel/
├── sentinel/
│   ├── cli.py
│   ├── scanner.py
│   ├── scorer.py
│   ├── reporter.py
│   ├── utils.py
│   ├── modules/
│   │   ├── ports.py
│   │   ├── firewall.py
│   │   ├── ssh_audit.py
│   │   ├── auth_logs.py
│   │   └── permissions.py
│   └── dashboard/
│       └── app.py
├── tests/
├── requirements.txt
└── README.md
```

---

## Dashboard (Coming Soon)

Sentinel will include a lightweight local dashboard that provides:

* Security score visualization
* Detailed findings by category
* Historical trends
* Real-time alerts

The dashboard will run locally and consume the same reports generated by the CLI from Sentinel's user data directory.

---

## Roadmap

* [ ] Hardening commands (`sentinel harden`)
* [ ] Fail2Ban integration
* [ ] Docker/container security checks
* [ ] Systemd service auditing
* [ ] CVE/package vulnerability checks
* [ ] Dashboard UI
* [ ] Historical tracking and scoring trends

---

## Contributing

Contributions are welcome!

If you'd like to contribute:

* Open an issue for bugs or feature requests
* Submit a pull request with improvements
* Help expand detection modules

---

## Disclaimer

Sentinel provides security insights and recommendations, but it does not guarantee complete system security. Always review changes before applying hardening actions.

---

## License

MIT License

---

## Support

If you find this project useful, consider giving it a star.
