From cea26ea7fb76797bb66b83459659ca2af62af7b7 Mon Sep 17 00:00:00 2001 From: Willie Date: Sat, 21 Feb 2026 20:59:16 +0800 Subject: [PATCH] feat: add dangling local markdown link detection to audit Scan .md files in skill directories for broken relative links during audit. Targets that don't exist on disk produce a LOW severity finding (pattern: dangling-link). External URLs, anchors, and fragments are skipped. Integrated into the existing walk (zero extra IO) and disableable via audit-rules.yaml (- id: dangling-link / enabled: false). The init-rules template, built-in skill reference, and website docs are updated. --- internal/audit/audit.go | 95 ++++++++++++++++++- internal/audit/audit_scan_skill_test.go | 121 ++++++++++++++++++++++++ internal/audit/patterns.go | 41 ++++++++ skills/skillshare/references/audit.md | 11 ++- tests/integration/audit_test.go | 58 ++++++++++++ website/docs/commands/audit.md | 18 +++- 6 files changed, 338 insertions(+), 6 deletions(-) diff --git a/internal/audit/audit.go b/internal/audit/audit.go index ab0fa0182..41b077d90 100644 --- a/internal/audit/audit.go +++ b/internal/audit/audit.go @@ -4,6 +4,7 @@ import ( "fmt" "os" "path/filepath" + "regexp" "strings" "skillshare/internal/utils" @@ -14,6 +15,13 @@ const ( maxScanDepth = 6 ) +// mdFileInfo holds data collected during the walk for structural checks. +type mdFileInfo struct { + relPath string + data []byte + absDir string // absolute directory containing this file +} + var riskWeights = map[string]int{ SeverityCritical: 25, SeverityHigh: 15, @@ -142,7 +150,8 @@ func RiskLabelFromScore(score int) string { // ScanSkill scans all scannable files in a skill directory using global rules. func ScanSkill(skillPath string) (*Result, error) { - return ScanSkillWithRules(skillPath, nil) + disabled := disabledIDsGlobal() + return scanSkillImpl(skillPath, nil, disabled) } // ScanFile scans a single file using global rules. @@ -166,12 +175,19 @@ func ScanSkillForProject(skillPath, projectRoot string) (*Result, error) { if err != nil { return nil, fmt.Errorf("load project rules: %w", err) } - return ScanSkillWithRules(skillPath, rules) + disabled := disabledIDsForProject(projectRoot) + return scanSkillImpl(skillPath, rules, disabled) } // ScanSkillWithRules scans all scannable files using the given rules. // If activeRules is nil, the default global rules are used. +// Structural checks (e.g. dangling-link) always run; to disable them +// use ScanSkill / ScanSkillForProject which honour audit-rules.yaml. func ScanSkillWithRules(skillPath string, activeRules []rule) (*Result, error) { + return scanSkillImpl(skillPath, activeRules, nil) +} + +func scanSkillImpl(skillPath string, activeRules []rule, disabled map[string]bool) (*Result, error) { info, err := os.Stat(skillPath) if err != nil { return nil, fmt.Errorf("cannot access skill path: %w", err) @@ -185,6 +201,8 @@ func ScanSkillWithRules(skillPath string, activeRules []rule) (*Result, error) { ScanTarget: skillPath, } + var mdFiles []mdFileInfo + err = filepath.Walk(skillPath, func(path string, fi os.FileInfo, walkErr error) error { if walkErr != nil { return nil @@ -225,6 +243,14 @@ func ScanSkillWithRules(skillPath string, activeRules []rule) (*Result, error) { return nil } + if strings.ToLower(filepath.Ext(fi.Name())) == ".md" { + mdFiles = append(mdFiles, mdFileInfo{ + relPath: relPath, + data: data, + absDir: filepath.Dir(path), + }) + } + findings := ScanContentWithRules(data, relPath, activeRules) result.Findings = append(result.Findings, findings...) @@ -234,6 +260,11 @@ func ScanSkillWithRules(skillPath string, activeRules []rule) (*Result, error) { return nil, fmt.Errorf("error scanning skill: %w", err) } + // Structural check: scan collected .md files for dangling local links. + if !disabled["dangling-link"] { + result.Findings = append(result.Findings, checkDanglingLinks(mdFiles)...) + } + result.updateRisk() return result, nil } @@ -364,3 +395,63 @@ func truncate(s string, maxLen int) string { } return s[:maxLen-3] + "..." } + +// mdLinkRe matches Markdown inline links: [label](target). +var mdLinkRe = regexp.MustCompile(`\[[^\]]*\]\(([^)]+)\)`) + +// checkDanglingLinks scans collected .md file data for local relative links +// whose targets do not exist on disk. Returns LOW-severity findings. +func checkDanglingLinks(files []mdFileInfo) []Finding { + var findings []Finding + for _, f := range files { + lines := strings.Split(string(f.data), "\n") + for lineNum, line := range lines { + for _, m := range mdLinkRe.FindAllStringSubmatch(line, -1) { + target := m[1] + if isExternalOrAnchor(target) { + continue + } + cleaned := stripFragment(target) + if cleaned == "" { + continue + } + abs := filepath.Join(f.absDir, cleaned) + if _, err := os.Stat(abs); err != nil { + findings = append(findings, Finding{ + Severity: SeverityLow, + Pattern: "dangling-link", + Message: fmt.Sprintf("broken local link: %q not found", target), + File: f.relPath, + Line: lineNum + 1, + Snippet: truncate(strings.TrimSpace(line), 80), + }) + } + } + } + } + return findings +} + +// isExternalOrAnchor returns true for links that should not be checked on disk. +func isExternalOrAnchor(target string) bool { + lower := strings.ToLower(target) + for _, prefix := range []string{ + "http://", "https://", "mailto:", "tel:", "data:", "ftp://", "//", + } { + if strings.HasPrefix(lower, prefix) { + return true + } + } + return strings.HasPrefix(target, "#") +} + +// stripFragment removes #fragment and ?query from a link target. +func stripFragment(target string) string { + if i := strings.IndexByte(target, '#'); i >= 0 { + target = target[:i] + } + if i := strings.IndexByte(target, '?'); i >= 0 { + target = target[:i] + } + return target +} diff --git a/internal/audit/audit_scan_skill_test.go b/internal/audit/audit_scan_skill_test.go index a8293bfa8..29485b11c 100644 --- a/internal/audit/audit_scan_skill_test.go +++ b/internal/audit/audit_scan_skill_test.go @@ -132,6 +132,127 @@ func TestIsScannable(t *testing.T) { } } +func TestScanSkill_DanglingLink(t *testing.T) { + dir := t.TempDir() + skillDir := filepath.Join(dir, "my-skill") + os.MkdirAll(skillDir, 0755) + os.WriteFile(filepath.Join(skillDir, "SKILL.md"), + []byte("# Skill\n\n[broken link](missing-file.md)\n"), 0644) + + result, err := ScanSkill(skillDir) + if err != nil { + t.Fatal(err) + } + + var found bool + for _, f := range result.Findings { + if f.Pattern == "dangling-link" && f.Severity == "LOW" { + found = true + if f.Line != 3 { + t.Errorf("expected line 3, got %d", f.Line) + } + if f.File != "SKILL.md" { + t.Errorf("expected file SKILL.md, got %s", f.File) + } + } + } + if !found { + t.Errorf("expected a LOW dangling-link finding, got findings: %+v", result.Findings) + } +} + +func TestScanSkill_ValidFileLink(t *testing.T) { + dir := t.TempDir() + skillDir := filepath.Join(dir, "my-skill") + os.MkdirAll(skillDir, 0755) + os.WriteFile(filepath.Join(skillDir, "guide.md"), []byte("# Guide"), 0644) + os.WriteFile(filepath.Join(skillDir, "SKILL.md"), + []byte("# Skill\n\n[guide](guide.md)\n"), 0644) + + result, err := ScanSkill(skillDir) + if err != nil { + t.Fatal(err) + } + for _, f := range result.Findings { + if f.Pattern == "dangling-link" { + t.Errorf("unexpected dangling-link finding for valid file link: %+v", f) + } + } +} + +func TestScanSkill_ValidDirectoryLink(t *testing.T) { + dir := t.TempDir() + skillDir := filepath.Join(dir, "my-skill") + os.MkdirAll(filepath.Join(skillDir, "resources"), 0755) + os.WriteFile(filepath.Join(skillDir, "SKILL.md"), + []byte("# Skill\n\n[resources](resources)\n"), 0644) + + result, err := ScanSkill(skillDir) + if err != nil { + t.Fatal(err) + } + for _, f := range result.Findings { + if f.Pattern == "dangling-link" { + t.Errorf("unexpected dangling-link finding for valid directory link: %+v", f) + } + } +} + +func TestScanSkill_ExternalLinkSkipped(t *testing.T) { + dir := t.TempDir() + skillDir := filepath.Join(dir, "my-skill") + os.MkdirAll(skillDir, 0755) + os.WriteFile(filepath.Join(skillDir, "SKILL.md"), + []byte("# Skill\n\n[site](https://example.com)\n[mail](mailto:a@b.com)\n"), 0644) + + result, err := ScanSkill(skillDir) + if err != nil { + t.Fatal(err) + } + for _, f := range result.Findings { + if f.Pattern == "dangling-link" { + t.Errorf("unexpected dangling-link finding for external link: %+v", f) + } + } +} + +func TestScanSkill_AnchorLinkSkipped(t *testing.T) { + dir := t.TempDir() + skillDir := filepath.Join(dir, "my-skill") + os.MkdirAll(skillDir, 0755) + os.WriteFile(filepath.Join(skillDir, "SKILL.md"), + []byte("# Skill\n\n[section](#overview)\n"), 0644) + + result, err := ScanSkill(skillDir) + if err != nil { + t.Fatal(err) + } + for _, f := range result.Findings { + if f.Pattern == "dangling-link" { + t.Errorf("unexpected dangling-link finding for anchor link: %+v", f) + } + } +} + +func TestScanSkill_DanglingLink_FragmentStripped(t *testing.T) { + dir := t.TempDir() + skillDir := filepath.Join(dir, "my-skill") + os.MkdirAll(skillDir, 0755) + os.WriteFile(filepath.Join(skillDir, "guide.md"), []byte("# Guide\n## Section"), 0644) + os.WriteFile(filepath.Join(skillDir, "SKILL.md"), + []byte("# Skill\n\n[section](guide.md#section)\n"), 0644) + + result, err := ScanSkill(skillDir) + if err != nil { + t.Fatal(err) + } + for _, f := range result.Findings { + if f.Pattern == "dangling-link" { + t.Errorf("unexpected dangling-link finding for link with fragment: %+v", f) + } + } +} + func TestTruncate(t *testing.T) { if got := truncate("short", 80); got != "short" { t.Errorf("truncate short = %q", got) diff --git a/internal/audit/patterns.go b/internal/audit/patterns.go index 611eccfcf..14c3bdf12 100644 --- a/internal/audit/patterns.go +++ b/internal/audit/patterns.go @@ -335,6 +335,10 @@ rules: # - id: system-writes-0 # enabled: false + # Example: disable the dangling-link structural check + # - id: dangling-link + # enabled: false + # Example: override a built-in rule (match by id, change severity) # - id: destructive-commands-2 # severity: MEDIUM @@ -372,6 +376,43 @@ func ValidateRulesYAML(raw string) error { return err } +// extractDisabledIDs returns the set of rule IDs explicitly disabled +// (enabled: false) in a merged yamlRule slice. +func extractDisabledIDs(yr []yamlRule) map[string]bool { + m := make(map[string]bool) + for _, r := range yr { + if r.Enabled != nil && !*r.Enabled { + m[r.ID] = true + } + } + return m +} + +// disabledIDsGlobal returns IDs disabled in global mode (builtin + global user overrides). +func disabledIDsGlobal() map[string]bool { + base := builtinYAML() + user, err := loadUserRules(globalAuditRulesPath()) + if err != nil || user == nil { + return extractDisabledIDs(base) + } + return extractDisabledIDs(mergeYAMLRules(base, user)) +} + +// disabledIDsForProject returns IDs disabled in project mode +// (builtin + global user + project user overrides). +func disabledIDsForProject(projectRoot string) map[string]bool { + base := builtinYAML() + globalUser, _ := loadUserRules(globalAuditRulesPath()) + if globalUser != nil { + base = mergeYAMLRules(base, globalUser) + } + projectUser, _ := loadUserRules(filepath.Join(projectRoot, ".skillshare", "audit-rules.yaml")) + if projectUser != nil { + base = mergeYAMLRules(base, projectUser) + } + return extractDisabledIDs(base) +} + // resetForTest resets cached state for testing. func resetForTest() { builtinOnce = sync.Once{} diff --git a/skills/skillshare/references/audit.md b/skills/skillshare/references/audit.md index d29ef16ee..d1bc8fcca 100644 --- a/skills/skillshare/references/audit.md +++ b/skills/skillshare/references/audit.md @@ -1,6 +1,6 @@ # Security Audit -Scan skills for prompt injection, data exfiltration, credential access, destructive commands, obfuscation, and suspicious URLs. +Scan skills for prompt injection, data exfiltration, credential access, destructive commands, obfuscation, suspicious URLs, and broken local links. ## Usage @@ -109,9 +109,10 @@ Summary box: | `env-access` | MEDIUM | Environment variable references | Excludes NODE_ENV, npm_* | | `escape-obfuscation` | MEDIUM | 3+ consecutive hex/unicode escapes | — | | `suspicious-fetch` | MEDIUM | URLs used in command context | — | -| `insecure-http` | MEDIUM | HTTP URLs (non-HTTPS) | — | | `system-writes` | MEDIUM | Writes to /etc, /usr, system paths | — | -| `shell-chain` | MEDIUM | Long shell pipe chains | — | +| `insecure-http` | LOW | HTTP URLs (non-HTTPS) | — | +| `dangling-link` | LOW | Broken local markdown links | Skips external/anchor links | +| `shell-chain` | INFO | Long shell pipe chains | — | ## Custom Audit Rules @@ -147,6 +148,10 @@ rules: - id: system-writes-0 enabled: false + # Disable the dangling-link structural check + - id: dangling-link + enabled: false + # Override severity of a built-in rule - id: destructive-commands-2 severity: LOW diff --git a/tests/integration/audit_test.go b/tests/integration/audit_test.go index d712baeb6..9b1489373 100644 --- a/tests/integration/audit_test.go +++ b/tests/integration/audit_test.go @@ -485,6 +485,64 @@ func TestAudit_InitRules_Global(t *testing.T) { result.AssertAnyOutputContains(t, "already exists") } +func TestAudit_DanglingLink_Low(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("link-skill", map[string]string{ + "SKILL.md": "---\nname: link-skill\n---\n# Skill\n\nSee [setup guide](docs/setup.md) for details.", + }) + sb.WriteConfig(`source: ` + sb.SourcePath + "\ntargets: {}\n") + + result := sb.RunCLI("audit", "link-skill") + result.AssertSuccess(t) // LOW does not exceed default CRITICAL threshold + result.AssertAnyOutputContains(t, "broken local link") + result.AssertAnyOutputContains(t, "docs/setup.md") + result.AssertAnyOutputContains(t, "Severity: c/h/m/l/i = 0/0/0/1/0") +} + +func TestAudit_DanglingLink_ValidFileNoFinding(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("link-skill", map[string]string{ + "SKILL.md": "---\nname: link-skill\n---\n# Skill\n\nSee [guide](guide.md) for details.", + "guide.md": "# Guide\nSome content here.", + }) + sb.WriteConfig(`source: ` + sb.SourcePath + "\ntargets: {}\n") + + result := sb.RunCLI("audit", "link-skill") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "No issues found") +} + +func TestAudit_DanglingLink_DisabledByRules(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + + sb.CreateSkill("link-skill", map[string]string{ + "SKILL.md": "---\nname: link-skill\n---\n# Skill\n\n[broken](nonexistent.md)\n", + }) + sb.WriteConfig(`source: ` + sb.SourcePath + "\ntargets: {}\n") + + // Without custom rules, dangling link should be detected + result := sb.RunCLI("audit", "link-skill") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "broken local link") + + // Disable the dangling-link check via global custom rules + configDir := filepath.Dir(sb.ConfigPath) + os.WriteFile(filepath.Join(configDir, "audit-rules.yaml"), []byte(`rules: + - id: dangling-link + enabled: false +`), 0644) + + // Now dangling links should NOT be flagged + result = sb.RunCLI("audit", "link-skill") + result.AssertSuccess(t) + result.AssertAnyOutputContains(t, "No issues found") +} + func TestAudit_InitRules_Project(t *testing.T) { sb := testutil.NewSandbox(t) defer sb.Cleanup() diff --git a/website/docs/commands/audit.md b/website/docs/commands/audit.md index 76604b339..174103c70 100644 --- a/website/docs/commands/audit.md +++ b/website/docs/commands/audit.md @@ -60,7 +60,7 @@ The `audit` command acts as a **gatekeeper** — scanning skill content for know ## What It Detects -The audit engine scans every text-based file in a skill directory against 25 built-in regex rules, organized into 5 severity levels. +The audit engine scans every text-based file in a skill directory against 25 built-in regex rules and structural checks, organized into 5 severity levels. ### CRITICAL (blocks installation and counted as Failed) @@ -107,10 +107,17 @@ These patterns are **suspicious in context** — they may be legitimate but dese These are lower-severity indicators that contribute to risk scoring and reporting: - `LOW`: weaker suspicious patterns (e.g., non-HTTPS URLs in commands — potential for man-in-the-middle attacks) +- `LOW`: **dangling local links** — broken relative markdown links whose target file or directory does not exist on disk - `INFO`: contextual hints like shell chaining patterns (for triage / visibility) > These findings don't block installation but raise the overall risk score. A skill with many LOW/INFO findings may warrant closer inspection. +#### Dangling Link Detection + +The audit engine also performs a **structural check** on `.md` files: it extracts all inline markdown links (`[label](target)`) and verifies that local relative targets exist on disk. External links (`http://`, `https://`, `mailto:`, etc.) and pure anchors (`#section`) are skipped. + +This catches common quality issues like missing referenced files, renamed paths, or incomplete skill packaging. Each broken link produces a `LOW` severity finding with pattern `dangling-link`. + ## Threat Categories Deep Dive ### Prompt Injection @@ -467,6 +474,10 @@ rules: # Disable a built-in rule - id: system-writes-0 enabled: false + + # Disable the dangling-link structural check + - id: dangling-link + enabled: false ``` ### Fields @@ -549,6 +560,10 @@ rules: # - id: system-writes-0 # enabled: false + # Example: disable the dangling-link structural check + # - id: dangling-link + # enabled: false + # Example: override a built-in rule (match by id, change severity) # - id: destructive-commands-2 # severity: MEDIUM @@ -658,6 +673,7 @@ Source of truth (full built-in definitions): | `suspicious-fetch-0` | suspicious-fetch | MEDIUM | | `system-writes-0` | system-writes | MEDIUM | | `insecure-http-0` | insecure-http | LOW | +| `dangling-link` | dangling-link | LOW | | `shell-chain-0` | shell-chain | INFO | ## Options