Skip to content

notque/vexjoy-agent / skills/analysis/assessment

assessment

Verified

Assessment: read-only inspection, codebase overview, value analysis, health checks, ADR consultation, decision analysis, multi-perspective critique.

FileKindSize
SKILL.mdskill md14.5 KB
references/adr-consultation/agent-prompts.mdmarkdown4.4 KB
references/adr-consultation/consultation-patterns.mdmarkdown10.3 KB
references/adr-consultation/consultation-preferred-patterns.mdmarkdown8.9 KB
references/adr-consultation/error-handling.mdmarkdown9.0 KB
references/codebase-overview/examples-and-errors.mdmarkdown7.0 KB
references/codebase-overview/exploration-strategies.mdmarkdown5.5 KB
references/codebase-overview/report-template.mdmarkdown4.8 KB
references/codebase-overview/statistical-analysis-examples.mdmarkdown13.1 KB
references/codebase-overview/statistical-metrics-catalog.mdmarkdown7.8 KB
references/codebase-overview/statistical-phase-details.mdmarkdown6.0 KB
references/codebase-overview/statistical-three-lenses.mdmarkdown9.1 KB
references/decision-helper/decision-archetypes.mdmarkdown7.4 KB
references/decision-helper/decision-preferred-patterns.mdmarkdown8.0 KB
references/multi-persona-critique/examples-and-errors.mdmarkdown6.6 KB
references/multi-persona-critique/personas.mdmarkdown12.4 KB
references/multi-persona-critique/roast-report-template.mdmarkdown4.8 KB
references/multi-persona-critique/roast.mdmarkdown12.3 KB
references/multi-persona-critique/synthesis-template.mdmarkdown7.0 KB
references/repo-value-analysis/phase7-implement-template.mdmarkdown6.8 KB
references/service-health-check/auth-endpoint-patterns.mdmarkdown7.6 KB
references/service-health-check/cve-source-check.mdmarkdown5.8 KB
references/service-health-check/endpoint-config-preferred-patterns.mdmarkdown6.7 KB
references/service-health-check/endpoint-validator.mdmarkdown8.9 KB
references/service-health-check/examples/current-sources.example.txtmarkdown218 B
references/service-health-check/examples/inventory.example.jsonconfig368 B
references/service-health-check/security-headers.mdmarkdown6.2 KB
references/service-health-check/tech-source-registry.jsonconfig8.6 KB
scripts/cartographer.pyscript19.0 KB
scripts/cartographer_omni.pyscript103.7 KB
scripts/cartographer_ultimate.pyscript15.9 KB
scripts/check-cve-sources.pyexecutablescript13.4 KB
scripts/tests/test_check_cve_sources.pyscript1.8 KB

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:]))
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall