Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
70 changes: 69 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ SecureVibe is released under the [MIT license](./LICENSE) and maintained by
| **secret pattern** | `skills/secret-detection/checklists/secret_detection.yaml` (`checks:` block, `type: secret_pattern`) and matching test in `skills/secret-detection/tests/corpus.json` | Provide a regex, severity, hotwords, and at least one valid + one invalid (false-positive) test fixture. PR-B1 unified the legacy `rules/dlp_patterns.json` + `rules/dlp_exclusions.json` into this single YAML; the i18n locale sidecar was dropped. |
| **False-positive fix** | The relevant `*_exclusions.json` or a skill-specific exclusion file | These PRs are merged quickly. |
| **Detection rule** | `rules/{cloud,endpoint,container,saas}/<platform>/<name>.yml` | Follow the Sigma format. Include `schema_version: "1.0"` so the validator picks it up. |
| **Compliance mapping** | `skills/compliance-awareness/frameworks/{cwe,owasp}_mapping.yaml` or `compliance/*_mapping.yaml` | Every skill ID must be present in both `cwe_mapping.yaml` and `owasp_mapping.yaml`. |
| **Compliance mapping** | `compliance/*_mapping.yaml` (control → skills) or `frameworks/{cwe,owasp}_mapping.yaml` (skill → OWASP/CWE items) | `compliance/` is the one the `map_compliance_control` tool and the `evidence` command read; `dev validate` fails CI on any skill ID there that has no `skills/<id>/SKILL.md`. `frameworks/` is descriptive metadata with no consumer — keep it accurate, but nothing breaks if a skill is absent. |
| **CLI / SDK / compiler code** | `cmd/secure-vibe/`, `cmd/secure-vibe/`, `internal/`, `sdk/{go,python,typescript}/` | Add or update Go tests (`*_test.go`) for behaviour changes. |
| **Docs** | `*.md` files at the repo root, in `docs/`, in `skills/*/`, or in `packaging/*/` | Prose changes are welcome — keep the brand SecureVibe and preserve technical identifiers (`secure-vibe`, the Go module path). |

Expand Down Expand Up @@ -148,6 +148,74 @@ exceeds the declared budget. When you grow a skill's prose:
If you find yourself bumping the budget, consider splitting the skill rather
than enlarging the existing tier.

## Three layers

A skill directory has three kinds of content, and they reach different readers.
Putting something in the wrong layer is how a rule ages into a false positive —
or into an API that never existed.

| Layer | Ships to the agent? | Holds |
|---|---|---|
| `SKILL.md` → ALWAYS / NEVER / KFP | Every target | **Invariants.** The security property, stated so it stays true when the ecosystem moves. Plus a handful of recognition anchors — the two or three symbol names an agent is most likely to be about to type. |
| `SKILL.md` → `## Context (for humans)` | **Only** the flat single-file targets at `--budget full` | Why the class exists, what the attacker economics are. Not delivered by a native skill bundle at any tier. |
| `references/*.md` | **Only** native skill bundles, opened on demand | **Exact APIs, code examples, version gates, framework defaults.** Everything that dates. |
| `rules/`, `checklists/` | **Never shipped** | Build-time input for the deterministic gate and the `dev test` corpus runner. |

The two middle rows do not overlap, and that is deliberate: `secure-vibe init`
installs native bundles by default, while `--tool universal` (and `--full-inline`)
compiles one flat document instead. So a fact can legitimately appear both in
`Context` and in a reference — each copy serves a target the other cannot reach.
`dynamic-verification` carries its oracle table twice for exactly this reason.
Before deleting one as a duplicate, check which target would lose it.

Two consequences worth stating plainly:

- **`rules/` is not a place to move content you want an agent to read.** Nothing
copies it into an installed skill, so material moved there leaves the agent's
world entirely. It pays off only when a detector actually parses it — the way
`container-security`'s `dkr-*` patterns are parsed in Go. Without a detector,
put the content in `references/`.
- **Every API name, class, enum or flag in ALWAYS / NEVER must be verified against
current documentation, or moved to a reference.** `deserialization-security`
shipped `LAMINAR_INTERNAL_DEFAULT` as a Jackson constant for a year; no such
value exists. A skill that names an API it invented is worse than one that names
none, because the agent will type it.

Anchors are the exception that earns its place: `pickle`, `npm ci`,
`hmac.compare_digest` cost a handful of tokens, are stable across years, and are
what makes a rule fire on the code in front of the agent. An enumeration of
twenty platform symbols is not an anchor — it is a catalogue, and it belongs in a
reference.

## One owner per rule

If another skill already covers something, and covers it better, **name that
skill instead of restating it**. A thinner copy of a neighbour's rule is worse
than no rule at all: an agent that triggers only this skill gets the weaker
version and its user believes the surface is covered.

`api-security` used to carry three token rules and two error-response rules.
`auth-security` and `error-handling-security` each stated the same rules more
precisely — `auth-security` also catches algorithm confusion (a client-supplied
`HS256` token signed with the issuer's public key), which the `alg=none` check
copied into `api-security` does not. Anyone who triggered `api-security` alone
got the half that misses the harder attack.

When you find a duplicate:

1. **Decide the owner by depth.** Whichever skill states it most precisely, or
catches variants the other misses, keeps the rule.
2. **Replace the copy with a pointer** that says what the owner covers and why
it matters — not a bare "see also". The pointer has to be worth its line, so
name the thing the reader would otherwise miss.
3. **Add the owner to `related_skills`.** A delegation the frontmatter does not
record is one the next author will re-duplicate.
4. **Check the `description`.** If it advertised the delegated topic, remove it,
or the skill keeps triggering on tasks it no longer answers.

The pointer must live in `ALWAYS` or `NEVER`. Those are the only sections that
reach the packaged skill — a note in `## Context` is dropped at build time.

## Style

- **Brand:** the project is **SecureVibe**. The Go module path remains
Expand Down
54 changes: 27 additions & 27 deletions DATA_QUALITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Auto-generated by `scripts/generate-data-quality.py`. Re-run after any change to the on-disk vulnerability or skills data; CI fails if the committed file is out of date.

_Generated: 2026-08-11 10:24 UTC_
_Generated: 2026-08-14 02:50 UTC_

## Summary

Expand All @@ -17,54 +17,54 @@ _Generated: 2026-08-11 10:24 UTC_

| Ecosystem | Entries | Curated | OSSF-derived | Other | Reference coverage | Last updated | Age |
|---|---:|---:|---:|---:|---:|---|---:|
| composer | 10 | 10 | 0 | 0 | 100.0% | 2026-06-21 | 50d ⚠️ |
| crates | 30 | 22 | 8 | 0 | 100.0% | 2026-06-21 | 50d ⚠️ |
| docker | 12 | 12 | 0 | 0 | 100.0% | 2026-06-21 | 50d ⚠️ |
| github-actions | 12 | 12 | 0 | 0 | 100.0% | 2026-06-21 | 50d ⚠️ |
| go | 30 | 13 | 17 | 0 | 100.0% | 2026-06-21 | 50d ⚠️ |
| maven | 14 | 12 | 2 | 0 | 100.0% | 2026-06-21 | 50d ⚠️ |
| npm | 2028 | 88 | 1940 | 0 | 100.0% | 2026-06-23 | 49d ⚠️ |
| nuget | 608 | 8 | 600 | 0 | 100.0% | 2026-05-14 | 88d ⚠️ |
| pypi | 618 | 59 | 559 | 0 | 100.0% | 2026-06-23 | 49d ⚠️ |
| rubygems | 456 | 9 | 447 | 0 | 100.0% | 2026-06-22 | 50d ⚠️ |
| composer | 10 | 10 | 0 | 0 | 100.0% | 2026-06-21 | 53d ⚠️ |
| crates | 30 | 22 | 8 | 0 | 100.0% | 2026-06-21 | 53d ⚠️ |
| docker | 12 | 12 | 0 | 0 | 100.0% | 2026-06-21 | 53d ⚠️ |
| github-actions | 12 | 12 | 0 | 0 | 100.0% | 2026-06-21 | 53d ⚠️ |
| go | 30 | 13 | 17 | 0 | 100.0% | 2026-06-21 | 53d ⚠️ |
| maven | 14 | 12 | 2 | 0 | 100.0% | 2026-06-21 | 53d ⚠️ |
| npm | 2028 | 88 | 1940 | 0 | 100.0% | 2026-06-23 | 52d ⚠️ |
| nuget | 608 | 8 | 600 | 0 | 100.0% | 2026-05-14 | 91d ⚠️ |
| pypi | 618 | 59 | 559 | 0 | 100.0% | 2026-06-23 | 52d ⚠️ |
| rubygems | 456 | 9 | 447 | 0 | 100.0% | 2026-06-22 | 52d ⚠️ |

## Typosquat database

- File: `vulnerabilities/supply-chain/typosquat-db/known_typosquats.json`
- Entries: **302**
- By source: `curated`: 71, `ossf-malicious-packages-derived`: 231
- Reference coverage: 100.0%
- Last updated: 2026-06-23 (49d ⚠️)
- Last updated: 2026-06-23 (52d ⚠️)

## OSV cache (SAMPLED)

> **SAMPLED.** This repo ships a stride-sampled subset of each ecosystem's OSV archive so the tree stays reviewable. The current sample target is set by `scripts/ingest-osv.py --per-ecosystem` (default 500). Operators who need full coverage should re-run with `--per-ecosystem 0`.

| Ecosystem | Advisories | Packages indexed | Generated at | Age |
|---|---:|---:|---|---:|
| composer | 122 | 38 | 2026-05-16 | 87d ⚠️ |
| crates | 139 | 69 | 2026-05-16 | 87d ⚠️ |
| go | 123 | 45 | 2026-05-16 | 87d ⚠️ |
| maven | 310 | 107 | 2026-05-16 | 87d ⚠️ |
| npm | 105 | 98 | 2026-05-16 | 87d ⚠️ |
| nuget | 767 | 107 | 2026-05-16 | 87d ⚠️ |
| pub | 26 | 18 | 2026-05-16 | 87d ⚠️ |
| pypi | 111 | 42 | 2026-05-16 | 87d ⚠️ |
| rubygems | 179 | 71 | 2026-05-16 | 87d ⚠️ |
| swift | 117 | 56 | 2026-05-16 | 87d ⚠️ |
| composer | 122 | 38 | 2026-05-16 | 89d ⚠️ |
| crates | 139 | 69 | 2026-05-16 | 89d ⚠️ |
| go | 123 | 45 | 2026-05-16 | 89d ⚠️ |
| maven | 310 | 107 | 2026-05-16 | 89d ⚠️ |
| npm | 105 | 98 | 2026-05-16 | 89d ⚠️ |
| nuget | 767 | 107 | 2026-05-16 | 89d ⚠️ |
| pub | 26 | 18 | 2026-05-16 | 89d ⚠️ |
| pypi | 111 | 42 | 2026-05-16 | 89d ⚠️ |
| rubygems | 179 | 71 | 2026-05-16 | 89d ⚠️ |
| swift | 117 | 56 | 2026-05-16 | 89d ⚠️ |

## CVE patterns (code-relevant)

- File: `vulnerabilities/cve/code-relevant/cve_patterns.json`
- Entries: **58**
- Reference coverage: 100.0%
- Last updated: 2026-06-20 (52d ⚠️)
- Last updated: 2026-06-20 (55d ⚠️)

## Manifest integrity

- File: `manifest.json`
- Release version: `2026.08.11.1`
- Released at: 2026-08-11T00:00:00Z
- Files indexed: 1301
- Signature: signed
- Release version: `2026.08.14.1`
- Released at: 2026-08-14T00:00:00Z
- Files indexed: 1449
- Signature: unsigned

2 changes: 1 addition & 1 deletion PROPOSAL.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ token_budget:
full: 1800 # tokens for full variant
rules_path: "rules/" # relative path to machine-readable rules
tests_path: "tests/" # relative path to test corpus
related_skills: ["dependency-audit", "supply-chain-security"]
related_skills: ["supply-chain-security", "secret-detection"]
last_updated: "2026-05-12"
sources:
- "OWASP Secrets Management Cheat Sheet"
Expand Down
6 changes: 3 additions & 3 deletions cmd/secure-vibe/cmd/cmd_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ func TestListOutputsAllSeven(t *testing.T) {
t.Fatal(err)
}
for _, id := range []string{
"api-security", "compliance-awareness", "dependency-audit",
"api-security", "crypto-misuse", "logging-security",
"container-security", "secret-detection",
"secure-code-review", "supply-chain-security",
} {
Expand Down Expand Up @@ -231,8 +231,8 @@ func TestInitFiltersSkillsList(t *testing.T) {
if !strings.Contains(got, "secret-detection") {
t.Errorf("expected secret-detection in output")
}
if strings.Contains(got, "compliance-awareness") {
t.Errorf("compliance-awareness should be filtered out")
if strings.Contains(got, "crypto-misuse") {
t.Errorf("crypto-misuse should be filtered out")
}
}

Expand Down
16 changes: 13 additions & 3 deletions cmd/secure-vibe/cmd/profile_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -89,21 +89,31 @@ func TestInitSkillsAndProfileIntersect(t *testing.T) {
}
out := string(body)

// Assert on the section heading, not on the bare id. Skills name each
// other now — api-security delegates token rules to auth-security in
// the body text — so a substring match on "auth-security" hits a
// cross-reference inside an included skill and reports an exclusion
// failure that never happened. A skill is *in* the output only when
// it has its own `## Title (`id`)` section.
included := func(id string) bool {
return strings.Contains(out, "(`"+id+"`)")
}

// api-security is in both --skills and --profile financial-services
// → included.
if !strings.Contains(out, "api-security") {
if !included("api-security") {
t.Errorf("api-security should be in the intersection (--skills AND --profile)")
}
// mobile-security IS a real skill and IS in --skills, but it is NOT
// in the financial-services profile. Intersection semantics MUST
// exclude it; override semantics would (wrongly) include it.
if strings.Contains(out, "mobile-security") {
if included("mobile-security") {
t.Errorf("mobile-security is not in the financial-services profile; intersection should exclude it. Override semantics would (wrongly) include it.")
}
// auth-security IS in the financial-services profile but is NOT in
// --skills. Intersection MUST exclude it (override would too — this
// covers the half of the intersection that is symmetric).
if strings.Contains(out, "auth-security") {
if included("auth-security") {
t.Errorf("auth-security is in the profile but not in --skills; intersection should exclude it")
}
}
64 changes: 64 additions & 0 deletions cmd/secure-vibe/cmd/validate.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"fmt"
"os"
"path/filepath"
"regexp"
"strings"

"github.com/spf13/cobra"
Expand Down Expand Up @@ -56,6 +57,16 @@ func validateCmd() *cobra.Command {
problems = append(problems, fmt.Sprintf("%s: rules_path %q not found", s.Path, rp))
}
}
// Each tier is a superset of the one below it, so the declared
// budgets must rise with the tiers. A budget that sits below the
// tier under it still passes the per-tier check while silently
// enforcing nothing.
if b := s.Frontmatter.TokenBudget; b.Minimal > b.Compact || b.Compact > b.Full {
problems = append(problems, fmt.Sprintf(
"%s: token_budget must be non-decreasing across tiers, got minimal=%d compact=%d full=%d",
s.Path, b.Minimal, b.Compact, b.Full,
))
}
for _, tier := range []skill.Tier{skill.TierMinimal, skill.TierCompact, skill.TierFull} {
limit := budgetFor(s, tier)
if limit <= 0 {
Expand Down Expand Up @@ -86,6 +97,7 @@ func validateCmd() *cobra.Command {
if err := validateSkillReferences(abs, knownIDs, &problems); err != nil {
return err
}
validateContextOnlyPointers(skills, knownIDs, &problems)

if len(problems) > 0 {
for _, p := range problems {
Expand Down Expand Up @@ -366,3 +378,55 @@ func collectProfileSkillRefs(dir string, problems *[]string) (map[string]profile
}
return out, nil
}

// skillMention matches a cross-skill pointer in either form the library
// uses: a backtick-quoted id (`auth-security`) or a wiki link
// ([[security-regression-tests]]). Matching only the first form let
// dynamic-verification's handoff sit unnoticed in `## Context`.
var skillMention = regexp.MustCompile("`([a-z][a-z0-9-]{2,})`" + `|\[\[([a-z][a-z0-9-]{2,})\]\]`)

// validateContextOnlyPointers rejects a delegation that names another skill
// in `## Context` and nowhere in ALWAYS / NEVER / KNOWN FALSE POSITIVES.
//
// Only the rule blocks reach a packaged skill: `## Context` is dropped from
// every native bundle and every rules-style target, so a pointer that lives
// only there is read by the humans editing the library and by no agent
// anywhere. The failure is invisible from the source file — the sentence is
// right there in SKILL.md — and it is worse than a missing pointer, because
// the neighbouring skill's rule gets restated thinly next to a delegation
// the reader believes is doing the routing. `threat-modeling` shipped its
// entire "who actually owns each control" paragraph this way.
func validateContextOnlyPointers(skills []*skill.Skill, knownIDs map[string]bool, problems *[]string) {
for _, s := range skills {
if s.Body.Context == "" {
continue
}
shipped := strings.Join(append(append(append([]string{},
s.Body.Always...), s.Body.Never...), s.Body.KnownFalsePositives...), "\n")

seen := map[string]bool{}
var orphans []string
for _, m := range skillMention.FindAllStringSubmatch(s.Body.Context, -1) {
id := m[1]
if id == "" {
id = m[2] // the [[wiki]] alternative
}
if id == s.Frontmatter.ID || !knownIDs[id] || seen[id] {
continue
}
seen[id] = true
if !strings.Contains(shipped, id) {
orphans = append(orphans, id)
}
}
if len(orphans) > 0 {
*problems = append(*problems, fmt.Sprintf(
"%s: `## Context` delegates to %s but no ALWAYS / NEVER / KNOWN FALSE POSITIVES "+
"bullet names %s. Context is stripped from every packaged target, so this "+
"pointer reaches no agent — move it into a rule bullet",
s.Path, strings.Join(orphans, ", "),
map[bool]string{true: "them", false: "it"}[len(orphans) > 1],
))
}
}
}
12 changes: 12 additions & 0 deletions cmd/secure-vibe/internal/compiler/compiler.go
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,12 @@ func sortedKeys[T any](m map[string]T) []string {
}

// Header is the common preamble injected at the top of every distribution.
// Header is used by the flat single-file targets. Those targets compile
// every skill body into one document and do not copy each skill's
// references/ directory, so a rule that names `references/<file>.md`
// inline resolves to nothing here. The note below says so rather than
// rewriting the rule text: the path is still useful — it names the file
// in the skills library — it just is not a path in this output.
func Header(toolDisplay string, tier skill.Tier, n int) string {
return fmt.Sprintf(`# Skills Library — %s (%s tier)

Expand All @@ -280,6 +286,12 @@ update the source skills under `+"`skills/`"+` and regenerate.

Contains %d security skills compiled at the %s budget tier.

Where a rule points at `+"`references/<file>.md`"+`, that path is relative to the
skill's own directory in the skills library — it is not shipped alongside this
file. Install a native skill bundle (`+"`secure-vibe init`"+` without
`+"`--tool universal`"+`) to get those files on disk, or read them in the
library source.

`, toolDisplay, tier, n, tier)
}

Expand Down
15 changes: 12 additions & 3 deletions cmd/secure-vibe/internal/compiler/compiler_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -101,14 +101,23 @@ func TestPerToolDefaultIsPointer(t *testing.T) {
// The routing destination: skills are files the
// agent opens itself.
"skills/<skill-id>/SKILL.md",
// A real description, proving the index carries
// the routing surface and not just IDs.
"Detect and prevent hardcoded secrets",
} {
if !strings.Contains(out, want) {
t.Errorf("%s pointer body missing %q", name, want)
}
}
// The index must carry each skill's real description, which is
// the entire routing surface. Read it from the loaded skill
// rather than hardcoding a fragment: a literal here asserts
// today's wording, so editing any description reddens this
// test for no reason and teaches the next author to change the
// string instead of looking.
for _, s := range skills {
if d := s.Frontmatter.Description; d != "" && !strings.Contains(out, d) {
t.Errorf("%s pointer body missing the description for %q", name, s.Frontmatter.ID)
break
}
}
// Skill discovery must not route through an MCP call.
// These tools are gone; a pointer that still advertises
// them sends the agent down a dead path.
Expand Down
Loading