3.3 KiB
Repository Guidelines
Project Structure & Module Organization
Year-specific directories (2000/–2025/) store curated CVE entries as markdown files named CVE-YYYY-NNNN.md. Each file follows the shared heading layout used across the repository. Supporting assets live in docs/: the generated CVE_list.json, static site files (index.html, logic.js, style.css), and the generate_cve_list.py helper. Automation now lives in scripts/update_cves.py, which syncs markdown and JSON from the latest GitHub PoCs. Reference inventories (github*.txt, references*.txt, blacklist.txt) and utilities such as removedups.py sit at the repository root.
Build, Test, and Development Commands
Run python3 scripts/update_cves.py from the repository root to pull fresh CVE descriptions from the CVE Program API, merge new PoC links from github.txt, and regenerate docs/CVE_list.json. Metadata responses are cached in data/cve_cache.json for one week by default; use --refresh-cache or tweak --cache-ttl when you need a fresh pull. Pass --cve CVE-2024-1234 when testing a single record, and --skip-json to avoid touching the compiled artifact during dry runs. For manual edits, cd docs && python3 generate_cve_list.py still regenerates the JSON directly. Use python3 removedups.py references.txt > references.txt.new to deduplicate lists before replacing the original file. rg "CVE-2024-1234" 2024 is the fastest way to confirm whether an entry already exists. Keep commands in the repository root to ensure relative paths resolve.
Coding Style & Naming Conventions
Name new entries CVE-YYYY-####.md and mirror the existing sections: title, badges, ### Description, then ### POC with #### Reference and #### Github. Prefer concise paragraphs and Markdown lists that start with - . Python helpers use standard library only, four-space indentation, snake_case identifiers, and inline comments only when they clarify parsing logic.
Testing Guidelines
No automated suite exists; rely on lightweight validation. After regenerating JSON, run python3 -m json.tool docs/CVE_list.json > /dev/null to confirm structure. Manually spot-check added markdown in a browser or Markdown preview to ensure badges render and links resolve. When touching scripts, execute them with sample files and review the diff to confirm no unintended rewrites.
Commit & Pull Request Guidelines
Existing history shows automation using Trending CVEs update YYYY-MM-DD HH:MM :robot: summaries. A scheduled workflow now commits daily updates via sync_cve_pocs.yml; keep manual commits focused on human-reviewed adjustments. When contributing manually, use a clear imperative line such as Add CVE-2024-1234 PoC entry and group related file changes per commit. Pull requests should describe the data source, mention regenerated artifacts, and note any manual verification steps; include screenshots only when UI assets change.
Security & Data Integrity
Verify every CVE reference against a reputable advisory before inclusion and avoid linking to weaponized exploits. Remove sensitive tokens or credentials from pasted content. Keep automation scripts dependency-free so they can run in restricted environments, and prefer relative paths to support archive exports and GitHub Actions runners.