The Security Frameworks is an open and collaborative initiative. Whether you are part of the Security Alliance or not, we welcome your contributions. Help us build the documentation and improve security in the blockchain ecosystem.
This handbook is designed for easy collaboration and automatic deployment through continuous integration. If you'd like to join our effort, feel free to fix typos, contribute new sections, or propose enhancements. If you want to take on a more active role for a specific domain, see Framework Stewardship.
Before contributing, please read our Code of Conduct to ensure that all interactions remain respectful, inclusive, and constructive.
Before contributing to SEAL Certifications specifically, please read the SEAL Certifications Contributing Guide for details on the certification framework and project specifics.
Join our Discord server, let others know what you are working on in the
frameworks-contribs group channel, and collaborate with other contributors writing about related topics.
The source code for the Security Frameworks is hosted on GitHub: github.com/security-alliance/frameworks.
- The main branch powers the stable Frameworks website (https://frameworks.securityalliance.org/) with reviewed and finalized content.
- The development branch (https://frameworks.securityalliance.dev/) contains ongoing updates, new sections, and draft content.
When contributing, please submit your Pull Requests to the development branch. Once changes are reviewed and approved, they will periodically be merged into the main branch for publication on the stable site.
There are several ways to contribute, depending on your preference and the scope of your changes. First, check existing PRs or branches to make sure your work has not been previously submitted.
If you are unsure whether your idea is a new page, a section under an existing page, or a whole new framework, open an issue or reach out on Discord before you start writing. We are happy to help you scope it.
- Use the "Contribute today!" button at the bottom of any page.
- Make fixes, formatting, and clarifications, favoring major modifications over just a few grammar mistakes.
- Changes go through GitHub's web interface without requiring local setup.
This covers writing a new page, adding a section to an existing page, or rewriting existing content.
The template.mdx is
the starting point for any new page. It lays out the required sections (key takeaway, intro, the basics, your content,
further reading), the optional ones, the frontmatter rules, and the import paths. The structure is the same one used
across every page on the site, which is what makes the Frameworks readable as a whole rather than as a pile of
individual contributions. Open it before you start writing, even if you are only adding a section to an existing page,
since the same structural rules apply.
The workflow:
- Fork the repository to your own GitHub account. For how to set up the project locally, see Development environment setup below.
- For a new page, copy
template.mdxinto the relevant framework folder underdocs/pages/, replace the placeholder content, and follow the instructions inside it. For changes to an existing page, edit the file directly; the same structural and frontmatter rules apply. - Make your changes in MDX on your fork. Add yourself to the file's
contributorsfield in the frontmatter, and create your profile indocs/pages/config/contributors.jsonif you do not already have one. This is how attribution works on the site. - Update the sidebar (
vocs.config.tsx) so your new page appears in site navigation. New content should always be added with thedev: trueflag, which keeps it on the development site only. Reviewed content gets promoted to the stable site periodically when we mergedevelopintomain. See Sidebar / Navigation below. - Run the build locally to make sure everything renders without errors. See Error checking.
- Open a Pull Request against the
developbranch. Use the Cloudflare Pages preview linked from the PR to verify the rendered site and make any final adjustments before review. All feedback and discussion should stay on the PR itself. - Notify reviewers by tagging the relevant steward (you can find stewards on the
Spotlight Zone page, listed alongside the framework they own) or a maintainer, and
request reviews directly in your PR. You can also paste your PR in the
frameworks-contribsDiscord channel for additional visibility. - Once reviewed and approved, your changes will be merged into
develop. Periodically, reviewed content fromdevelopis merged intomainfor the stable site.
A framework is a domain of security knowledge with enough depth and structure to warrant its own dedicated space on the site, an introduction, a set of pages covering different angles of the topic, and a steward who maintains it over time. Adding one is a bigger commitment than a single page, but it is also how the Frameworks grow.
The workflow is the same as adding a new page above, with these extra steps at the start:
- Create a new folder at
docs/pages/<your-framework-name>/. Use kebab-case (only normal dashes, no underscores or other separators). - Write
overview.mdxin that folder using the page template. The overview introduces the framework as a whole and lists every sub-page in the framework with a brief description. The template's "Overview pages only" comment shows the format. - Write the framework's other pages, each one using the same template.
- Run the build command. Beyond the usual error checking, this also generates the auto-generated index file your new framework needs to display correctly.
Look at the existing frameworks under docs/pages/ for examples of how pages are organized within a framework, how
the overview ties them together, and how internal cross-links are structured.
From there, follow the rest of the page-contribution workflow above (sidebar registration, attribution, PR, review).
If you are interested in a framework that does not currently have an active steward, you can become one yourself. See the Stewards guide for details on responsibilities, the open frameworks looking for stewards, and how to get started.
Choose the development approach that works best for you:
The easiest way to get started is to use our pre-configured devcontainer with VSCode:
- Prerequisites: VSCode with Dev Containers extension
- Open the project: VSCode will detect the devcontainer configuration
- Reopen in container: Command Palette (Ctrl+Shift+P) → "Dev Containers: Reopen in Container"
- Start developing: All tools are pre-installed and ready to use
Since you won't require extensions for the initiative to work, you can just create a devcontainer using the CLI and access it through whatever means suit you best.
Using DevContainer CLI (Recommended):
- Install DevContainer CLI
git clone https://github.com/security-alliance/frameworks.git
cd frameworks && git checkout develop
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash
# Get the IP address of the container, by running `hostname -I | awk '{print $1}'`. Should be printed automatically in the terminal after the creation as well
# Inside container: pnpm exec just serve
# Access the docs at http://<IP>:5173If you prefer to install dependencies locally on your machine:
Prerequisites:
- Node.js (v22 or later) and pnpm (for running Vocs locally)
- markdownlint-cli2 (For linting markdown files)
- Docker (Optional: For running the devcontainer)
- GitHub CLI (Optional: For using
ghto interact with GitHub)
Setup:
-
Install all prerequisites listed above
-
Clone the repository:
git clone https://github.com/security-alliance/frameworks.git cd frameworks && git checkout develop
-
Install Node.js dependencies:
pnpm install
-
Start the local development server
pnpm exec just serve -
Once the server is running, access the site on port
5173.
(Optional) Authenticate with GitHub CLI: The GitHub CLI (gh) is already preinstalled in the devcontainer. You can
authenticate by running gh auth login in the terminal, making it easy to interact with GitHub directly from your
development environment.
The page template is the source of truth for what every page should contain: required and optional sections, frontmatter rules, import paths, and writing guidance. Open it before you start writing.
The sections below cover the parts of contributing that live outside the page itself: how the sidebar works, how to make sure the build passes, and the writing style we expect across all pages.
Every page needs a title, a description, tags, and contributors. The shape looks like this:
---
title: "Your Page Title | Security Alliance"
description: "Your description here, 140-160 characters."
tags:
- Engineer/Developer
- Security Specialist
contributors:
- role: wrote
users: [your-github-username]
- role: reviewed
users: []
---Two things worth knowing up front:
- Titles stay under 60 characters including the
| Security Alliancesuffix; use| SEALfor longer titles. Avoid generic names like "Overview" or "Guide" alone. - Contributors are managed centrally. Your
users:entries reference profiles indocs/pages/config/contributors.json. Add yourself there if you do not already have an entry.
The full rules (description length, searchable terms, role list for tags, the auto-generation behavior for new tags, and worked examples) live in the page template.
Because of how we handle the .org and .dev domains in different branches, when contributing new pages you must
also update vocs.config.tsx so that the page appears in the site's sidebar. New content should always be added
with dev: true. Reviewed content gets promoted to the stable site periodically when we merge develop into main.
Example of a category with multiple pages:
{
text: 'Monitoring', // Category name visible in the sidebar
collapsed: true,
dev: true, // Indicates this category is in development
items: [
{ text: 'Overview', link: '/monitoring/README', dev: true }, // Indicates this page is in development
{ text: 'Guidelines', link: '/monitoring/guidelines', dev: true },
{ text: 'Thresholds', link: '/monitoring/thresholds', dev: true },
]
},A new page added to an existing, already-promoted category should still be set with dev: true, even if the parent
category does not have the flag. The dev: true belongs at the page level until that page is reviewed.
This ensures that new content appears correctly in the site's navigation for readers on the .dev site while staying
hidden from the stable .org site until ready.
Before pushing changes, always make sure your build works without errors:
- Run
pnpm exec just buildorpnpm run docs:build - Preview the updated content locally at port
4173with:pnpm exec just previeworpnpm run docs:preview
This helps catch build or formatting issues early so reviewers see clean contributions.
If you accidentally made unsigned commits in your fork, you'll need to rewrite them so they show as Verified before opening a PR.
- Understand how many commits you have to fix
- Run this command, replacing
Nwith the number of commits to go back (starting from the latest one):
git rebase -i HEAD~NIn the editor that opens:
- Change
pick→editfor each unsigned commit. - Save and exit.
For each commit you're editing:
git commit --amend -S --no-edit
git rebase --continueRepeat until all commits are re-signed.
Since history was rewritten, you need to force-push:
git push --forceCheck locally:
git log --show-signatureOr look at your branch on GitHub, commits should show a green Verified badge.
Wiki pages follow standard MDX.
The audience of this wiki is technical, and the content should reflect that. There are many guides on technical and documentation writing you can learn from; for example, you can check this lecture to get started.
- Write in an objective, explanatory tone; avoid unnecessary simplifications.
- Use concise sentences and break down complex ideas with bullet points, tables, images, or block-quotes.
- Always link your resources and verify them.
- Introduce acronyms and technical jargon before using them.
- Web3 changes fast; write the content to be as future-proof as possible.
- Do not submit content entirely generated by AI; however, we recommend using it to fix grammar or phrasing.
- Consider tutorials or hands-on guides for practical steps.
- Use visualizations (mermaid, diagrams, tables) to clarify concepts.
- Add recommended reading or dependencies at the top of a page if relevant.
- Focus on delivering credible, formal, technical content without unnecessary high-level introductions; use examples, comparisons, or anecdotes to clarify complex topics.
- Use American English consistently.
- Follow consistent terminology, capitalization, and nomenclature (see Ethereum.org style guide).
- Usage of images and visualizations is encouraged. If you are using an image created by a third party, make sure its license allows it and provide a link to the original. For creating your own visualizations, we suggest excalidraw.com.
- Feel free to use emojis or icons where it fits, for example in block-quotes.
-
Like GitHub, we also support Mermaid!
You can use codeblocks using the
mermaidkeyword, and you can create beautiful graphical representations. There's a playground where you can jump straight to draw!
pie title What Voldemort doesn't have? "FRIENDS" : 2 "FAMILY" : 3 "NOSE" : 45
- Adding images is welcome and encouraged.
Please follow the steps below to include them correctly:
1. After making your changes and opening a PR, add the images you want to include
in the PR's comments (by uploading them directly)
2. During the review, a maintainer will upload your images to our S3 bucket and reply with the links you should use.
3. Once you receive the new links, update your PR to add the images' links.
> ⚠️ Please do not add images directly to the repository.
> This helps us avoid bloating the Git history and ensures all images follow our standardized storage and delivery method.
### Linking resources
- Prefer descriptive names for external links (e.g., `inevitableeth.com` instead of "this wiki").
- Avoid overwhelming readers with too many inline links; consider a **Resources** section at the bottom.
- Use relative paths for internal links and heading IDs for specific sections.
- Provide archived mirrors or snapshots for important external references.
### In-page notices
- Use block-quote notices at the top of pages for context.
- **Incomplete pages** should include a stub notice:
> ⚠️ This article is still in progress. Help the framework by contributing and expanding it.
Pages with minimal content which need more work to cover the topic need to include a notice:
> ⚠️ This article is a [stub](https://en.wikipedia.org/wiki/Wikipedia:Stub), help the framework by
> [contributing](/docs/pages/contribute/contributing.mdx) and expanding it.
## Anything else?
This page is also open for contributions. Suggest improvements to our style and guidelines in the GitHub repo.
## About this page
Originally inspired by the [Ethereum Protocol Fellows](https://github.com/eth-protocol-fellows/protocol-studies).