diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 422c4385..6d8e5ce7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,10 +11,11 @@ while this copy is needed to make it highlighted in the repository dashboard. # **Contributing guidelines** 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. +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. +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](/docs/pages/contribute/stewards.mdx). **Before contributing, please read our [Code of Conduct](https://github.com/security-alliance/frameworks/blob/develop/CODE_OF_CONDUCT.md)** to ensure that all @@ -38,46 +39,90 @@ finalized content. 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 be merged into the **main branch** for publication on the stable site. +approved, they will periodically be merged into the **main branch** for publication on the stable site. ## Ways to contribute -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. +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](https://discord.gg/securityalliance) before you start writing. We are happy to help +you scope it. ### 1. Quick edits -- 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 -- If someone already has an open PR, you can review the Cloudflare Pages preview linked from that PR and leave - proofreading or feedback on the PR itself without opening your own PR. This is a rendered preview for review, not a - separate commenting feature on the live site. - -### 2. Add a new section or expand an existing one - -All contributions should follow this workflow: - -1. **Fork the repository** to your own GitHub account. -2. **Follow the [`template.mdx`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx) -page** when creating or expanding content. It contains pre-defined components and structure required for consistency -in MDX files. -3. **Make your changes** in MDX (typos, improvements, or new content) on your fork. -4. **Open a Pull Request (PR) against the `develop` branch** of this repository. Once submitted, 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. -5. **Notify reviewers** by tagging a steward or maintainer, requesting reviews directly in your PR. -6. Additionally, you can paste your PR and/or potential associated issues to the `frameworks-contribs` Discord channel. -7. Once reviewed and approved, your changes will be merged into `develop`. -8. Don't forget to add yourself to the YAML header of the file you're modifying, given that is the way we provide - attribution. You should also create your profile inside the contributors list, at `docs/pages/config/contributors.json`. -9. Periodically, reviewed content from `develop` is merged into `main` for the stable site. - -If you’re interested in a framework that doesn’t currently have an active steward, you can **become one yourself**. See -the [Stewards guide](/docs/pages/contribute/stewards.mdx) for details on responsibilities and how to get started. - -**⚠️ Please sign and verify all commits.** (If you have unsigned commits, follow the “Fixing Unsigned Commits” section -below to update them) +- 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. + +### 2. Add a new page or expand an existing one + +This covers writing a new page, adding a section to an existing page, or rewriting existing content. + +The [`template.mdx`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/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: + +1. **Fork the repository** to your own GitHub account. For how to set up the project locally, see + [Development environment setup](#development-environment-setup) below. +2. **For a new page**, copy `template.mdx` into the relevant framework folder under `docs/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. +3. **Make your changes** in MDX on your fork. Add yourself to the file's `contributors` field in the frontmatter, and + create your profile in [`docs/pages/config/contributors.json`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/contributors.json) + if you do not already have one. This is how attribution works on the site. +4. **Update the sidebar** (`vocs.config.tsx`) so your new page appears in site navigation. New content should always + be added with the `dev: true` flag, which keeps it on the development site only. Reviewed content gets promoted to + the stable site periodically when we merge `develop` into `main`. See [Sidebar / Navigation](#sidebar--navigation) + below. +5. **Run the build locally** to make sure everything renders without errors. See [Error checking](#error-checking). +6. **Open a Pull Request against the `develop` branch.** 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. +7. **Notify reviewers** by tagging the relevant steward (you can find stewards on the + [Spotlight Zone](/docs/pages/contribute/spotlight-zone.mdx) 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-contribs` Discord channel for + additional visibility. +8. Once reviewed and approved, your changes will be merged into `develop`. Periodically, reviewed content from + `develop` is merged into `main` for the stable site. + +**⚠️ Please sign and verify all commits.** If you have unsigned commits, follow the [Fixing unsigned +commits](#fixing-unsigned-commits) section below to update them. + +### 3. Add a new framework + +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](#2-add-a-new-page-or-expand-an-existing-one) above, with these extra +steps at the start: + +1. **Create a new folder** at `docs/pages//`. Use kebab-case (only normal dashes, no underscores + or other separators). +2. **Write `overview.mdx`** in that folder using the [page template](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx). + 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. +3. **Write the framework's other pages**, each one using the same template. +4. **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). + +### Want to take on more? + +If you are interested in a framework that does not currently have an active steward, you can become one yourself. +See the [Stewards guide](/docs/pages/contribute/stewards.mdx) for details on responsibilities, the open frameworks looking for +stewards, and how to get started. ## Development environment setup @@ -151,140 +196,57 @@ If you prefer to install dependencies locally on your machine: authenticate by running `gh auth login` in the terminal, making it easy to interact with GitHub directly from your development environment. -## Fixing unsigned commits - -If you accidentally made unsigned commits in your fork, you’ll need to rewrite them so they show as **Verified** before -opening a PR. - -### 1. Rebase your recent commits - -- Understand how many commits you have to fix -- Run this command, replacing `N` with the number of commits to go back (starting from the latest one): - -```bash -git rebase -i HEAD~N -``` - -### 2. Mark commits to fix - -In the editor that opens: +## Page requirements -- Change `pick` → `edit` for each unsigned commit. -- Save and exit. +The [page template](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx) 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. -### 3. Re-sign each commit +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. -For each commit you’re editing: +### Frontmatter -```bash -git commit --amend -S --no-edit -git rebase --continue -``` - -Repeat until all commits are re-signed. - -### 4. Push your changes - -Since history was rewritten, you need to **force-push**: - -```bash -git push --force -``` - -### 5. Verify - -Check locally: - -```bash -git log --show-signature -``` - -Or look at your branch on GitHub — commits should show a green **Verified** badge. - -## Contributor tasks beyond content changes - -When contributing to the Security Frameworks, there are several additional responsibilities to ensure your updates -integrate smoothly into the site and maintain proper structure: - -### 1. Frontmatter - -Every page requires frontmatter at the top of the file. Here are the key fields: - -#### Title and Description - -Add a title and description to every page you add: +Every page needs a `title`, a `description`, `tags`, and `contributors`. The shape looks like this: ```yaml --- title: "Your Page Title | Security Alliance" -# SEO meta description: 140-160 chars. Start with the framework/topic name, include -# searchable terms (tool names, attack types, standards), use action verbs. description: "Your description here, 140-160 characters." ---- -``` - -**Titles** should be concise and descriptive—avoid generic names like "Overview" or "Guide" alone. -Use "Preparing for a Smart Contract Audit" instead of "Preparation". Keep titles under 60 characters -(including the `| Security Alliance` suffix) so they display fully in search results. If your title -is too long, use `| SEAL` instead. - -**Meta descriptions** appear in search results and determine whether researchers click through. -Aim for 140-160 characters, include searchable terms whitehats use (tool names, attack types, -standards), and use action verbs. See -[Google's guide](https://developers.google.com/search/docs/appearance/snippet) for more details. - -- ✅ `"Smart contract audits: scoping, static analysis, manual review, and formal verification."` -- ❌ `"This page covers security topics."` (too vague, no searchable terms) - -#### Tags - -Assign tags to categorize content by role, topic, or skill level: - -```yaml ---- tags: - Engineer/Developer - Security Specialist ---- -``` - -Proper tagging makes your contribution discoverable and filterable on the site. - -#### Contributors - -Add yourself and other relevant contributors: - -```yaml ---- contributors: - role: wrote users: [your-github-username] - role: reviewed - users: [reviewer1, reviewer2] + users: [] --- ``` -Contributors are **managed centrally**: +Two things worth knowing up front: -- **Contributor database:** `docs/pages/config/contributors.json` -- **Usage guide:** `docs/pages/config/using-contributors.mdx` +- **Titles** stay under 60 characters including the `| Security Alliance` suffix; use `| SEAL` for longer titles. + Avoid generic names like "Overview" or "Guide" alone. +- **Contributors are managed centrally.** Your `users:` entries reference profiles in + [`docs/pages/config/contributors.json`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/contributors.json). + Add yourself there if you do not already have an entry. -This helps track contributions and ensures proper attribution. +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](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx?plain=1). -For a complete frontmatter example, see the [template file](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx?plain=1). - -### 2. Sidebar / Navigation +### Sidebar / Navigation 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. For content still in review, remember -to set `dev: true`. +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: ```tsx { text: 'Monitoring', // Category name visible in the sidebar - collapsed: false, + collapsed: true, dev: true, // Indicates this category is in development items: [ { text: 'Overview', link: '/monitoring/README', dev: true }, // Indicates this page is in development @@ -292,13 +254,15 @@ Example of a category with multiple pages: { text: 'Thresholds', link: '/monitoring/thresholds', dev: true }, ] }, - ``` -This ensures that new content appears correctly in the site’s navigation for readers on the `.dev` site while staying +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. -### 3. Error Checking +### Error checking Before pushing changes, always make sure your build works without errors: @@ -307,28 +271,77 @@ Before pushing changes, always make sure your build works without errors: This helps catch build or formatting issues early so reviewers see clean contributions. +## Fixing unsigned commits + +If you accidentally made unsigned commits in your fork, you'll need to rewrite them so they show as **Verified** before +opening a PR. + +### 1. Rebase your recent commits + +- Understand how many commits you have to fix +- Run this command, replacing `N` with the number of commits to go back (starting from the latest one): + +```bash +git rebase -i HEAD~N +``` + +### 2. Mark commits to fix + +In the editor that opens: + +- Change `pick` → `edit` for each unsigned commit. +- Save and exit. + +### 3. Re-sign each commit + +For each commit you're editing: + +```bash +git commit --amend -S --no-edit +git rebase --continue +``` + +Repeat until all commits are re-signed. + +### 4. Push your changes + +Since history was rewritten, you need to **force-push**: + +```bash +git push --force +``` + +### 5. Verify + +Check locally: + +```bash +git log --show-signature +``` + +Or look at your branch on GitHub, commits should show a green **Verified** badge. + ## Style guide -Wiki pages follow standard MDX. +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](https://www.youtube.com/watch?v=vtIzMaLkCaM) to get started. +documentation writing you can learn from; for example, you can check [this +lecture](https://www.youtube.com/watch?v=vtIzMaLkCaM) to get started. ### Writing guidelines - 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 +- 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 +- 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. -- You can use mermaid diagrams for visualizations ### Content standardization @@ -338,7 +351,7 @@ guide](https://ethereum.org/contributing/style-guide/content-standardization)). - 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](https://github.com/excalidraw/excalidraw). -- Feel free to use [emojis](https://docsify.js.org/#/emoji?id=emoji) or [icons](https://icongr.am/fontawesome) where it +- Feel free to use [emojis](https://docsify.js.org/#/emoji?id=emoji) or [icons](https://icongr.am/fontawesome) where it fits, for example in block-quotes. ### Visual representation / drawings @@ -355,13 +368,13 @@ 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) + 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. @@ -370,7 +383,7 @@ pie title What Voldemort doesn't have? ### Linking resources -- Prefer descriptive names for external links (e.g., `inevitableeth.com` instead of “this wiki”). +- 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. @@ -389,7 +402,7 @@ Pages with minimal content which need more work to cover the topic need to inclu ## Anything else? -This page is also open for contributions! Suggest improvements to our style and guidelines in the GitHub repo. +This page is also open for contributions. Suggest improvements to our style and guidelines in the GitHub repo. ## About this page diff --git a/docs/pages/config/template.mdx b/docs/pages/config/template.mdx index 5c23e8c6..ca4bbe27 100644 --- a/docs/pages/config/template.mdx +++ b/docs/pages/config/template.mdx @@ -1,14 +1,43 @@ --- -title: "Template" -# SEO meta description: 140-160 chars. Start with the framework/topic name, include -# searchable terms (tool names, attack types, standards), use action verbs. -description: "Replace this with a concise summary of the page content. Include searchable keywords relevant to security researchers and whitehats." +title: "Page Title | Security Alliance" +# Keep titles under 60 characters total (including "| Security Alliance"). +# For long titles, use "| SEAL" instead: "A Longer Page Title | SEAL" + +description: "Replace this with a concise summary of the page content." +# 140-160 characters. Start with the topic name, include searchable terms +# (tool names, attack types, standards), and use action verbs. +# Good: "Smart contract audits: scoping, static analysis, manual review, and formal verification." +# Avoid: "This page covers security topics." Too vague, no searchable terms. + tags: +# Existing tags (use any that apply): - Security Specialist - Operations & Strategy - Community & Marketing - HR - Engineer/Developer + - DevOps + - SRE + - SEAL/Initiative + - Cloud + - DAO + - Legal & Compliance + - Protocol + - Whitehat + - Certifications + - Multisig Security + - SFC + - DeFi + - Operations + - Risk Management + - Treasury Ops + - Business Tools + - Communication Platforms + - DevOps Accounts + - Smart Contracts +# Need a tag that doesn't exist yet? Just add it. The build will auto-generate +# a unique color for it and register it in components/shared/tagColors.ts automatically. + contributors: - role: wrote users: [mattaereal] @@ -18,6 +47,74 @@ contributors: users: [] --- +{/* + This file is the template for new framework pages. Copy it as your starting + point, replace the placeholder content, and remove any instructional comments + before opening a PR. + + The structure below is a proposed layout, not a strict mold. Some sections + are marked (required), every page needs these. The rest are optional building + blocks; pick the ones that fit your content. Pages on this site mix conceptual, + procedural, and reference material, often within the same page, and the + template is meant to support that. + + Do NOT remove the imports and the components below (e.g. or ). + They are required for every page to render correctly. + + For the full contribution workflow (environment setup, signed commits, + sidebar updates, build commands), see docs/pages/contribute/contributing. + + Heading hierarchy: # for the page title, ## for sections, ### for subsections. + Never skip levels (e.g., jumping from ## directly to ####), as it breaks the + table of contents and screen-reader navigation. +*/} + +{/* ============================================================================ + ADDING A WHOLE NEW FRAMEWORK? READ THIS. OTHERWISE SKIP TO THE IMPORT BELOW. + ============================================================================ + + If you are contributing a single page or rewriting an existing one, this + block does not apply to you. Skip ahead. + + If you are unsure whether your topic is a new framework, a section in an + existing one, or a single page, open an issue first so we can align on + scope before you start writing. + + If you are creating a new framework (a new folder under docs/pages/ with + multiple pages), the workflow is: + + 1. Create a new folder: docs/pages//. Use kebab-case. + Do not use underscores or any other separator. Only normal dashes are + allowed. + + 2. Write an overview.mdx in that folder using this template. The overview + page introduces the framework as a whole and ends with a "Pages" section + listing every sub-page with a one-line description (see the OVERVIEW + PAGES note further down in this file). + + 3. Write the rest of the framework's pages, each one using this template. + + 4. Register the new framework in the sidebar with the `dev: true` flag, so + it appears on the dev site but stays off production until reviewed. + + 5. Run the build command. This generates the auto-generated index file and + handles the other site-side artifacts your new framework needs to + display correctly. + + 6. Reference implementation: see docs/pages/supply-chain/ as a working + example of a complete framework. + + For full details on the workflow above (sidebar syntax, build command, + signed commits, PR conventions), see docs/pages/contribute/contributing. +============================================================================ */} + +{/* + IMPORT PATH: the '../../../components' path below works for pages placed at + docs/pages//.mdx (one level deep inside a + framework folder). If your page sits one level deeper, for example + docs/pages///.mdx, add one more '../' + so the import becomes '../../../../components'. +*/} import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } from '../../../components' @@ -28,68 +125,102 @@ import { TagList, AttributionList, TagProvider, TagFilter, ContributeFooter } fr -Key Takeaway prompt: Without removing or modifying anything in the document, just after the heading, describe in a -succinct way (no more than 40 words), all the key points or tl;dr so that anyone can get a good grasp of the contents -just by reading it. Don't add unnecessary sentences that sound like conclusions, like "By ensuring this..." "Doing all -these...", "Having these security practices...". Use the following format: +> 🔑 **Key Takeaway**: [Required. One or two sentences a reader can walk away +> with if they read nothing else. Not a summary of the page; the *point* of the +> page. Avoid filler conclusions like "By doing this..." or "Having these +> practices...". Prefer concrete claims over abstract ones.] -> 🔑 **Key Takeaway**: +[Required. This block sits directly under the Key Takeaway with no heading of +its own, so the page opens as continuous reading. Write two or three short +paragraphs in plain language that introduce the topic and establish the stakes. +The Frameworks are read by people at every level of expertise, from seasoned +security engineers to community managers learning the basics, so do not assume +the reader already knows what you are talking about. Explain what the topic is, +who it affects, and why it matters in the Web3 context specifically.] -[Context / Problem statement. In this first part, we introduce the topic, in no more than a few paragraphs. For example -for Threat Modeling inside Operational Security Framework: "Effective security requires understanding **what you're -protecting and who you're protecting it from**. Without a structured threat model, security efforts become unfocused and -inefficient. Different entities face different threats based on their assets, visibility, and technological footprint." -It can be this short, or it can have more context] +## The basics -## Practical guidance +[Required. The foundational, definitional layer. Use this section to lay out +the core concepts, components, or vocabulary the rest of the page builds on. +For a topic like supply chain security, this is where you would explain what +makes up a supply chain in the Web3 context. For a topic like threat modeling, +this is where you would explain what a threat model is and what it contains. -1. **Step-by-Step Actions** – numbered list users can follow. -2. **Best-Practice Checklist** – bullet list they can literally tick. -3. **Role-Based Tips** – highlight differences for Ops, HR, Dev, etc. -(This mirrors OWASP Cheat Sheet brevity.) +Rename this section to something specific to your topic if a better name +exists ("What Makes Up a Web3 Supply Chain", "Anatomy of a Phishing Attack", +"Components of a Threat Model"), but do not skip the layer itself. A reader +who is new to the topic should be oriented before any deeper content begins.] -## Why is it important +## [Your section title] -Explain consequences of ignoring this guidance and link to real incidents or CISA/NIST advisories supporting each risk. +[Required. This is where the substance of your page lives. You are an expert +on this topic; break it into the sections that make sense for what you have +to teach, name them after their actual content, and write each one in the +format that fits best. -## Implementation details +Use ### subsections within each one as needed. -| Sub-Topic | Related Page | -| ----------- | -------------- | -| Device Hardening | `../endpoint-security/...` | -| Network Segmentation | `../network-security/...` | +Common formats to mix and match within a section: -Cross-linking reduces duplication, following docs-as-code best practice. +- **Walkthrough**: numbered steps, top to bottom. Use when order matters. +- **Checklist**: bullet points the reader can tick. Use when order does not matter. +- **Decision tree or matrix**: table or branching guide. Use when the right + answer depends on the reader's situation. +- **Plain explanation**: paragraphs. Use when the content is conceptual or + when format would get in the way. -## 5 Common pitfalls & examples +When discussing failure modes or common mistakes, anchor them to a specific +recommendation rather than collecting them in a separate "pitfalls" section. +For example: "Rotate signing keys quarterly. Teams often skip this because no +incident forces it, which is exactly when key compromise causes the most +damage." This keeps the warning where it is useful instead of in a generic list.] -Real-world breach snippets or failure stories that illustrate mistakes to avoid. -{/* :contentReference[oaicite:6]{index=6} */} +## Real-world examples -## 6 Quick-reference / Cheat sheet +[Optional. Include only if you can point to a specific incident, breach, +post-mortem, or named scenario. Skip the section entirely if you do not have one. -A compact table or numbered list for on-the-job use, inspired by OWASP cheat sheets. -{/* :contentReference[oaicite:7]{index=7} */} +When you do include an example, link to the source: an incident write-up, a +CISA advisory, a CVE, a post-mortem, or a credible reporting source.] -## 7 Further Reading & Tools +{/* ============================================================================ + OVERVIEW PAGES ONLY: include the "Pages" section below. -Automatically generated from the `references:` field or add authoritative links here. + If this is the overview.mdx for a framework, include a Pages section that + lists every sub-page in the framework with a one-line description, like this: -{/* -CITATION SOURCES -turn0search0 Jekyll front-matter basics – validates YAML metadata structure. -turn0search2 NIST practice guides use an executive-summary section. -turn0search3 CISA report templates also open with Executive Summary. -turn0search4 OWASP Cheat Sheet series shows concise prescriptive guidance. -turn0search5 Kubernetes style guide recommends short sections & headings. -turn0search6 Google developer style guide echoes those principles. -turn0search7 Version-history tables are a best practice for change control. -turn0search8 Jekyll step-by-step docs reinforce YAML front-matter placement. -turn0search11 CISA advisories supply risk context references. -turn0search12 OWASP Cheat Sheet project cited for quick-reference idea. -turn0search13 Kubernetes “page content types” shows cross-linking strategy. -turn0search10 NIST CSF overview underpins risk-management rationale. -*/} + ## Pages + + 1. [Dependency Awareness](/supply-chain/dependency-awareness): + managing external packages, version pinning, lockfile integrity, and + protection against typosquatting. + 2. [Web3 Supply Chain Threats](/supply-chain/web3-supply-chain-threats): + threat vectors specific to Web3, from frontend library hijacking to + infrastructure compromise. + + Keep this list in sync with the sidebar config when pages are added, + renamed, or removed. + + If this is a regular sub-page (not an overview), delete this comment and + skip straight to "Further Reading & Tools" below. +============================================================================ */} + +## Further Reading & Tools + +[Required. Two types of links belong here: + +1. Related pages within the frameworks or entire frameworks. Use paths relative + to your page, with a short description of why the reader would follow the link: + - [Wallet Security](/wallet-security/overview): specific wallet security practices + - [DevSecOps](/devsecops/overview): integrating dependency scanning into CI/CD + +2. External articles, standards, or tools cited in the content. Use full URLs: + - [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/) + - [CISA Known Exploited Vulnerabilities Catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) + +Every external claim made in the page body should be traceable to a link here +or to an inline citation. Use descriptive link text. No bare URLs, no "click +here", no "this article".] --- diff --git a/docs/pages/contribute/contributing.mdx b/docs/pages/contribute/contributing.mdx index a2612bf4..e3cb7a98 100644 --- a/docs/pages/contribute/contributing.mdx +++ b/docs/pages/contribute/contributing.mdx @@ -23,10 +23,11 @@ import { ContributeFooter, TagFilter, TagProvider, MermaidRenderer } from '../.. # **Contributing guidelines** 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. +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. +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](/contribute/stewards). **Before contributing, please read our [Code of Conduct](https://github.com/security-alliance/frameworks/blob/develop/CODE_OF_CONDUCT.md)** to ensure that all @@ -50,46 +51,90 @@ finalized content. 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 be merged into the **main branch** for publication on the stable site. +approved, they will periodically be merged into the **main branch** for publication on the stable site. ## Ways to contribute 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](https://discord.gg/securityalliance) before you start writing. We are happy to help +you scope it. + ### 1. Quick edits -- 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 -- If someone already has an open PR, you can review the Cloudflare Pages preview linked from that PR and leave - proofreading or feedback on the PR itself without opening your own PR. This is a rendered preview for review, not a - separate commenting feature on the live site. - -### 2. Add a new section or expand an existing one - -All contributions should follow this workflow: - -1. **Fork the repository** to your own GitHub account. -2. **Follow the [`template.mdx`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx) -page** when creating or expanding content. It contains pre-defined components and structure required for consistency -in MDX files. -3. **Make your changes** in MDX (typos, improvements, or new content) on your fork. -4. **Open a Pull Request (PR) against the `develop` branch** of this repository. Once submitted, 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. -5. **Notify reviewers** by tagging a steward or maintainer, requesting reviews directly in your PR. -6. Additionally, you can paste your PR and/or potential associated issues to the `frameworks-contribs` Discord channel. -7. Once reviewed and approved, your changes will be merged into `develop`. -8. Don't forget to add yourself to the YAML header of the file you're modifying, given that is the way we provide - attribution. You should also create your profile inside the contributors list, at `docs/pages/config/contributors.json`. -9. Periodically, reviewed content from `develop` is merged into `main` for the stable site. - -If you’re interested in a framework that doesn’t currently have an active steward, you can **become one yourself**. See -the [Stewards guide](/contribute/stewards) for details on responsibilities and how to get started. - -**⚠️ Please sign and verify all commits.** (If you have unsigned commits, follow the “Fixing Unsigned Commits” section -below to update them) +- 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. + +### 2. Add a new page or expand an existing one + +This covers writing a new page, adding a section to an existing page, or rewriting existing content. + +The [`template.mdx`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/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: + +1. **Fork the repository** to your own GitHub account. For how to set up the project locally, see + [Development environment setup](#development-environment-setup) below. +2. **For a new page**, copy `template.mdx` into the relevant framework folder under `docs/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. +3. **Make your changes** in MDX on your fork. Add yourself to the file's `contributors` field in the frontmatter, and + create your profile in [`docs/pages/config/contributors.json`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/contributors.json) + if you do not already have one. This is how attribution works on the site. +4. **Update the sidebar** (`vocs.config.tsx`) so your new page appears in site navigation. New content should always + be added with the `dev: true` flag, which keeps it on the development site only. Reviewed content gets promoted to + the stable site periodically when we merge `develop` into `main`. See [Sidebar / Navigation](#sidebar--navigation) + below. +5. **Run the build locally** to make sure everything renders without errors. See [Error checking](#error-checking). +6. **Open a Pull Request against the `develop` branch.** 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. +7. **Notify reviewers** by tagging the relevant steward (you can find stewards on the + [Spotlight Zone](/contribute/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-contribs` Discord channel for + additional visibility. +8. Once reviewed and approved, your changes will be merged into `develop`. Periodically, reviewed content from + `develop` is merged into `main` for the stable site. + +**⚠️ Please sign and verify all commits.** If you have unsigned commits, follow the [Fixing unsigned +commits](#fixing-unsigned-commits) section below to update them. + +### 3. Add a new framework + +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](#2-add-a-new-page-or-expand-an-existing-one) above, with these extra +steps at the start: + +1. **Create a new folder** at `docs/pages//`. Use kebab-case (only normal dashes, no underscores + or other separators). +2. **Write `overview.mdx`** in that folder using the [page template](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx). + 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. +3. **Write the framework's other pages**, each one using the same template. +4. **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). + +### Want to take on more? + +If you are interested in a framework that does not currently have an active steward, you can become one yourself. +See the [Stewards guide](/contribute/stewards) for details on responsibilities, the open frameworks looking for +stewards, and how to get started. ## Development environment setup @@ -163,140 +208,57 @@ If you prefer to install dependencies locally on your machine: authenticate by running `gh auth login` in the terminal, making it easy to interact with GitHub directly from your development environment. -## Fixing unsigned commits - -If you accidentally made unsigned commits in your fork, you’ll need to rewrite them so they show as **Verified** before -opening a PR. - -### 1. Rebase your recent commits - -- Understand how many commits you have to fix -- Run this command, replacing `N` with the number of commits to go back (starting from the latest one): - -```bash -git rebase -i HEAD~N -``` - -### 2. Mark commits to fix - -In the editor that opens: +## Page requirements -- Change `pick` → `edit` for each unsigned commit. -- Save and exit. +The [page template](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx) 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. -### 3. Re-sign each commit +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. -For each commit you’re editing: +### Frontmatter -```bash -git commit --amend -S --no-edit -git rebase --continue -``` - -Repeat until all commits are re-signed. - -### 4. Push your changes - -Since history was rewritten, you need to **force-push**: - -```bash -git push --force -``` - -### 5. Verify - -Check locally: - -```bash -git log --show-signature -``` - -Or look at your branch on GitHub — commits should show a green **Verified** badge. - -## Contributor tasks beyond content changes - -When contributing to the Security Frameworks, there are several additional responsibilities to ensure your updates -integrate smoothly into the site and maintain proper structure: - -### 1. Frontmatter - -Every page requires frontmatter at the top of the file. Here are the key fields: - -#### Title and Description - -Add a title and description to every page you add: +Every page needs a `title`, a `description`, `tags`, and `contributors`. The shape looks like this: ```yaml --- title: "Your Page Title | Security Alliance" -# SEO meta description: 140-160 chars. Start with the framework/topic name, include -# searchable terms (tool names, attack types, standards), use action verbs. description: "Your description here, 140-160 characters." ---- -``` - -**Titles** should be concise and descriptive—avoid generic names like "Overview" or "Guide" alone. -Use "Preparing for a Smart Contract Audit" instead of "Preparation". Keep titles under 60 characters -(including the `| Security Alliance` suffix) so they display fully in search results. If your title -is too long, use `| SEAL` instead. - -**Meta descriptions** appear in search results and determine whether researchers click through. -Aim for 140-160 characters, include searchable terms whitehats use (tool names, attack types, -standards), and use action verbs. See -[Google's guide](https://developers.google.com/search/docs/appearance/snippet) for more details. - -- ✅ `"Smart contract audits: scoping, static analysis, manual review, and formal verification."` -- ❌ `"This page covers security topics."` (too vague, no searchable terms) - -#### Tags - -Assign tags to categorize content by role, topic, or skill level: - -```yaml ---- tags: - Engineer/Developer - Security Specialist ---- -``` - -Proper tagging makes your contribution discoverable and filterable on the site. - -#### Contributors - -Add yourself and other relevant contributors: - -```yaml ---- contributors: - role: wrote users: [your-github-username] - role: reviewed - users: [reviewer1, reviewer2] + users: [] --- ``` -Contributors are **managed centrally**: +Two things worth knowing up front: -- **Contributor database:** `docs/pages/config/contributors.json` -- **Usage guide:** `docs/pages/config/using-contributors.mdx` +- **Titles** stay under 60 characters including the `| Security Alliance` suffix; use `| SEAL` for longer titles. + Avoid generic names like "Overview" or "Guide" alone. +- **Contributors are managed centrally.** Your `users:` entries reference profiles in + [`docs/pages/config/contributors.json`](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/contributors.json). + Add yourself there if you do not already have an entry. -This helps track contributions and ensures proper attribution. +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](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx?plain=1). -For a complete frontmatter example, see the [template file](https://github.com/security-alliance/frameworks/blob/develop/docs/pages/config/template.mdx?plain=1). - -### 2. Sidebar / Navigation +### Sidebar / Navigation 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. For content still in review, remember -to set `dev: true`. +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: ```tsx { text: 'Monitoring', // Category name visible in the sidebar - collapsed: false, + collapsed: true, dev: true, // Indicates this category is in development items: [ { text: 'Overview', link: '/monitoring/README', dev: true }, // Indicates this page is in development @@ -304,13 +266,15 @@ Example of a category with multiple pages: { text: 'Thresholds', link: '/monitoring/thresholds', dev: true }, ] }, - ``` -This ensures that new content appears correctly in the site’s navigation for readers on the `.dev` site while staying +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. -### 3. Error Checking +### Error checking Before pushing changes, always make sure your build works without errors: @@ -319,28 +283,77 @@ Before pushing changes, always make sure your build works without errors: This helps catch build or formatting issues early so reviewers see clean contributions. +## Fixing unsigned commits + +If you accidentally made unsigned commits in your fork, you'll need to rewrite them so they show as **Verified** before +opening a PR. + +### 1. Rebase your recent commits + +- Understand how many commits you have to fix +- Run this command, replacing `N` with the number of commits to go back (starting from the latest one): + +```bash +git rebase -i HEAD~N +``` + +### 2. Mark commits to fix + +In the editor that opens: + +- Change `pick` → `edit` for each unsigned commit. +- Save and exit. + +### 3. Re-sign each commit + +For each commit you're editing: + +```bash +git commit --amend -S --no-edit +git rebase --continue +``` + +Repeat until all commits are re-signed. + +### 4. Push your changes + +Since history was rewritten, you need to **force-push**: + +```bash +git push --force +``` + +### 5. Verify + +Check locally: + +```bash +git log --show-signature +``` + +Or look at your branch on GitHub, commits should show a green **Verified** badge. + ## Style guide -Wiki pages follow standard MDX. +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](https://www.youtube.com/watch?v=vtIzMaLkCaM) to get started. +documentation writing you can learn from; for example, you can check [this +lecture](https://www.youtube.com/watch?v=vtIzMaLkCaM) to get started. ### Writing guidelines - 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 +- 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 +- 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. -- You can use mermaid diagrams for visualizations ### Content standardization @@ -350,7 +363,7 @@ guide](https://ethereum.org/contributing/style-guide/content-standardization)). - 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](https://github.com/excalidraw/excalidraw). -- Feel free to use [emojis](https://docsify.js.org/#/emoji?id=emoji) or [icons](https://icongr.am/fontawesome) where it +- Feel free to use [emojis](https://docsify.js.org/#/emoji?id=emoji) or [icons](https://icongr.am/fontawesome) where it fits, for example in block-quotes. ### Visual representation / drawings @@ -382,7 +395,7 @@ fits, for example in block-quotes. ### Linking resources -- Prefer descriptive names for external links (e.g., `inevitableeth.com` instead of “this wiki”). +- 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. @@ -401,7 +414,7 @@ Pages with minimal content which need more work to cover the topic need to inclu ## Anything else? -This page is also open for contributions! Suggest improvements to our style and guidelines in the GitHub repo. +This page is also open for contributions. Suggest improvements to our style and guidelines in the GitHub repo. ## About this page