[hapheus]

Problem

Prior to this PR, release versioning, vulnerability scanning, provenance/SBOM generation, and runtime hardening guidelines were undocumented and unverified. Users lacked guidance for running torproxy with read-only filesystems or dropped Linux capabilities in hardened production environments, and CI lacked automated vulnerability scanning.

Resolves #24

Solution

Implemented Milestone 7 tasks without breaking changes:

• M7-01 (Predictable Releases): Bumped version to 1.2.0 in pyproject.toml and added org.opencontainers.image.version="1.2.0" label in Dockerfile. Documented SemVer guarantees, upgrade paths, and instant rollback procedures in docs/releases.md.
• M7-02 (Vulnerability Scanning): Added automated Trivy vulnerability scanning to the CI gate (pr-gate.yml), and documented the vulnerability management policy, SLA, and false-positive handling in SECURITY.md.
• M7-03 (SBOM & Provenance): Enabled Buildx SBOM and provenance generation (mode=max) in publish-dockerhub.yml. Created DOCKERHUB.md and configured automated description sync.
• M7-04 (Runtime Hardening): Created docs/hardening.md and a production-ready examples/hardened-production/ configuration demonstrating read_only: true, cap_drop: [ALL], no-new-privileges: true, and scratch tmpfs mounts. Added automated tests in test_examples.py and a smoke check in CI.

Compatibility

• 100% backward compatible: Default execution mode, ports (8118, 9050, 8080), environment variables, REST endpoints, and existing Compose files remain untouched.
• Runtime hardening and read-only rootfs are fully optional and opt-in.

Tests

• Hermetic unit tests: 141 passed in 2.69s with 99.65% code coverage.
• Linter: ruff check . passed cleanly with 0 errors.
• ShellCheck: docker/start.sh, docker/healthcheck.sh, and tests/integration/verify_container.sh passed with 0 warnings.
• Example tests: tests/unit/test_examples.py validates 4 examples (17 tests) including hardened production.
• CI gate runs container smoke test, hardened container test, upgrade smoke test, and Trivy scan.

Security and Privacy

• Verified non-root user execution (torproxy).
• Clarified threat boundaries and vulnerability response policy in SECURITY.md.
• Added verified recipes for cap_drop: [ALL] and read_only: true without affecting Tor or Privoxy function.

Documentation

• Created docs/releases.md, docs/hardening.md, DOCKERHUB.md, and examples/hardened-production/README.md.
• Updated README.md and SECURITY.md.

Remaining Limitations

• Live image signing with cosign requires key/OIDC configuration on the GitHub repository.