Skip to content
Skip to Content
Apothem
Security

OpenSSF Best Practices badge

Apothem's answers to the OpenSSF Best Practices passing criteria, with the evidence for each one and the gaps that remain.

The OpenSSF Best Practices badge (formerly the CII Best Practices badge) is a self-assessment: a project answers a fixed list of criteria on bestpractices.dev, and the site awards the passing badge when every answer meets the rule for its level. OpenSSF Scorecard's CII-Best-Practices check reads the result, so this page also backs that row on the Scorecard posture page.

This page is the answer sheet. It lists every passing-level criterion, the answer Apothem gives, a one-line justification, and the file or page that shows it. The criteria were taken from the live passing criteria and the criteria source on 2026-11-07: 67 criteria, of which 43 are MUST, 10 are SHOULD and 14 are SUGGESTED.

Status

Apothem is not yet registered on bestpractices.dev, so it has no badge yet. The answers below cover every passing criterion:

LevelMetN/AUnmet
MUST (43)3940
SHOULD (10)811
SUGGESTED (14)1310

The passing badge needs every MUST criterion Met, every SHOULD criterion Met or Unmet with a reason, and every SUGGESTED criterion answered Met or Unmet. An N/A answer counts as Met, and only criteria that allow it take one; the one N/A among the SUGGESTED criteria, dynamic_analysis_unsafe, is one of them. With these answers the project qualifies.

