schema_v2.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/perfecxion/securecode-v2/schemas/securecode-v2.json",
  "title": "SecureCode v2.0 Training Example",
  "description": "Schema for secure code training dataset examples with validation, artifact type classification, and incident grounding.",
  "version": "2.0.0",
  "type": "object",
  "required": ["id", "metadata", "conversations", "validation"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9_]+-\\d{6}$",
      "description": "Unique identifier in format '{category}-{6-digit-number}' (e.g., 'sql_injection-000001', 'kubernetes_misconfig-000042')"
    },

    "metadata": {
      "type": "object",
      "required": [
        "artifact_type",
        "primary_language",
        "category",
        "subcategory",
        "owasp_2021",
        "cwe",
        "severity",
        "severity_basis",
        "complexity",
        "created",
        "validated"
      ],
      "properties": {
        "artifact_type": {
          "type": "string",
          "enum": ["application_code", "config_iac", "policy", "query", "mixed"],
          "description": "Primary classification of the code artifact. Values: application_code (executable code in programming languages), config_iac (configuration files or Infrastructure as Code), policy (security policies, IAM policies, OPA/Rego rules), query (standalone database or search queries), mixed (multiple artifact types combined)"
        },

        "primary_language": {
          "type": "string",
          "description": "Primary language or format of the artifact. For application_code, this is the programming language. For config_iac, this is the configuration format.",
          "enum": [
            "python", "javascript", "java", "go", "php",
            "csharp", "typescript", "ruby", "rust", "kotlin",
            "c", "cpp", "swift",
            "yaml", "json", "hcl", "toml", "xml",
            "sql", "graphql", "rego"
          ]
        },

        "secondary_languages": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "python", "javascript", "java", "go", "php",
              "csharp", "typescript", "ruby", "rust", "kotlin",
              "c", "cpp", "swift",
              "yaml", "json", "hcl", "toml", "xml",
              "sql", "graphql", "rego", "html", "css", "bash", "powershell"
            ]
          },
          "description": "Additional languages or formats present in multi-language examples (e.g., SQL embedded in Python, YAML in Go applications)"
        },

        "framework": {
          "type": "string",
          "description": "Primary framework or platform (e.g., 'django', 'spring-boot', 'express', 'kubernetes', 'terraform', 'github-actions', 'docker-compose')",
          "examples": [
            "django", "flask", "fastapi",
            "spring-boot", "spring-security",
            "express", "nestjs", "react", "vue", "angular",
            "gin", "echo", "fiber",
            "laravel", "symfony",
            "rails",
            "kubernetes", "docker", "docker-compose",
            "terraform", "ansible", "pulumi",
            "github-actions", "gitlab-ci", "jenkins",
            "aws-cdk", "aws-cloudformation", "azure-arm"
          ]
        },

        "category": {
          "type": "string",
          "enum": [
            "broken_access_control",
            "cryptographic_failures",
            "injection",
            "insecure_design",
            "security_misconfiguration",
            "vulnerable_components",
            "auth_failures",
            "integrity_failures",
            "logging_failures",
            "ssrf",
            "cloud_security",
            "api_security",
            "ai_ml_security"
          ],
          "description": "Top-level vulnerability category aligned with OWASP Top 10 2021"
        },

        "subcategory": {
          "type": "string",
          "description": "Specific vulnerability type (e.g., 'sql_injection', 'idor', 'prompt_injection', 'kubernetes_misconfig')"
        },

        "technique": {
          "type": "string",
          "description": "Specific attack technique or vulnerability pattern being demonstrated"
        },

        "owasp_2021": {
          "type": "string",
          "pattern": "^A\\d{2}:2021-.+|Modern Threats$",
          "description": "OWASP Top 10 2021 category (e.g., 'A01:2021-Broken Access Control') or 'Modern Threats' for AI/ML/Cloud security"
        },

        "cwe": {
          "type": "string",
          "pattern": "^CWE-\\d+$",
          "description": "Common Weakness Enumeration ID (e.g., 'CWE-89' for SQL Injection)"
        },

        "severity": {
          "type": "string",
          "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"],
          "description": "Vulnerability severity rating based on potential impact"
        },

        "severity_basis": {
          "type": "string",
          "enum": ["cvss_v3", "cvss_v4", "vendor_rating", "author_assigned", "cwe_default"],
          "description": "Method used to determine severity level. Values: cvss_v3 (CVSS v3.1 base score), cvss_v4 (CVSS v4.0 base score), vendor_rating (vendor security advisory), author_assigned (dataset authors following documented criteria), cwe_default (typical impact for CWE category). See severity_assignment_methodology.md for full criteria."
        },

        "cvss_score": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 10.0,
          "description": "CVSS base score when severity_basis is 'cvss_v3' or 'cvss_v4'"
        },

        "cvss_vector": {
          "type": "string",
          "description": "Full CVSS vector string (e.g., 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H')"
        },

        "complexity": {
          "type": "string",
          "enum": ["simple", "moderate", "complex", "advanced"],
          "description": "Example complexity level indicating code sophistication and required expertise"
        },

        "created": {
          "type": "string",
          "format": "date",
          "description": "Creation date in ISO 8601 format (YYYY-MM-DD)"
        },

        "validated": {
          "type": "boolean",
          "description": "Whether example passed all validation checks"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "artifact_type": { "const": "application_code" }
            }
          },
          "then": {
            "properties": {
              "primary_language": {
                "enum": [
                  "python", "javascript", "java", "go", "php",
                  "csharp", "typescript", "ruby", "rust", "kotlin",
                  "c", "cpp", "swift"
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "artifact_type": { "const": "config_iac" }
            }
          },
          "then": {
            "properties": {
              "primary_language": {
                "enum": ["yaml", "json", "hcl", "toml", "xml"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "artifact_type": { "const": "policy" }
            }
          },
          "then": {
            "properties": {
              "primary_language": {
                "enum": ["yaml", "json", "rego", "hcl"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "artifact_type": { "const": "query" }
            }
          },
          "then": {
            "properties": {
              "primary_language": {
                "enum": ["sql", "graphql", "json"]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "severity_basis": { "enum": ["cvss_v3", "cvss_v4"] }
            }
          },
          "then": {
            "required": ["cvss_score"]
          }
        }
      ]
    },

    "context": {
      "type": "object",
      "description": "Real-world incident context providing grounding for the vulnerability example",
      "properties": {
        "real_world_incident": {
          "type": "string",
          "minLength": 10,
          "description": "Name and brief description of real incident this example is modeled after"
        },
        "impact": {
          "type": "string",
          "minLength": 20,
          "description": "Measured impact with specific figures where available (financial losses, records exposed, systems compromised, etc.)"
        },
        "attack_vector": {
          "type": "string",
          "description": "Technical description of how the attack was executed"
        },
        "business_impact": {
          "type": "string",
          "description": "Business consequences including regulatory, reputational, and operational impacts"
        },
        "cve": {
          "type": ["string", "null"],
          "pattern": "^CVE-\\d{4}-\\d{4,}$",
          "description": "CVE identifier if applicable. Pattern enforces CVE-YYYY-NNNNN format."
        },
        "cwe_chain": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^CWE-\\d+$"
          },
          "description": "Chain of CWEs if vulnerability involves multiple weakness types"
        },
        "year": {
          "type": "integer",
          "minimum": 2017,
          "maximum": 2030,
          "description": "Year of incident or CVE publication"
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to authoritative source documenting the incident (NVD, vendor advisory, security research)"
        },
        "mitre_attack": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^T\\d{4}(\\.\\d{3})?$"
          },
          "description": "MITRE ATT&CK technique IDs (e.g., 'T1190' for Exploit Public-Facing Application)"
        }
      },
      "dependentRequired": {
        "cve": ["year"]
      }
    },

    "incident_grounding": {
      "type": "object",
      "description": "Required when CVE is null - provides alternative grounding for the vulnerability pattern",
      "properties": {
        "grounding_type": {
          "type": "string",
          "enum": ["industry_pattern", "security_research", "cwe_documented", "owasp_documented", "vendor_advisory", "bug_bounty"],
          "description": "Type of evidence grounding this example"
        },
        "source_reference": {
          "type": "string",
          "description": "Citation or reference to the grounding source (paper title, advisory ID, program reference)"
        },
        "source_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to the grounding source documentation"
        },
        "prevalence": {
          "type": "string",
          "enum": ["common", "frequent", "occasional", "rare"],
          "description": "How often this vulnerability pattern is observed in the wild"
        },
        "rationale": {
          "type": "string",
          "minLength": 50,
          "description": "Explanation of why this example is relevant without a specific CVE"
        }
      },
      "required": ["grounding_type", "rationale"]
    },

    "conversations": {
      "type": "array",
      "minItems": 2,
      "description": "Multi-turn conversation array demonstrating the vulnerability and its remediation",
      "items": {
        "type": "object",
        "required": ["turn", "from", "value"],
        "properties": {
          "turn": {
            "type": "integer",
            "minimum": 1,
            "description": "Turn number in conversation (1-indexed)"
          },
          "from": {
            "type": "string",
            "enum": ["human", "assistant"],
            "description": "Speaker role - 'human' for user queries, 'assistant' for model responses"
          },
          "value": {
            "type": "string",
            "minLength": 20,
            "description": "Message content including code examples, explanations, and security analysis"
          }
        }
      }
    },

    "siem_detection": {
      "type": "object",
      "description": "SIEM detection guidance for operational security teams. See siem_schema.json for full structure.",
      "properties": {
        "detection_coverage": {
          "type": "string",
          "enum": ["full", "partial", "none", "not_applicable"],
          "description": "Level of automated detection coverage available"
        },
        "coverage_notes": {
          "type": "string",
          "description": "Explanation of coverage level, detection gaps, or why not applicable"
        },
        "log_sources": {
          "type": "array",
          "description": "Required log sources for detection",
          "items": {
            "type": "object",
            "required": ["source_type", "source_name"],
            "properties": {
              "source_type": {
                "type": "string",
                "enum": [
                  "web_access", "authentication", "database", "network_flow",
                  "cloud_audit", "container", "endpoint", "waf", "api_gateway",
                  "application", "dns", "proxy", "load_balancer", "firewall"
                ]
              },
              "source_name": {
                "type": "string"
              },
              "required_fields": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          }
        },
        "rules_reference": {
          "type": "string",
          "description": "Reference to full SIEM rules in siem_detection/ directory"
        }
      }
    },

    "validation": {
      "type": "object",
      "required": ["syntax_check", "security_review", "code_execution", "reviewed_by", "review_date"],
      "description": "Validation status and quality assurance information",
      "properties": {
        "syntax_check": {
          "type": "string",
          "enum": ["passed", "failed", "not_tested"],
          "description": "Syntax validation status - code parses without errors"
        },
        "security_review": {
          "type": "string",
          "enum": ["passed", "failed", "not_reviewed"],
          "description": "Security expert review status - vulnerability accurately demonstrated"
        },
        "code_execution": {
          "type": "string",
          "enum": ["passed", "failed", "not_tested"],
          "description": "Code execution test status - code runs in isolated environment"
        },
        "encoding_check": {
          "type": "string",
          "enum": ["passed", "failed", "not_tested"],
          "description": "UTF-8 encoding validation - no encoding errors"
        },
        "duplication_check": {
          "type": "string",
          "enum": ["passed", "failed", "not_tested"],
          "description": "Duplicate detection status - example is unique in dataset"
        },
        "cve_validation": {
          "type": "string",
          "enum": ["verified", "not_found", "partial_match", "not_applicable"],
          "description": "CVE validation against NVD database"
        },
        "reviewed_by": {
          "type": "string",
          "description": "Validator identifier (automated system or human expert handle)"
        },
        "review_date": {
          "type": "string",
          "format": "date",
          "description": "Date of most recent validation (YYYY-MM-DD)"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of validation issues found, empty if all checks passed"
        },
        "irr_score": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Inter-rater reliability score if multiple reviewers assessed this example"
        }
      }
    }
  },

  "if": {
    "properties": {
      "context": {
        "properties": {
          "cve": { "type": "null" }
        }
      }
    }
  },
  "then": {
    "required": ["id", "metadata", "conversations", "validation", "incident_grounding"]
  },

  "definitions": {
    "programming_languages": {
      "description": "Languages that produce executable application code",
      "enum": [
        "python", "javascript", "java", "go", "php",
        "csharp", "typescript", "ruby", "rust", "kotlin",
        "c", "cpp", "swift"
      ]
    },
    "configuration_formats": {
      "description": "Data serialization formats used for configuration and Infrastructure as Code",
      "enum": ["yaml", "json", "hcl", "toml", "xml"]
    },
    "query_languages": {
      "description": "Domain-specific languages for data querying",
      "enum": ["sql", "graphql", "rego"]
    },
    "artifact_type_classification_rules": {
      "description": "Rules for classifying artifact types",
      "rules": [
        {
          "artifact_type": "application_code",
          "criteria": "Code that executes in a runtime (Python interpreter, JVM, Node.js, Go runtime, etc.)",
          "valid_languages": ["python", "javascript", "java", "go", "php", "csharp", "typescript", "ruby", "rust", "kotlin", "c", "cpp", "swift"]
        },
        {
          "artifact_type": "config_iac",
          "criteria": "Configuration files or Infrastructure as Code that define system state or deployment",
          "valid_languages": ["yaml", "json", "hcl", "toml", "xml"],
          "frameworks": ["kubernetes", "docker", "docker-compose", "terraform", "ansible", "pulumi", "github-actions", "gitlab-ci", "jenkins", "aws-cloudformation", "azure-arm"]
        },
        {
          "artifact_type": "policy",
          "criteria": "Access control definitions, security policies, or authorization rules",
          "valid_languages": ["yaml", "json", "rego", "hcl"],
          "frameworks": ["opa", "aws-iam", "azure-rbac", "gcp-iam"]
        },
        {
          "artifact_type": "query",
          "criteria": "Standalone database or search queries not embedded in application code",
          "valid_languages": ["sql", "graphql", "json"]
        },
        {
          "artifact_type": "mixed",
          "criteria": "Examples containing multiple artifact types (e.g., Python with embedded SQL, YAML with Go templates)",
          "note": "Use primary_language for dominant artifact, list others in secondary_languages"
        }
      ]
    },
    "severity_assignment_criteria": {
      "description": "Criteria for assigning severity levels",
      "CRITICAL": {
        "cvss_range": "9.0-10.0",
        "indicators": [
          "Unauthenticated remote code execution",
          "Authentication bypass to admin privileges",
          "Full database exfiltration without authentication",
          "Cryptographic key compromise",
          "Supply chain attack enabling arbitrary code execution"
        ]
      },
      "HIGH": {
        "cvss_range": "7.0-8.9",
        "indicators": [
          "Authenticated remote code execution",
          "Privilege escalation to admin",
          "Partial data breach (PII exposure)",
          "Session hijacking",
          "SQL injection with limited scope"
        ]
      },
      "MEDIUM": {
        "cvss_range": "4.0-6.9",
        "indicators": [
          "Information disclosure (non-PII)",
          "Denial of service",
          "CSRF with limited impact",
          "Weak cryptography (not yet exploited)",
          "Missing security headers"
        ]
      },
      "LOW": {
        "cvss_range": "0.1-3.9",
        "indicators": [
          "Verbose error messages revealing implementation details",
          "Missing non-critical security headers",
          "Configuration weakness unexploitable alone"
        ]
      }
    }
  }
}