Skip to content

docs: answer the OpenSSF Best Practices criteria in .bestpractices.json - #370

Merged
DeepDiver1975 merged 2 commits into
mainfrom
docs/bestpractices-badge
Sep 16, 2026
Merged

DeepDiver1975 merged 2 commits into
mainfrom
docs/bestpractices-badge

Conversation

@DeepDiver1975

Copy link
Copy Markdown
Contributor

Summary

The second half of the OpenSSF work. The Scorecard badge reports
CII-Best-Practices as 0 simply because the project has never been registered,
and that check is worth 5 points on its own. More to the point, the badge is a
published checklist a Kreisbrandinspektion can actually read, rather than a
single number.

Registering needs a GitHub login and stays a human step. Answering the 67
criteria does not: the BadgeApp reads a .bestpractices.json from the
repository root and offers its contents as automation proposals, which its own
documentation prefers over POSTing to the API. Nothing is stored until you
review and save, so this file proposes, it does not assert on your behalf.

What is in the file

61 Met, 5 N/A, 1 Unmet. All 43 MUST criteria answered. Every justification
carries an evidence URL, and every one of those URLs was fetched and returns
200.

I validated every key against the BadgeApp's own criteria.yml rather than a
summary of it. That caught a real error in my working draft: the criterion is
build_floss_tools, not build_floss. This matters more than a typo
normally would, because an unrecognised key is silently ignored — the file would
have looked complete and quietly done nothing.

The five N/A answers

Each checked against the na_allowed flag in criteria.yml, so none of them is
an invalid answer:

Criterion Why
crypto_password_storage No accounts, no login, no password authentication. Nothing to store.
vulnerability_report_response No report in the last six months, which is the case the criterion names.
release_notes_vulns No vulnerability has been fixed, so no release note has had to name one. This one also sets na_justification_required, so the justification is mandatory and is present.
dynamic_analysis_unsafe C# is memory-safe; no unsafe blocks, no own native code.
dynamic_analysis_fixed No dynamic analysis runs, so it has no findings.

The one Unmet

dynamic_analysis, which is SUGGESTED and does not block the passing badge. Its
justification names where fuzzing would matter first rather than dressing up the
gap: the .fwincident and master-data JSON parsers, the two components that read
input the user did not author.

Two answers that are yours, not mine

know_secure_design and know_common_errors are assertions about the
maintainer, and neither permits N/A. I pre-filled both as Met with justifications
built from evidence that actually exists in the repo — the threat model in
SECURITY.md that names its own limitations, the deliberate removal of the
accept-any-certificate fallback, least-privilege workflow tokens, sanitised
attachment names, the scoped Android FileProvider. Please read those two
before you save them.

Your part, after this merges

  1. Log in at bestpractices.dev with GitHub.
  2. Add the project with repo URL https://github.com/CodeForFire/lagebuch.
  3. In each section press Save (and continue) 🤖. The robot reads this file
    and fills the section in.
  4. Review, adjust anything you disagree with, save.
  5. Send me the numeric project ID and the badge goes into the README next to the
    Scorecard one.

Expected effect on Scorecard: CII-Best-Practices 0 to 5, which together with
Maintained and SAST settling on their own should take the aggregate from 6.3
to roughly 7.4.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PXhXSh2pae9WnaACYUUe3V

The Scorecard badge reports CII-Best-Practices as 0 because the project has
never been registered. Registration needs a GitHub login and stays a human
step, but the 67 criteria do not have to be typed into a web form: the BadgeApp
reads a .bestpractices.json from the repository root and offers it as
automation proposals, which its own documentation prefers over POSTing to the
API. Nothing is stored until the maintainer reviews and saves.

Every key was validated against the BadgeApp's own criteria.yml rather than a
summary of it. That caught a real error in the working draft — the criterion is
build_floss_tools, not build_floss — which matters because an unrecognised key
is silently ignored, so the file would have looked complete and done nothing.

61 Met, 5 N/A, 1 Unmet. All 43 MUST criteria are answered.

The five N/A answers were each checked against the na_allowed flag in
criteria.yml, and release_notes_vulns additionally carries the justification its
na_justification_required flag demands:

