finding-protocol
Finding documentation protocol — Markdown template, YAML frontmatter schema, CVSS v4.0 severity guide, confidence levels, naming conventions, post-creation checklist.
Best for Security teamsWorks with GitHubLow risk
⌘source
- author
@PurpleAILAB- language
- Python
★2.1kstars
366forks
Apr 18, 2026
✦overview.md
Key Features
- ·Standardized Markdown template for security findings
- ·Automatic ID generation based on file count
- ·CVSS v4.0 scoring and vector fields
- ·File naming convention with severity and slugified title
- ·YAML frontmatter schema for structured metadata
Use Cases
- →Documenting a newly discovered vulnerability in a security assessment
- →Creating a standardized report for a penetration testing engagement
- →Recording a security issue during code review for later triage
Best for
- ✓Security teams
- ✓Penetration testers
Not ideal for
- !General bug tracking outside security context
FAQs
name
finding-protocol
description
Finding documentation protocol — Markdown template, YAML frontmatter schema, CVSS v4.0 severity guide, confidence levels, naming conventions, post-creation checklist.
allowed-tools:Read Write
metadata:{"subdomain":"reporting","when_to_use":"write finding, record finding, create finding, document vulnerability, FIND-, findings/, severity, cvss","tags":"finding, protocol, template, cvss, severity, reporting, documentation","mitre_attack":[]}
Finding Protocol
Recording Findings
When you discover a vulnerability or notable security issue, create an individual
Markdown file in the findings/ directory using write_file().
File Naming Convention
findings/{severity}-{slugified-title}.md
Derive the slug from the finding title — lowercase, hyphens for spaces, strip special characters.
The id field in YAML frontmatter (FIND-001, FIND-002, ...) is the canonical cross-reference.
Determine the next ID by counting existing files: ls findings/*.md | wc -l.
Examples:
findings/critical-exposed-mysql-api-example-com.mdfindings/high-subdomain-takeover-staging-herokuapp.mdfindings/medium-missing-hsts-header-www.md
Finding Document Template
Every finding MUST use this Markdown structure with YAML frontmatter:
---
id: FIND-001
severity: critical
cvss_score: 9.8
cvss_vector: "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N"
cvss_version: "4.0"
cwe: [CWE-89]
mitre: [T1190]
affected_target: "10.0.0.5"
affected_component: "MySQL 5.7 on port 3306"
confidence: verified
objective_id: OBJ-001
phase: recon
agent: recon
detected: null
remediation_priority: immediate
$install
1-click copynpx skills add PurpleAILAB/Decepticon --skill finding-protocolSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
5/ 5
excellentVery clear and well structured, with almost no room for misunderstanding.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
5/ 5
very highHighly actionable with clear, concrete steps that an agent can follow directly.