Skip to content

Commit 5b325e4

Browse files
author
Hayim.Shaul@ibm.com
committed
docs: add OpenSSF Security Baseline compliance assessment
Document where Panurus stands against the OpenSSF Open Source Project Security Baseline (OSPS Baseline) v2026.02.19, so contributors and consumers can see which security practices are in place and which are still missing. Add docs/openssf/ with an index page and one page per Baseline level: - README.md distinguishes the OSPS Baseline from the separately tracked OpenSSF Best Practices Badge, records that the project targets Level 2 in full, summarises the per-level tallies, groups the findings into six gap themes, and gives a procedure for re-running the assessment. - baseline_level_1.md, baseline_level_2.md and baseline_level_3.md cover all 64 controls with a status and per-row evidence. Every "Met" row cites a file, a release artifact or a publicly readable GitHub setting; controls that depend on organization settings or on channels outside the repository are marked "Unverified" rather than assumed. The assessment surfaces a few concrete gaps, notably that the only required status check on main is DCO while the ruleset requiring CodeQL is disabled, that release tags are lightweight and releases carry no checksum manifest, and that tests.yml interpolates a workflow_dispatch input directly into a shell step. Register the new pages in mkdocs.yml under a new Security section, which also de-orphans the existing security/selector_resource_limits.md page, and link them from docs/README.md, SECURITY.md and CONTRIBUTING.md. Signed-off-by: Hayim.Shaul@ibm.com <hayimsha@fhe03.vpc.cloud9.ibm.com>
1 parent 0dd324a commit 5b325e4

8 files changed

Lines changed: 399 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,12 @@ Please refer to the [Development Guidelines](docs/development/development.md) fo
3939
* **Linear History**: We use rebase workflow, not merge commits.
4040
* **Coding Standards**: See [docs/development/general.md](docs/development/general.md) and [docs/development/idiomatic.md](docs/development/idiomatic.md) for Go coding standards.
4141

42+
## Security
43+
44+
Vulnerabilities must not be reported through public issues — follow the [Security Policy](SECURITY.md) instead.
45+
46+
The security practices the project holds itself to are recorded as a self-assessment against the [OpenSSF Security Baseline](docs/openssf/README.md), including the controls that are still unmet. If your contribution closes one of those gaps, reference the corresponding `OSPS-*` control in the pull request.
47+
4248
## Reporting Issues
4349

