@blamejs/exceptd-skills 0.9.1

package/lib/schemas/cve-catalog.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://exceptd.com/schemas/cve-catalog.schema.json",
+  "title": "exceptd CVE Catalog Entry",
+  "description": "Schema for a single CVE entry in data/cve-catalog.json. CVE keys (e.g. CVE-2026-31431) map to objects matching this schema. The reserved key _meta is not validated against this schema.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "name",
+    "type",
+    "cvss_score",
+    "cvss_vector",
+    "cisa_kev",
+    "poc_available",
+    "ai_discovered",
+    "active_exploitation",
+    "affected",
+    "affected_versions",
+    "vector",
+    "patch_available",
+    "patch_required_reboot",
+    "live_patch_available",
+    "framework_control_gaps",
+    "atlas_refs",
+    "attack_refs",
+    "rwep_score",
+    "rwep_factors",
+    "source_verified",
+    "verification_sources",
+    "last_updated"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable vulnerability name (e.g. 'Copy Fail')."
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Vulnerability class (LPE, RCE-via-prompt-injection, RCE-supply-chain, etc.)."
+    },
+    "cvss_score": {
+      "type": "number",
+      "minimum": 0.0,
+      "maximum": 10.0
+    },
+    "cvss_vector": {
+      "type": "string",
+      "pattern": "^CVSS:[0-9]+(\\.[0-9]+)?/"
+    },
+    "cisa_kev": { "type": "boolean" },
+    "cisa_kev_date": {
+      "type": ["string", "null"],
+      "description": "ISO date string when added to CISA KEV, or null."
+    },
+    "cisa_kev_due_date": {
+      "type": ["string", "null"]
+    },
+    "poc_available": { "type": "boolean" },
+    "poc_description": { "type": "string" },
+    "ai_discovered": {
+      "description": "Whether the vulnerability was discovered with AI assistance.",
+      "type": ["boolean", "string"]
+    },
+    "ai_discovery_notes": { "type": "string" },
+    "ai_assisted_weaponization": { "type": "boolean" },
+    "ai_assisted_notes": { "type": "string" },
+    "active_exploitation": {
+      "type": "string",
+      "enum": ["confirmed", "suspected", "none", "unknown"]
+    },
+    "affected": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Free-form description of affected products/versions."
+    },
+    "affected_versions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "vector": { "type": "string", "minLength": 1 },
+    "complexity": { "type": "string" },
+    "complexity_notes": { "type": "string" },
+    "patch_available": { "type": "boolean" },
+    "patch_required_reboot": { "type": "boolean" },
+    "live_patch_available": { "type": "boolean" },
+    "live_patch_tools": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "live_patch_notes": { "type": "string" },
+    "framework_control_gaps": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "Map of framework control ID (or ALL-MAJOR-FRAMEWORKS) to gap statement. Per AGENTS.md rule #4, no orphaned controls.",
+      "additionalProperties": { "type": "string" }
+    },
+    "atlas_refs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^AML\\.T[0-9]{4}(\\.[0-9]{3})?$" }
+    },
+    "attack_refs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^T[0-9]{4}(\\.[0-9]{3})?$" }
+    },
+    "rwep_score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "rwep_factors": {
+      "type": "object",
+      "required": [
+        "cisa_kev",
+        "poc_available",
+        "ai_factor",
+        "active_exploitation",
+        "blast_radius",
+        "patch_available",
+        "live_patch_available",
+        "reboot_required"
+      ],
+      "properties": {
+        "cisa_kev": { "type": "number" },
+        "poc_available": { "type": "number" },
+        "ai_factor": { "type": "number" },
+        "active_exploitation": { "type": "number" },
+        "blast_radius": { "type": "number" },
+        "patch_available": { "type": "number" },
+        "live_patch_available": { "type": "number" },
+        "reboot_required": { "type": "number" }
+      },
+      "additionalProperties": true
+    },
+    "source_verified": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    },
+    "verification_sources": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri" },
+      "minItems": 1
+    },
+    "last_updated": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+    }
+  }
+}

package/lib/schemas/manifest.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://exceptd.com/schemas/manifest.schema.json",
+  "title": "exceptd manifest.json",
+  "description": "Schema for the top-level manifest.json describing the exceptd skill collection.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "name",
+    "version",
+    "description",
+    "atlas_version",
+    "threat_review_date",
+    "skills"
+  ],
+  "properties": {
+    "name": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "description": { "type": "string", "minLength": 1 },
+    "homepage": { "type": "string", "format": "uri" },
+    "license": { "type": "string", "minLength": 1 },
+    "atlas_version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+    "threat_review_date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "sources_dir": { "type": "string" },
+    "agents_dir": { "type": "string" },
+    "reports_dir": { "type": "string" },
+    "skills": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/skillEntry" }
+    }
+  },
+  "$defs": {
+    "skillEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "version",
+        "path",
+        "description",
+        "triggers",
+        "data_deps",
+        "atlas_refs",
+        "attack_refs",
+        "framework_gaps",
+        "last_threat_review"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$"
+        },
+        "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+        "path": {
+          "type": "string",
+          "pattern": "^skills/[a-z0-9][a-z0-9-]*[a-z0-9]/skill\\.md$"
+        },
+        "description": { "type": "string", "minLength": 10 },
+        "triggers": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "data_deps": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9._-]+\\.json$" }
+        },
+        "atlas_refs": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^AML\\.T[0-9]{4}(\\.[0-9]{3})?$" }
+        },
+        "attack_refs": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^T[0-9]{4}(\\.[0-9]{3})?$" }
+        },
+        "framework_gaps": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "forward_watch": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "last_threat_review": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "Set by lib/verify.js when signing is not in use; replaced by signature when lib/sign.js runs."
+        },
+        "signature": {
+          "type": "string",
+          "description": "Ed25519 signature over skill.md content, base64-encoded. Added by lib/sign.js."
+        },
+        "signed_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp written by lib/sign.js."
+        }
+      }
+    }
+  }
+}

package/lib/schemas/skill-frontmatter.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://exceptd.com/schemas/skill-frontmatter.schema.json",
+  "title": "exceptd Skill Frontmatter",
+  "description": "Schema for the YAML frontmatter at the top of every skills/<name>/skill.md. Mirrors the spec in AGENTS.md (Skill File Format).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name",
+    "version",
+    "description",
+    "triggers",
+    "data_deps",
+    "atlas_refs",
+    "attack_refs",
+    "framework_gaps",
+    "last_threat_review"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+      "description": "Lowercase kebab-case identifier matching the directory under skills/."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semantic version string. Quoted in YAML to preserve string type."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10,
+      "description": "One-line trigger description used by AI assistant skill matching."
+    },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Phrase patterns that invoke the skill."
+    },
+    "data_deps": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9._-]+\\.json$"
+      },
+      "description": "Filenames (relative to data/) that this skill reads. Each must resolve to an existing file."
+    },
+    "atlas_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^AML\\.T[0-9]{4}(\\.[0-9]{3})?$"
+      },
+      "description": "MITRE ATLAS TTP IDs at the pinned version (currently v5.1.0)."
+    },
+    "attack_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^T[0-9]{4}(\\.[0-9]{3})?$"
+      },
+      "description": "MITRE ATT&CK technique IDs."
+    },
+    "framework_gaps": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Framework control IDs whose gap this skill addresses. Each must resolve in data/framework-control-gaps.json."
+    },
+    "rfc_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(RFC-[0-9]+|DRAFT-[A-Z0-9-]+)$"
+      },
+      "description": "Optional. IETF RFC numbers (e.g. RFC-8446) or Internet-Draft slugs (e.g. DRAFT-IETF-TLS-ECDHE-MLKEM) the skill depends on. Each must resolve in data/rfc-references.json."
+    },
+    "cwe_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^CWE-[0-9]+$"
+      },
+      "description": "Optional. CWE (Common Weakness Enumeration) IDs the skill addresses as root-cause weakness classes. Each must resolve in data/cwe-catalog.json."
+    },
+    "d3fend_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^D3-[A-Z]+$"
+      },
+      "description": "Optional. MITRE D3FEND defensive technique IDs the skill maps to. Each must resolve in data/d3fend-catalog.json."
+    },
+    "dlp_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^DLP-[A-Z0-9-]+$"
+      },
+      "description": "Optional. DLP control IDs the skill addresses (channels, classifiers, surfaces, enforcement, evidence). Each must resolve in data/dlp-controls.json."
+    },
+    "forward_watch": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Upcoming standards changes or new TTPs to watch for skill update."
+    },
+    "last_threat_review": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "ISO date of the last threat-intel review for this skill."
+    }
+  }
+}

package/lib/scoring.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * RWEP — Real-World Exploit Priority scoring engine
+ * Supplements CVSS with exploit availability, active exploitation, and operational constraints.
+ */
+
+const CVE_SCHEMA_REQUIRED = [
+  'type', 'cvss_score', 'cvss_vector', 'cisa_kev', 'poc_available',
+  'ai_discovered', 'active_exploitation', 'affected', 'patch_available',
+  'patch_required_reboot', 'live_patch_available', 'live_patch_tools',
+  'rwep_score', 'rwep_factors', 'atlas_refs', 'attack_refs',
+  'source_verified', 'verification_sources', 'last_updated'
+];
+
+// blast_radius range is 0-30; represents breadth of affected population.
+// AI-discovered and AI-assisted-weaponization both contribute the ai_factor (+15).
+// reboot_required applies whenever patch requires reboot, regardless of live-patch availability,
+// because live-patch is a temporary workaround — full remediation window is extended.
+const RWEP_WEIGHTS = {
+  cisa_kev:             25,
+  poc_available:        20,
+  ai_factor:            15,
+  active_exploitation:  20,
+  blast_radius:         30,
+  patch_available:     -15,
+  live_patch_available:-10,
+  reboot_required:       5
+};
+
+function score(cveId, catalog) {
+  const entry = catalog[cveId];
+  if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
+  return entry.rwep_score;
+}
+
+function scoreCustom(factors) {
+  const {
+    cisa_kev = false,
+    poc_available = false,
+    ai_assisted_weapon = false,
+    ai_discovered = false,
+    active_exploitation = 'none',
+    blast_radius = 0,
+    patch_available = false,
+    live_patch_available = false,
+    reboot_required = false
+  } = factors;
+
+  let score = 0;
+  score += cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0;
+  score += poc_available ? RWEP_WEIGHTS.poc_available : 0;
+  score += (ai_assisted_weapon || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
+  score += active_exploitation === 'confirmed' ? RWEP_WEIGHTS.active_exploitation : 0;
+  score += active_exploitation === 'suspected' ? Math.floor(RWEP_WEIGHTS.active_exploitation / 2) : 0;
+  score += Math.min(RWEP_WEIGHTS.blast_radius, blast_radius);
+  score += patch_available ? RWEP_WEIGHTS.patch_available : 0;
+  score += live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0;
+  score += reboot_required ? RWEP_WEIGHTS.reboot_required : 0;
+
+  return Math.min(100, Math.max(0, score));
+}
+
+function timeline(rwepScore) {
+  if (rwepScore >= 90) return { hours: 4, label: 'Immediate — live patch or isolate within 4 hours' };
+  if (rwepScore >= 75) return { hours: 24, label: 'Urgent — patch or compensating controls within 24 hours' };
+  if (rwepScore >= 60) return { hours: 72, label: 'High — patch within 72 hours' };
+  if (rwepScore >= 40) return { hours: 168, label: 'Elevated — patch within 7 days' };
+  if (rwepScore >= 20) return { hours: 720, label: 'Standard — patch within 30 days' };
+  return { hours: null, label: 'Low — next scheduled maintenance' };
+}
+
+function compare(cveId, catalog) {
+  const entry = catalog[cveId];
+  if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
+
+  const rwep = entry.rwep_score;
+  const cvss = entry.cvss_score;
+  const cvssEquivalent = cvss * 10;
+  const delta = rwep - cvssEquivalent;
+
+  let explanation = '';
+  if (delta > 20) {
+    explanation = `RWEP significantly higher than CVSS equivalent. Factors driving delta: `;
+    const driving = [];
+    if (entry.cisa_kev) driving.push('CISA KEV (+25)');
+    if (entry.poc_available) driving.push('public PoC (+20)');
+    if (entry.ai_discovered) driving.push('AI-discovered (+15 weaponization)');
+    if (entry.active_exploitation === 'confirmed') driving.push('confirmed exploitation (+20)');
+    if (entry.patch_required_reboot && !entry.live_patch_available) driving.push('reboot required (+5)');
+    explanation += driving.join(', ');
+    explanation += '. Framework patch SLAs calibrated to CVSS are insufficient for this CVE.';
+  } else if (delta < -20) {
+    explanation = `RWEP lower than CVSS equivalent. Mitigating factors: `;
+    const mitigating = [];
+    if (entry.patch_available) mitigating.push('patch available (-15)');
+    if (entry.live_patch_available) mitigating.push('live patch available (-10)');
+    if (!entry.poc_available) mitigating.push('no public PoC');
+    if (!entry.cisa_kev) mitigating.push('not CISA KEV');
+    explanation += mitigating.join(', ');
+  } else {
+    explanation = 'CVSS and RWEP are broadly aligned for this CVE.';
+  }
+
+  return {
+    cve_id: cveId,
+    cvss: cvss,
+    rwep: rwep,
+    cvss_framework_sla: timeline(cvssEquivalent),
+    rwep_actual_sla: timeline(rwep),
+    delta,
+    explanation
+  };
+}
+
+function validate(catalog) {
+  const errors = [];
+  for (const [cveId, entry] of Object.entries(catalog)) {
+    if (cveId.startsWith('_')) continue;
+    for (const field of CVE_SCHEMA_REQUIRED) {
+      if (!(field in entry)) {
+        errors.push(`${cveId}: missing required field '${field}'`);
+      }
+    }
+    if (entry.poc_available && (!entry.poc_description || entry.poc_description.trim() === '')) {
+      errors.push(`${cveId}: poc_available=true but poc_description is empty`);
+    }
+    if (entry.live_patch_available && (!entry.live_patch_tools || entry.live_patch_tools.length === 0)) {
+      errors.push(`${cveId}: live_patch_available=true but live_patch_tools is empty`);
+    }
+    const calculatedRwep = scoreCustom({
+      cisa_kev: entry.cisa_kev,
+      poc_available: entry.poc_available,
+      ai_assisted_weapon: entry.ai_assisted_weaponization || false,
+      ai_discovered: entry.ai_discovered || false,
+      active_exploitation: entry.active_exploitation,
+      blast_radius: entry.rwep_factors ? entry.rwep_factors.blast_radius : 0,
+      patch_available: entry.patch_available,
+      live_patch_available: entry.live_patch_available,
+      reboot_required: entry.patch_required_reboot
+    });
+    if (Math.abs(calculatedRwep - entry.rwep_score) > 5) {
+      errors.push(`${cveId}: rwep_score ${entry.rwep_score} diverges from calculated ${calculatedRwep} by more than 5 — verify factors`);
+    }
+  }
+  return errors;
+}
+
+module.exports = { score, scoreCustom, timeline, compare, validate, RWEP_WEIGHTS };