Skip to content

Commit 3dd2646

Browse files
bx33661bx33661
committed
feat: add TypeScript CLI (omv setup / doctor)
Adds the omv CLI so users can install skills via npx oh-my-vul setup. Updates README, CLAUDE.md, CI workflow, and package metadata. Constraint: zero runtime dependencies — only @types/node + typescript as devDeps Confidence: high Scope-risk: narrow
1 parent 321911b commit 3dd2646

54 files changed

Lines changed: 1136 additions & 552 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/validate.yml‎

Lines changed: 25 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,20 @@ on:
55
pull_request:
66

77
jobs:
8+
cli:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- uses: actions/setup-node@v4
13+
with:
14+
node-version: "20"
15+
- name: Install dependencies
16+
run: npm ci
17+
- name: Build CLI
18+
run: npm run build
19+
- name: Typecheck
20+
run: npm run typecheck
21+
822
skill:
923
runs-on: ubuntu-latest
1024
steps:
@@ -13,15 +27,15 @@ jobs:
1327
run: python3 scripts/validate_skill.py
1428
- name: Run release packaging check
1529
run: python3 scripts/release_check.py
16-
- name: Build and validate vuln-finder package
17-
run: bash scripts/package_skill.sh vuln-finder "$RUNNER_TEMP/vuln-finder.skill"
18-
- name: Build and validate vuldb-report package
19-
run: bash scripts/package_skill.sh vuldb-report "$RUNNER_TEMP/vuldb-report.skill"
30+
- name: Build and validate omv-find package
31+
run: bash scripts/package_skill.sh skills/omv-find "$RUNNER_TEMP/omv-find.skill"
32+
- name: Build and validate omv-report package
33+
run: bash scripts/package_skill.sh skills/omv-report "$RUNNER_TEMP/omv-report.skill"
2034
- name: Check golden invalid-flags eval
21-
run: python3 vuln-finder/scripts/check_output.py --eval-id 26 --output vuln-finder/evals/golden/invalid-flags.md
22-
- name: Check vuldb-report blocked handoff golden eval
23-
run: python3 vuldb-report/scripts/check_output.py --eval-id 4 --output vuldb-report/evals/golden/blocked-handoff.md
24-
- name: Check vuldb-report OSV golden eval
25-
run: python3 vuldb-report/scripts/check_output.py --eval-id 5 --output vuldb-report/evals/golden/osv-prototype-pollution.json
26-
- name: Check vuldb-report duplicate CNA golden eval
27-
run: python3 vuldb-report/scripts/check_output.py --eval-id 7 --output vuldb-report/evals/golden/duplicate-cna-warning.md
35+
run: python3 skills/omv-find/scripts/check_output.py --eval-id 26 --output skills/omv-find/evals/golden/invalid-flags.md
36+
- name: Check omv-report blocked handoff golden eval
37+
run: python3 skills/omv-report/scripts/check_output.py --eval-id 4 --output skills/omv-report/evals/golden/blocked-handoff.md
38+
- name: Check omv-report OSV golden eval
39+
run: python3 skills/omv-report/scripts/check_output.py --eval-id 5 --output skills/omv-report/evals/golden/osv-prototype-pollution.json
40+
- name: Check omv-report duplicate CNA golden eval
41+
run: python3 skills/omv-report/scripts/check_output.py --eval-id 7 --output skills/omv-report/evals/golden/duplicate-cna-warning.md

‎.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# oh-my-vul state directory — findings, context snapshots, logs
2+
.omv/
3+
4+
# TypeScript build output
5+
dist/
6+
node_modules/
7+
8+
# Python
9+
__pycache__/
10+
*.py[cod]
11+
*.pyo
12+
13+
# macOS
14+
.DS_Store
15+
16+
# Editor
17+
.vscode/
18+
.idea/
19+
*.swp
20+
*.swo

‎CLAUDE.md‎

Lines changed: 98 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,90 @@
11
# CLAUDE.md
22

3-
This repository contains a small multi-skill project for passive vulnerability research and VulDB/CVE reporting.
3+
oh-my-vul is a modular, community-oriented collection of LLM-friendly vulnerability research skills for Claude Code.
44

5-
The project is mostly Markdown instructions plus deterministic helper scripts. There is no compiled application code.
5+
The project ships a TypeScript CLI (`omv`) for installing skills, plus Markdown skill definitions and Python dev tools. Users install via `npx oh-my-vul setup`.
66

77
## Structure
88

