Add a CVE to the library.

The library grows one CVE at a time. If you have built a vulnerable target that others could use, we want it here.

You can add a new playbook, write the doc for one that has none, or fix a mistake in an old one. Small fixes count too.

Every contribution comes in as a pull request. We don't take files by email or chat.

• A new Ansible playbook for a CVE, with its write-up.
• A write-up for an existing playbook that has no doc yet.
• Fixes for broken playbooks, wrong versions, typos or dead links.
• Translations of the site pages.

This site and its write-ups cover how to get the vulnerable service running and confirm it is up. They stop there.

• No exploit code, PoCs, payloads or shellcode.
• No commands that trigger the bug.
• No step-by-step on how the attack works.

CVE IDs, product names and version numbers are fine. A PR that includes attack content will be asked to remove it before we merge.

Fork the repo, make a branch, and add your files.

git clone https://github.com/YOUR-NAME/ansible.git
cd ansible
git checkout -b add-CVE-YYYY-NNNNN

1. Build the playbook at cve/cve-yyyy-nnnnn.yml. Use a lowercase file name. Put any service files or configs it copies in cve/files/cve-yyyy-nnnnn/.
2. Start the playbook with the clean-base guard (see below).
3. Add a verify tag that checks the service is up and on the affected version.
4. Copy the write-up template and fill it in. Delete the comment at the top before you open the PR.
5. Test it on a fresh clean-base snapshot. Run it, verify, restore, run it again.
6. Push your branch and open a pull request.

The guard stops the playbook if the VM already has a lab on it. It checks for /etc/lab-state and writes that marker before the build starts. Put it at the top of your playbook:

pre_tasks:
  - name: Guard against a non-clean-base VM
    import_tasks: _guard.yml
    vars:
      lab_cve: CVE-YYYY-NNNNN

Leave the guard without a tag. That way --tags verify skips it and the check still works on a VM that is already built.

git add .
git commit -m "Add CVE-YYYY-NNNNN playbook and write-up"
git push origin add-CVE-YYYY-NNNNN

Every CVE write-up follows the same shape, so the pages read the same. Use cve-writeup.md.

It has these parts, in this order:

1. Front matter: CVE, title, product, version, severity, CVSS, type, difficulty, tags, added date, author. Add github if you want your name linked.
2. About this target: what the product is, what the CVE affects, and a small table with product, version, type, CVSS and port.
3. Before you start: the base VM, the ansible repo, base/bootstrap.yml, and a clean-base snapshot. Add anything extra, like more RAM.
4. Run the playbook: what it installs and sets up, and the guard.
5. Verify the target: the verify tag and what the reader should see.
6. Files in the pull request
7. What defenders can look for
8. How it was fixed
9. Reset
10. References
11. Credit

Keep sentences short and plain. Use exact commands and exact version numbers.

• Playbook runs clean from clean-base and ends with failed=0.
• The playbook starts with the clean-base guard, and the guard has no tag.
• A second run on a used VM fails and names the lab already installed.
• The verify tag passes and prints target OK.
• Files sit at cve/cve-yyyy-nnnnn.yml and cve/files/cve-yyyy-nnnnn/.
• Write-up uses the template, the top comment is deleted, and there is no attack content.
• The write-up has the defenders, fix, reset and references sections filled in.
• Product, version and CVSS match the NVD entry.
• Inventory file, host IP and snapshot name match the get-started steps.
• The author field is set to your name.

A maintainer reads your PR, builds the playbook on a clean VM, and leaves comments if something needs a change. Once it passes, we merge it and the CVE shows up in the library.

Reviews can take a few days. If nobody has replied after a week, leave a comment on the PR.

Your name goes on the CVE page under Credit. Write-ups the core team wrote show TheHackingMachine Team. Everything else shows the name in the author field.