From ab0f616edbefda070d93ffdba23a19ffe185b01c Mon Sep 17 00:00:00 2001 From: Pranav Verma Date: Sat, 17 Oct 2026 14:46:02 +0000 Subject: [PATCH] Update the README and release steps for v0.1.0 --- CHANGELOG.md | 1 + README.md | 54 +++++++++++++++++++++++++++++++++++++++++------ docs/releasing.md | 6 +++--- 3 files changed, 52 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e268020..f8c6617 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ follow [Semantic Versioning](https://semver.org/) from the first tagged release. - CISA secure-by-design mapping in `docs/assurance.md`, including why monitor mode is the default. ### Changed +- README: v0.1.0 status, install section (container and release archive), a "What it does not do" section, governance and citation links. `docs/releasing.md` describes the signed-tag, pull-request release flow. - The startup message that says monitor mode does not block is now a warning, so it shows at `-log-level warn`. - `SECURITY.md` supported-versions table; `docs/releasing.md` states that breaking changes may land in a minor release below 1.0. diff --git a/README.md b/README.md index 6f61b4c..63b41e8 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,29 @@ what Log4j would see in each request, and blocks exploit attempts before they reach the host. It is a **compensating control**, not a fix: patch, remove `JndiLookup`, or retire the host as soon as you can. -> **Status: pre-release.** The inspection engine and the proxy (HTTP/1.1, HTTPS and HTTP/2, -> metrics, health checks, configuration) are heavily tested, and the detection corpus has -> been validated in a lab against real Log4j 2.14.1 (107 of 107 JNDI attempts caught, 0 -> misses, 0 false positives; see [the lab report](docs/lab-report.md)). There is no tagged -> release yet, so pin a commit and test in monitor mode before relying on it. See the -> [roadmap](docs/ROADMAP.md). +> **Status: v0.1.0, first stable release.** The inspection engine and the proxy +> (HTTP/1.1, HTTPS and HTTP/2, metrics, health checks, configuration) are heavily +> tested, and the detection corpus was validated in a lab against real Log4j 2.14.1 +> (107 of 107 JNDI attempts caught, 0 misses, 0 false positives; see +> [the lab report](docs/lab-report.md)). Releases are signed, reproducible and +> carry build provenance and an SBOM ([verify them](docs/releasing.md)). Below 1.0 +> the public surface may still change in a minor release, always noted in the +> [changelog](CHANGELOG.md). Start in monitor mode before relying on it. + +## What it does not do + +Read this before deploying. LogShield is a compensating control for one attack +class, not a substitute for patching. + +- It protects only traffic that **crosses the proxy**. Other ports, other + protocols (syslog, SMTP, LDAP, message queues) and internal pivots need network + segmentation. +- It cannot see **second-order injection**: data stored earlier and logged later + by another component. +- Any signature-style control can miss an **encoding it does not model**. The + [threat model](docs/threat-model.md) lists the known gaps. +- A fresh install is in **monitor mode**: it records and counts, it does not + block, until you switch to `-mode block` ([why](docs/assurance.md#cisa-secure-by-design)). ## Why a proxy, and why not just a regex @@ -44,6 +61,25 @@ multipart parts, and Basic or Bearer credentials. LogShield therefore: The proxy then guarantees that **what it forwards is exactly what it inspected**. +## Install + +Pick one. Every release is signed and attested; the +[verification commands](docs/releasing.md#verifying-a-download) take a minute. + +```sh +# Container: distroless, non-root, multi-arch. Pin the digest in production. +docker run --rm -p 8080:8080 \ + -e LOGSHIELD_UPSTREAM=http://192.0.2.10:8081 \ + ghcr.io/turlafsb/logshield:v0.1.0 + +# Static binary (Linux, macOS, Windows; amd64 and arm64): download from the +# Releases page, then +tar xzf logshield_v0.1.0_linux_amd64.tar.gz +./logshield_v0.1.0_linux_amd64/logshield -version +``` + +Or build from source (Go 1.24 or newer), as below. + ## Quick start ```sh @@ -205,6 +241,7 @@ test against systems you do not own or have written authorization to test. | Load and latency report | [docs/load-report.md](docs/load-report.md) | | Metrics, health checks, overload, Prometheus and Sigma rules | [docs/observability.md](docs/observability.md) | | Roadmap and changelog | [docs/ROADMAP.md](docs/ROADMAP.md), [CHANGELOG.md](CHANGELOG.md) | +| Project governance, security policy, support | [GOVERNANCE.md](GOVERNANCE.md), [SECURITY.md](SECURITY.md), [SUPPORT.md](SUPPORT.md) | ## Development @@ -223,6 +260,11 @@ make vuln # govulncheck See [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and [GOVERNANCE.md](GOVERNANCE.md). +## Citing + +If you use LogShield in research, cite it with the metadata in +[CITATION.cff](CITATION.cff) (GitHub shows a "Cite this repository" button). + ## Security To report a vulnerability, use GitHub private vulnerability reporting as diff --git a/docs/releasing.md b/docs/releasing.md index b52df36..7e07de7 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -69,8 +69,8 @@ rather than by tag. ## Cutting a release (maintainers) -1. `main` is green. Run `scripts/repo-settings.sh --protect` once, before the first release, so `main` requires pull requests and passing checks. -2. Move the `[Unreleased]` entries in `CHANGELOG.md` under a new `## [x.y.z] - date` heading. -3. Tag the merge commit and push the tag: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`. Use a suffix such as `-rc.1` for a pre-release (no `latest` image tag, marked as a pre-release). +1. `main` is green and protected: every change, including the release notes, goes through a pull request (`scripts/repo-settings.sh --protect` recreates the ruleset). +2. In a pull request, move the `[Unreleased]` entries in `CHANGELOG.md` under a new `## [x.y.z] - date` heading, and squash-merge it. GitHub signs the merge commit. +3. Pull `main`, then create a **signed** tag on that merge commit and push it: `git tag -s vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`. Use a suffix such as `-rc.1` for a pre-release (no `latest` image tag, marked as a pre-release). The workflow refuses tags that are not on `main`. 4. The workflow tests, builds, signs, attests, pushes the image and creates the GitHub release. If anything fails nothing is published half-way: re-run the workflow, or delete the tag and the draft artifacts and start again. 5. Verify the release with the commands above before announcing it.