Metadata-Version: 2.4
Name: linwarden
Version: 0.14.0
Summary: Rootless Linux host inventory and hardening audit CLI.
Author: Linwarden contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/kingkyylian/linwarden
Project-URL: Documentation, https://github.com/kingkyylian/linwarden/tree/main/docs
Project-URL: Issues, https://github.com/kingkyylian/linwarden/issues
Keywords: linux,security,hardening,inventory,audit,cli,sysadmin
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy<2,>=1.13; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Dynamic: license-file

# Linwarden

[![CI](https://github.com/kingkyylian/linwarden/actions/workflows/ci.yml/badge.svg)](https://github.com/kingkyylian/linwarden/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/linwarden.svg)](https://pypi.org/project/linwarden/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Linwarden is a rootless Linux hardening scanner for CI and fleet triage. It reads ordinary system files such as `/etc/os-release`, `/etc/ssh/sshd_config`, and selected `/proc/sys` values, then produces Markdown, JSON, or SARIF artifacts without installing an agent, daemon, privileged helper, database, or network service.

The project goal is practical: give maintainers a small, auditable tool that explains risky Linux defaults without needing an agent, daemon, privileged service, external database, or network access.

## Why Linwarden

Use Linwarden when you need a fast security posture signal, not a heavyweight compliance platform.

| Need | Linwarden approach |
| --- | --- |
| CI-friendly output | JSON, Markdown, and SARIF for GitHub code scanning. |
| Low operational risk | Read-only collection from ordinary Linux files. |
| Offline analysis | Scan mounted roots, image extracts, containers, and fixtures. |
| Explainable findings | Every rule includes evidence, impact, remediation, and references. |
| Small supply chain | Zero runtime dependencies beyond Python 3.9+. |

Linwarden is not a CIS or STIG replacement. It is the lightweight first pass that tells operators what deserves attention before they reach for heavier scanners.

## Features

- Rootless collection from `/etc`, `/proc`, and procfs sysctl paths.
- Deterministic JSON output for CI pipelines and scheduled host scans.
- Markdown output suitable for GitHub job summaries and issue attachments.
- SARIF output suitable for GitHub-native security ingestion.
- JSON config support for profiles, disabled rules, and justified suppressions.
- Optional effective OpenSSH config collection through `sshd -T`, including Match context.
- Package update and host firewall posture signals where rootless files expose them.
- Package metadata freshness checks for common package manager cache markers.
- Bridge interface and bridge firewall hook posture checks for container hosts.
- Static container runtime posture checks for exposed Docker or Podman APIs and Docker group membership.
- Optional package vulnerability findings from a local JSON feed.
- Release checksum manifests with optional detached GPG signatures.
- Severity scoring with `critical`, `high`, `medium`, and `low` buckets.
- CI-friendly exit thresholds through `--fail-on`.
- Composite GitHub Action wrapper through `uses: kingkyylian/linwarden@v0.14.0`.
- Fixture-root scanning for tests, containers, forensic copies, and offline analysis.
- Zero runtime dependencies beyond Python 3.9+.

## Quick Start

Install from PyPI:

```bash
python3 -m pip install linwarden
linwarden --version
linwarden scan --format markdown
```

For an isolated CLI install:

```bash
pipx install linwarden
```

From a development checkout:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
linwarden scan --format markdown
```

Run against the included fixture:

```bash
PYTHONPATH=src python3 -m linwarden scan \
  --root tests/fixtures/linux-root \
  --format json \
  --fail-on high
```

Exit code `2` means at least one finding matched the selected threshold.

## Common Workflows

| Workflow | Command or doc |
| --- | --- |
| Local triage | `linwarden scan --format markdown` |
| CI failure threshold | `linwarden scan --format json --fail-on high` |
| GitHub code scanning | `uses: kingkyylian/linwarden@v0.14.0` |
| Mounted image scan | `linwarden scan --root /mnt/server-image --format json` |
| Effective SSH scan | `linwarden scan --sshd-mode effective --sshd-match user=deploy` |
| Tool positioning | [docs/comparison.md](docs/comparison.md) |

## CLI

```text
linwarden profiles [--format markdown|json]

linwarden scan [--root PATH] [--proc-root PATH] [--etc-root PATH] [--sys-root PATH]
               [--config PATH] [--format markdown|json|sarif]
               [--vulnerability-feed PATH] [--vulnerability-feed-format linwarden|trivy|grype|osv]
               [--sshd-mode static|effective|auto] [--sshd-binary PATH]
               [--sshd-match KEY=VALUE]
               [--output PATH]
               [--fail-on off|low|medium|high|critical]
```

Common examples:

```bash
linwarden profiles
linwarden scan --format markdown --output linwarden-report.md
linwarden scan --format json --fail-on high
linwarden scan --config linwarden.json --format sarif --output linwarden.sarif
linwarden scan --sshd-mode effective --format json
linwarden scan --sshd-mode effective --sshd-match user=deploy --sshd-match addr=203.0.113.10
linwarden scan --root /mnt/server-image --format json
linwarden scan --proc-root /host/proc --etc-root /host/etc --sys-root /host/sys --format markdown
linwarden scan --vulnerability-feed ./linwarden-vulnerabilities.json --format sarif
linwarden scan --vulnerability-feed ./trivy-report.json --vulnerability-feed-format trivy --format sarif
linwarden scan --vulnerability-feed ./grype-report.json --vulnerability-feed-format grype --format sarif
linwarden scan --vulnerability-feed ./osv-scanner-report.json --vulnerability-feed-format osv --format sarif
```

## Configuration

Linwarden accepts a zero-dependency JSON config file:

```json
{
  "profile": "router",
  "disabled_rules": ["LNX-NET-002"],
  "suppressions": [
    {
      "rule_id": "LNX-SSH-002",
      "reason": "Temporary migration host; password auth removed after cutover."
    }
  ]
}
```

Profiles:

| Profile | Behavior |
| --- | --- |
| `server` | Default for general Linux servers. No profile suppressions. |
| `workstation` | Interactive desktop or laptop posture. No profile suppressions; SSH, firewall, package, and kernel findings stay visible. |
| `router` | For hosts that intentionally route traffic. Suppresses IPv4, IPv6, and bridge forwarding findings. |
| `container` | For container or image-root scans where host-kernel sysctl values may be inherited. Suppresses kernel and filesystem sysctl findings. |

Suppressed findings remain visible in JSON and Markdown reports. SARIF output includes active findings only.

## Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | Scan completed and no selected threshold was met. |
| `1` | CLI usage error from argument parsing. |
| `2` | Scan completed and `--fail-on` threshold was met. |

## Current Rules

| Rule | Severity | Area | Summary |
| --- | --- | --- | --- |
| `LNX-SSH-001` | high | SSH | `PermitRootLogin yes` is enabled. |
| `LNX-SSH-002` | medium | SSH | `PasswordAuthentication yes` is enabled. |
| `LNX-SSH-003` | high | SSH | `PermitEmptyPasswords yes` is enabled. |
| `LNX-SSH-004` | medium | SSH | `MaxAuthTries` is above `4`. |
| `LNX-SSH-005` | medium | SSH | `AllowTcpForwarding yes` or `all` is enabled. |
| `LNX-KRN-001` | high | Kernel | `kernel.randomize_va_space=0` disables ASLR. |
| `LNX-KRN-002` | high | Kernel | `vm.mmap_min_addr` is below `65536`. |
| `LNX-KRN-003` | medium | Kernel | `kernel.kptr_restrict=0` exposes kernel pointers. |
| `LNX-FS-001` | high | Filesystem | `fs.protected_hardlinks=0` disables hardlink protection. |
| `LNX-FS-002` | high | Filesystem | `fs.protected_symlinks=0` disables symlink protection. |
| `LNX-NET-001` | medium | Network | `net.ipv4.ip_forward=1` is enabled. |
| `LNX-NET-002` | low | Network | `net.ipv4.conf.all.accept_redirects=1` is enabled. |
| `LNX-NET-003` | medium | Network | `net.ipv6.conf.all.forwarding=1` is enabled. |
| `LNX-NET-004` | low | Network | `net.ipv6.conf.all.accept_redirects=1` is enabled. |
| `LNX-NET-005` | medium | Network | Bridge IPv4 firewall hooks are disabled while bridge interfaces exist. |
| `LNX-NET-006` | medium | Network | Bridge IPv6 firewall hooks are disabled while bridge interfaces exist. |
| `LNX-NET-007` | medium | Network | A bridge interface has forwarding enabled. |
| `LNX-PKG-001` | medium | Packages | Package updates are available. |
| `LNX-PKG-002` | high | Packages | Security package updates are available. |
| `LNX-PKG-003` | medium | Packages | Package metadata is stale. |
| `LNX-PKG-004` | feed severity | Packages | A local vulnerability feed reports an affected package. |
| `LNX-FW-001` | medium | Firewall | A known host firewall is disabled. |
| `LNX-SVC-001` | medium | Services | An enabled systemd service appears externally bound. |
| `LNX-CTR-001` | high | Containers | A container runtime API is bound to non-loopback TCP. |
| `LNX-CTR-002` | high | Containers | The Docker group grants daemon-level access to non-root users. |

Rule details live in [docs/rules.md](docs/rules.md).

## Report Score

Linwarden starts each report at `100` and subtracts a fixed penalty per finding:

| Severity | Penalty |
| --- | --- |
| critical | 35 |
| high | 20 |
| medium | 10 |
| low | 3 |

The score is intentionally simple. It is a triage signal, not a compliance rating.

## Project Layout

```text
src/linwarden/
  cli.py          command line entry point
  config.py       profiles, disabled rules, and suppressions
  collectors.py   host snapshot collection
  parsers.py      small parsers for Linux files
  rules.py        built-in hardening checks
  reporters.py    JSON, Markdown, and SARIF rendering
  models.py       report data structures
tests/
  fixtures/       deterministic Linux fixture root
docs/
  architecture.md implementation overview
  configuration.md profile and suppression config
  comparison.md    positioning against adjacent Linux security tools
  contributor-ideas.md scoped contribution backlog
  github-actions.md CI and SARIF workflow examples
  launch.md      copy and checklist for public announcements
  positioning.md maintainer messaging guide
  release.md      release artifact and publishing workflow
  rules.md        rule catalog
  report-schema.md JSON report contract
schemas/
  report.schema.json machine-readable JSON report schema
```

## Development

```bash
make test
make compile
make lint
make typecheck
make smoke
make smoke-sarif
make check
```

Use `make check PYTHON=.venv/bin/python` when running through a project virtualenv.

No network services or privileged permissions are required for the test suite.

## Security Model

Linwarden is read-only by default. It does not modify host state, load kernel modules, call package managers, or send telemetry. Reports can contain host configuration details, so treat generated artifacts as operationally sensitive.

## Known Limits

- Static SSH mode reads `sshd_config` plus simple `Include` directives; `Match` behavior may differ from effective OpenSSH config.
- Effective SSH mode executes `sshd -T`; use it only when scanning the live host intentionally.
- Package metadata age relies on local cache marker mtimes and does not call package manager commands.
- Package vulnerability findings require an explicit local JSON feed and never fetch remote CVE data.
- Bridge posture checks rely on procfs and sysfs files inside the scanned root; missing bridge data is treated as unknown.
- Firewalld and nftables service state is inferred from systemd enablement markers when present; config-only detection leaves enabled state unknown.
- Enabled systemd service exposure detection is static and only flags common wildcard bind options in service unit `ExecStart` lines.
- Container runtime posture checks only report explicit static evidence from config, group, or enabled unit files; missing runtime files are unknown, not safe.
- Missing files are treated as absent data so scans can run in containers and fixture roots.
- Linwarden is a hardening triage tool, not a full CIS or DISA STIG compliance scanner.

Please report vulnerabilities using [SECURITY.md](SECURITY.md).

## Roadmap

- Fixture-backed distro coverage for package metadata and firewall posture.
- Static container runtime signals only when evidence is reliable and rootless.
- Release checks that keep GitHub artifacts, attestations, and PyPI installs verifiable.

Contributor-ready ideas live in [docs/contributor-ideas.md](docs/contributor-ideas.md).

## License

MIT. See [LICENSE](LICENSE).
