Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
14 changes: 11 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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

Expand Down
8 changes: 7 additions & 1 deletion docs/ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,20 @@ 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).
- **Container health check.** The distroless image has no shell, so a plain `docker run` has no built-in `HEALTHCHECK`; a small `-healthcheck` mode would close that gap.
- **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
Expand Down
2 changes: 1 addition & 1 deletion docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down