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.
This commit is contained in:
Willie
2026-02-21 21:12:51 +08:00
parent 8e58cc7383
commit cea26ea7fb
6 changed files with 338 additions and 6 deletions
+93 -2
View File
@@ -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
}
+121
View File
@@ -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)
+41
View File
@@ -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{}
+8 -3
View File
@@ -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
+58
View File
@@ -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()
+17 -1
View File
@@ -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