- crypto_password_storage: no accounts, no login, no stored passwords
- vulnerability_report_response: no report in the last six months
- release_notes_vulns: no vulnerability has been fixed, so none has been named
- dynamic_analysis_unsafe: C# is memory-safe, no unsafe blocks, no own native code
- dynamic_analysis_fixed: no dynamic analysis runs, so it has no findings

The single Unmet is dynamic_analysis, which is only SUGGESTED and does not block
the passing badge. Its justification says where fuzzing would matter first
rather than dressing the gap up: the .fwincident and master-data JSON parsers,
the two components that read input the user did not author.

Every URL cited in a justification was fetched and returns 200.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PXhXSh2pae9WnaACYUUe3V
Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>
@DeepDiver1975

Copy link
Copy Markdown
Contributor Author

@claude review

@claude

claude Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

Claude finished @DeepDiver1975's task in 1m 55s —— View job


Review: docs: answer the OpenSSF Best Practices criteria in .bestpractices.json

  • Gather context (PR diff, CLAUDE.md/AGENTS.md instructions)
  • Read .bestpractices.json in full
  • Validate structure/keys and cross-check factual claims against the repo
  • Spot-check evidence for know_secure_design/know_common_errors (the two "yours, not mine" answers)
  • Post review feedback

Summary

This is a pure-data docs PR (one JSON file, no src/ changes, so no CHANGELOG entry is required and no screenshots apply per AGENTS.md). I spot-checked the claims that are easy to get wrong and they hold up:

  • .editorconfig:11-17 confirms the CA2007/CA1716 suppression rationale referenced in warnings_fixed_justification (line 91).
  • SECURITY.md does name its own limitations explicitly (self-asserted operator identity, PIN-as-trust-boundary), backing know_secure_design_justification (line 95).
  • src/LageBuch.Sync/RemoteIncidentSession.cs has a real ServerCertificateCustomValidationCallback, consistent with the "removed accept-any-certificate fallback" claim.
  • The Android FileProvider is scoped (file_paths.xml, AndroidManifest.xml), backing know_common_errors_justification (line 97).
  • IncidentHostController.cs:51 uses RandomNumberGenerator.GetInt32 for the share PIN, matching crypto_random_justification (line 115), and no System.Random/unsafe usage exists in src/.
  • Directory.Build.props does set the analysis knobs referenced in warnings_justification/warnings_fixed_justification.

So the two maintainer-authored assertions are well-evidenced, not just plausible-sounding text.

Minor nit

  • vulnerabilities_fixed_60_days_justification (line 121) says "Dependabot covers five package ecosystems weekly." .github/dependabot.yml actually configures 5 update blocks across 3 ecosystem types (github-actions, docker, nuget — the latter repeated three times for different directories). Worth rewording to "five update configurations across three ecosystems" (or similar) so a reviewer on bestpractices.dev doesn't misread it as 5 distinct ecosystems. Low stakes — doesn't affect Met/Unmet status either way.
    Fix this →

One judgment call worth a second look

  • crypto_password_storage_status: N/A (line 112) — reasoning is that the share PIN is ephemeral, in-memory, never persisted. That's a defensible N/A since nothing is stored, but the PIN is still used as an authentication secret compared over the wire (per SECURITY.md's "PIN plus network reachability is the entire access-control boundary"). If the BadgeApp reviewer reads the criterion as covering any authentication secret rather than strictly "stored passwords," they may push back and ask for Met with a note on how the PIN comparison is done (constant-time compare, TLS-only transmission, etc.) instead of N/A. Not a blocker — just flagging it as the one answer most likely to get a comment during human review on bestpractices.dev, alongside know_secure_design/know_common_errors which the PR description already calls out for a careful read.

Everything else

Structurally sound: 67 status/justification pairs (61 Met, 5 N/A, 1 Unmet, matching the PR description exactly), every justification carries an evidence URL, and the build_floss_tools key (not build_floss) is used correctly per the description's own note about the BadgeApp silently ignoring unrecognized keys. I could not reach raw.githubusercontent.com from this sandbox to re-validate every key name and na_allowed/na_justification_required flag against criteria.yml directly (network access to that host wasn't permitted here), so that specific cross-check relies on the author's stated diligence rather than my own independent confirmation — worth being aware of, though nothing I found contradicts it.

