notque/vexjoy-agent / skills/analysis/assessment
assessment
VerifiedAssessment: read-only inspection, codebase overview, value analysis, health checks, ADR consultation, decision analysis, multi-perspective critique.
scripts/check-cve-sources.py
View on GitHub#!/usr/bin/env python3
"""check-cve-sources.py — audit CVE/vulnerability source coverage for a tech stack.
Three-phase methodology:
1. LOAD inventory + registry + (optional) currently-monitored sources
2. MAP & VERIFY resolve each component to authoritative feeds; mark monitored;
optionally HEAD-check URL reachability
3. REPORT emit JSON + Markdown audit reports
stdlib only. Generic. Vendor-neutral.
"""
from __future__ import annotations
import argparse
import json
import os
import re
import sys
import urllib.error
import urllib.request
from datetime import datetime, timezone
DEFAULT_REGISTRY = os.path.join(
os.path.dirname(os.path.abspath(__file__)),
"..",
"references",
"service-health-check",
"tech-source-registry.json",
)
HEAD_TIMEOUT = 5
REACHABLE_CODES = {200, 301, 302, 403, 405}
# ----------------------------- LOAD -----------------------------------------
def load_registry(path: str) -> dict:
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
def build_lookup(registry: dict) -> dict[str, dict]:
"""Map name + aliases (lowercased) -> tech entry."""
lookup: dict[str, dict] = {}
for entry in registry.get("technologies", []):
keys = [entry["name"]] + list(entry.get("aliases", []))
for k in keys:
lookup[k.lower()] = entry
return lookup
def parse_inventory(path: str) -> list[dict]:
"""JSON inventory: [{name, version?, type?}, ...] or {components: [...]}."""
with open(path, "r", encoding="utf-8") as f:
data = json.load(f)
if isinstance(data, dict):
components = data.get("components", [])
elif isinstance(data, list):
components = data
else:
raise ValueError("Inventory JSON must be a list or {components: [...]}")
out = []
for c in components:
if isinstance(c, str):
name, ver = _split_pin(c)
out.append({"name": name, "version": ver, "type": ""})
elif isinstance(c, dict):
out.append(
{
"name": c.get("name", "").strip(),
"version": str(c.get("version", "")).strip(),
"type": c.get("type", "").strip(),
}
)
return [c for c in out if c["name"]]
def parse_inline(spec: str) -> list[dict]:
"""Parse 'name@ver,name,name@ver' into component list."""
out = []
for token in spec.split(","):
token = token.strip()
if not token:
continue
name, ver = _split_pin(token)
out.append({"name": name, "version": ver, "type": ""})
return out
def _split_pin(token: str) -> tuple[str, str]:
if "@" in token:
n, v = token.split("@", 1)
return n.strip(), v.strip()
return token.strip(), ""
def load_current_sources(path: str) -> set[str]:
"""One URL per line; blank and # comments skipped."""
urls: set[str] = set()
with open(path, "r", encoding="utf-8") as f:
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
urls.add(_normalize_url(line))
return urls
def _normalize_url(url: str) -> str:
# Drop trailing slash, lowercase scheme+host for comparison.
m = re.match(r"^(https?://)([^/]+)(/.*)?$", url, re.IGNORECASE)
if not m:
return url.rstrip("/")
scheme, host, path = m.group(1).lower(), m.group(2).lower(), (m.group(3) or "")
return f"{scheme}{host}{path}".rstrip("/")
# ----------------------------- MAP & VERIFY ---------------------------------
def map_component(component: dict, lookup: dict[str, dict]) -> dict:
key = component["name"].lower()
entry = lookup.get(key)
if entry is None:
return {
**component,
"status": "unmapped",
"type": component.get("type") or "unknown",
"sources": [],
}
sources = [{**s, "monitored": False, "reachable": None} for s in entry.get("sources", [])]
return {
**component,
"status": "mapped",
"type": component.get("type") or entry.get("type", "unknown"),
"sources": sources,
}
def mark_monitored(mapped: list[dict], current: set[str]) -> None:
for comp in mapped:
for s in comp["sources"]:
if _normalize_url(s["url"]) in current:
s["monitored"] = True
def head_check(url: str) -> bool | None:
"""Return True (reachable), False (definitely unreachable), None (network error)."""
try:
req = urllib.request.Request(url, method="HEAD")
with urllib.request.urlopen(req, timeout=HEAD_TIMEOUT) as resp:
return resp.status in REACHABLE_CODES
except urllib.error.HTTPError as e:
return e.code in REACHABLE_CODES
except (urllib.error.URLError, TimeoutError, OSError):
return None
except Exception:
return None
def verify_urls(mapped: list[dict]) -> int:
"""HEAD-check every URL; return count of definitively unreachable URLs."""
unreachable = 0
seen: dict[str, bool | None] = {}
for comp in mapped:
for s in comp["sources"]:
url = s["url"]
if url not in seen:
seen[url] = head_check(url)
s["reachable"] = seen[url]
if seen[url] is False:
unreachable += 1
return unreachable
# ----------------------------- REPORT ---------------------------------------
def summarize(mapped: list[dict]) -> dict:
n = len(mapped)
n_mapped = sum(1 for c in mapped if c["status"] == "mapped")
n_unmapped = n - n_mapped
n_monitored = sum(1 for c in mapped if c["status"] == "mapped" and any(s["monitored"] for s in c["sources"]))
n_gaps = (
sum(1 for c in mapped if c["status"] == "mapped" and not any(s["monitored"] for s in c["sources"])) + n_unmapped
)
n_unreachable = sum(1 for c in mapped for s in c["sources"] if s.get("reachable") is False)
coverage = round(100.0 * n_monitored / n, 1) if n else 0.0
return {
"components": n,
"mapped": n_mapped,
"unmapped": n_unmapped,
"monitored": n_monitored,
"coverage_pct": coverage,
"gaps": n_gaps,
"unreachable": n_unreachable,
}
def render_json(service: str, mapped: list[dict], summary: dict) -> dict:
return {
"service": service,
"generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
"summary": summary,
"components": mapped,
}
def _marker(comp: dict) -> str:
if comp["status"] == "unmapped":
return "❌"
if any(s["monitored"] for s in comp["sources"]):
return "✅"
return "⚠️"
def _reach_str(reachable) -> str:
if reachable is True:
return "ok"
if reachable is False:
return "DOWN"
return "—"
def render_markdown(service: str, mapped: list[dict], summary: dict, checked: bool) -> str:
ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
out: list[str] = []
out.append(f"# CVE Source Coverage Report: {service}")
out.append("")
out.append(f"_Generated: {ts}_")
out.append("")
out.append("## Summary")
out.append("")
out.append("| Metric | Value |")
out.append("|--------|-------|")
out.append(f"| Components | {summary['components']} |")
out.append(f"| Mapped to registry | {summary['mapped']} |")
out.append(f"| Unmapped | {summary['unmapped']} |")
out.append(f"| Monitored (≥1 source) | {summary['monitored']} |")
out.append(f"| Coverage | {summary['coverage_pct']}% |")
out.append(f"| Gaps | {summary['gaps']} |")
if checked:
out.append(f"| Unreachable URLs | {summary['unreachable']} |")
out.append("")
out.append("Legend: ✅ mapped + monitored • ⚠️ mapped, not monitored • ❌ unmapped")
out.append("")
out.append("## Components")
out.append("")
header = "| Status | Component | Version | Type | Sources |"
sep = "|--------|-----------|---------|------|---------|"
out.append(header)
out.append(sep)
for c in mapped:
sources_cell = _format_sources(c["sources"], checked)
out.append(
f"| {_marker(c)} | `{c['name']}` | {c.get('version') or '—'} | {c.get('type') or '—'} | {sources_cell} |"
)
out.append("")
# Gaps
gap_rows = [c for c in mapped if c["status"] == "mapped" and not any(s["monitored"] for s in c["sources"])]
if gap_rows:
out.append("## Gaps — Sources to add")
out.append("")
out.append("Components mapped to authoritative sources you do not currently monitor:")
out.append("")
for c in gap_rows:
out.append(f"### {c['name']}")
for s in c["sources"]:
if s["priority"] == "primary":
out.append(f"- **primary** ({s['kind']}): {s['url']}")
for s in c["sources"]:
if s["priority"] != "primary":
out.append(f"- secondary ({s['kind']}): {s['url']}")
out.append("")
# Unmapped
unmapped = [c for c in mapped if c["status"] == "unmapped"]
if unmapped:
out.append("## Unmapped — Registry Extension TODO")
out.append("")
out.append("These components are not in the registry. Add entries (see `references/registry-schema.md`):")
out.append("")
for c in unmapped:
out.append(f"- [ ] `{c['name']}` (version `{c.get('version') or '?'}`, type `{c.get('type') or '?'}`)")
out.append("")
return "\n".join(out) + "\n"
def _format_sources(sources: list[dict], checked: bool) -> str:
if not sources:
return "—"
cells = []
for s in sources:
flag = "✓" if s["monitored"] else "·"
reach = f" [{_reach_str(s.get('reachable'))}]" if checked else ""
cells.append(f"{flag} {s['priority']}/{s['kind']}{reach}")
return "<br>".join(cells)
# ----------------------------- CLI ------------------------------------------
def parse_args(argv: list[str]) -> argparse.Namespace:
p = argparse.ArgumentParser(
description="Audit CVE/vulnerability source coverage for a technology stack.",
)
src = p.add_mutually_exclusive_group(required=True)
src.add_argument("--inventory", help="Path to JSON inventory file.")
src.add_argument("--inline", help='Inline list: "name@ver,name,name@ver"')
p.add_argument("--current-sources", help="Optional path; one URL per line.")
p.add_argument("--service", default="service", help="Service name for report header.")
p.add_argument("--check-urls", action="store_true", help="HEAD-check source URLs (5s timeout).")
p.add_argument("--registry", default=DEFAULT_REGISTRY, help="Path to tech-source-registry.json.")
p.add_argument("--out-dir", default=".", help="Output directory (default: cwd).")
return p.parse_args(argv)
def main(argv: list[str]) -> int:
args = parse_args(argv)
# PHASE 1: LOAD
try:
registry = load_registry(args.registry)
except (OSError, json.JSONDecodeError) as e:
print(f"ERROR: failed to load registry: {e}", file=sys.stderr)
return 3
lookup = build_lookup(registry)
if args.inventory:
try:
components = parse_inventory(args.inventory)
except (OSError, json.JSONDecodeError, ValueError) as e:
print(f"ERROR: failed to load inventory: {e}", file=sys.stderr)
return 3
else:
components = parse_inline(args.inline)
if not components:
print("ERROR: inventory is empty", file=sys.stderr)
return 3
current = set()
if args.current_sources:
try:
current = load_current_sources(args.current_sources)
except OSError as e:
print(f"WARN: failed to load current sources ({e}); proceeding without.", file=sys.stderr)
# PHASE 2: MAP & VERIFY
mapped = [map_component(c, lookup) for c in components]
if current:
mark_monitored(mapped, current)
unreachable_count = 0
if args.check_urls:
unreachable_count = verify_urls(mapped)
# PHASE 3: REPORT
summary = summarize(mapped)
payload = render_json(args.service, mapped, summary)
md = render_markdown(args.service, mapped, summary, checked=args.check_urls)
os.makedirs(args.out_dir, exist_ok=True)
date_tag = datetime.now(timezone.utc).strftime("%Y%m%d")
safe_service = re.sub(r"[^A-Za-z0-9_.-]+", "-", args.service)
json_path = os.path.join(args.out_dir, f"cve-source-report-{safe_service}-{date_tag}.json")
md_path = os.path.join(args.out_dir, f"cve-source-report-{safe_service}-{date_tag}.md")
with open(json_path, "w", encoding="utf-8") as f:
json.dump(payload, f, indent=2, ensure_ascii=False)
f.write("\n")
with open(md_path, "w", encoding="utf-8") as f:
f.write(md)
print(f"Service: {args.service}")
print(f"Components: {summary['components']}")
print(f"Mapped: {summary['mapped']} (unmapped: {summary['unmapped']})")
print(f"Monitored: {summary['monitored']} (coverage: {summary['coverage_pct']}%)")
print(f"Gaps: {summary['gaps']}")
if args.check_urls:
print(f"Unreachable: {summary['unreachable']}")
print(f"JSON report: {json_path}")
print(f"MD report: {md_path}")
if args.check_urls and unreachable_count > 0:
return 2
if summary["gaps"] > 0:
return 1
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |