diff --git a/CHANGELOG.md b/CHANGELOG.md index e4d0336..f1fcf74 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ follow [Semantic Versioning](https://semver.org/) from the first tagged release. ## [Unreleased] +### Added +- `GOVERNANCE.md`, and a documented advisory and CVE process in `SECURITY.md`. + +### Changed +- `SECURITY.md` supported-versions table; `docs/releasing.md` states that breaking changes may land in a minor release below 1.0. + ## [0.1.0] - 2026-10-17 First stable release. It is the 0.1.0-rc.1 candidate (below) plus the TLS change listed here, proven end to end by the release pipeline and by the lab (107 of 107 real Log4j JNDI lookups flagged, no miss, leak or false positive). Verify what you download as described in [docs/releasing.md](docs/releasing.md), run in monitor mode first, and read [docs/threat-model.md](docs/threat-model.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 025c583..19a17bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,8 +27,8 @@ make integration # proxy in front of real Node, Python and JDK backends ``` Commits should be small and focused, with an imperative subject line -(`engine: bound decode depth`). Open a pull request against `main`; CI must be -green. +(`engine: bound decode depth`). Open a pull request against `main`; `main` is protected, so every change +merges through a pull request with green CI (squash merge, linear history). ## Reporting security issues diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..9a4bfb6 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,43 @@ +# Governance + +LogShield is a small, maintainer-led project. This page says who decides what, +so contributors and adopters know what to expect. + +## Roles + +- **Maintainer** ([@TurlaFSB](https://github.com/TurlaFSB)): owns the roadmap, + reviews and merges changes, cuts releases, and handles security reports. +- **Contributor**: anyone who opens an issue or a pull request. Contributors + follow [CONTRIBUTING.md](CONTRIBUTING.md) and the + [Code of Conduct](CODE_OF_CONDUCT.md). + +New maintainers are added by invitation of the current maintainer, after a +sustained record of good changes and reviews. The rights that matter are +repository admin, release tagging and access to private vulnerability reports. + +## How decisions are made + +- Changes go through pull requests against `main`. The branch ruleset requires + passing CI (lint, tests, vulnerability and supply-chain checks); the history + stays linear. +- Design decisions with lasting consequences are recorded as ADRs in + [docs/adr](docs/adr). A change that breaks the public surface described in + [docs/releasing.md](docs/releasing.md) needs an ADR or a changelog entry that + explains it. +- Detection changes need tests, and bypass fixes need a corpus entry. Evidence + decides: a rule that cannot show its false-positive rate is not merged. +- Disagreements are settled on the pull request or issue, in public and on the + technical merits. The maintainer has the final say. + +## Releases and security + +Releases are cut only by tagging a commit on `main`; the signed, reproducible +pipeline in [docs/releasing.md](docs/releasing.md) does the rest. Vulnerability +reports follow [SECURITY.md](SECURITY.md). + +## Continuity + +There is currently one maintainer. To keep the project usable if that changes: +everything needed to build, test, release and verify is in this repository and +its CI; there are no secrets to hand over, because releases are signed keylessly +by the workflow itself; and the repository can be forked and rebuilt by anyone. diff --git a/README.md b/README.md index 3887a81..6f61b4c 100644 --- a/README.md +++ b/README.md @@ -221,7 +221,7 @@ make eval # regenerate the evaluation report make vuln # govulncheck ``` -See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). +See [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and [GOVERNANCE.md](GOVERNANCE.md). ## Security diff --git a/SECURITY.md b/SECURITY.md index 6e10e18..50ee506 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -5,9 +5,16 @@ Responsible reports are welcome and appreciated. ## Supported versions -LogShield is pre-release. Only the latest release candidate or release, and the -latest commit on `main`, are supported. After `v1.0.0`, the latest minor release -line receives security fixes. +| Version | Security fixes | +|---|---| +| Latest release (currently the 0.1 line) | Yes | +| Older releases | No: upgrade to the latest release | +| `main` | Best effort, the fix lands here first | + +LogShield is below 1.0, so the latest release is the only supported line. From +`v1.0.0`, the latest minor release of the latest major line receives security +fixes. Releases are signed and attested; see +[docs/releasing.md](docs/releasing.md) to verify what you run. ## Reporting a vulnerability @@ -54,6 +61,21 @@ Out of scope: This is a student-maintained project, so these are good-faith targets rather than contractual guarantees. +## Advisories and CVE identifiers + +A confirmed vulnerability is published as a GitHub Security Advisory on this +repository, with a CVE identifier requested through GitHub (a CNA) when the +issue affects released versions. The advisory names the affected and fixed +versions and credits the reporter. The fix is also recorded under **Security** +in [CHANGELOG.md](CHANGELOG.md). + +## Good-faith research + +Testing LogShield on your own systems, or in a lab you control, is welcome. We +will not pursue anyone who reports a vulnerability in good faith, stays within +the scope above, avoids harming others' data or services, and gives us the +chance to fix it before public disclosure. + ## Disclosure We follow coordinated disclosure. We ask for up to 90 days to fix a confirmed diff --git a/docs/releasing.md b/docs/releasing.md index 05c78d2..b52df36 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -10,6 +10,11 @@ that the version number protects is: - rule IDs (`LSH-xxxx`) and their meaning (severity, mandatory or not); - the verdict semantics: what `malicious` and `suspicious` mean, and the HTTP behaviour of block, monitor and fail-closed. +Below 1.0 the promise is weaker, on purpose: a breaking change to any of these +may land in a **minor** release (`0.x`), always listed under **Changed** or +**Removed** in the changelog, and never in a patch release. From `1.0.0` the +rules below apply in full. + A change that breaks any of these is a **major** release. New rules, new decodings, new settings and new metrics are **minor**. Detection can only get stricter within a major version, apart from false-positive fixes, which are