OpenSSF Best Practices — status & answer canon¶

Single source of truth for the OpenSSF Best Practices Badge application of legal-text-mcp-de. Use this document when filling in or refreshing answers on bestpractices.dev/projects/12860.

Live status snapshot¶

Pulled from the public JSON endpoint (https://www.bestpractices.dev/projects/12860.json):

Tier	Progress	Notes
Passing	100 %	Awarded.
Silver	100 %	Awarded.
Gold	78 %	3 structural blockers; see "Gold pathway" below.
OSPS Baseline	not yet	Separate 2025 track (OSPS-AC / -BR / -DO / -GV / -LE / -QA / -SA / -VM / -VM-*). Application pending.

Counts (Best Practices tiers): 126 Met / 0 N/A / 3 Unmet / 67 unanswered (the 67 are the OSPS Baseline criteria, not the Gold tier).

Project metadata answers¶

Use these verbatim on the application form.

Field	Answer
`homepage_url`	`https://klein-business.github.io/legal-text-mcp-de/`
`repo_url`	`https://github.com/klein-business/legal-text-mcp-de`
`report_url`	`https://github.com/klein-business/legal-text-mcp-de/security/advisories`
Licence	Apache-2.0
Primary language	Python (3.12 / 3.13)

Basics¶

Basic project website content¶

The project's main website is the GitHub repository and the docs site at https://klein-business.github.io/legal-text-mcp-de. Both describe what the software does, allow users to view contents, and allow users to view recent changes.

FLOSS licence¶

Apache License 2.0. See LICENSE.

Documentation¶

README, documentation site (versioned via mike), CONTRIBUTING (with first-contribution onramp and architecture tour), SECURITY, Versioning policy, Threat model.

Other project basics¶

Public version-control repository on GitHub.
Public issue tracker on GitHub + Discussions.
Welcoming environment: Contributor Covenant 2.1.

Change control¶

Public version-controlled source repository¶

GitHub. Full history preserved; tags are signed via keyless OIDC (cosign + Sigstore).

Unique version numbering¶

Strict SemVer 2.0.0; releases tagged vMAJOR.MINOR.PATCH. Current release: v2.1.1.

Release notes¶

CHANGELOG.md follows Keep a Changelog 1.1.0. Per-release notes generated by release-please and verified against the SLSA-3 provenance attached to every tag.

Reporting¶

Bug-reporting process¶

Public GitHub Issues with templates for bug reports and feature requests. Response targets documented in SUPPORT.md.

Vulnerability-reporting process¶

GitHub Security Advisories with martin@klein.business as the backup channel. SLA: 5 business days acknowledgement, 90 days coordinated disclosure. See SECURITY.md.

Quality¶

Working build system¶

uv build produces sdist and wheel deterministically. CI verifies on every PR (Build (sdist + wheel) job).

Automated test suite¶

547 tests (tests/) covering MCP tools, HTTP API, CLI, source adapters, search, citation parsing, and integration smoke-tests. Coverage measured by pytest-cov and enforced via [tool.coverage.report] fail_under = 86 in pyproject.toml (combined statement + branch). Statement-only sits at 90.1 % and branch-only at 80.0 % — both above the Gold-tier floors.

New tests for new functionality¶

Documented in CONTRIBUTING.md; enforced by review. Pattern: every new MCP tool / HTTP route / CLI subcommand ships with at least one test in the matching tests/test_* file.

Warning flags¶

ruff enforces lint rules and formatting. mypy --strict is enforced in CI on seven modules: config, http_models, legal_texts.errors, legal_texts.models, legal_texts.sources, cli.*, and http_api. Together these cover the entire user-facing API surface (CLI + HTTP + shared models). The remaining modules run under a warning-gate (continue-on-error: true) that surfaces issues without blocking CI; ratchet to strict continues module-by-module.

Security¶

Knowledge of secure design¶

Threat model published at docs/operations/threat-model. Maintainer has direct experience in secure software design.

Use basic good cryptographic practices¶

The project does not implement cryptography; it consumes well-vetted cryptographic primitives via Sigstore cosign (signing), SLSA-3 attestations (provenance), and SHA-256 digests pinning the corpus archive in deployment/Dockerfile.hosted.

Secured delivery against MITM and package modification¶

HTTPS for all source and release distribution. PyPI Trusted Publisher + PEP 740 attestations on every wheel/sdist. GHCR images signed via cosign keyless + SBOM attestations (cyclonedx). The Dockerfile.hosted pins by image digest (@sha256:…), not tag.

Publicly known vulnerabilities¶

Dependabot weekly scans on pip, github-actions, and docker ecosystems + CodeQL SAST + Trivy image scan. Known issues tracked as GitHub Security Advisories.

Analysis¶

Static analysis¶

CodeQL (Python) runs on PR and weekly. Mypy --strict on scripts/, src/legal_text_mcp_de/cli/, and src/legal_text_mcp_de/http_api.py (hard-failing CI job); mypy plain on the rest of src/.

Dynamic analysis¶

Test suite functions as dynamic analysis. End-to-end integration tests against the real HTTP and MCP surfaces live in scripts/verify_e2e.py and are gated by the Release gate (fixture-backed) job in CI.

Silver-level extras (all met)¶

Public roadmap — ROADMAP.md documents planned work for the next 3–6 months.
Governance — GOVERNANCE.md describes the BDFL model and path to co-maintainer.
Code of Conduct — Contributor Covenant 2.1 with enforcement contact.
Two-factor authentication — Maintainer uses 2FA on GitHub. PyPI account uses 2FA. GHCR access is through GitHub Actions only (no long-lived tokens).
Signed releases — cosign keyless signing on all GHCR images; Sigstore attestations on PyPI wheel/sdist.
Reproducible builds — uv build with pinned uv.lock is deterministic given the same Python version and OS. Full hermetic reproduction is provided by SLSA-3.
Memory-safe language — Python is memory-safe by default.
Hardened delivery — TLS everywhere; PEP 740 + cosign for artefact integrity; Dependabot for dependency freshness.

Gold pathway¶

Three structural blockers prevent Gold today. Two are governance, one is hosting:

`two_person_review` (governance)¶

Two-person review of code changes (at minimum for new code commits).

Status: Unmet — solo-maintainer project. Self-review is performed against CODE_REVIEW.md and branch protection enforces signed commits + DCO sign-off + CI green + Conventional Commit titles before any merge.

Mitigation in flight: - good first issue funnel published, 4 scoped issues opened (PRs #91–#94). - GOVERNANCE.md documents the criteria for promoting a contributor to co-maintainer. - Listed in punkpeye/awesome-mcp-servers to widen the contributor funnel.

Once a second maintainer is on board, branch protection will require review from a second eligible reviewer.

`contributors_unassociated` (governance)¶

≥2 unassociated significant contributors in past 12 months.

Status: Unmet — same root cause as two_person_review. Same mitigation flight plan: the contributor funnel published above is the path.

`hardened_site` (hosting)¶

Production website applies hardening headers (CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy).

Status: Unmet — GitHub Pages does not let project owners set response headers on the docs site. The project does not collect any PII on the docs site and does not execute third-party JS, so practical risk is low. Options under evaluation:

Migrate docs hosting to Cloudflare Pages (full header control).
Migrate to a self-hosted Caddy in front of an S3 / R2 bucket.
Accept the partial-compliance gap and document the rationale.

No timeline yet; the cost/benefit of (1) or (2) versus the structural governance blockers makes them lower priority.

OSPS Baseline (separate 2025 track)¶

The 67 unanswered criteria under OSPS-* belong to the OpenSSF Project Security Baseline — a 2025 track that overlaps with Best Practices but is awarded separately. Application planned after the Gold pathway settles.

Refresh checklist (run before each big release)¶

[ ] Pull live JSON: curl https://www.bestpractices.dev/projects/12860.json | jq .
[ ] Bump test count in "Automated test suite" if uv run pytest --collect-only -q | tail differs.
[ ] Bump version reference in "Unique version numbering".
[ ] If new strict modules were added to mypy CI, update "Warning flags" and "Static analysis".
[ ] If the contributor funnel changes (new mitigations, new first-PRs landed), update the Gold pathway section.
[ ] Re-submit Project basics answers on bestpractices.dev so the freshness timestamp ticks forward (auto-mailed reminders trigger every ~6 months otherwise).