diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 81910aa..6598cc2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -18,7 +18,7 @@ body: id: input attributes: label: Smallest input that reproduces it - description: Use inert values only (example.com, *.invalid, 192.0.2.0/24). Never include real hosts or secrets. + description: Use inert values only (example.com, *.invalid, 192.0.2.0/24). Never include real hosts or secrets. For a wrong verdict, the output of `logshield check` (or `logshield check -json`) for the payload is the best reproduction; its output is defanged, so it is safe to paste. render: text validations: required: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 74d49dd..b594c20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,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, roadmap, deployment guide and bug-report template now point to `logshield check`, the Grafana dashboard and the challenge page. - README: screenshots of `logshield check` runs from the lab, as a proof of concept. - README: a plain-language "At a glance" section (what it is, who it is for, how you use it) and common questions. Roadmap: measured results next to the targets, a corrected coverage floor, and an "After 0.1" list. - 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. diff --git a/README.md b/README.md index ec57618..3f88ef8 100644 --- a/README.md +++ b/README.md @@ -60,8 +60,15 @@ security engineers who need a documented compensating control for them. blocks nothing, so you can check it against your real traffic. 4. Switch to **block mode**. Attack requests now get a `403` and never reach the application. -5. Watch the [metrics and logs](docs/observability.md), and keep a plan to patch - or retire the application, because this is a stopgap. +5. Watch the [metrics and logs](docs/observability.md) (a ready-made + [Grafana dashboard](examples/grafana/README.md) is included), and keep a plan + to patch or retire the application, because this is a stopgap. + +**See it work in two minutes, with nothing to deploy:** run +[`logshield check`](#try-a-payload-without-a-proxy) on a payload to see the +verdict and why, or start the one-command +[Grafana demo](examples/grafana/README.md) to watch blocked requests, detections +by rule and latency on a live dashboard. A longer walk-through, with deployment patterns for systemd, Kubernetes and nginx, is in [docs/deployment.md](docs/deployment.md). @@ -95,7 +102,8 @@ payloads only, and it does not replace a WAF. **I found a bypass.** Please report it privately, as described in [SECURITY.md](SECURITY.md). Confirmed bypasses become regression tests and are -credited. +credited. Want to try to find one? [docs/challenge.md](docs/challenge.md) says +what counts and how to test an idea in five minutes. ## What it does not do diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 69cc7ff..95a6bee 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -51,7 +51,7 @@ These started as goals and were then confirmed by measurement (details in the Candidates, roughly in order of value. None is promised. -- **Outside review.** Invite someone who knows Log4j or OT security to try to bypass it; every confirmed bypass becomes a corpus entry. +- **Outside review.** The invitation is published ([challenge](challenge.md)); the first independent report is still to come. Every confirmed bypass becomes a corpus entry. - **Wider validation.** Run the lab against more Log4j versions (such as 2.15 and 2.16) and more JDKs, and extend the differential to other logging paths. - **Measurements still missing.** Memory under concurrent load and behaviour on production-shaped traffic ([performance](performance.md)). - **Control self-test canary** (Step 4). @@ -59,6 +59,12 @@ Candidates, roughly in order of value. None is promised. - **SLSA Build Level 3**, by moving the release build into an isolated reusable workflow ([assurance](assurance.md)). - **A second maintainer**, which also raises the Code-Review and OpenSSF scores. +## Done since 0.1.0 + +- `logshield check`, to explain the verdict for one payload without a proxy. +- A Grafana dashboard on the documented metrics, with a one-command demo. +- A public challenge page for independent testers ([challenge](challenge.md)). + ## Working agreement One sub-step at a time. Each is implemented, reported, and reviewed before the diff --git a/docs/deployment.md b/docs/deployment.md index 46276f8..d0b599e 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -16,7 +16,7 @@ terminator) and the application it protects, and make the application reachable ## First rollout 1. Start in **monitor** mode (the default). Nothing is blocked; every verdict is logged and counted. -2. Watch `logshield_requests_total` and the logs for a few days of real traffic. Any `malicious` verdict on traffic you recognise as legitimate is a false positive worth a report. +2. Watch `logshield_requests_total` and the logs for a few days of real traffic (the [Grafana dashboard](../examples/grafana/README.md) shows "Would be blocked / s", the number to watch before you enforce). Any `malicious` verdict on traffic you recognise as legitimate is a false positive worth a report. To see why a specific request was flagged, replay its suspicious part through `logshield check` ([proxy](proxy.md#explaining-a-verdict-logshield-check)). 3. Switch `mode` to `block`. Consider `block_suspicious` once you have seen what your traffic produces for `suspicious` (see [the hardened profile](configuration.md)). 4. Alert on `blocked` events and on any rise in `suspicious`.