bookstack-mcp

Projects that follow the best practices below can voluntarily self-certify and show that they've achieved an Open Source Security Foundation (OpenSSF) best practices badge.

There is no set of practices that can guarantee that software will never have defects or vulnerabilities; even formal methods can fail if the specifications or assumptions are wrong. Nor is there any set of practices that can guarantee that a project will sustain a healthy and well-functioning development community. However, following best practices can help improve the results of projects. For example, some practices enable multi-person review before release, which can both help find otherwise hard-to-find technical vulnerabilities and help build trust and a desire for repeated interaction among developers from different companies. To earn a badge, all MUST and MUST NOT criteria must be met, all SHOULD criteria must be met OR be unmet with justification, and all SUGGESTED criteria must be met OR unmet (we want them considered at least). If you want to enter justification text as a generic comment, instead of being a rationale that the situation is acceptable, start the text block with '//' followed by a space. Feedback is welcome via the GitHub site as issues or pull requests There is also a mailing list for general discussion.

We gladly provide the information in several locales, however, if there is any conflict or inconsistency between the translations, the English version is the authoritative version.
If this is your project, please show your baseline badge status on your project page! The baseline badge status looks like this: Baseline badge level for project 12116 is baseline-3 Here is how to embed the baseline badge:
You can show your baseline badge status by embedding this in your markdown file:
[![OpenSSF Baseline](https://www.bestpractices.dev/projects/12116/baseline)](https://www.bestpractices.dev/projects/12116)
or by embedding this in your HTML:
<a href="https://www.bestpractices.dev/projects/12116"><img src="https://www.bestpractices.dev/projects/12116/baseline"></a>


These are the Baseline Level 2 criteria. These criteria are from baseline version v2025.10.10 with updated criteria text from version v2026.02.19. Criteria that are new in version v2026.02.19 are labeled "future" and will begin to be enforced starting 2026-06-01. Please provide answers to the "future" criteria before that date.

Baseline Series: Baseline Level 1 Baseline Level 2 Baseline Level 3

        

 Basics

  • General

    Note that other projects may use the same name.

    BookStack stores your team's knowledge — but AI assistants can't access it without an integration. BookStack MCP Server bridges that gap, connecting AI assistants (Claude Desktop, LibreChat, and any MCP-compatible client) directly to your BookStack instance so they can search, read, and manage your documentation through natural language.

    Please use SPDX license expression format; examples include "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "GPL-2.0+", "LGPL-3.0+", "MIT", and "(BSD-2-Clause OR Ruby)". Do not include single quotes or double quotes.
    If there is more than one language, list them as comma-separated values (spaces optional) and sort them from most to least used. If there is a long list, please list at least the first three most common ones. If there is no language (e.g., this is a documentation-only or test-only project), use the single character "-". Please use a conventional capitalization for each language, e.g., "JavaScript".
    The Common Platform Enumeration (CPE) is a structured naming scheme for information technology systems, software, and packages. It is used in a number of systems and databases when reporting vulnerabilities.

 Controls 19/19 ●

  • Controls


    Enough for a badge!

    When a CI/CD task is executed with no permissions specified, the CI/CD system MUST default the task's permissions to the lowest permissions granted in the pipeline. [OSPS-AC-04.01]
    Configure the project's settings to assign the lowest available permissions to new pipelines by default, granting additional permissions only when necessary for specific tasks.

    All workflows declare permissions: read-all at the top level, establishing read-only as the baseline for every job. Individual jobs that require write access (e.g. pushing to GHCR, creating git tags) override only the specific permissions they need at the job level. GitHub Actions honours the most restrictive scope when no job-level override is present, so any task without explicit permissions inherits the read-all baseline rather than the default broad token permissions.


    Enough for a badge!

    When an official release is created, that release MUST be assigned a unique version identifier. [OSPS-BR-02.01]
    Assign a unique version identifier to each release produced by the project, following a consistent naming convention or numbering scheme. Examples include SemVer, CalVer, or git commit id.

    Every release is tagged with a unique semantic version identifier (e.g. v2.5.6) derived from the version field in packages/stdio/package.json. The CI/CD pipeline (docker-publish.yml) reads this value at merge time, asserts the version tag does not already exist in the registry, and creates the git tag only after the multi-arch Docker manifest is verified. Attempting to release a version that already exists in GHCR causes the pipeline to fail, enforcing uniqueness.


    Enough for a badge!

    When an official release is created, that release MUST contain a descriptive log of functional and security modifications. [OSPS-BR-04.01]
    Ensure that all releases include a descriptive change log. It is recommended to ensure that the change log is human-readable and includes details beyond commit messages, such as descriptions of the security impact or relevance to different use cases. To ensure machine readability, place the content under a markdown header such as "## Changelog".

    Each release produces a GitHub Release (automated via the merge job in docker-publish.yml) with notes extracted from the corresponding ## [X.Y.Z] section of CHANGELOG.md. The changelog follows the Keep a Changelog format and documents changes under categorised headings: Added, Fixed, Security, Dependencies, and Changed. See the v2.5.6 release as an example.


    Enough for a badge!

    When a build and release pipeline ingests dependencies, it MUST use standardized tooling where available. [OSPS-BR-05.01]
    Use a common tooling for your ecosystem, such as package managers or dependency management tools to ingest dependencies at build time. This may include using a dependency file, lock file, or manifest to specify the required dependencies, which are then pulled in by the build system.

    The build pipeline uses npm ci — the standardized, deterministic install command for Node.js/npm projects. npm ci installs exclusively from package-lock.json, ensuring exact, reproducible dependency versions across all CI runs. This is the npm-recommended practice for automated environments over npm install.


    Enough for a badge!

    When an official release is created, that release MUST be signed or accounted for in a signed manifest including each asset's cryptographic hashes. [OSPS-BR-06.01]
    Sign all released software assets at build time with a cryptographic signature or attestations, such as GPG or PGP signature, Sigstore signatures, SLSA provenance, or SLSA VSAs. Include the cryptographic hashes of each asset in a signed manifest or metadata file.

    Docker images are published to GHCR with SLSA Level 2 provenance attestations generated by actions/attest-build-provenance during each post-merge build. The attestation records the builder identity, source commit SHA, and a signed manifest of the image digests, anchored to the GitHub Actions OIDC token. The attestation is stored in the repository's attestation log and can be verified with gh attestation verify.


    Enough for a badge!

    When the project has made a release, the project documentation MUST include a description of how the project selects, obtains, and tracks its dependencies. [OSPS-DO-06.01]
    It is recommended to publish this information alongside the project's technical & design documentation on a publicly viewable resource such as the source code repository, project website, or other channel.

    Dependencies are declared in packages/core/package.json and packages/stdio/package.json and locked in package-lock.json. All installs use npm ci for reproducible builds. Updates are automated via Dependabot (weekly schedule for npm, GitHub Actions, and Docker base image). Vulnerability tracking uses npm audit on every CI build, OSV Scanner, and Trivy image scanning. See the Dependency Management section in README.md.


    Enough for a badge!

    (Future criterion) The project documentation MUST include instructions on how to build the software, including required libraries, frameworks, SDKs, and dependencies. [OSPS-DO-07.01]
    It is recommended to publish this information alongside the project's contributor documentation, such as in CONTRIBUTING.md or other developer task documentation. This may also be documented using Makefile targets or other automation scripts.

    Build instructions are documented in README.md under "Quick Start" (prerequisites: Node.js 18+, npm; steps: npm install, npm run build) and in CONTRIBUTING.md under "Getting started". Required dependencies are listed in packages/core/package.json and packages/stdio/package.json. The project has no system-level library requirements beyond Node.js and npm.


    Enough for a badge!

    While active, the project documentation MUST include a list of project members with access to sensitive resources. [OSPS-GV-01.01]
    Document project participants and their roles through such artifacts as members.md, governance.md, maintainers.md, or similar file within the source code repository of the project. This may be as simple as including names or account handles in a list of maintainers, or more complex depending on the project's governance.

    MAINTAINERS.md in the repository root lists all project members with access to sensitive resources (GitHub repo admin, GHCR registry, GitHub Actions secrets). The project has a single maintainer: @paradoxbound. No manually stored secrets exist — the only credential used by CI is the auto-provisioned GITHUB_TOKEN


    Enough for a badge!

    While active, the project documentation MUST include descriptions of the roles and responsibilities for members of the project. [OSPS-GV-01.02]
    Document project participants and their roles through such artifacts as members.md, governance.md, maintainers.md, or similar file within the source code repository of the project.

    MAINTAINERS.md describes the project's single Maintainer role held by @paradoxbound, with responsibilities covering repository administration, release management (approving and merging PRs, triggering the release pipeline), and ownership of sensitive resources (GitHub repo, GHCR registry, Actions secrets).


    Enough for a badge!

    While active, the project documentation MUST include a guide for code contributors that includes requirements for acceptable contributions. [OSPS-GV-03.02]
    Extend the CONTRIBUTING.md or CONTRIBUTING/ contents in the project documentation to outline the requirements for acceptable contributions, including coding standards, testing requirements, and submission guidelines for code contributors. It is recommended that this guide is the source of truth for both contributors and approvers.

    CONTRIBUTING.md in the repository root provides a contribution guide covering: repository setup and build steps, project structure, the pull request workflow (fork → branch from main → pass type-check and build → open PR), how to run tests, security vulnerability reporting, and the code style requirements (TypeScript strict mode, native fetch only, Zod schemas for inputs, specific error handling patterns). These constitute the requirements for acceptable contributions.


    Enough for a badge!

    While active, the version control system MUST require all code contributors to assert that they are legally authorized to make the associated contributions on every commit. [OSPS-LE-01.01]
    Include a DCO in the project's repository, requiring code contributors to assert that they are legally authorized to commit the associated contributions on every commit. Use a status check to ensure the assertion is made. A CLA also satisfies this requirement. Some version control systems, such as GitHub, may include this in the platform terms of service.

    All pull requests are checked by a GitHub Actions DCO workflow (dco.yml) that fails if any commit lacks a Signed-off-by: line. The DCO sign-off check is required before merging. Contributors are instructed to use git commit -s in CONTRIBUTING.md. This implements the Developer Certificate of Origin, asserting legal authorisation to contribute under the MIT License.


    Enough for a badge!

    When a commit is made to the primary branch, any automated status checks for commits MUST pass or be manually bypassed. [OSPS-QA-03.01]
    Configure the project's version control system to require that all automated status checks pass or require manual acknowledgement before a commit can be merged into the primary branch. It is recommended that any optional status checks are NOT configured as a pass or fail requirement that approvers may be tempted to bypass.

    GitHub branch protection on main requires all status checks to pass before merging. The required checks are: test (functional-tests.yml), build-and-push (docker-publish.yml), and pre-merge-cd-check (docker-publish.yml). "Do not allow bypassing the above settings" is enabled, preventing administrators from merging without passing checks. Bypasses are therefore explicit and require removing branch protection rules, which is itself a logged, auditable action.


    Enough for a badge!

    Prior to a commit being accepted, the project's CI/CD pipelines MUST run at least one automated test suite to ensure the changes meet expectations. [OSPS-QA-06.01]
    Automated tests should be run prior to every merge into the primary branch. The test suite should be run in a CI/CD pipeline and the results should be visible to all contributors. The test suite should be run in a consistent environment and should be run in a way that allows contributors to run the tests locally. Examples of test suites include unit tests, integration tests, and end-to-end tests.

    The functional-tests.yml workflow runs on every pull request targeting main and on every push to main. It executes npm run build, npm run type-check, and npm test (the full vitest suite including unit tests, fuzz tests, and where credentials are available, functional tests against a live BookStack instance). This check is a required status check — PRs cannot merge unless it passes.


    Enough for a badge!

    When the project has made a release, the project documentation MUST include design documentation demonstrating all actions and actors within the system. [OSPS-SA-01.01]
    Include designs in the project documentation that explains the actions and actors. Actors include any subsystem or entity that can influence another segment in the system. Ensure this is updated for new features or breaking changes.

    The README Architecture section documents all actors (MCP client, bookstack-mcp server, BookStack API client, BookStack instance, operator) in a table, and includes an ASCII data flow diagram showing the complete request/response path through the system — from MCP client through stdio transport, Zod validation, the BookStack HTTP client, and back. Key design decisions (native fetch, write-gate, Zod schemas, stdio transport, monorepo split) are also documented.


    Enough for a badge!

    When the project has made a release, the project documentation MUST include descriptions of all external software interfaces of the released software assets. [OSPS-SA-02.01]
    Document all software interfaces (APIs) of the released software assets, explaining how users can interact with the software and what data is expected or produced. Ensure this is updated for new features or breaking changes.

    The README documents all external software interfaces: the MCP tool interface (45 tools listed with descriptions), the environment variable configuration interface, the BookStack REST API dependency (with authentication format), and the stdio transport interface as consumed by each supported MCP client (Claude Desktop and LibreChat).


    Enough for a badge!

    When the project has made a release, the project MUST perform a security assessment to understand the most likely and impactful potential security problems that could occur within the software. [OSPS-SA-03.01]
    Performing a security assessment informs both project members as well as downstream consumers that the project understands what problems could arise within the software. Understanding what threats could be realized helps the project manage and address risk. This information is useful to downstream consumers to demonstrate the security acumen and practices of the project. Ensure this is updated for new features or breaking changes.

    SECURITY.md contains a Security Assessment section documenting six threats with severity ratings (HIGH/MEDIUM/LOW) and existing mitigations: API credential exposure, unintended write operations, prompt injection via BookStack content, insecure transport (now enforced at startup), supply chain compromise, and SSRF via BOOKSTACK_BASE_URL.


    Enough for a badge!

    While active, the project documentation MUST include a policy for coordinated vulnerability disclosure (CVD), with a clear timeframe for response. [OSPS-VM-01.01]
    Create a SECURITY.md file at the root of the directory, outlining the project's policy for coordinated vulnerability disclosure. Include a method for reporting vulnerabilities. Set expectations for how the project will respond and address reported issues.

    SECURITY.md documents a coordinated vulnerability disclosure policy: reporters use GitHub's private Security Advisory feature, can expect acknowledgement within 7 days and a patch or mitigation within 30 days where feasible, and will be credited in the advisory unless they request otherwise.


    Enough for a badge!

    While active, the project documentation MUST provide a means for private vulnerability reporting directly to the security contacts within the project. [OSPS-VM-03.01]
    Provide a means for security researchers to report vulnerabilities privately to the project. This may be a dedicated email address, a web form, VCS specialized tools, email addresses for security contacts, or other methods.

    SECURITY.md directs reporters to use GitHub's private Security Advisory feature (https://github.com/paradoxbound/bookstack-mcp/security/advisories/new), which routes directly to the maintainer without public disclosure. The README also links to SECURITY.md via the Security Considerations section.


    Enough for a badge!

    While active, the project documentation MUST publicly publish data about discovered vulnerabilities. [OSPS-VM-04.01]
    Provide information about known vulnerabilities in a predictable public channel, such as a CVE entry, blog post, or other medium. To the degree possible, this information should include affected version(s), how a consumer can determine if they are vulnerable, and instructions for mitigation or remediation.

    SECURITY.md states that once a fix is released, the GitHub Security Advisory will be published publicly and a CVE requested where appropriate, and that security fixes are recorded in CHANGELOG.md under the relevant release.



This data is available under the Community Data License Agreement – Permissive, Version 2.0 (CDLA-Permissive-2.0). This means that a Data Recipient may share the Data, with or without modifications, so long as the Data Recipient makes available the text of this agreement with the shared Data. Please credit Jim Bailey and the OpenSSF Best Practices badge contributors.

Project badge entry owned by: Jim Bailey.
Entry created on 2026-03-08 10:20:21 UTC, last updated on 2026-03-10 14:13:23 UTC. Last achieved passing badge on 2026-03-10 14:13:23 UTC.