Three MUST answers depend on facts only the maintainer can confirm, and they are marked "maintainer confirms" in the tables: vulnerability_report_response (no report arrived by email) and know_secure_design and know_common_errors (the developers' own knowledge). They count in the table above as the answer shown. The one Unmet SHOULD criterion, crypto_weaknesses, carries its reason in the table and in Remaining gaps.

Register the project

Registration is done by the maintainer in one sitting:

  1. Sign in at bestpractices.dev with the GitHub account that owns the repository.
  2. Choose Get Your Badge Now! and enter the repository URL, https://github.com/ahmed-g-gad/apothem. The site fills in some answers on its own; check each one against the tables below.
  3. Work through the six sections (Basics, Change Control, Reporting, Quality, Security, Analysis). For each criterion, choose the answer in the Answer column, paste the Justification, and add the Evidence link. Eight Met answers must carry a URL in the justification text: contribution, contribution_requirements, license_location, release_notes, report_process, report_archive, vulnerability_report_process and vulnerability_report_private. Their justifications below already include it.
  4. Before answering vulnerability_report_response, confirm that no vulnerability report reached the email address in SECURITY.md in the last 6 months. If one did, answer Met and give the time to the first response, which must be 14 days or less.
  5. Answer know_secure_design and know_common_errors only after confirming they describe the maintainer's own knowledge; the site asks about the people who develop the project, and the linked files are the supporting evidence.
  6. Save each section. When the site shows 100% for the passing level, copy the badge Markdown it offers and add the badge to the README header next to the Scorecard badge, with its row in the Badge policy table.

Scorecard reads the badge level through the bestpractices.dev API on its next run. Its CII-Best-Practices check scores a registered project that is still in progress at 2, a passing badge at 5, silver at 7 and gold at 10; gold needs more than one developer.

Answers

Basics: Basic project website content

CriterionLevelAnswerJustificationEvidence
description_goodMUSTMetThe README opening paragraph and the docs home page say in plain terms that Apothem takes one shared profile of coding-assistant settings and writes it into the native configuration of each supported coding assistant, so users stop keeping hand-made copies in sync.README.md
interactMUSTMetThe README and the website explain how to install Apothem (the Install section and /docs/install), where to report bugs or request features (GitHub Issues, with GitHub Discussions open for questions), and how to contribute (CONTRIBUTING.md and the developer guide)./docs/community/discussions
contributionMUSTMetCONTRIBUTING.md describes the fork-and-pull-request workflow against main and the issue templates for bug reports and feature requests: https://github.com/ahmed-g-gad/apothem/blob/main/CONTRIBUTING.md#pull-request-submissionCONTRIBUTING.md#pull-request-submission
contribution_requirementsSHOULDMetCONTRIBUTING.md lists what an acceptable contribution needs: Ruff lint and format, mypy, pytest, the conformity gate, tests for new functionality, Conventional Commits, DCO sign-off, and a PR description with what, why and verification: https://github.com/ahmed-g-gad/apothem/blob/main/CONTRIBUTING.md#routine-verificationCONTRIBUTING.md#routine-verification

Basics: FLOSS license

CriterionLevelAnswerJustificationEvidence
floss_licenseMUSTMetApothem is released under the MIT License, with vendored typing code under PSF-2.0, and both are OSI-approved free licenses.LICENSE
floss_license_osiSUGGESTEDMetBoth licenses that apply to the distribution, MIT and PSF-2.0, are on the OSI approved list.pyproject.toml
license_locationMUSTMetThe license text is in the top-level LICENSE file (https://github.com/ahmed-g-gad/apothem/blob/main/LICENSE), and REUSE-style copies are in the LICENSES/ directory (MIT.txt, PSF-2.0.txt).LICENSE

Basics: Documentation

CriterionLevelAnswerJustificationEvidence
documentation_basicsMUSTMetThe docs site covers installing (/docs/install), a first run (quickstart and getting-started tutorial), day-to-day use (/docs/usage), and safe use (the installer trust model and signature checks on /docs/install, plus the trust boundaries on /docs/security)./docs/install
documentation_interfaceMUSTMetThe CLI reference has one page per command, giving its synopsis, options, and output formats, and the profile-fields and settings reference pages document the input profile format./docs/cli-reference

Basics: Other

CriterionLevelAnswerJustificationEvidence
sites_httpsMUSTMetThe home page https://apothem.ahmedgad.com/ is served over HTTPS and its plain-HTTP address redirects to HTTPS (301); the repository is on github.com and the downloads come from GitHub Releases, npmjs.com, and https://apothem.ahmedgad.com/install.sh, all over HTTPS./
discussionMUSTMetGitHub Issues, Pull Requests and GitHub Discussions are open to anyone with a free GitHub account; they are searchable, every topic has its own URL, and a browser is all that is needed.discussions
englishSHOULDMetThe main documentation (README, CONTRIBUTING, SECURITY, the docs site) is written in English, with translations as extras, and issues and pull requests are taken and handled in English./docs
maintainedMUSTMetThe project is active: releases ship every few days to weeks, pull requests are merged each week, issues get closed, and SECURITY.md commits to acknowledging vulnerability reports within 48 hours.releases

Change Control: Public version-controlled source repository

CriterionLevelAnswerJustificationEvidence
repo_publicMUSTMetThe source is in a public Git repository on GitHub.repository
repo_trackMUSTMetGit history on GitHub records each commit's change, author and timestamp, for example bf371159 by Ahmed G. Gad on 2026-11-07.commits/main
repo_interimMUSTMetThe repository holds every interim commit and pull-request merge between releases, not only the release commits.commits/main
repo_distributedSUGGESTEDMetThe project uses Git, hosted on GitHub.repository

Change Control: Unique version numbering

CriterionLevelAnswerJustificationEvidence
version_uniqueMUSTMetEach release has its own version number, set in pyproject.toml and matched by a git tag and a GitHub Release.releases
version_semverSUGGESTEDMetReleases use Semantic Versioning in the form vMAJOR.MINOR.PATCH, as the CHANGELOG states in its header and the release tags show.CHANGELOG.md
version_tagsSUGGESTEDMetEvery release is marked with a git tag of the form vMAJOR.MINOR.PATCH that points at its release commit.tags

Change Control: Release notes

CriterionLevelAnswerJustificationEvidence
release_notesMUSTMetCHANGELOG.md (https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md) and each GitHub Release have hand-written notes for every version, not raw git log output, grouped under headings such as Added and Security.CHANGELOG.md
release_notes_vulnsMUSTN/ANo release so far has fixed a publicly known vulnerability with a CVE or a published advisory. Release notes will name the CVE or advisory ID of any that a future release fixes.security/advisories

Reporting: Bug-reporting process

CriterionLevelAnswerJustificationEvidence
report_processMUSTMetUsers report bugs through GitHub Issues with a bug-report form, and SUPPORT.md and CONTRIBUTING.md send bug reports there: https://github.com/ahmed-g-gad/apothem/blob/main/SUPPORT.mdSUPPORT.md
report_trackerSHOULDMetThe project tracks individual issues in its public GitHub issue tracker, with issue forms for bugs, feature requests, documentation, and questions.issues
report_responsesMUSTMetNo user outside the project has filed a bug report yet; every issue on the tracker has been handled and closed, and SUPPORT.md commits to triage within 7 days.issues?q=is%3Aissue
enhancement_responsesSHOULDMetNo enhancement request from outside the project has been filed yet, so none is unanswered; the feature-request form and the 7-day triage commitment are in place.issues?q=is%3Aissue
report_archiveMUSTMetThe public GitHub issue tracker (https://github.com/ahmed-g-gad/apothem/issues?q=is%3Aissue) and GitHub Discussions keep every report and reply, including closed ones, and anyone can search them.issues?q=is%3Aissue

Reporting: Vulnerability report process

CriterionLevelAnswerJustificationEvidence
vulnerability_report_processMUSTMetThe security page on the project site (https://apothem.ahmedgad.com/docs/security) and SECURITY.md both tell reporters to use GitHub Private Vulnerability Reporting on the Security tab, with email to [email protected] as a second channel./docs/security
vulnerability_report_privateMUSTMetSECURITY.md (https://github.com/ahmed-g-gad/apothem/blob/main/SECURITY.md#reporting-a-vulnerability) tells reporters to send private reports through GitHub Private Vulnerability Reporting, a web form over HTTPS that opens a workspace only the reporter and the maintainer can see; the feature is turned on.SECURITY.md#reporting-a-vulnerability
vulnerability_report_responseMUSTN/A, maintainer confirmsNo vulnerability report from outside the project reached GitHub Private Vulnerability Reporting in the last 6 months; the maintainer confirms at registration that none arrived by email either. SECURITY.md commits to acknowledging a report within 48 hours.SECURITY.md#response-timeline

Quality: Working build system

CriterionLevelAnswerJustificationEvidence
buildMUSTMetThe project builds its sdist and wheel from source with the setuptools backend declared in pyproject.toml, run as python -m build in the release workflow, and the Makefile wraps install, test and release steps.pyproject.toml
build_common_toolsSUGGESTEDMetThe build uses common Python tools (setuptools, pip, the PyPA build front end) and a GNU Make Makefile.Makefile
build_floss_toolsSHOULDMetEvery build tool used (CPython, setuptools, pip, PyPA build, GNU Make, and Node/npm for the docs site and shim) is FLOSS, and no proprietary tool is needed to build from source.pyproject.toml

Quality: Automated test suite

CriterionLevelAnswerJustificationEvidence
testMUSTMetThe MIT-licensed repository includes a pytest suite under tests/ (444 test_*.py files), and CONTRIBUTING.md and the CI workflow show how to run it (make test / python -m pytest).CONTRIBUTING.md#routine-verification
test_invocationSHOULDMetThe suite runs with the standard Python invocation pytest / python -m pytest, configured in pyproject.toml, and with make test.pyproject.toml
test_mostSUGGESTEDMetCI measures line plus branch coverage and fails below set floors: 80% for the engine, 81% for the conformity package and 70% for the audit package, so most code and branches are exercised./docs/developer-guide
test_continuous_integrationSUGGESTEDMetGitHub Actions CI runs the pytest suite across an OS by Python 3.10-3.14 matrix plus a coverage job on pushes and pull requests to main that touch the source, tests, scripts, site or workflow paths, and its runs are public..github/workflows/ci.yml

Quality: New functionality testing

CriterionLevelAnswerJustificationEvidence
test_policyMUSTMetCONTRIBUTING.md requires every pull request that adds functionality to add tests for it in the same pull request, and every bug fix to add a regression test; the pull request template asks for the tests in its Test plan.CONTRIBUTING.md#tests-for-new-functionality
tests_are_addedMUSTMetRecent feature changes added tests with the code, for example the native hooks change (#156) and the native subagents change (#154).commit/e9b3b3db
tests_documented_addedSUGGESTEDMetThe contribution guide states the test requirement, and the pull request template has a Test plan section that asks which tests were added.CONTRIBUTING.md#tests-for-new-functionality

Quality: Warning flags

CriterionLevelAnswerJustificationEvidence
warningsMUSTMetThe project runs the ruff linter with 17 rule families (including bugbear, bandit-style S checks and complexity) and mypy in strict mode on every CI run, plus shellcheck and PSScriptAnalyzer on the installer scripts and bandit and CodeQL for security analysis.pyproject.toml
warnings_fixedMUSTMetruff check . and mypy run clean, and CI fails on any ruff or mypy finding; the remaining suppressions are per-file ignores in pyproject.toml, each with a written reason, and inline noqa or type: ignore markers that flag false positives in the source.pyproject.toml
warnings_strictSUGGESTEDMetThe project runs mypy in strict mode, a wide ruff rule selection (annotations, security, bugbear, pathlib, return checks), a complexity limit that is only allowed to go down and that CI tightens to 15 for the CLI and install driver, and bandit plus CodeQL, which shows it turns on warnings wherever practical.pyproject.toml

Security: Secure development knowledge

CriterionLevelAnswerJustificationEvidence
know_secure_designMUSTMet, maintainer confirmsThe maintainer confirms this at registration. The shipped design shows the principles: a threat model, a deny floor no allow-list widens, validation before any write, writes limited to harness directories, fail-closed signature checks, and read-only default workflow permissions./docs/security#threat-model
know_common_errorsMUSTMet, maintainer confirmsThe maintainer confirms this at registration. The code guards against the error classes that apply to a CLI that writes files: write targets are checked for path traversal and symlink crossings (with property tests), YAML is read with a safe loader, and diagnostics redact secret-like values; CI runs bandit, the ruff S rules and CodeQL security-extended.src/apothem/harnesses/_shared/install_driver_pathsafety.py

Security: Use basic good cryptographic practices

CriterionLevelAnswerJustificationEvidence
crypto_publishedMUSTMetThe only cryptography the software relies on is published, expert-reviewed algorithms and protocols: SHA-256 through Python's hashlib, Sigstore signatures on the release SHA256SUMS checked by cosign in the installers, OpenPGP Ed25519 tag signatures checked by git verify-tag, SHA-1 in Git's object IDs (which link a signed tag to its commit and, on a clone install, to every checked-out file) and in the OpenPGP v4 fingerprint that pins the maintainer key, SHA-256 release checksums, and TLS made by curl, git, cosign, pip, npm, Invoke-WebRequest or Python's urllib.scripts/installer/install.sh
crypto_callSHOULDMetApothem implements no cryptographic primitive itself; it calls Python's hashlib, cosign, git (with GnuPG for tag signatures and git hash-object for blob IDs), sha256sum/shasum or Get-FileHash, and .NET's SHA1 and SHA256 classes in the PowerShell installers, and leaves TLS to curl, git, cosign, pip, npm, Invoke-WebRequest and Python's urllib.scripts/installer/install.sh
crypto_flossMUSTMetEvery function that depends on cryptography can be built from FLOSS: CPython's hashlib and ssl modules with OpenSSL, git with GnuPG, coreutils sha256sum or Perl's shasum, curl, and Sigstore cosign for release signing and for checking release signatures. On Windows, install.ps1 hashes with PowerShell's Get-FileHash and downloads with Invoke-WebRequest, which call the operating system's crypto and TLS libraries, as git does when it is set to use SChannel; on Linux and macOS, install.sh does the same work with the FLOSS tools above..github/workflows/release.yml
crypto_keylengthMUSTMetThe software generates no keys. Every digest Apothem's own code computes is SHA-256 (256 bits, above the 224-bit minimum), except one: install.ps1 and update.ps1 hash each committed .gitattributes file they read as git hashes a blob, to check it against its object ID, and in this repository's SHA-1 object format that is a 160-bit SHA-1 hash. The release tags it verifies are signed with an Ed25519 key, and the Sigstore signatures cosign checks on SHA256SUMS use ECDSA P-256 (both above the 224-bit elliptic-curve minimum). Every release tag published so far is signed over a SHA-512 digest (OpenPGP digest algorithm 10, as gpg --list-packets shows for the tag's signature); the signer's GnuPG settings choose that digest, not the key. The installers' checks also rely on 160-bit SHA-1 hashes: Git's object IDs, which on a clone install reach every checked-out file, and the OpenPGP v4 fingerprint that pins the maintainer key. Git's object format and the OpenPGP key format set those sizes, not a setting in Apothem; the crypto_weaknesses answer covers this reliance, since that criterion names SHA-1.src/apothem/lib/propagation.py
crypto_workingMUSTMetNo default mechanism uses a broken algorithm such as MD4, MD5, single DES or RC4, and the code uses no cipher modes. Apothem's own hashing is SHA-256, except that install.ps1 and update.ps1 recompute the git object ID of each committed .gitattributes file they read, which is SHA-1 in this repository. The installers' checks also rely on SHA-1, in Git's object IDs (on a clone install, for every checked-out file) and in the maintainer key's OpenPGP v4 fingerprint; the criteria name SHA-1, under crypto_weaknesses, as an algorithm with known serious weaknesses, not among the broken algorithms listed here.src/apothem/audit/build_inventory.py
crypto_weaknessesSHOULDUnmetApothem's own hashing is SHA-256, except that install.ps1 and update.ps1 recompute the SHA-1 git object ID of each committed .gitattributes file they read, and the checks in its one-shot installers and update scripts still rest on SHA-1. By default, every network install through the installers and every update of an existing clone through the update scripts checks a maintainer-signed git tag, which names its commit by a SHA-1 object ID (the repository uses Git's SHA-1 object format), and the scripts pin the maintainer key by its OpenPGP v4 fingerprint, which is also a SHA-1 hash. An install without cosign, and every install or update over an existing Apothem clone, installs a checkout of that commit, so every installed file rests on SHA-1. With cosign installed and no existing Apothem clone, the installed files rest on SHA-256: cosign checks the Sigstore signature on the release SHA256SUMS and that its certificate was issued to a run on the tag's commit, and the installer then checks the archive's SHA-256. The link from the signed tag to that commit still rests on SHA-1; the collision detection in Git's default build lowers that risk but does not remove it. The npm shim and the plugin and extension channels run no signature or digest check of their own.scripts/installer/install.sh
crypto_pfsSHOULDN/AApothem implements no key agreement protocol; curl, git, cosign, pip, npm, Invoke-WebRequest and Python's urllib make its TLS connections, each through the TLS library it is built with or the operating system's.src/apothem/audit/check_links.py
crypto_password_storageMUSTN/AApothem is a local configuration CLI that does not authenticate external users and does not store passwords.README.md
crypto_randomMUSTN/AThe software generates no cryptographic keys or nonces; it does not import random or secrets, and release signing uses short-lived Sigstore keys created by cosign in CI..github/workflows/release.yml

Security: Secured delivery against man-in-the-middle (MITM) attacks

CriterionLevelAnswerJustificationEvidence
delivery_mitmMUSTMetEvery delivery channel uses HTTPS (the GitHub repo and Releases, npm, the Marketplace, and apothem.ahmedgad.com, which redirects http to https with a 301). Release artifacts carry cosign signatures, and the sdist, wheel, SBOM and VS Code package also carry SLSA provenance. The installers check the release tag's GPG signature against the pinned maintainer key and confirm that the signed tag is the one named for the release. When cosign is installed and the install folder is not already an Apothem git clone, they also check the cosign signature on SHA256SUMS from a run on that tag's commit.SECURITY.md
delivery_unsignedMUSTMetThe installers fetch the release SHA256SUMS over HTTPS from GitHub Releases. With cosign installed and no existing Apothem clone, the default path accepts it only after the release tag's GPG signature and cosign's check of its Sigstore signature both pass; otherwise the default path checks the GPG tag signature and clones or fetches the tag instead, and only the opt-in checksum mode uses SHA256SUMS unsigned, and the installers run it only when APOTHEM_ALLOW_UNVERIFIED=1 is also set. Checksum mode does not verify the release. SHA256SUMS comes from the same release as the archive, so a match only shows the download isn't damaged; anyone who can change the release's files can change both. An existing clone is fetched and its tag is checked before the clone is checked out.scripts/installer/install.sh

Security: Publicly known vulnerabilities fixed

CriterionLevelAnswerJustificationEvidence
vulnerabilities_fixed_60_daysMUSTMetNo vulnerability of medium or higher severity has been publicly known and unpatched for more than 60 days: on 2026-11-08, Dependabot and code scanning showed 0 open alerts.security
vulnerabilities_critical_fixedSHOULDMetCritical dependency alerts have been fixed quickly; the two critical Next.js alerts of 2026-10-23 in the docs-site build were closed within two days.SECURITY.md#response-timeline

Security: Other security issues

CriterionLevelAnswerJustificationEvidence
no_leaked_credentialsMUSTMetGitleaks runs in pre-commit and in CI, and GitHub secret scanning has no open alerts. Its only past alert was a placeholder Google-key-shaped test fixture (AIzaEXAMPLEFIXTURE plus zeros), which was resolved as used_in_tests..pre-commit-config.yaml

Analysis: Static code analysis

CriterionLevelAnswerJustificationEvidence
static_analysisMUSTMetCodeQL (security-extended suite, Python and Actions), bandit, ruff with the flake8-bandit S rules, mypy and zizmor run in CI on pushes and pull requests to main that touch the listed source and workflow paths, so the code of every release commit is analyzed before the tag is pushed..github/workflows/codeql.yml
static_analysis_common_vulnerabilitiesSUGGESTEDMetCodeQL runs the security-extended query suite, and bandit plus ruff's S (flake8-bandit) rules check for common Python security flaws such as injection, unsafe subprocess calls and unsafe deserialization..github/codeql/codeql-config.yml
static_analysis_fixedMUSTMetNo code-scanning alert is open on 2026-11-08; recent high and medium findings were fixed within two days, and each dismissed alert carries a written reason (a design choice recorded on the Scorecard posture page, or a Scorecard check that cannot pass yet), none an exploitable flaw./docs/security/openssf-scorecard-target#score-interpretation
static_analysis_oftenSUGGESTEDMetBandit, ruff and mypy run in CI on pushes and pull requests to main that touch the listed paths, and CodeQL runs on pushes and pull requests that touch src/ or the workflows, plus a weekly scheduled re-analysis..github/workflows/ci.yml

Analysis: Dynamic code analysis

CriterionLevelAnswerJustificationEvidence
dynamic_analysisSUGGESTEDMetCI runs the Hypothesis property-based tests in tests/property/, which execute the engine's parsers, merge, path-safety and profile loader with varied generated inputs, before any release tag is pushed.tree/main/tests/property
dynamic_analysis_unsafeSUGGESTEDN/AApothem is written in Python, with JavaScript for the npm shim and VS Code extension, and ships no C, C++ or other memory-unsafe code, including in its vendored pure-Python dependencies.tree/main/src/apothem
dynamic_analysis_enable_assertionsSUGGESTEDMetThe pytest and Hypothesis suites run in CI on a normal Python interpreter without -O, with pytest assertion rewriting, so all assert-based checks in the tests and property tests are active, while production code carries no assert statements.pyproject.toml
dynamic_analysis_fixedMUSTMetNo vulnerability of medium or higher severity found by the property tests or any other test run is left unfixed.tree/main/tests/property

Remaining gaps

These items are not blockers for the passing badge, and they need more than a statement in a repository file:

  • crypto_weaknesses (SHOULD, Unmet). The signed tag that the one-shot installers and the update scripts check names the release commit by a SHA-1 object ID, because the repository uses Git's SHA-1 object format, and the scripts pin the maintainer key by its OpenPGP v4 fingerprint, a SHA-1 hash; forging that pin would take a SHA-1 second preimage, not a collision. An install without cosign, and every install or update over an existing Apothem clone, installs a checkout of that commit, where every installed file rests on SHA-1. With cosign installed and no existing Apothem clone, the installed files rest on SHA-256 (the signed SHA256SUMS, checked by cosign against the tag's commit, and the archive digest), but the link from the maintainer's signed tag to that commit still rests on SHA-1. The gap stays open because the scripts check no maintainer-signed SHA-256 digest when they install a checkout, and the repository still uses Git's SHA-1 object format. Meeting the criterion needs a SHA-256 digest that the maintainer signs, checked on every default path, or a repository in Git's SHA-256 object format on a host that offers one, together with a way to pin the maintainer key that does not rest on SHA-1.
  • README badge. The badge itself can be added to the README only after registration gives the project its bestpractices.dev ID. It is a third-party registry badge, so the change also adds its row to the per-badge table on the Badge policy page.

Keep the answers current

Re-check this page when a change touches one of the linked files, and when bestpractices.dev changes its passing criteria. The live criteria page and the criteria.yml file in the badge repository are the sources to compare against.

References

On this page