Skip to content

BestPracticesChecklist.md

Latest commit

 

History

History
252 lines (165 loc) · 14.2 KB

BestPracticesChecklist.md

File metadata and controls

252 lines (165 loc) · 14.2 KB
Raw

AOSSIE Best Practices Checklist

Criteria adapted from the OpenSSF Best Practices Badge (MIT / CC BY 3.0) by OpenSSF contributors. Modified for AOSSIE multi-repo template use.

Purpose: Covers OpenSSF Best Practices criteria that are NOT auto-detected by OpenSSF Scorecard. Scorecard already handles: License, SAST tools, CI tests, Security Policy file, Branch Protection, Pinned Dependencies, Signed Releases, Maintained status, and Known Vulnerabilities.

How to use:

  1. Fill in checkboxes below — tick [x] for Met, leave [ ] for Unmet, use [~] for N/A
  2. Add a brief note or URL after each item as evidence
  3. Run the checklist-score workflow to update the badge automatically

Legend:

  • 🔴 MUST — Required for passing
  • 🟡 SHOULD — Required unless documented rationale given
  • 🔵 SUGGESTED — Optional but recommended
  • ⚪ N/A — Mark [~] if not applicable, add justification

Score Summary

Category Met Total Status
Basics 8 8 ✅
Change Control 5 6 🟡
Reporting 3 8 🔴
Quality 4 11 🔴
Security 4 9 🔴
Analysis 2 7 🔴
Total 26 49 53%

🏗️ Basics

Project Website & Documentation

  • 🔴 description_good — The project README/website clearly describes what the software does and what problem it solves.

    • Evidence URL: README.md — "ThruBox Server" intro ("dumb encrypted mailbox")

  • 🔴 interact — The project provides information on how to obtain the software, submit bug reports, and contribute.

    • Evidence URL: README.md "Getting Started"/"Contributing", GitHub Issues, CONTRIBUTING.md

  • 🔴 contribution — CONTRIBUTING.md explains the contribution process (e.g., PRs are used, how to open one).

    • Evidence URL: CONTRIBUTING.md "Development Workflow" / "Pull Request Guidelines"

  • 🟡 contribution_requirements — CONTRIBUTING.md references acceptable contribution standards (coding style, tests required, etc.).

    • Evidence URL: CONTRIBUTING.md "Code Style Guidelines", "Test Your Changes"

  • 🔴 documentation_basics — Basic documentation exists for the software (README, Wiki, or docs folder).

    • Evidence URL: README.md, AGENTS.md, brand/Brand.md

  • 🔴 documentation_interface — Reference documentation describes the external interface (API inputs/outputs, CLI flags, config schema, etc.).

    • Evidence URL: README.md "API Endpoints" (send/fetch/delete) and "Configuration" table (YAML keys / env vars)

Other Basics

  • 🔴 discussion — Project has a searchable, URL-addressable discussion mechanism (GitHub Issues, Discord with archive, mailing list, etc.) that doesn't require proprietary client software.

  • 🟡 english — Documentation is provided in English and English bug reports/comments are accepted.

    • Note: All docs and issues are in English.

🔄 Change Control

Version Control

  • 🔵 repo_distributed — Project uses a distributed VCS (e.g., git). (SUGGESTED)
    • Evidence URL: GitHub repo, git history

Version Numbering

  • 🔴 version_unique — Each release has a unique version identifier (e.g., v1.0.0).

    • Evidence URL: Git tag v1.0.0; GitHub Release v0.0.1

  • 🔵 version_semver — Project uses SemVer or CalVer format. (SUGGESTED)

    • Note: Tags follow SemVer (v1.0.0, v0.0.1).

  • 🔵 version_tags — Releases are tagged in the VCS (e.g., git tag v1.0.0). (SUGGESTED)

    • Evidence URL: git tag output

Release Notes

  • 🔴 release_notes — Each release includes human-readable release notes summarizing major changes. Raw git log output is NOT acceptable.

    • Evidence URL: .github/workflows/release-drafter.yml auto-generates categorized release notes from PR titles/labels.

  • 🔴 release_notes_vulns — Release notes identify every publicly known vulnerability (with CVE) fixed in that release.

    • Evidence URL: [~] N/A — Justification: no publicly known/disclosed vulnerabilities to date.

🐛 Reporting