No code changes requested; this looks ready to merge pending the maintainer's own read-through of know_secure_design/know_common_errors as the PR description requests.

Two points from the review on #370.

The Dependabot claim was wrong. .github/dependabot.yml has five update blocks
but only three distinct ecosystems: github-actions, docker, and nuget repeated
across three package directories. Calling that "five package ecosystems"
overstated the coverage to anyone checking, so it now says what is actually
configured.

crypto_password_storage stays N/A. The criterion's own rationale in the
BadgeApp's criteria.yml is explicit that it covers storing passwords for
authenticating external users, and credentials the software holds to
authenticate itself elsewhere are deliberately out of scope. Lagebuch stores no
passwords at all, so there is nothing for it to apply to.

The review's point still stands that a human reviewer may read "authentication
secret" more broadly and ask about the share PIN, so the justification now
answers that before it is asked: generated per session with the platform CSPRNG,
memory only, never written to disk, discarded with the session, carried only
inside TLS, and brute force answered by per-source-IP exponential backoff ahead
of routing. It links SECURITY.md, which says plainly that the PIN plus network
reachability is the whole access-control boundary.

No status changed. Still 61 Met, 5 N/A, 1 Unmet, re-validated against
criteria.yml.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PXhXSh2pae9WnaACYUUe3V
Signed-off-by: Thomas Müller <1005065+DeepDiver1975@users.noreply.github.com>
@DeepDiver1975

Copy link
Copy Markdown
Contributor Author

Both points addressed in 8da4c14.

The Dependabot nit was a real error, thank you. .github/dependabot.yml has
five update blocks but only three distinct ecosystems: github-actions,
docker, and nuget repeated across three package directories. "Five package
ecosystems" overstated the coverage to anyone checking. It now reads "five
update configurations covering three ecosystems, GitHub Actions, Docker and
NuGet, the last across three separate package directories."

crypto_password_storage stays N/A, and I went to the source to be sure.
The criterion's own rationale in the BadgeApp's criteria.yml is explicit:

Sometimes software needs to have a credential, such as a password, to
authenticate it to other systems; those are intentionally out of scope for
this criterion, because in many cases it's not possible to store them as
iterated hashes using per-user salt.

The criterion is about storing passwords for authenticating external users.
Lagebuch stores none, so it has nothing to apply to, and na_allowed is set for
it.

That said, your point stands that a human reviewer may read "authentication
secret" more broadly and ask about the share PIN. So the justification now
answers it before it is asked: generated per session with
RandomNumberGenerator.GetInt32, memory only, never written to disk, discarded
with the session, carried only inside TLS, and brute force answered by
per-source-IP exponential backoff in middleware ahead of routing rather than by
a longer secret. It links SECURITY.md, which states plainly that the PIN plus
network reachability is the whole access-control boundary. Changing it to Met
would be worse, because it would assert a hashing practice for something that is
never stored.

No status changed: still 61 Met, 5 N/A, 1 Unmet.

On the cross-check you could not run. You flagged that
raw.githubusercontent.com was unreachable from your sandbox, so the key-name
and na_allowed validation rested on my say-so. Fair, and worth closing rather
than leaving as trust. That check is a script, not an eyeball: it loads the
BadgeApp's criteria.yml, rejects any key absent from the level-0 set, rejects
N/A where na_allowed is unset, rejects a missing justification where
na_justification_required is set, and rejects any MUST left at ? or Unmet.
Its output on the current file:

OK: 67 criteria answered, all keys canonical.
    43 MUST criteria, none left unanswered.
    status mix: {'Met': 61, 'N/A': 5, 'Unmet': 1}

That is also how the build_floss_tools versus build_floss error was caught
before it shipped, which is the failure mode worth guarding: an unrecognised key
is silently ignored, so a wrong name produces a file that looks complete and
does nothing.

@DeepDiver1975
DeepDiver1975 merged commit fa68882 into main Sep 16, 2026
6 checks passed
@DeepDiver1975
DeepDiver1975 deleted the docs/bestpractices-badge branch September 16, 2026 21:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant