Skip to main content
Version: Current

Contribute a CVE

Add an existing CVE implementation to the CVE library through cradle-lang/cradle-lib-cve.

By the end of this guide, you will:

  1. Import your CVE module and its supporting files.
  2. Generate an index.md article using the heuristic template.
  3. Review the article and choose its publication status.
  4. Open a draft pull request for validation and review.
  5. Understand how the article reaches the website after approval.

:::info Start with a working module This guide assumes you already have a CVE implementation. AI generates documentation only. It does not create the implementation, render its templates, deploy it or test the vulnerability. Verify the article against your actual files and record runtime results separately. :::

Before you start​

You need:

  • Git, Node.js 22 or newer, and npm.
  • A GitHub account.
  • Your CVE module, including its manifest, Ansible template and supporting files.
  • Permission to redistribute the implementation and its assets.
  • An OpenAI-compatible LLM server configured for article generation.

Run all commands from the cradle-lib-cve repository root unless stated otherwise. Each module belongs in a top-level folder such as CVE-2026-12345/. Use the actual CVE identifier for your contribution; the ID in this guide is an example.

Contribution workflow​

You prepare and review the contribution:

CVE module files
↓
Import with --generate-index
↓
Review the article
↓
Draft PR

CI, maintainers and website automation handle publication:

CVE validation and PR review
↓
Source PR merged and main validated
↓
Website PR created and reviewed
↓
Website PR merged and CVE library published

1. Set up the repository​

Fork cradle-lib-cve if you do not have write access. Replace YOUR-GITHUB-USERNAME with your account; contributors with write access can clone upstream instead.

These commands work in PowerShell, Bash and Zsh:

git clone https://github.com/YOUR-GITHUB-USERNAME/cradle-lib-cve.git
cd cradle-lib-cve
git switch -c add-my-cve
npm ci

For an existing checkout, start from an up-to-date main and create a contribution branch. CVE implementations are maintained in cradle-lib-cve; configuration modules and TTP heuristics are separate contributions.

Configure article generation once​

If your checkout already has an LLM connection configured, continue to Prepare your source folder.

Create .env beside package.json without overwriting an existing file.

PowerShell​

if (!(Test-Path -LiteralPath .env)) {
Copy-Item -LiteralPath .env.example -Destination .env
}
notepad .env

Bash / Zsh​

if [ ! -f .env ]; then
cp .env.example .env
fi
nano .env

Enter your server's API base URL, an available model and your key:

SERVER="https://your-llm-server.example/v1"
REMOTE_LLM_MODEL="your-model-name"
REMOTE_LLM_API_KEY="your-key-here"

The endpoint must support OpenAI-compatible Chat Completions. Connection options and recovery details are in the maintainer reference.

:::warning Credentials and module content Never commit .env or put credentials inside module files. Selected module text is sent to your configured server; check that you have permission to share it. Hidden and TOML files are excluded from LLM input, and binary/image contents are not sent. Review any reported omissions or truncation. :::

2. Prepare your source folder​

Keep your completed implementation and its documentation together:

MyCve/
├── README.md
├── manifest.json
├── ansible/
│ └── CVE-2026-12345.j2
└── files/
└── supporting-script.sh

files/ is optional. A README is useful evidence for the generated article: describe the implementation, setup, requirements, verification steps and original authorship. Include only assets you can redistribute.

The manifest must identify the same CVE as the template and destination folder:

{
"framework": "cve",
"value": "CVE-2026-12345",
"os": "ubuntu",
"os_version": "20.04",
"configs": []
}

Replace the example operating system and version with your module's actual requirements. Use paired null values when neither is specified. List required configuration modules in configs; use an empty list when none are implied. The required template is ansible/<CVE-ID>.j2 and must not be empty.

3. Import the module and generate its article​

Use this command, replacing the CVE ID and source path with your own:

PowerShell​

npm run library:new -- cve CVE-2026-12345 --from "C:\path\to\MyCve" --generate-index

Bash / Zsh​

npm run library:new -- cve CVE-2026-12345 --from "$HOME/Downloads/MyCve" --generate-index

The command copies the module into a new top-level folder and generates its article from the supplied README, manifest and implementation. It uses the website's heuristic template, with a portable copy at library/_templates/heuristic/index.md in cradle-lib-cve. The generator fills in the CVE identity automatically.

You should now have:

CVE-2026-12345/
├── index.md
├── README.md
├── manifest.json
├── ansible/
│ └── CVE-2026-12345.j2
└── files/
└── supporting-script.sh

Your original folder is unchanged. Hidden files and caches are skipped during import; other files, including binary assets, are preserved. Selected symbolic links are rejected. Compare the imported folder with your source to confirm that all required files are present.

Existing module folders are never overwritten. If your source already contains an authored index.md, it is preserved even with --generate-index; review its metadata and publication status yourself. Use index.md rather than index.mdx.

4. Review the article​

Edit CVE-2026-12345/index.md and verify it against the implementation. The heuristic template covers:

  • Mapping and implementation: the CVE, affected behavior and what this module sets up.
  • Use and requirements: compatible systems, dependencies, backend requirements, CRADLE usage and verification steps.
  • Attribution and licensing: original authors, sources and redistribution terms.

Describe expected behavior separately from observed results. Record the versions and environment used for any actual tests. Mark undocumented or unverified details clearly rather than treating AI-generated prose as evidence.

Front matter and publication status​

The generated article starts with metadata like this:

---
title: My CVE module
description: Short summary of the implementation and its purpose.
framework: cve
identifier: CVE-2026-12345
draft: true
---

Keep framework: cve and the exact module identifier. Do not add id or slug; the website derives its article ID from the CVE identifier.

Generated articles always start as drafts. Keep draft: true while preparing the article; set draft: false when it is ready for publication after review. A GitHub draft PR and the article's draft field are separate controls.

You do not need to enter a GitHub module link or sourceUrl. During website handoff, automation generates the module-folder URL and pins it to the validated source commit. Relative article links to supporting files are rewritten to that same commit.

The website receives index.md and the module-folder link, with internal identity/provenance metadata. Manifests, Ansible templates, scripts and binaries stay in cradle-lib-cve; they are not copied into the website.

5. Open a draft PR​

Before submitting, confirm that:

  • The manifest and template match the CVE identifier.
  • Required implementation files and assets are included.
  • index.md accurately describes the module and its requirements.
  • Claimed test results have supporting evidence.
  • Attribution, licensing and file links are complete.
  • draft has the intended value.
  • No credentials, .env, node_modules or export bundles are staged.

Stage the complete module folder and inspect it before committing:

git add CVE-2026-12345/
git diff --cached
git status --short
git commit -m "Add CVE module and documentation"
git push -u origin add-my-cve

Open a pull request targeting cradle-lang/cradle-lib-cve's main and select Create draft pull request. Describe the module, included files, requirements, checks actually run and known limitations. Mark it ready for review when the contribution and its CI checks are ready.

GitHub automatically checks module identities, manifest structure, required templates, article links, exported Markdown and manifest-implied configurations. It also runs the import, generation and export tests. You do not need to run website export or synchronization commands to submit your contribution.

:::info Validation is not runtime testing Repository checks do not render or execute provisioning templates, deploy machines, verify remote downloads or run the vulnerability. Record separate runtime tests and their results in the article and PR. :::

6. What happens after submission​

StageWhat happens
CVE PRCI checks your module and article; maintainers review the contribution.
Source mergeFull validation runs on main. A successful run sends the validated documentation to the website automation.
Website PRAutomation imports the article and source link, runs website tests and a production build, then opens or updates a separate review PR.
Website merge and deploymentMaintainers merge the website PR. A successful Pages deployment publishes articles with draft: false.

A source merge alone does not publish the webpage. After website deployment, find your module in the CVE library. Check its article and View on GitHub link. For the example identifier, the article path would be /library/heuristics/cve-cve-2026-12345; use your actual ID.

Troubleshooting​

ProblemWhat to check or do
The module already existsEdit the existing module or choose the correct new CVE ID. Imports never overwrite a folder.
The manifest or template is rejectedCheck framework: cve, the exact CVE ID, paired OS/version values, configs, and ansible/<CVE-ID>.j2.
Article generation failsCheck the server URL, model and API access. Copied files and the starter article are retained; use the maintainer recovery reference to retry generation.
The article was preserved instead of generatedYour source contains an authored index.md. Import preserves it; review and edit that article.
A local article link fails validationUse an existing file or directory inside the CVE module and check its spelling and case.
The CVE does not appear on the websiteCheck draft: false, source validation, the website review PR and Pages deployment status.

See cradle-lib-cve's contributor guide for the source instructions. Integration setup and recovery are in the maintainer reference.