Bug Reporting

  • 🔴 report_process — A bug-reporting process exists (e.g., GitHub Issues link in README).

    • Evidence URL: GitHub Issues; .github/workflows/create-initial-issues.yml

  • 🟡 report_tracker — An issue tracker (e.g., GitHub Issues) is used to track individual bugs.

    • Evidence URL: GitHub Issues

  • 🔴 report_responses — A majority of bug reports submitted in the last 2–12 months have been acknowledged (response ≠ fix).

    • Self-certification note: Not yet assessed — needs maintainer review of issue history.

  • 🟡 enhancement_responses — More than 50% of enhancement requests in the last 2–12 months have received a response.

    • Self-certification note: Not yet assessed.

  • 🔴 report_archive — Reports and responses are publicly archived and searchable (GitHub Issues satisfies this).

    • Evidence URL: GitHub Issues

Vulnerability Reporting

  • 🔴 vulnerability_report_process — A vulnerability reporting process is documented (e.g., SECURITY.md).

    • Evidence URL: Not present — no SECURITY.md in repo.

  • 🟡 vulnerability_report_private — If private vulnerability reporting is supported, the method for private submission is documented.

    • Evidence URL: [~] N/A — Justification: no SECURITY.md/private channel documented yet.

  • 🔴 vulnerability_report_response — Initial response to any vulnerability report received in the last 6 months was within 14 days.

    • Self-certification note: [~] N/A — Justification: no reports received (no vulnerability reporting process exists yet).

✅ Quality

Build System

  • 🔴 build — If the project requires building, a working build system exists that can auto-rebuild from source.

    • Evidence URL: go build -o relay-server ./cmd/relay (documented in README/CONTRIBUTING); .github/workflows/release-goreleaser.yml

  • 🔵 build_common_tools — Common build tools are used (npm, pip, cargo, make, gradle, etc.). (SUGGESTED)

    • Evidence URL: Standard go build/go mod; GoReleaser for release artifacts.

  • 🟡 build_floss_tools — The project can be built using only FLOSS tools.

    • Note: Go toolchain, GCC, and Docker are all FLOSS.

Automated Testing

  • 🔵 test_invocation — The test suite can be invoked in a standard way for the language (e.g., npm test, pytest, cargo test). (SUGGESTED)

    • Evidence URL: go test ./... is the standard command, but no _test.go files exist in the repo yet — nothing to invoke.

  • 🔵 test_most — The test suite covers most code branches, input fields, and functionality. (SUGGESTED)

    • Estimated coverage %: 0% — no tests exist yet.

New Functionality Testing Policy

  • 🔴 test_policy — The project has a general policy that new functionality must include tests in the automated test suite.

    • Evidence (CONTRIBUTING reference or informal policy): CONTRIBUTING.md now asks contributors to add _test.go coverage for new functionality, but this isn't yet an enforced/CI-gated policy.

  • 🔴 tests_are_added — Evidence exists that the test policy has been followed in recent major changes (e.g., PRs include tests).

    • Evidence URL (recent PR with tests): Not applicable yet — no tests exist in the repo.

  • 🔵 tests_documented_added — The test policy is documented in contribution instructions. (SUGGESTED)

    • Evidence URL: CONTRIBUTING.md "Test Your Changes"

Linting / Warning Flags

  • 🔴 warnings — At least one linter or compiler warning flag is enabled (ESLint, Pylint, clippy, golangci-lint, Slither for Solidity, etc.).

    • Tool used: None currently configured — no .golangci.yml and no CI step runs golangci-lint or go vet. (.coderabbit.yaml references golangci-lint only as an AI-review suggestion, not an enforced tool.)

  • 🔴 warnings_fixed — Warnings from the linter are addressed (not suppressed without reason).

    • Note: [~] N/A — Justification: no linter currently configured (see warnings above).

  • 🔵 warnings_strict — Project uses maximum strictness in linter config where practical. (SUGGESTED)

    • Note: Not applicable yet — no linter configured.

🔐 Security

Secure Development Knowledge

  • 🔴 know_secure_design — At least one primary developer knows how to design secure software (familiar with OWASP, threat modeling, secure-by-default principles).

    • Self-certification note: To be self-certified by a maintainer.

  • 🔴 know_common_errors — At least one primary developer knows common vulnerability types for this software's category and how to mitigate them (e.g., injection, XSS, reentrancy for Solidity, prompt injection for AI).

    • Self-certification note: To be self-certified by a maintainer — particularly SQL injection and rate-limit bypass given this is a public relay API.