9-
- `vuln-finder/SKILL.md` - skill entry point for finding and ranking open-source packages worth auditing.
10-
- `vuln-finder/references/ecosystems.md` - ecosystem registry sources, GitHub search shapes, keyword rotation, and flagship exclusions.
11-
- `vuln-finder/references/vuln-patterns.md` - vulnerability aliases and source -> sink -> guard patterns.
12-
- `vuln-finder/references/scoring.md` - scoring rubric, confidence adjustments, filtering, and LOC estimation rules.
13-
- `vuln-finder/references/output-contract.md` - final table contract, audit tips, invalid request response, and sparse-result handling.
14-
- `vuln-finder/references/handoff-contract.md` - handoff packet emitted when a confirmed finding should be passed to `vuldb-report`.
15-
- `vuln-finder/scripts/collect_metadata.py` - collects GitHub and selected registry metadata as JSON.
16-
- `vuln-finder/scripts/estimate_loc.sh` - estimates source LOC from a GitHub URL or local checkout.
17-
- `vuln-finder/scripts/check_output.py` - heuristic eval-output checker for saved model outputs.
18-
- `vuln-finder/evals/evals.json` - behavior-focused eval scenarios.
19-
- `vuln-finder/evals/golden/invalid-flags.md` - stable golden output for the invalid flag eval.
20-
- `vuldb-report/SKILL.md` - skill entry point for VulDB form output, CVE checklist, and GHSA advisory drafting.
21-
- `vuldb-report/references/ecosystems.md` - vendor/product/version rules, duplicate-CVE sources, install commands, and CWE/Class mapping.
22-
- `vuldb-report/references/cvss-builder.md` - CVSS v3.1 metric decision table and common vectors.
23-
- `vuldb-report/references/handoff-contract.md` - handoff packet consumer contract from `vuln-finder`.
24-
- `vuldb-report/references/report-templates.md` - VulDB, GHSA, OSV JSON, and standalone Markdown advisory templates.
25-
- `vuldb-report/references/examples/` - filled advisory examples.
26-
- `vuldb-report/scripts/check_output.py` - heuristic eval-output checker for saved report outputs.
27-
- `vuldb-report/evals/evals.json` - behavior-focused report-generation eval scenarios.
28-
- `scripts/validate_skill.py` - project-level validator for all skill directories and optional `.skill` packages.
29-
- `scripts/package_skill.sh` - project-level package builder for any root-level skill directory.
30-
- `scripts/release_check.py` - release-time validator, package builder, and SHA-256 manifest printer.
31-
- `.github/workflows/validate.yml` - CI validation, packaging checks, and the stable golden eval.
32-
- `vuln-finder.skill` and `vuldb-report.skill` - packaged skill artifacts.
33-
34-
## Skill Invocation
9+
```
10+
src/
11+
cli/
12+
omv.ts — CLI entry point (setup / doctor / help)
13+
setup.ts — copies skills/ to ~/.claude/skills/
14+
doctor.ts — checks installation health
15+
paths.ts — path utilities (claudeSkillsDir, packageRoot, …)
16+
index.ts — package exports
17+
18+
skills/
19+
omv/SKILL.md — collection manager (/omv)
20+
omv-find/SKILL.md — find and rank audit targets (/omv-find)
21+
omv-find/references/
22+
scoring.md — scoring rubric, confidence adjustments, filtering, LOC estimation
23+
output-contract.md — final table contract, audit tips, invalid-request template
24+
omv-find/scripts/check_output.py — heuristic eval checker
25+
omv-find/evals/evals.json — behavior-focused eval scenarios
26+
omv-find/evals/golden/ — stable golden outputs
27+
omv-report/SKILL.md — generate VulDB/CVE/GHSA/OSV reports (/omv-report)
28+
omv-report/references/
29+
ecosystems.md — vendor/product/version rules, CWE mapping, duplicate-CVE databases
30+
report-templates.md — VulDB, GHSA, OSV JSON, Markdown advisory templates
31+
examples/ — filled advisory examples
32+
omv-report/scripts/check_output.py — heuristic eval checker
33+
omv-report/evals/evals.json — behavior-focused report-generation eval scenarios
34+
omv-report/evals/golden/ — stable golden outputs
35+
36+
shared/
37+
references/
38+
ecosystems.md — ecosystem registry sources, GitHub search shapes, flagship exclusions
39+
vuln-patterns.md — vulnerability aliases and source -> sink -> guard patterns
40+
cvss-builder.md — CVSS v3.1 metric decision table and common vectors
41+
scripts/
42+
collect_metadata.py — collects GitHub and selected registry metadata as JSON
43+
estimate_loc.sh — estimates source LOC from a GitHub URL or local checkout
44+
45+
contracts/
46+
evidence.v1.yaml — finding object: the typed boundary between omv-find and omv-report
47+
candidate-list.v1.yaml — candidate table entry schema produced by omv-find
48+
threat-map.v1.yaml — dataflow threat map schema (planned: omv-audit M2+)
49+
50+
agents/
51+
vuln-scanner.md — passive candidate discovery
52+
dataflow-tracer.md — source -> sink -> guard analysis
53+
cvss-analyst.md — CVSS v3.1 computation
54+
dedup-analyst.md — duplicate CVE/GHSA search
55+
report-writer.md — platform-specific advisory rendering
56+
57+
scripts/
58+
validate_skill.py — validates all skill directories and optional .skill packages
59+
package_skill.sh — builds a .skill archive from a skill directory
60+
release_check.py — release-time validator, package builder, SHA-256 manifest printer
61+
62+
registry.yaml — collection metadata: versions, produces/consumes bindings
63+
.github/workflows/validate.yml — CI validation, packaging checks, stable golden evals
64+
```
65+
66+
## CLI
67+
68+
```sh
69+
# Install skills to ~/.claude/skills/
70+
npx oh-my-vul setup
71+
npx oh-my-vul setup --force # overwrite existing
72+
npx oh-my-vul setup --dry-run # preview only
73+
74+
# Check installation health
75+
omv doctor
76+
```
77+
78+
Build the CLI:
79+
80+
```sh
81+
npm install
82+
npm run build # tsc + chmod dist/cli/omv.js
83+
npm run typecheck # type-check without emitting
84+
```
3585

3686
```sh
37-
/vuln-finder [--lang npm|python|go|rust|java|ruby|php|csharp|swift|dart|elixir|perl|r|lua|all] [--vuln VULN_TYPE] [--count N] [keyword ...]
87+
/omv-find [--lang npm|python|go|rust|java|ruby|php|csharp|swift|dart|elixir|perl|r|lua|all] [--vuln VULN_TYPE] [--count N] [keyword ...]
3888
```
3989

4090
Supported vulnerability aliases:
@@ -54,29 +104,29 @@ python3 scripts/validate_skill.py
54104
Validate one skill:
55105

56106
```sh
57-
python3 scripts/validate_skill.py vuln-finder
58-
python3 scripts/validate_skill.py vuldb-report
107+
python3 scripts/validate_skill.py skills/omv-find
108+
python3 scripts/validate_skill.py skills/omv-report
59109
```
60110

61111
Rebuild packages:
62112

63113
```sh
64-
bash scripts/package_skill.sh vuln-finder
65-
bash scripts/package_skill.sh vuldb-report
114+
bash scripts/package_skill.sh skills/omv-find
115+
bash scripts/package_skill.sh skills/omv-report
66116
```
67117

68-
Run the stable `vuln-finder` golden eval:
118+
Run the stable `omv-find` golden eval:
69119

70120
```sh
71-
python3 vuln-finder/scripts/check_output.py --eval-id 26 --output vuln-finder/evals/golden/invalid-flags.md
121+
python3 skills/omv-find/scripts/check_output.py --eval-id 26 --output skills/omv-find/evals/golden/invalid-flags.md
72122
```
73123

74-
Run stable `vuldb-report` golden evals:
124+
Run stable `omv-report` golden evals:
75125

76126
```sh
77-
python3 vuldb-report/scripts/check_output.py --eval-id 4 --output vuldb-report/evals/golden/blocked-handoff.md
78-
python3 vuldb-report/scripts/check_output.py --eval-id 5 --output vuldb-report/evals/golden/osv-prototype-pollution.json
79-
python3 vuldb-report/scripts/check_output.py --eval-id 7 --output vuldb-report/evals/golden/duplicate-cna-warning.md
127+
python3 skills/omv-report/scripts/check_output.py --eval-id 4 --output skills/omv-report/evals/golden/blocked-handoff.md
128+
python3 skills/omv-report/scripts/check_output.py --eval-id 5 --output skills/omv-report/evals/golden/osv-prototype-pollution.json
129+
python3 skills/omv-report/scripts/check_output.py --eval-id 7 --output skills/omv-report/evals/golden/duplicate-cna-warning.md
80130
```
81131

82132
Run release checks:
@@ -86,10 +136,16 @@ python3 scripts/release_check.py
86136
python3 scripts/release_check.py --write-artifacts
87137
```
88138

89-
Packages should contain root-level `SKILL.md` plus the skill's `references/`, `scripts/`, and `evals/` directories when present. They should not contain nested skill directory entries such as `vuln-finder/` or `vuldb-report/`.
139+
Packages contain root-level `SKILL.md` plus the skill's `references/`, `scripts/`, and `evals/` directories when present. They must not contain nested skill directory entries such as `omv-find/` or `omv-report/`.
140+
141+
## Contracts
142+
143+
Skills reference `contracts/` directly rather than duplicating schema in their `references/`. When adding a new skill that consumes Evidence.v1, reference `../../contracts/evidence.v1.yaml` from the SKILL.md body. The validator handles `../../shared/references/` and `../../contracts/` path prefixes.
90144

91145
## Design Notes
92146

93-
Keep each `SKILL.md` concise. Put ecosystem-specific guidance, vulnerability matrices, scoring details, examples, and output contracts in `references/` so the agent can load only what the current request needs.
147+
Keep each `SKILL.md` concise. Put ecosystem-specific guidance, vulnerability matrices, scoring details, examples, and output contracts in `references/` so the agent loads only what the current request needs.
148+
149+
When adding new ecosystems or vulnerability classes, update the relevant shared reference file and add at least one eval scenario. Prefer deterministic script checks for repetitive behavior instead of expanding the main prompt.
94150

95-
When adding new ecosystems or vulnerability classes, update the relevant reference file and add at least one eval scenario. Prefer deterministic script checks for repetitive behavior instead of expanding the main prompt.
151+
When adding a new skill: place it in `skills/<name>/` with a `SKILL.md` whose frontmatter `name` matches the directory name, add focused `references/` and `evals/`, then run `python3 scripts/validate_skill.py` and rebuild packages.

0 commit comments

Comments
 (0)