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

references/service-health-check/cve-source-check.md

View on GitHub
# CVE Source Check

Audits CVE/vulnerability source coverage for a technology stack. Given an inventory
of components and (optionally) the feeds you currently monitor, it maps each
component to authoritative CVE sources, flags gaps, and emits audit-ready reports.

## Scope

| In scope | Out of scope |
|---|---|
| Mapping components to authoritative feeds via a versioned registry | Running vulnerability scanners (Trivy/Snyk/etc.) |
| Reporting coverage and gaps in JSON + Markdown | Fetching CVE content or ranking by severity |
| Optional HEAD-check for source URL reachability | Integrating with private/commercial vuln databases |
| Audit-ready output (deterministic, reproducible) | Live LLM research per run |

## Inputs

| Flag | Purpose |
|---|---|
| `--inventory <file>` | JSON inventory: `[{name, version?, type?}, ...]` or `{components: [...]}`. |
| `--inline "name@ver,name,..."` | Quick comma-separated list. Mutually exclusive with `--inventory`. |
| `--current-sources <file>` | Optional. One URL per line. Blank lines and `#` comments skipped. |
| `--service <name>` | Free-form name used in report header and filenames. |
| `--check-urls` | HEAD-check every source URL (5s timeout, graceful degradation). |
| `--registry <path>` | Override default `tech-source-registry.json`. |
| `--out-dir <path>` | Output directory (default: cwd). |

JSON inventory format only. YAML is not supported.

## Outputs

| File | Format |
|---|---|
| `cve-source-report-{service}-{YYYYMMDD}.md` | Human-readable audit report. |
| `cve-source-report-{service}-{YYYYMMDD}.json` | Machine-readable per `output-formats.md`. |

| Exit code | Meaning |
|---|---|
| 0 | Full coverage. |
| 1 | Gaps exist (unmapped components or unmonitored sources). |
| 2 | At least one source URL is unreachable (only with `--check-urls`). |
| 3 | Input error (missing/malformed registry or inventory). |

## Workflow

### Phase 1: LOAD

1. Locate the registry: `references/service-health-check/tech-source-registry.json` in the assessment skill by default.
2. Build an inventory:
   - From `--inventory`: parse JSON; accept either a list or `{components: [...]}`.
   - From `--inline`: split on commas, parse `name@version` pairs.
3. If `--current-sources` is provided, read URLs (one per line); normalize for
   case-insensitive comparison.

**Gate**: at least one inventory component is present. Empty inventory -> exit 3.

### Phase 2: MAP & VERIFY

1. For each component, look up `name` (and aliases) in the registry.
   - Found -> status `mapped`, attach the registry's source list.
   - Missing -> status `unmapped`, sources `[]`.
2. If current sources were loaded, mark each source `monitored: true` when its
   normalized URL appears in the set.
3. If `--check-urls` is set, HEAD-check every unique source URL. Treat
   200/301/302/403/405 as reachable; record definite failures and network errors
   distinctly. See `source-verification.md`.

**Gate**: every component has a status; every source has `monitored` and
`reachable` fields populated (`reachable: null` when checks are skipped).

### Phase 3: REPORT

1. Compute the summary: components, mapped/unmapped, monitored, coverage %,
   gaps, unreachable.
2. Write the JSON report.
3. Write the Markdown report:
   - Summary table.
   - Components table with status markers.
   - **Gaps** section listing primary then secondary sources to add (only when
     gaps exist).
   - **Unmapped** section listing registry-extension TODOs (only when unmapped
     components exist).
4. Print a one-screen summary to stdout including report paths.
5. Set the exit code per the table above.

**Gate**: both files exist on disk and the summary printed; exit code reflects
the audit result.

## Quick start

```bash
# Inline, offline, no monitoring data
python3 ~/.claude/skills/assessment/scripts/check-cve-sources.py \
  --inline "go@1.22,alpine@3.19,postgres@16,redis@7,nginx@1.25" \
  --service my-service

# Inventory file + current monitored feeds
python3 ~/.claude/skills/assessment/scripts/check-cve-sources.py \
  --inventory ~/.claude/skills/assessment/references/service-health-check/examples/inventory.example.json \
  --current-sources ~/.claude/skills/assessment/references/service-health-check/examples/current-sources.example.txt \
  --service my-service

# Same, with link verification
python3 ~/.claude/skills/assessment/scripts/check-cve-sources.py \
  --inventory ~/.claude/skills/assessment/references/service-health-check/examples/inventory.example.json \
  --current-sources ~/.claude/skills/assessment/references/service-health-check/examples/current-sources.example.txt \
  --service my-service \
  --check-urls
```

## Extending the registry

To add a technology, edit `references/service-health-check/tech-source-registry.json`. Each entry needs `name`,
`aliases`, `type`, and 1-3 `sources`. Schema lives at `registry-schema.md`.

## Error handling

### "ERROR: failed to load registry"
Cause: registry file missing or malformed JSON.
Solution: confirm `tech-source-registry.json` is at `--registry` (or default
location) and parses with `python3 -m json.tool`.

### "ERROR: failed to load inventory"
Cause: inventory file missing, malformed JSON, or unexpected shape.
Solution: validate with `python3 -m json.tool`. Inventory must be a list or an
object with a `components` key.

### "ERROR: inventory is empty"
Cause: no usable components after parsing.
Solution: confirm each entry has a `name`. Inline form requires non-empty tokens.

### Coverage stuck at 0%
Cause: `--current-sources` URLs do not match registry URLs exactly.
Solution: copy URLs directly from the registry. The script normalizes scheme/host
case and trailing slash; everything else must match.

### `--check-urls` flags many failures
Cause: network issues (proxy, DNS, offline).
Solution: re-run without `--check-urls` for the audit; investigate network
separately. Network errors do not affect the gap exit code.
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