mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
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:
+93
-2
@@ -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
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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{}
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user