linwarden 0.13.1__tar.gz

linwarden-0.13.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linwarden contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

linwarden-0.13.1/MANIFEST.in

@@ -0,0 +1,11 @@
+include LICENSE
+include README.md
+include action.yml
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.json *.md *.sarif
+recursive-include schemas *.json
+recursive-include scripts *.py
+recursive-include tests *.py
+recursive-include tests/fixtures *
+recursive-exclude docs/checkpoints *

linwarden-0.13.1/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: linwarden
+Version: 0.13.1
+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)
+[![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.13.1`.
+- Fixture-root scanning for tests, containers, forensic copies, and offline analysis.
+- Zero runtime dependencies beyond Python 3.9+.
+
+## Quick Start
+
+From a 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.13.1` |
+| 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
+
+- PyPI trusted publishing.
+
+Contributor-ready ideas live in [docs/contributor-ideas.md](docs/contributor-ideas.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

linwarden-0.13.1/README.md

@@ -0,0 +1,261 @@
+# Linwarden
+
+[![CI](https://github.com/kingkyylian/linwarden/actions/workflows/ci.yml/badge.svg)](https://github.com/kingkyylian/linwarden/actions/workflows/ci.yml)
+[![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.13.1`.
+- Fixture-root scanning for tests, containers, forensic copies, and offline analysis.
+- Zero runtime dependencies beyond Python 3.9+.
+
+## Quick Start
+
+From a 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.13.1` |
+| 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
+
+- PyPI trusted publishing.
+
+Contributor-ready ideas live in [docs/contributor-ideas.md](docs/contributor-ideas.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).