4450
If you find a bug or have a feature request, please search the [Issues](https://github.com/LFDT-Panurus/panurus/issues) to see if it has already been reported. If not, please open a new issue.

‎SECURITY.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,10 @@ Panurus uses GitHub's private vulnerability patching features, which allow the f
8787
and reviewed in a private fork associated with the advisory. Maintainers needing access or
8888
assistance can contact <community-architects@lfdecentralizedtrust.org>.
8989

90+
## Security Practices
91+
92+
Panurus keeps a self-assessment against the [OpenSSF Security Baseline](https://baseline.openssf.org) under [docs/openssf](docs/openssf/README.md). It records the baseline level the project targets, which controls are already satisfied, and which gaps remain.
93+
9094
---
9195

9296
This policy borrows heavily from the recommendations of the OpenSSF Vulnerability Disclosure

‎docs/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ If you are developing *using* Panurus or contributing *to* Panurus, check out th
3737
* [Testing](development/testing.md)
3838
* [Test & Benchmark Profiler](../cmd/profiler/README.md)
3939

40+
## Security
41+
42+
* [**OpenSSF Security Baseline**](openssf/README.md): Which OpenSSF Baseline level Panurus targets, what is already satisfied, and what is still pending.
43+
* [Selector Resource Limits](security/selector_resource_limits.md): Bounds enforced by the token selector.
44+
* [Security Policy](../SECURITY.md): How to report a vulnerability.
45+
4046
## Evolution
4147

4248
* [**Evolution Summary (v0.4.0 -> Present)**](evolution_summary.md): A summary of how the functionalities provided by Panurus have evolved since tag v0.4.0 when it was still called `token-sdk`.

‎docs/openssf/README.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# OpenSSF Security Baseline
2+
3+
This section records how Panurus measures up against the
4+
[OpenSSF Open Source Project Security Baseline](https://baseline.openssf.org) (OSPS Baseline), so that
5+
contributors and consumers can see which security practices the project already follows, which ones
6+
are still missing, and how to re-run the assessment.
7+
8+
## Two different OpenSSF programs
9+
10+
The two OpenSSF programs that apply to a project like Panurus are often confused. They are separate,
11+
and only the first one is assessed here.
12+
13+
| Program | Identifiers | Levels | Used here |
14+
|---------|-------------|--------|-----------|
15+
| [OSPS Baseline](https://baseline.openssf.org) | `OSPS-<CATEGORY>-<NN>.<NN>` | Level 1, Level 2, Level 3 | Yes — the pages below |
16+
| [Best Practices Badge](https://www.bestpractices.dev) | free-form criteria | passing, silver, gold | No — tracked separately in the project's [badge entry](https://www.bestpractices.dev/en/projects/7176) |
17+
18+
The OSPS Baseline levels are *not* named "passing", "silver" or "gold" — those are Best Practices
19+
Badge tiers. Baseline levels are scoped by project size instead:
20+
21+
- **Level 1** — any code or non-code project, any number of maintainers or users.
22+
- **Level 2** — a code project with at least two maintainers and a small, consistent user base.
23+
- **Level 3** — a code project with a large, consistent user base.
24+
25+
Every Baseline control is a `MUST`; the Baseline deliberately contains no `SHOULD` entries.
26+
27+
## What Panurus targets
28+
29+
Panurus has several active maintainers (see [MAINTAINERS.md](../../MAINTAINERS.md)), tagged releases,
30+
and downstream users, so **Level 2 is the level the project aims to satisfy in full**. Level 1 is
31+
almost entirely satisfied today; Level 3 is documented as a longer-term target because it requires
32+
release-signing, SBOM, VEX and threat-modeling work that has not started.
33+
34+
## Assessment
35+
36+
- **Assessed against:** OSPS Baseline **v2026.02.19** (the current release at the time of writing)
37+
- **Assessment date:** 2026-08-03
38+
- **Assessed release:** `v0.16.0`
39+
40+
| Level | Controls | Met | Partially met | Not met | Unverified |
41+
|-------|---------:|----:|--------------:|--------:|-----------:|
42+
| [Level 1](baseline_level_1.md) | 24 | 20 | 2 | 0 | 2 |
43+
| [Level 2](baseline_level_2.md) | 19 | 11 | 5 | 2 | 1 |
44+
| [Level 3](baseline_level_3.md) | 21 | 3 | 6 | 12 | 0 |
45+
46+
Status values used in the per-level tables:
47+
48+
| Status | Meaning |
49+
|--------|---------|
50+
| **Met** | Satisfied, with evidence in this repository or in a publicly verifiable GitHub setting. |
51+
| **Partially Met** | Partly satisfied; the remaining gap is named in the notes. |
52+
| **Not Met** | Not satisfied today. |
53+
| **Unverified** | Cannot be confirmed from public repository state; needs confirmation by a maintainer or org administrator. |
54+
55+
Nothing is marked **Met** on the basis of "this is standard practice for the foundation". A control is
56+
only **Met** when a file in this repository, a release artifact, or a publicly readable GitHub
57+
setting shows it.
58+
59+
## Main gaps
60+
61+
The assessment converges on a small number of themes rather than 20 unrelated items:
62+
63+
1. **Release provenance.** Releases carry no signed manifest, no checksums and no SBOM, and the tags
64+
are lightweight rather than signed — so there is nothing for a consumer to verify, and no
65+
documented verification procedure (`OSPS-BR-06.01`, `OSPS-DO-03.01`, `OSPS-DO-03.02`,
66+
`OSPS-QA-02.02`).
67+
2. **Support lifecycle.** No statement of how long a release is supported or when it stops receiving
68+
security fixes (`OSPS-DO-04.01`, `OSPS-DO-05.01`).
69+
3. **Security analysis artifacts.** No published security assessment or threat model, and the
70+
project README states it has not been audited (`OSPS-SA-03.01`, `OSPS-SA-03.02`).
71+
4. **Policy thresholds.** CodeQL, `golangci-lint` and Dependabot all run, but no document defines the
72+
severity threshold at which findings must be fixed, or what happens before a release
73+
(`OSPS-VM-05.01`, `OSPS-VM-05.02`, `OSPS-VM-06.01`).
74+
5. **Enforcement vs. policy.** [DEVELOPMENT.md](../../DEVELOPMENT.md) requires one maintainer approval
75+
per PR, but the active branch ruleset requires zero approving reviews and only the DCO check, so
76+
the policy is honored by convention rather than enforced by the platform (`OSPS-QA-03.01`,
77+
`OSPS-QA-07.01`).
78+
6. **Undeclared workflow permissions.** Most workflows declare least-privilege `permissions:`, but
79+
`tests.yml`, `md_links.yml` and `protect-integration-test-types.yml` do not, and one
80+
`workflow_dispatch` input is interpolated straight into a shell step (`OSPS-AC-04.01`,
81+
`OSPS-AC-04.02`, `OSPS-BR-01.04`).
82+
83+
## How to reassess
84+
85+
1. Check whether a newer Baseline release exists at
86+
[baseline.openssf.org](https://baseline.openssf.org). Only the version labeled *current* should
87+
be used for new compliance work, and control identifiers are occasionally retired between
88+
versions.
89+
2. Pull the machine-readable checklist for that version (for example
90+
`https://baseline.openssf.org/versions/2026-02-19-checklist.md`) and diff its control list against
91+
the tables in [Level 1](baseline_level_1.md), [Level 2](baseline_level_2.md) and
92+
[Level 3](baseline_level_3.md).
93+
3. Re-verify each row against the repository, not against memory. Controls about GitHub
94+
configuration can be checked with the API, for example:
95+
96+
```bash
97+
# branch rulesets: which checks and approvals are actually enforced on main
98+
gh api repos/LFDT-Panurus/panurus/rulesets
99+
gh api repos/LFDT-Panurus/panurus/rulesets/<id>
100+
101+
# release assets, signatures and changelog
102+
gh release view v0.16.0 --json tagName,assets,body
103+
104+
# private vulnerability reporting and published advisories
105+
gh api repos/LFDT-Panurus/panurus/private-vulnerability-reporting
106+
gh api repos/LFDT-Panurus/panurus/security-advisories
107+
```
108+
109+
4. Update the header of each page (Baseline version, assessment date, assessed release) and the
110+
summary table above.
111+
5. Open a GitHub issue for every control that moves to, or stays at, **Not Met**, and reference the
112+
control identifier in the issue so progress stays traceable.
113+
6. If the project also wants credit on the Best Practices Badge, update
114+
[project 7176](https://www.bestpractices.dev/en/projects/7176) separately — the two programs do
115+
not share data.
116+
117+
## Related documentation
118+
119+
- [Security policy](../../SECURITY.md) — how to report a vulnerability
120+
- [Contributing](../../CONTRIBUTING.md) and [Development guidelines](../development/general.md)
121+
- [Selector resource limits](../security/selector_resource_limits.md) — a security-relevant design note

‎docs/openssf/baseline_level_1.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# OSPS Baseline Level 1
2+
3+
Self-assessment of Panurus against **Level 1** of the
4+
[OpenSSF Security Baseline](https://baseline.openssf.org), version **v2026.02.19**.
5+
6+
- **Assessment date:** 2026-08-03
7+
- **Assessed release:** `v0.16.0`
8+
- **Status legend and methodology:** see the [section overview](README.md)
9+
10+
Level 1 applies to any project regardless of size. Requirement wording below is abbreviated; the
11+
authoritative text is the [Baseline v2026.02.19 control list](https://baseline.openssf.org/versions/2026-02-19).
12+
13+
## Access Control
14+
15+
| Control | Requirement | Status | Evidence / notes |
16+
|---------|-------------|--------|------------------|
17+
| `OSPS-AC-01.01` | MFA required to read or modify sensitive resources in the authoritative repository | **Unverified** | Organization-level setting for `LFDT-Panurus`, not readable from the repository. Needs confirmation by an org administrator. |
18+
| `OSPS-AC-02.01` | New collaborators get manual permission assignment or the lowest privileges by default | **Unverified** | Contributions arrive through forks and pull requests, so no repository write access is needed to contribute. The default member privilege of the organization still needs confirmation by an org administrator. |
19+
| `OSPS-AC-03.01` | Direct commits to the primary branch are blocked by an enforcement mechanism | **Met** | Active organization ruleset `DCO` targets `~DEFAULT_BRANCH` and includes a `pull_request` rule, so changes must arrive through a pull request (`gh api repos/LFDT-Panurus/panurus/rulesets`). |
20+
| `OSPS-AC-03.02` | Deleting the primary branch is treated as sensitive and requires confirmation | **Met** | The same active ruleset includes `deletion` and `non_fast_forward` rules, which block branch deletion and force-pushes on `main` outright. |
21+
22+
## Build and Release
23+
24+
| Control | Requirement | Status | Evidence / notes |
25+
|---------|-------------|--------|------------------|
26+
| `OSPS-BR-01.01` | Untrusted pipeline metadata is sanitized and validated before use | **Met** | The only event fields interpolated into workflow steps are commit SHAs and the PR number ([token-validation-benchmark.yml](https://github.com/LFDT-Panurus/panurus/blob/main/.github/workflows/token-validation-benchmark.yml) lines 111-120 and 234); no attacker-controlled free text (branch name, PR title, PR body) reaches a `run:` block. |
27+
| `OSPS-BR-01.03` | Pipelines operating on untrusted code snapshots cannot reach privileged credentials | **Met** | [token-validation-benchmark.yml](https://github.com/LFDT-Panurus/panurus/blob/main/.github/workflows/token-validation-benchmark.yml) uses `pull_request_target` with a read-only default token (`permissions: contents: read`, line 44); `pull-requests: write` is granted only to the `compare` job (line 197), which never checks out or executes PR head code. The `benchmark` job that runs PR code holds no write scope and no secrets. |
28+
| `OSPS-BR-03.01` | Official project channel URIs are delivered over encrypted channels | **Met** | All channels listed in [README.md](../../README.md) and [CONTRIBUTING.md](../../CONTRIBUTING.md) are HTTPS (GitHub, `discord.gg`), and the documentation site is served over HTTPS (`site_url` in [mkdocs.yml](https://github.com/LFDT-Panurus/panurus/blob/main/mkdocs.yml)). |
29+
| `OSPS-BR-03.02` | Official distribution channels are protected against adversary-in-the-middle attacks | **Met** | Releases are consumed as Go modules through the HTTPS module proxy with `go.sum` checksum verification, and as HTTPS GitHub release archives. Tool downloads in the [Makefile](https://github.com/LFDT-Panurus/panurus/blob/main/Makefile) also use HTTPS. |
30+
| `OSPS-BR-07.01` | Unintentional storage of unencrypted secrets in version control is prevented | **Partially Met** | CI credentials are referenced only through the GitHub `secrets` context, and generated/local artifacts are excluded by [.gitignore](https://github.com/LFDT-Panurus/panurus/blob/main/.gitignore). However no repository-side secret scanner (for example `gitleaks`) runs in CI or as a pre-commit hook, and GitHub secret-scanning/push-protection settings are not publicly readable. |
31+
32+
## Documentation
33+
34+
| Control | Requirement | Status | Evidence / notes |
35+
|---------|-------------|--------|------------------|
36+
| `OSPS-DO-01.01` | User guides for all basic functionality | **Met** | [Documentation index](../README.md), covering the [Token API](../tokenapi.md), [usage guide](../token_sdk_usage.md), [configuration](../configuration.md), [services](../services.md) and per-tool READMEs under `cmd/`. |
37+
| `OSPS-DO-02.01` | A guide for reporting defects | **Met** | "Reporting Issues" in [CONTRIBUTING.md](../../CONTRIBUTING.md), plus structured issue forms in [.github/ISSUE_TEMPLATE](https://github.com/LFDT-Panurus/panurus/tree/main/.github/ISSUE_TEMPLATE) (`bug_report.yml`, `feature_request.yml`, `good_first_issue.yml`). |
38+
39+
## Governance
40+
41+
| Control | Requirement | Status | Evidence / notes |
42+
|---------|-------------|--------|------------------|
43+
| `OSPS-GV-02.01` | Mechanisms for public discussion of proposed changes and obstacles | **Met** | GitHub issues and pull requests, GitHub Discussions (enabled on the repository), and the `#panurus` Discord channel linked from [README.md](../../README.md) and [CONTRIBUTING.md](../../CONTRIBUTING.md). |
44+
| `OSPS-GV-03.01` | Documented explanation of the contribution process | **Met** | [CONTRIBUTING.md](../../CONTRIBUTING.md), [DEVELOPMENT.md](../../DEVELOPMENT.md) and [docs/development](../development/development.md). |
45+
46+
## Legal
47+
48+
| Control | Requirement | Status | Evidence / notes |
49+
|---------|-------------|--------|------------------|
50+
| `OSPS-LE-02.01` | Source code license meets the OSI or FSF definition | **Met** | Apache License 2.0 ([LICENSE](https://github.com/LFDT-Panurus/panurus/blob/main/LICENSE)); GitHub reports the SPDX identifier `Apache-2.0`. |
51+
| `OSPS-LE-02.02` | Released software assets are under an OSI/FSF-conforming license | **Met** | Releases are source and Go module releases of this repository, covered by the same Apache-2.0 license; per-file license headers are enforced by the `licensecheck` target in [checks.mk](https://github.com/LFDT-Panurus/panurus/blob/main/checks.mk). |
52+
| `OSPS-LE-03.01` | License is kept in the repository's `LICENSE` file | **Met** | [LICENSE](https://github.com/LFDT-Panurus/panurus/blob/main/LICENSE) at the repository root. |
53+
| `OSPS-LE-03.02` | License is included alongside release assets | **Met** | Release archives are snapshots of the tagged tree and therefore contain `LICENSE`. |
54+
55+
## Quality
56+
57+
| Control | Requirement | Status | Evidence / notes |
58+
|---------|-------------|--------|------------------|
59+
| `OSPS-QA-01.01` | Source repository is publicly readable at a static URL | **Met** | <https://github.com/LFDT-Panurus/panurus> is public. |
60+
| `OSPS-QA-01.02` | Public record of all changes, authors and timestamps | **Met** | Full Git history is public; the project requires a linear, rebase-based history ([DEVELOPMENT.md](../../DEVELOPMENT.md)). |
61+
| `OSPS-QA-02.01` | Repository contains a dependency list for direct language dependencies | **Met** | `go.mod` / `go.sum` for the root module and each of the eight additional modules (`cmd/*`, `integration`, `tools`, `token/services/storage/db/kvs/hashicorp`). |
62+
| `OSPS-QA-04.01` | Projects with multiple repositories document the list of codebases | **Met** | Panurus is a single repository. Its Go modules and standalone CLI tools are listed in the [documentation index](../README.md). |
63+
| `OSPS-QA-05.01` | Version control contains no generated executable artifacts | **Met** | No tracked executables, archives or shared objects; build output (`/site/`, `coverage.out`, generated service output directories) is excluded by [.gitignore](https://github.com/LFDT-Panurus/panurus/blob/main/.gitignore). |
64+
| `OSPS-QA-05.02` | Version control contains no unreviewable binary artifacts | **Partially Met** | No binaries are shipped, but binary fixtures are tracked: Idemix key material under `cmd/tokengen/testdata/idemix/` and `token/core/zkatdlog/nogh/v1/**/testdata/`, and PNG diagrams under `docs/imgs/`. These are regenerable test/documentation assets rather than code, but they are not human-reviewable in a diff. |
65+
66+
## Vulnerability Management
67+
68+
| Control | Requirement | Status | Evidence / notes |
69+
|---------|-------------|--------|------------------|
70+
| `OSPS-VM-02.01` | Documentation contains security contacts | **Met** | [SECURITY.md](../../SECURITY.md) names `security@hyperledger.org` as the reporting address. |
71+
72+
## Summary
73+
74+
| Status | Count |
75+
|--------|------:|
76+
| Met | 20 |
77+
| Partially Met | 2 |
78+
| Not Met | 0 |
79+
| Unverified | 2 |
80+
| **Total** | **24** |
81+
82+
The two **Unverified** rows are organization settings rather than repository content, and the two
83+
**Partially Met** rows are narrow: no CI-side secret scanner, and binary test fixtures in the tree.

0 commit comments

Comments
 (0)