Cryptography (mark N/A if project does not handle cryptography)

  • [~] 🔴 crypto_published — Only publicly reviewed cryptographic protocols/algorithms are used by default.

    • Note: N/A — The server stores/relays opaque encrypted blobs; it never performs encryption/decryption itself (README: "server never sees plaintext").

  • [~] 🟡 crypto_call — Project calls an established crypto library rather than reimplementing crypto functions.

    • Library used: N/A — No cryptography implemented server-side.

  • [~] 🔴 crypto_working — No broken algorithms (MD4, MD5, single DES, RC4, Dual_EC_DRBG) used unless required for interoperability (must be documented).

    • Note: N/A — No cryptography implemented server-side.

  • [~] 🔴 crypto_keylength — Key lengths meet NIST 2030 minimums by default.

    • Note: N/A — No cryptography implemented server-side.

  • 🔴 crypto_password_storage — Passwords for external users are stored as iterated salted hashes (Argon2id, bcrypt, scrypt, PBKDF2).

    • Note: Server supports optional API key authentication (security.api_key) — not yet verified whether the key is stored/compared as a hash or in plaintext. Needs a maintainer/code review; not marking N/A since an API key is a credential.

  • 🔴 crypto_random — Cryptographic keys and nonces are generated using a CSPRNG; insecure generators (Math.random, rand()) are NOT used for security purposes.

    • Note: Not yet verified — requires a code review of the API key generation path, if any.

  • 🟡 delivery_unsigned — Cryptographic hashes are NOT retrieved over plain HTTP without a signature check.

    • Note: Not assessed.

🔬 Analysis

Static Code Analysis

  • 🔴 static_analysis_fixed — All medium+ severity vulnerabilities found by static analysis are fixed in a timely manner after confirmation.

    • Note: Not yet assessed — needs maintainer review of CodeQL alert history.

  • 🔵 static_analysis_common_vulnerabilities — The static analysis tool includes checks for common vulnerabilities in the language/environment (e.g., eslint-plugin-security, bandit, Slither). (SUGGESTED)

    • Tool + ruleset: CodeQL (.github/workflows/codeql.yml, Go support), Gitleaks secret scanning (.github/workflows/gitleaks-scanning.yml), OSV-Scanner for dependency vulnerabilities (osv-scanner-pr.yml, osv-scanner-scheduled.yml).

  • 🔵 static_analysis_often — Static analysis runs on every commit or at least daily (CI integration). (SUGGESTED)

    • Evidence URL: codeql.yml (push/PR + weekly), gitleaks-scanning.yml (push + daily 4 AM cron).

Dynamic Code Analysis

  • 🔵 dynamic_analysis — At least one dynamic analysis tool is applied before major releases (fuzzer, web app scanner like OWASP ZAP, etc.). (SUGGESTED)

    • Tool used: Not currently used.

  • 🔵 dynamic_analysis_enable_assertions — Dynamic analysis / testing runs with assertions enabled (not just production mode). (SUGGESTED)

    • Note: Not assessed.

  • 🔴 dynamic_analysis_fixed — Medium+ severity vulnerabilities found by dynamic analysis are fixed in a timely manner.

    • Note: Not applicable yet — no dynamic analysis tool configured.

  • 🔵 dynamic_analysis_unsafe — If the project uses memory-unsafe languages (C/C++), memory safety tools (Valgrind, AddressSanitizer) are used. (SUGGESTED)

    • Note: The application code is Go (memory-safe), but github.com/mattn/go-sqlite3 links C code via CGo, which Go's memory safety doesn't cover. No Valgrind/AddressSanitizer is currently used against that path — marking unmet rather than N/A.

📎 Project-Specific Notes

Add domain-specific notes here for Web3, Full-Stack, or AI projects.

Backend / API Notes

  • This server never decrypts or inspects message payloads — all crypto_* criteria are N/A for the payload path itself.
  • The optional security.api_key feature is a credential the server does handle — crypto_password_storage/crypto_random are left unmet pending a maintainer code review of how the key is generated/compared, rather than assumed N/A.
  • No _test.go files exist yet — the biggest Quality gap. Recommend prioritizing tests for the message CRUD handlers and rate limiter before the next release.
  • No linter (golangci-lint/go vet) is wired into CI yet, despite being referenced in .coderabbit.yaml's review instructions.

This checklist complements OpenSSF Scorecard (auto-detected checks) and is inspired by the OpenSSF Best Practices Badge passing criteria.