From 08ecb7afad0d3f90e2efeb0bc167a8ea7ffeca14 Mon Sep 17 00:00:00 2001 From: Willie Date: Fri, 13 Nov 2026 15:14:05 +0800 Subject: [PATCH] fix(audit): report audit-rules load errors and block installs whose audit cannot run (#882) * fix(audit): report audit-rules load errors in global scans The global scan entry points (ScanSkill, ScanSkillWithFollow, ScanSkillFiltered, ScanFile) dropped the error from Rules() and scanned with no pattern rules. One bad regex in the global audit-rules.yaml turned every pattern check off with no warning, so audits reported fewer findings than they should have (#879). Project mode already returned the error. Return the error from the global path as well, and name the failing file in it: parse errors from loadUserRules and compile errors from Rules() and RulesWithProject now carry the path. When a project scan fails to compile, the global file is blamed only if it fails on its own, so a project file that disables a broken global rule still loads. The cached markdown split now takes the rules its caller already loaded instead of loading them again and dropping the error. * fix(install): block installs whose audit cannot run Once global scans return rule-load errors, install treated the error as a warning and installed the skill with no audit at all. update already fails closed on a scan error, and --force there accepts findings, not an install nobody could check. A scan error now blocks skill, agent and tracked-repo installs and removes what was installed. --force does not override it; --skip-audit still bypasses scanning. The error wraps the new install.ErrAuditScanFailed rather than audit.ErrBlocked, so install output and the dashboard do not offer a --force retry that cannot help. upgrade reinstalls the built-in skill with --force, which deleted the old copy before the audit ran. A typo in audit-rules.yaml would have left users without the skill, so upgrade now stages the download through the update path and keeps the installed copy when the audit fails. update --all counted the new error as a silent skip. It is now listed under "Blocked by security audit" with its reason and makes the run exit non-zero. The install warning summary that counted "audit scan error" warnings is removed, since nothing emits them any more. Fixes #879 --- cmd/skillshare/install.go | 2 +- cmd/skillshare/install_audit_render.go | 11 +-- cmd/skillshare/install_warning_output_test.go | 6 +- cmd/skillshare/update_audit_render.go | 5 +- cmd/skillshare/update_handlers.go | 5 +- cmd/skillshare/update_test.go | 10 ++ cmd/skillshare/upgrade.go | 2 + internal/audit/audit_rules_test.go | 99 +++++++++++++++++++ internal/audit/audit_scan_skill.go | 12 ++- internal/audit/markdown_links.go | 9 +- internal/audit/patterns.go | 26 ++++- internal/install/install_audit.go | 26 +++-- internal/install/install_local_test.go | 55 +++++++++++ skills/skillshare/references/audit.md | 2 +- skills/skillshare/references/install.md | 4 +- .../docs/reference/commands/audit-rules.md | 2 + website/docs/reference/commands/audit.md | 2 +- website/docs/reference/commands/install.md | 6 +- .../docs/understand/tracked-repositories.md | 2 +- .../current/reference/commands/audit-rules.md | 2 + .../current/reference/commands/audit.md | 2 +- .../current/reference/commands/install.md | 6 +- .../understand/tracked-repositories.md | 2 +- .../current/reference/commands/audit-rules.md | 2 + .../current/reference/commands/audit.md | 2 +- .../current/reference/commands/install.md | 6 +- .../understand/tracked-repositories.md | 2 +- .../current/reference/commands/audit-rules.md | 2 + .../current/reference/commands/audit.md | 2 +- .../current/reference/commands/install.md | 6 +- .../understand/tracked-repositories.md | 2 +- .../current/reference/commands/audit-rules.md | 2 + .../current/reference/commands/audit.md | 2 +- .../current/reference/commands/install.md | 6 +- .../understand/tracked-repositories.md | 2 +- 35 files changed, 270 insertions(+), 64 deletions(-) diff --git a/cmd/skillshare/install.go b/cmd/skillshare/install.go index f7081651f..633d167c1 100644 --- a/cmd/skillshare/install.go +++ b/cmd/skillshare/install.go @@ -663,7 +663,7 @@ func printInstallHelp() { {"--name ", "Override installed name when exactly one skill is installed"}, {"--kind ", "Restrict discovery/install to skill or agent"}, {"--into ", "Install into subdirectory (e.g. \"frontend\" or \"frontend/react\")"}, - {"-f, --force", "Overwrite existing skill; also continue if audit would block"}, + {"-f, --force", "Overwrite existing skill; also continue if audit findings would block"}, {"-u, --update", "Update existing (git pull if possible, else reinstall)"}, {"-b, --branch ", "Git branch, tag, or commit SHA to install from (default: remote default)"}, {"-t, --track", "Keep a Git checkout for updates; no selection prompt.\nCannot combine with --all, --yes, --skill, or --agent"}, diff --git a/cmd/skillshare/install_audit_render.go b/cmd/skillshare/install_audit_render.go index 4dcb64f17..55936ca3d 100644 --- a/cmd/skillshare/install_audit_render.go +++ b/cmd/skillshare/install_audit_render.go @@ -50,7 +50,6 @@ type batchInstallWarningDigest struct { skillsWithFindings int belowThresholdSkillCount int aboveThresholdSkillCount int - scanErrorSkillCount int skippedAuditSkillCount int highCriticalBySkill map[string]int nonAuditLines []string @@ -128,7 +127,7 @@ func digestInstallWarnings(warnings []string) installWarningDigest { switch { case strings.HasPrefix(warning, "audit findings "): digest.statusLines = append(digest.statusLines, firstWarningLine(warning)) - case strings.HasPrefix(warning, "audit scan error"), strings.HasPrefix(warning, "audit skipped"), strings.HasPrefix(warning, "audit "): + case strings.HasPrefix(warning, "audit skipped"), strings.HasPrefix(warning, "audit "): digest.otherAuditLines = append(digest.otherAuditLines, firstWarningLine(warning)) default: digest.nonAuditLines = append(digest.nonAuditLines, warning) @@ -516,8 +515,6 @@ func summarizeBatchInstallWarnings(results []skillInstallResult) batchInstallWar for _, line := range digest.otherAuditLines { switch { - case strings.HasPrefix(line, "audit scan error"): - summary.scanErrorSkillCount++ case strings.HasPrefix(line, "audit skipped"): summary.skippedAuditSkillCount++ default: @@ -607,9 +604,6 @@ func renderBatchInstallWarningsCompact(results []skillInstallResult, totalWarnin if summary.aboveThresholdSkillCount > 0 { ui.Warning("%s had findings at/above threshold and continued due to --force", plural(summary.aboveThresholdSkillCount, "skill")) } - if summary.scanErrorSkillCount > 0 { - ui.Warning("%s had audit scan errors", plural(summary.scanErrorSkillCount, "skill")) - } if summary.skippedAuditSkillCount > 0 { ui.Warning("%s skipped audit (--skip-audit)", plural(summary.skippedAuditSkillCount, "skill")) } @@ -661,9 +655,6 @@ func renderUltraCompactAuditSummary(results []skillInstallResult, _ int) { if summary.aboveThresholdSkillCount > 0 { statusParts = append(statusParts, fmt.Sprintf("%d above threshold (--force)", summary.aboveThresholdSkillCount)) } - if summary.scanErrorSkillCount > 0 { - statusParts = append(statusParts, fmt.Sprintf("%d scan errors", summary.scanErrorSkillCount)) - } if len(statusParts) > 0 { ui.Warning("%s", strings.Join(statusParts, ", ")) } diff --git a/cmd/skillshare/install_warning_output_test.go b/cmd/skillshare/install_warning_output_test.go index 91f1d417f..3155e6239 100644 --- a/cmd/skillshare/install_warning_output_test.go +++ b/cmd/skillshare/install_warning_output_test.go @@ -18,7 +18,7 @@ func TestDigestInstallWarnings_ClassifiesAuditAndNonAudit(t *testing.T) { "audit HIGH: Python shell execution detected (SKILL.md:10)\n \"subprocess.run(\"", "audit LOW: External URL in markdown link (README.md:4)", "audit findings detected, but none at/above block threshold (CRITICAL)", - "audit scan error: timeout", + "audit skipped (--skip-audit)", "some non-audit warning", } @@ -79,7 +79,6 @@ func TestSummarizeBatchInstallWarnings_AggregatesAcrossSkills(t *testing.T) { warnings: []string{ "audit HIGH: finding-3 (b.md:1)", "audit HIGH: finding-4 (b.md:2)", - "audit scan error: timeout", }, }, { @@ -108,9 +107,6 @@ func TestSummarizeBatchInstallWarnings_AggregatesAcrossSkills(t *testing.T) { if summary.belowThresholdSkillCount != 1 { t.Fatalf("expected belowThresholdSkillCount=1, got %d", summary.belowThresholdSkillCount) } - if summary.scanErrorSkillCount != 1 { - t.Fatalf("expected scanErrorSkillCount=1, got %d", summary.scanErrorSkillCount) - } if summary.skippedAuditSkillCount != 1 { t.Fatalf("expected skippedAuditSkillCount=1, got %d", summary.skippedAuditSkillCount) } diff --git a/cmd/skillshare/update_audit_render.go b/cmd/skillshare/update_audit_render.go index 133af9265..480cce848 100644 --- a/cmd/skillshare/update_audit_render.go +++ b/cmd/skillshare/update_audit_render.go @@ -184,7 +184,7 @@ func displayUpdateBlockedSection(blocked []batchBlockedEntry) { label := blockedSkillLabel(b.name, digest.threshold) ui.StepFail(label, compactBlockedUpdateMessage(b.errMsg)) } - ui.Note("Use --force or --skip-audit to bypass") + ui.Note("Use --force to override findings or --skip-audit to bypass scanning") } // compactBlockedUpdateMessage extracts a compact message from a blocked update error. @@ -199,6 +199,9 @@ func compactBlockedUpdateMessage(errMsg string) string { parts = append(parts, fmt.Sprintf("(%s, %d %s)", digest.threshold, digest.findingCount, suffix)) } else if digest.threshold != "" { parts = append(parts, "("+digest.threshold+")") + } else { + // No findings: the audit itself failed, so show why. + return firstWarningLine(errMsg) } return strings.Join(parts, " ") } diff --git a/cmd/skillshare/update_handlers.go b/cmd/skillshare/update_handlers.go index e6baec405..e7e5fd6a0 100644 --- a/cmd/skillshare/update_handlers.go +++ b/cmd/skillshare/update_handlers.go @@ -436,9 +436,10 @@ func printUpdateRow(mark, name, detail string, took time.Duration) { } // isSecurityError returns true if the error originated from the audit gate. -// All security-related errors wrap audit.ErrBlocked as a sentinel. +// Security-related errors wrap audit.ErrBlocked, or install.ErrAuditScanFailed +// when a reinstall's audit could not run. func isSecurityError(err error) bool { - return errors.Is(err, audit.ErrBlocked) + return errors.Is(err, audit.ErrBlocked) || errors.Is(err, install.ErrAuditScanFailed) } func truncateString(s string, maxLen int) string { return truncateStr(s, maxLen) } diff --git a/cmd/skillshare/update_test.go b/cmd/skillshare/update_test.go index 7fe03b314..9e4ca82ed 100644 --- a/cmd/skillshare/update_test.go +++ b/cmd/skillshare/update_test.go @@ -81,6 +81,9 @@ func TestIsSecurityError(t *testing.T) { // Wrapped sentinel {fmt.Errorf("outer: %w", fmt.Errorf("inner: %w", audit.ErrBlocked)), true}, + // An install audit that could not run blocks the update too + {fmt.Errorf("outer: %w", install.ErrAuditScanFailed), true}, + // Non-sentinel errors with similar text should NOT match {fmt.Errorf("security audit something"), false}, {fmt.Errorf("was rolled back successfully"), false}, @@ -269,3 +272,10 @@ func TestIsGroupDir_UnprefixedCheckoutIsGroup(t *testing.T) { t.Error("a _-prefixed checkout is a tracked repo, not a group") } } + +func TestCompactBlockedUpdateMessage_ShowsScanFailure(t *testing.T) { + msg := "audit scan failed: load rules: bad regex\n\nFix the cause or use --skip-audit to bypass scanning" + if got := compactBlockedUpdateMessage(msg); got != "audit scan failed: load rules: bad regex" { + t.Fatalf("compactBlockedUpdateMessage() = %q", got) + } +} diff --git a/cmd/skillshare/upgrade.go b/cmd/skillshare/upgrade.go index 2fcf08a68..61c01e1a3 100644 --- a/cmd/skillshare/upgrade.go +++ b/cmd/skillshare/upgrade.go @@ -364,8 +364,10 @@ func doSkillDownload(skillshareSkillDir, sourceDir, fromVersion string) error { } source.Name = "skillshare" + // Update stages the download, so a failed audit keeps the installed skill. _, err = install.Install(source, skillshareSkillDir, install.InstallOptions{ Force: true, + Update: true, DryRun: false, }) spinner.Stop() diff --git a/internal/audit/audit_rules_test.go b/internal/audit/audit_rules_test.go index 31cd06e2d..c2bd91e4f 100644 --- a/internal/audit/audit_rules_test.go +++ b/internal/audit/audit_rules_test.go @@ -494,3 +494,102 @@ func TestProjectRules_DisableTierRule(t *testing.T) { t.Error("tier-interpreter-network should be suppressed when disabled in audit-rules.yaml") } } + +const badRegexRules = `rules: + - id: bad-regex + severity: HIGH + pattern: custom + message: "Bad rule" + regex: '[invalid' +` + +func TestGlobalScans_ReturnRulesLoadError(t *testing.T) { + resetForTest() + t.Cleanup(resetForTest) + + tmpDir := t.TempDir() + cfgDir := filepath.Join(tmpDir, "config") + os.MkdirAll(cfgDir, 0755) + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(cfgDir, "config.yaml")) + rulesPath := filepath.Join(cfgDir, "audit-rules.yaml") + os.WriteFile(rulesPath, []byte(badRegexRules), 0644) + + skillDir := filepath.Join(tmpDir, "skill") + os.MkdirAll(skillDir, 0755) + skillFile := filepath.Join(skillDir, "SKILL.md") + os.WriteFile(skillFile, []byte("# Skill\n"), 0644) + + scans := map[string]func() (*Result, error){ + "ScanSkill": func() (*Result, error) { return ScanSkill(skillDir) }, + "ScanSkillFiltered": func() (*Result, error) { return ScanSkillFiltered(skillDir, DefaultRegistry()) }, + "ScanFile": func() (*Result, error) { return ScanFile(skillFile) }, + } + for name, scan := range scans { + t.Run(name, func(t *testing.T) { + result, err := scan() + if err == nil { + t.Fatalf("expected rules-load error, got result %+v", result) + } + if !strings.Contains(err.Error(), rulesPath) || !strings.Contains(err.Error(), "bad-regex") { + t.Errorf("error should name %s and the rule, got: %v", rulesPath, err) + } + }) + } +} + +func TestRulesWithProject_InvalidProjectRuleNamesFile(t *testing.T) { + resetForTest() + t.Cleanup(resetForTest) + + tmpDir := t.TempDir() + cfgDir := filepath.Join(tmpDir, "config") + os.MkdirAll(cfgDir, 0755) + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(cfgDir, "config.yaml")) + projectRoot := filepath.Join(tmpDir, "project") + projectPath := ProjectAuditRulesPath(projectRoot) + os.MkdirAll(filepath.Dir(projectPath), 0755) + os.WriteFile(projectPath, []byte(badRegexRules), 0644) + + _, err := RulesWithProject(projectRoot) + if err == nil || !strings.Contains(err.Error(), projectPath) { + t.Fatalf("error should name %s, got: %v", projectPath, err) + } +} + +func TestRulesWithProject_BadGlobalRule(t *testing.T) { + tests := map[string]struct { + projectRules string + wantErr bool + }{ + "project disables it": {projectRules: "rules:\n - id: bad-regex\n enabled: false\n"}, + "error names global file": {projectRules: "rules:\n - id: other\n enabled: false\n", wantErr: true}, + } + for name, tc := range tests { + t.Run(name, func(t *testing.T) { + resetForTest() + t.Cleanup(resetForTest) + + tmpDir := t.TempDir() + cfgDir := filepath.Join(tmpDir, "config") + os.MkdirAll(cfgDir, 0755) + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(cfgDir, "config.yaml")) + globalPath := filepath.Join(cfgDir, "audit-rules.yaml") + os.WriteFile(globalPath, []byte(badRegexRules), 0644) + projectRoot := filepath.Join(tmpDir, "project") + projectPath := ProjectAuditRulesPath(projectRoot) + os.MkdirAll(filepath.Dir(projectPath), 0755) + os.WriteFile(projectPath, []byte(tc.projectRules), 0644) + + _, err := RulesWithProject(projectRoot) + if !tc.wantErr { + if err != nil { + t.Fatalf("RulesWithProject() error: %v", err) + } + return + } + if err == nil || !strings.Contains(err.Error(), globalPath) { + t.Fatalf("error should name %s, got: %v", globalPath, err) + } + }) + } +} diff --git a/internal/audit/audit_scan_skill.go b/internal/audit/audit_scan_skill.go index 1ad3d9218..a6a8f722a 100644 --- a/internal/audit/audit_scan_skill.go +++ b/internal/audit/audit_scan_skill.go @@ -110,11 +110,12 @@ func scanSkillImpl(skillPath string, activeRules []rule, disabled map[string]boo var mdContentRules, mdLinkRules []rule if resolvedRules == nil { rules, err := Rules() - if err == nil { - resolvedRules = rules + if err != nil { + return nil, fmt.Errorf("load rules: %w", err) } + resolvedRules = rules // Use cached split for global rules. - mdContentRules, mdLinkRules = globalSplitMarkdownLinkRules() + mdContentRules, mdLinkRules = globalSplitMarkdownLinkRules(rules) } else { mdContentRules, mdLinkRules = splitMarkdownLinkRules(resolvedRules) } @@ -615,9 +616,10 @@ func scanFileImpl(filePath string, activeRules []rule, disabled map[string]bool) resolvedRules := activeRules if resolvedRules == nil { rules, err := Rules() - if err == nil { - resolvedRules = rules + if err != nil { + return nil, fmt.Errorf("load rules: %w", err) } + resolvedRules = rules } isMarkdown := strings.EqualFold(filepath.Ext(info.Name()), ".md") diff --git a/internal/audit/markdown_links.go b/internal/audit/markdown_links.go index ff37aafac..4d09a7861 100644 --- a/internal/audit/markdown_links.go +++ b/internal/audit/markdown_links.go @@ -15,13 +15,10 @@ var ( splitGlobalLinkRules []rule ) -// globalSplitMarkdownLinkRules returns the cached split of global rules. -func globalSplitMarkdownLinkRules() (contentRules []rule, linkRules []rule) { +// globalSplitMarkdownLinkRules returns the cached split of the global rules, +// which the caller has already loaded with Rules(). +func globalSplitMarkdownLinkRules(rules []rule) (contentRules []rule, linkRules []rule) { splitGlobalOnce.Do(func() { - rules, err := Rules() - if err != nil { - return - } splitGlobalContentRules, splitGlobalLinkRules = splitMarkdownLinkRules(rules) }) return splitGlobalContentRules, splitGlobalLinkRules diff --git a/internal/audit/patterns.go b/internal/audit/patterns.go index 40ae9ece8..3d1038827 100644 --- a/internal/audit/patterns.go +++ b/internal/audit/patterns.go @@ -191,7 +191,8 @@ func Rules() ([]rule, error) { return } - userYAML, err := loadUserRules(globalAuditRulesPath()) + path := globalAuditRulesPath() + userYAML, err := loadUserRules(path) if err != nil { globalRulesErr = fmt.Errorf("global user rules: %w", err) return @@ -203,7 +204,10 @@ func Rules() ([]rule, error) { } merged := mergeYAMLRules(builtinYAML(), userYAML) - globalRules, globalRulesErr = compileRules(merged) + globalRules, err = compileRules(merged) + if err != nil { + globalRulesErr = fmt.Errorf("global user rules: %s: %w", path, err) + } }) return globalRules, globalRulesErr } @@ -246,7 +250,17 @@ func RulesWithProject(projectRoot string) ([]rule, error) { } merged := mergeYAMLRules(baseYAML, projectYAML) - return compileRules(merged) + rules, err := compileRules(merged) + if err != nil { + // Blame the global file when its rules fail on their own. + if globalUserYAML != nil { + if _, globalErr := Rules(); globalErr != nil { + return nil, globalErr + } + } + return nil, fmt.Errorf("project user rules: %s: %w", projectPath, err) + } + return rules, nil } // builtinYAML returns the parsed (not compiled) builtin rules for merging. @@ -378,7 +392,11 @@ func loadUserRules(path string) ([]yamlRule, error) { } return nil, fmt.Errorf("read %s: %w", path, err) } - return parseRulesYAML(data) + rules, err := parseRulesYAML(data) + if err != nil { + return nil, fmt.Errorf("%s: %w", path, err) + } + return rules, nil } // isPatternLevel returns true when an overlay entry targets all rules diff --git a/internal/install/install_audit.go b/internal/install/install_audit.go index 7ee6bc542..4459e7c0b 100644 --- a/internal/install/install_audit.go +++ b/internal/install/install_audit.go @@ -30,7 +30,8 @@ func checkFollowedCheckoutClean(repoPath string, opts InstallOptions) error { // auditInstalledResource runs the audit gate shared by skill and agent installs. // scan performs the actual scan; cleanupOnBlock removes the installed artifact -// when findings at/above threshold fire and --force is not set. +// when the scan fails, or when findings at/above threshold fire and --force is +// not set. func auditInstalledResource( destPath string, result *InstallResult, @@ -53,9 +54,7 @@ func auditInstalledResource( scanResult, err := scan() if err != nil { - // Non-fatal: warn but don't block - result.Warnings = append(result.Warnings, fmt.Sprintf("audit scan error: %v", err)) - return nil + return scanFailedError(destPath, err, cleanupOnBlock) } result.AuditRiskScore = scanResult.RiskScore result.AuditRiskLabel = scanResult.RiskLabel @@ -107,6 +106,19 @@ func auditInstalledResource( return nil } +// ErrAuditScanFailed marks an install refused because its audit could not run. +var ErrAuditScanFailed = errors.New("audit scan failed") + +// scanFailedError removes an install whose audit could not run. --force does +// not override it: accepting findings is not accepting an unaudited install. +// It does not wrap audit.ErrBlocked, so callers do not offer --force. +func scanFailedError(path string, scanErr error, cleanup func() error) error { + if cleanupErr := cleanup(); cleanupErr != nil { + return fmt.Errorf("%w: %v\n\nAutomatic cleanup failed for %s: %v\nManual removal is required", ErrAuditScanFailed, scanErr, path, cleanupErr) + } + return fmt.Errorf("%w: %w\n\nFix the cause or use --skip-audit to bypass scanning", ErrAuditScanFailed, scanErr) +} + func auditInstalledSkill(destPath string, result *InstallResult, opts InstallOptions) error { scan := func() (*audit.Result, error) { if opts.AuditProjectRoot != "" { @@ -153,7 +165,8 @@ func cleanEmptyInstallParents(path, stopAt string) { // auditTrackedRepo scans an entire tracked repo directory for security threats. // It blocks installation when findings are at or above configured threshold -// unless force is enabled. On block, the repo directory is removed. +// unless force is enabled. On block or a failed scan, the repo directory is +// removed. func auditTrackedRepo(repoPath string, result *TrackedRepoResult, opts InstallOptions) error { if opts.SkipAudit { result.AuditSkipped = true @@ -175,8 +188,7 @@ func auditTrackedRepo(repoPath string, result *TrackedRepoResult, opts InstallOp scanResult, err = audit.ScanSkillWithFollow(repoPath, opts.SourceFollow) } if err != nil { - result.Warnings = append(result.Warnings, fmt.Sprintf("audit scan error: %v", err)) - return nil + return scanFailedError(repoPath, err, func() error { return removeAll(repoPath) }) } result.AuditRiskScore = scanResult.RiskScore result.AuditRiskLabel = scanResult.RiskLabel diff --git a/internal/install/install_local_test.go b/internal/install/install_local_test.go index a360da8f4..447c3adcd 100644 --- a/internal/install/install_local_test.go +++ b/internal/install/install_local_test.go @@ -687,3 +687,58 @@ func TestAuditMessagesExplainLoweredSeverity(t *testing.T) { } } } + +// A scan that cannot run blocks the install even with --force: accepting +// findings is not the same as accepting an unaudited install. +func TestAudit_ScanErrorBlocksAndCleansUp(t *testing.T) { + audits := map[string]func(path string) error{ + "skill": func(path string) error { + return auditInstalledSkill(path, &InstallResult{}, InstallOptions{AuditOverride: true}) + }, + "tracked repo": func(path string) error { + return auditTrackedRepo(path, &TrackedRepoResult{}, InstallOptions{AuditOverride: true}) + }, + } + for name, run := range audits { + t.Run(name, func(t *testing.T) { + tmp := t.TempDir() + cfgDir := filepath.Join(tmp, "config") + os.MkdirAll(cfgDir, 0755) + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(cfgDir, "config.yaml")) + os.WriteFile(filepath.Join(cfgDir, "audit-rules.yaml"), []byte("rules:\n - id: bad-regex\n severity: HIGH\n pattern: custom\n message: bad\n regex: '[invalid'\n"), 0644) + audit.ResetGlobalCache() + t.Cleanup(audit.ResetGlobalCache) + destDir := createLocalSkillSource(t, tmp, "scan-error") + + err := run(destDir) + if !errors.Is(err, ErrAuditScanFailed) || !strings.Contains(err.Error(), "bad-regex") { + t.Fatalf("expected scan error naming the rule, got: %v", err) + } + if _, statErr := os.Stat(destDir); !os.IsNotExist(statErr) { + t.Fatalf("expected %s to be removed, stat error: %v", destDir, statErr) + } + }) + } +} + +// upgrade reinstalls the built-in skill with Force and Update, so a scan +// that cannot run must leave the installed copy in place. +func TestInstall_ForceUpdateScanErrorKeepsExistingSkill(t *testing.T) { + tmp := t.TempDir() + cfgDir := filepath.Join(tmp, "config") + os.MkdirAll(cfgDir, 0755) + t.Setenv("SKILLSHARE_CONFIG", filepath.Join(cfgDir, "config.yaml")) + os.WriteFile(filepath.Join(cfgDir, "audit-rules.yaml"), []byte("rules:\n - id: bad-regex\n severity: HIGH\n pattern: custom\n message: bad\n regex: '[invalid'\n"), 0644) + audit.ResetGlobalCache() + t.Cleanup(audit.ResetGlobalCache) + srcDir := createLocalSkillSource(t, tmp, "builtin") + destDir := createLocalSkillSource(t, filepath.Join(tmp, "skills"), "builtin") + source := &Source{Type: SourceTypeLocalPath, Raw: srcDir, Path: srcDir, Name: "builtin"} + + if _, err := Install(source, destDir, InstallOptions{Force: true, Update: true}); err == nil { + t.Fatal("expected scan error") + } + if _, err := os.Stat(filepath.Join(destDir, "SKILL.md")); err != nil { + t.Fatalf("existing skill should remain: %v", err) + } +} diff --git a/skills/skillshare/references/audit.md b/skills/skillshare/references/audit.md index a5a1ba84b..8601aa8dc 100644 --- a/skills/skillshare/references/audit.md +++ b/skills/skillshare/references/audit.md @@ -151,7 +151,7 @@ skillshare audit --init-rules # Global: ~/.config/skillshare/audit-rules.y skillshare audit --init-rules -p # Project: .skillshare/audit-rules.yaml ``` -Three-layer merge (later overrides earlier): built-in → global → project. Set `confidence` from 0 to 1 by rule ID or pattern; rules without a value default to 0.95. The HIGH prose patterns `anti-refusal`, `prompt-leakage`, `memory-poisoning`, `agent-snooping`, and `persistence` detect narrowly phrased risky directives. +Three-layer merge (later overrides earlier): built-in → global → project. A rules file that cannot be read, parsed, or compiled makes every scan using it a scan error that names the file. Set `confidence` from 0 to 1 by rule ID or pattern; rules without a value default to 0.95. The HIGH prose patterns `anti-refusal`, `prompt-leakage`, `memory-poisoning`, `agent-snooping`, and `persistence` detect narrowly phrased risky directives. ```yaml rules: diff --git a/skills/skillshare/references/install.md b/skills/skillshare/references/install.md index 96255aaa7..e578a9826 100644 --- a/skills/skillshare/references/install.md +++ b/skills/skillshare/references/install.md @@ -132,7 +132,7 @@ or `--kind agent` to choose which resource to manage. | `--kind ` | Restrict resource discovery | | `--agent, -a ` | Select agents by name (comma-separated) | | `--branch, -b ` | Select a Git branch, tag or commit SHA (overrides a ref in a web URL) | -| `--force, -f` | Overwrite existing and explicitly override audit blocking | +| `--force, -f` | Overwrite existing and explicitly override audit blocking from findings (not a failed scan) | | `--update, -u` | Update if exists | | `--track, -t` | Track for updates (preserves .git); a local path works if it is a git repository. Rejects `--all`, `--yes`, `--skill`, and `--agent` | | `--skill, -s ` | Select specific skills from multi-skill repo (comma-separated). Rejects `--track`, `--all`, and `--yes` | @@ -162,7 +162,7 @@ Tracked custom names must not contain path separators (`/`, `\`) or `..`. **License display:** If a SKILL.md has a `license` frontmatter field, it's shown in selection prompts (e.g., `my-skill (MIT)`) and in the single-skill confirmation box. -**Security audit:** Install auto-scans skills after download. Blocking follows the active threshold (default `CRITICAL`), while aggregate risk is reported separately for context. Use `--force` to override blocking, `--skip-audit` to skip scanning, or `--audit-threshold` / `--threshold` / `-T` to override threshold per command. +**Security audit:** Install auto-scans skills after download. Blocking follows the active threshold (default `CRITICAL`), while aggregate risk is reported separately for context. Use `--force` to override blocking, `--skip-audit` to skip scanning, or `--audit-threshold` / `--threshold` / `-T` to override threshold per command. A scan that cannot run (for example, an invalid `audit-rules.yaml`) blocks the install, and `--force` does not override it. **Private repos (HTTPS):** Provider tokens are sent only over HTTPS on the default port (or 443): `github.com`, `gitlab.com`, `bitbucket.org`, `dev.azure.com`, `*.visualstudio.com`, `gitea.com`, and `cnb.cool`. Self-hosted Gitea/CNB requires an exact hostname in `gitea_hosts`/`cnb_hosts`, even if its name contains the provider name. For self-hosted GitHub/GitLab or other hosts, use a host-scoped Git credential helper, or set `SKILLSHARE_GIT_TOKEN` only for the intended invocation. That generic fallback can be sent to **any HTTPS source**; provider-looking names do not authorize provider tokens. SSH and host-scoped Git credential helpers work as usual. diff --git a/website/docs/reference/commands/audit-rules.md b/website/docs/reference/commands/audit-rules.md index 85383f1c6..1c609c5b0 100644 --- a/website/docs/reference/commands/audit-rules.md +++ b/website/docs/reference/commands/audit-rules.md @@ -269,6 +269,8 @@ skillshare audit # Check a specific skill skillshare audit --json | jq '.skills[].findings' # Inspect findings programmatically ``` +If a rules file cannot be read, parsed, or compiled (for example, an invalid regex), every scan that uses it reports a scan error naming the file, and `audit` exits `2`. Installs are blocked until you fix the file. + Summary interpretation: - `Failed` counts skills with findings at or above the active threshold. diff --git a/website/docs/reference/commands/audit.md b/website/docs/reference/commands/audit.md index 7adc24523..6e3e1afe1 100644 --- a/website/docs/reference/commands/audit.md +++ b/website/docs/reference/commands/audit.md @@ -210,7 +210,7 @@ skillshare install /path/to/skill --skip-audit # Bypasses scanning (use with caution) ``` -`--force` overrides block decisions. `--skip-audit` disables scanning for that install command. +`--force` overrides block decisions from findings; a scan that cannot run still blocks. `--skip-audit` disables scanning for that install command. There is no config flag to globally disable install-time audit. Use `--skip-audit` only for commands where you intentionally want to bypass scanning. diff --git a/website/docs/reference/commands/install.md b/website/docs/reference/commands/install.md index 9b42ccc88..a7edd3851 100644 --- a/website/docs/reference/commands/install.md +++ b/website/docs/reference/commands/install.md @@ -293,7 +293,7 @@ See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. |------|-------|-------------| | `--name ` | | Override installed name when exactly one skill is installed | | `--into ` | | Install into subdirectory (e.g. `--into frontend` or `--into frontend/react`) | -| `--force` | `-f` | Overwrite existing skill; override audit blocking and cross-path duplicate check | +| `--force` | `-f` | Overwrite existing skill; override audit blocking from findings (not a failed scan) and cross-path duplicate check | | `--update` | `-u` | Update if exists (git pull or reinstall) | | `--branch ` | `-b` | Git branch, tag, or commit SHA to install from (default: remote default branch) | | `--track` | `-t` | Keep `.git` for tracked repos. Cannot combine with `--all`, `--yes`, `--skill`, or `--agent`. | @@ -625,6 +625,7 @@ install-skills: Every skill is automatically scanned for security threats during installation: - Findings at or above `audit.block_threshold` **block installation** (default: `CRITICAL`) +- If the scan cannot run (for example, `audit-rules.yaml` has an invalid regex), the install is blocked and removed. `--force` does not override this; fix the cause or use `--skip-audit` - Lower findings are shown as warnings and include risk score context - `audit.block_threshold` only controls block level; it does **not** disable scanning - There is no config switch to always skip audit; use `--skip-audit` per command when needed @@ -654,7 +655,7 @@ skillshare install suspicious-skill --threshold high skillshare install suspicious-skill -T h ``` -Use `--force` to override block decisions, or `--skip-audit` to bypass scanning entirely. See [audit](/docs/reference/commands/audit) for scanning details. +Use `--force` to override block decisions from findings, or `--skip-audit` to bypass scanning entirely. See [audit](/docs/reference/commands/audit) for scanning details. The install decision uses **finding severity vs threshold**. Risk score/label is reported for context and does not by itself block installs. By default, audit findings are shown as a compact summary (grouped by severity and message). Use `--audit-verbose` to see the full list. @@ -664,6 +665,7 @@ Tracked repos use the same threshold model, but the scan scope and failure handl - Fresh `--track` install scans the **entire cloned repository** (not just one skill folder) - Findings at/above threshold block install unless `--force` is used +- A scan that cannot run also blocks install, even with `--force` - On blocked fresh install, skillshare automatically removes the cloned repo from source - If automatic cleanup fails, install returns an explicit error and tells you to remove the path manually diff --git a/website/docs/understand/tracked-repositories.md b/website/docs/understand/tracked-repositories.md index 65a02fe53..eccb6a7ae 100644 --- a/website/docs/understand/tracked-repositories.md +++ b/website/docs/understand/tracked-repositories.md @@ -52,7 +52,7 @@ skillshare sync 4. Entire repo is security-audited using active install threshold (`audit.block_threshold` or `--threshold`) 5. Nested skills are flattened for AI CLIs -If findings hit the threshold, install is blocked unless `--force` is used. On block, skillshare removes the cloned repo automatically; if cleanup fails, the command reports the exact path for manual cleanup. +If findings hit the threshold, install is blocked unless `--force` is used. A scan that cannot run also blocks it, even with `--force`. On block, skillshare removes the cloned repo automatically; if cleanup fails, the command reports the exact path for manual cleanup. --- diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md index f4d34c5a5..dcadb5357 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md @@ -269,6 +269,8 @@ skillshare audit # 特定の Skill をチェック skillshare audit --json | jq '.skills[].findings' # findings をプログラムから確認 ``` +ルールファイルを読み込み・解析・コンパイルできない場合(例えば無効な正規表現)、そのファイルを使うすべてのスキャンがファイル名を示すスキャンエラーを報告し、`audit` は `2` で終了します。ファイルを修正するまでインストールはブロックされます。 + サマリーの解釈: - `Failed` は、有効な閾値以上の findings を持つ Skill を数える。 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit.md index 579149a7b..c85e84706 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/audit.md @@ -210,7 +210,7 @@ skillshare install /path/to/skill --skip-audit # スキャンをバイパスする(注意して使用) ``` -`--force` はブロックの判定を上書きします。`--skip-audit` は、そのインストールコマンドに対するスキャンを無効化します。 +`--force` は検出結果によるブロックの判定を上書きします。スキャンを実行できない場合はブロックされたままです。`--skip-audit` は、そのインストールコマンドに対するスキャンを無効化します。 install 時の audit をグローバルに無効化する config フラグはありません。意図的にスキャンをバイパスしたいコマンドに限って `--skip-audit` を使用してください。 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md index 74da405f8..26c459bcb 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -287,7 +287,7 @@ skillshare sync |------|-------|-------------| | `--name ` | | インストールされる Skill がちょうど 1 つの場合、インストール名を上書き | | `--into ` | | サブディレクトリへインストール(例: `--into frontend` または `--into frontend/react`) | -| `--force` | `-f` | 既存の Skill を上書き。監査によるブロックとクロスパス重複チェックを無視 | +| `--force` | `-f` | 既存の Skill を上書き。監査の検出結果によるブロック(スキャン失敗は除く)とクロスパス重複チェックを無視 | | `--update` | `-u` | 存在する場合は更新(git pull または再インストール) | | `--branch ` | `-b` | インストール元の git ブランチ、タグ、または commit SHA(デフォルト: リモートのデフォルトブランチ) | | `--track` | `-t` | トラック対象リポジトリとして `.git` を保持。`--all`、`--yes`、`--skill`、`--agent` との併用は拒否されます。 | @@ -617,6 +617,7 @@ install-skills: すべての Skill は、インストール時に自動的にセキュリティ脅威をスキャンされます。 - `audit.block_threshold` 以上の検出結果は **インストールをブロック** します(デフォルト: `CRITICAL`) +- スキャンを実行できない場合(例えば `audit-rules.yaml` に無効な正規表現がある)、インストールはブロックされ削除されます。`--force` では上書きできません。原因を修正するか `--skip-audit` を使用してください - それより低い検出結果は警告として表示され、リスクスコアのコンテキストも含まれます - `audit.block_threshold` はブロックのレベルのみを制御し、スキャン自体を無効化するものでは **ありません** - 常時 audit をスキップする config スイッチはありません。必要な場合はコマンドごとに `--skip-audit` を使用してください @@ -646,7 +647,7 @@ skillshare install suspicious-skill --threshold high skillshare install suspicious-skill -T h ``` -ブロック判定を上書きするには `--force`、スキャンを完全にバイパスするには `--skip-audit` を使用します。スキャンの詳細は [audit](/docs/reference/commands/audit) を参照してください。 +検出結果によるブロック判定を上書きするには `--force`、スキャンを完全にバイパスするには `--skip-audit` を使用します。スキャンの詳細は [audit](/docs/reference/commands/audit) を参照してください。 インストールの判定は **検出結果の重大度 vs 閾値** で行われます。リスクスコア/ラベルは参考情報として報告されるだけで、それ単体でインストールをブロックすることはありません。デフォルトでは、監査結果は(重大度とメッセージでグルーピングされた)コンパクトな要約として表示されます。完全なリストを見るには `--audit-verbose` を使用してください。 @@ -656,6 +657,7 @@ skillshare install suspicious-skill -T h - 新規の `--track` インストールでは、(1 つの Skill フォルダだけでなく)**クローンされたリポジトリ全体** がスキャンされます - 閾値以上の検出結果があると、`--force` を使わない限りインストールをブロックします +- スキャンを実行できない場合も、`--force` を使ってもインストールをブロックします - 新規インストールがブロックされた場合、skillshare はクローンしたリポジトリをソースから自動的に削除します - 自動クリーンアップが失敗した場合、install は明示的なエラーを返し、パスを手動で削除するよう案内します diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index 37d99f2c0..4aac24f27 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -52,7 +52,7 @@ skillshare sync 4. リポジトリ全体が、有効なインストールしきい値(`audit.block_threshold` または `--threshold`)を使ってセキュリティ監査されます 5. ネストされた Skill は AI CLI 向けにフラット化されます -検出結果がしきい値に達した場合、`--force` を使わない限りインストールはブロックされます。ブロックされた場合、skillshare はクローンされたリポジトリを自動的に削除します。クリーンアップに失敗した場合は、手動でクリーンアップするための正確なパスがコマンドから報告されます。 +検出結果がしきい値に達した場合、`--force` を使わない限りインストールはブロックされます。スキャンを実行できない場合も、`--force` を使ってもブロックされます。ブロックされた場合、skillshare はクローンされたリポジトリを自動的に削除します。クリーンアップに失敗した場合は、手動でクリーンアップするための正確なパスがコマンドから報告されます。 --- diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md index 8e38dabdf..92306c6fc 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md @@ -269,6 +269,8 @@ skillshare audit # 특정 skill 확인 skillshare audit --json | jq '.skills[].findings' # findings를 프로그래밍 방식으로 검사 ``` +규칙 파일을 읽거나 파싱하거나 컴파일할 수 없으면(예: 잘못된 정규식), 그 파일을 사용하는 모든 스캔이 파일 경로를 포함한 스캔 오류를 보고하고 `audit`는 `2`로 종료합니다. 파일을 고칠 때까지 설치는 차단됩니다. + 요약 해석: - `Failed`는 활성 threshold 이상의 findings가 있는 skill 수입니다. diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit.md index 8809b936a..6d0d7a11c 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/audit.md @@ -210,7 +210,7 @@ skillshare install /path/to/skill --skip-audit # 스캔 우회 (주의해서 사용) ``` -`--force`는 차단 결정을 무시합니다. `--skip-audit`는 해당 install 명령에 대한 스캔을 비활성화합니다. +`--force`는 findings로 인한 차단 결정을 무시합니다. 스캔을 실행할 수 없으면 계속 차단됩니다. `--skip-audit`는 해당 install 명령에 대한 스캔을 비활성화합니다. 설치 시점 audit를 전역적으로 비활성화하는 config 플래그는 없습니다. 의도적으로 스캔을 우회하려는 명령에서만 `--skip-audit`를 사용하십시오. diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md index 10bce2c77..be41770ac 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -287,7 +287,7 @@ skillshare sync |------|-------|-------------| | `--name ` | | 정확히 하나의 skill이 설치될 때 설치된 이름을 재정의 | | `--into ` | | 하위 디렉터리에 설치 (예: `--into frontend` 또는 `--into frontend/react`) | -| `--force` | `-f` | 기존 skill을 덮어쓰기; audit 차단 및 cross-path 중복 검사를 재정의 | +| `--force` | `-f` | 기존 skill을 덮어쓰기; audit findings 차단(스캔 실패 제외) 및 cross-path 중복 검사를 재정의 | | `--update` | `-u` | 존재하면 업데이트 (git pull 또는 재설치) | | `--branch ` | `-b` | 설치할 git branch, tag 또는 commit SHA (기본값: remote 기본 브랜치) | | `--track` | `-t` | tracked repo용으로 `.git`을 유지. `--all`, `--yes`, `--skill`, `--agent`와 함께 사용할 수 없습니다. | @@ -617,6 +617,7 @@ install-skills: 모든 skill은 설치 중에 보안 위협에 대해 자동으로 스캔됩니다. - `audit.block_threshold` 이상의 findings는 **설치를 차단합니다** (기본값: `CRITICAL`) +- 스캔을 실행할 수 없으면(예: `audit-rules.yaml`에 잘못된 정규식이 있음) 설치가 차단되고 제거됩니다. `--force`로는 무시할 수 없으니 원인을 고치거나 `--skip-audit`을 사용하세요 - 그보다 낮은 findings는 경고로 표시되며 위험 점수 컨텍스트를 포함합니다 - `audit.block_threshold`는 차단 레벨만 제어합니다; 스캔 자체를 비활성화하지는 **않습니다** - audit을 항상 건너뛰는 config 스위치는 없습니다; 필요할 때는 명령별로 `--skip-audit`을 사용하세요 @@ -646,7 +647,7 @@ skillshare install suspicious-skill --threshold high skillshare install suspicious-skill -T h ``` -차단 결정을 재정의하려면 `--force`를, 스캔 자체를 우회하려면 `--skip-audit`을 사용하세요. 스캐닝에 대한 자세한 내용은 [audit](/docs/reference/commands/audit)을 참고하세요. +findings로 인한 차단 결정을 재정의하려면 `--force`를, 스캔 자체를 우회하려면 `--skip-audit`을 사용하세요. 스캐닝에 대한 자세한 내용은 [audit](/docs/reference/commands/audit)을 참고하세요. install 결정은 **finding severity vs threshold**를 기준으로 합니다. Risk score/label은 컨텍스트로 보고될 뿐 그 자체로 설치를 차단하지 않습니다. 기본적으로 audit findings는 (severity와 메시지로 그룹화된) 요약으로 표시됩니다. 전체 목록을 보려면 `--audit-verbose`를 사용하세요. @@ -656,6 +657,7 @@ Tracked repo는 동일한 threshold 모델을 사용하지만, 스캔 범위와 - 신규 `--track` 설치는 (skill 폴더 하나가 아니라) **clone된 repository 전체**를 스캔합니다 - threshold 이상의 findings는 `--force`가 사용되지 않는 한 설치를 차단합니다 +- 스캔을 실행할 수 없는 경우에도 `--force`와 관계없이 설치를 차단합니다 - 신규 설치가 차단되면, skillshare는 source에서 clone된 repo를 자동으로 제거합니다 - 자동 정리가 실패하면, install은 명시적인 오류를 반환하고 경로를 수동으로 제거하라고 안내합니다 diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index abfb8b4f1..d6635a4aa 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -52,7 +52,7 @@ skillshare sync 4. 활성 install 임계값(`audit.block_threshold` 또는 `--threshold`)을 사용해 전체 repo가 보안 감사됨 5. AI CLI를 위해 중첩된 skill이 평탄화됨 -발견 사항이 임계값에 도달하면 `--force`를 사용하지 않는 한 설치가 차단됩니다. 차단 시 skillshare는 clone된 repo를 자동으로 제거합니다. 정리에 실패하면 수동 정리를 위한 정확한 경로를 명령이 보고합니다. +발견 사항이 임계값에 도달하면 `--force`를 사용하지 않는 한 설치가 차단됩니다. 스캔을 실행할 수 없는 경우에도 `--force`와 관계없이 차단됩니다. 차단 시 skillshare는 clone된 repo를 자동으로 제거합니다. 정리에 실패하면 수동 정리를 위한 정확한 경로를 명령이 보고합니다. --- diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md index 2b5826b53..78e5973d1 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md @@ -269,6 +269,8 @@ skillshare audit # Check a specific skill skillshare audit --json | jq '.skills[].findings' # Inspect findings programmatically ``` +如果规则文件无法读取、解析或编译(例如正则表达式无效),使用它的每次扫描都会报告指明该文件的扫描错误,`audit` 以 `2` 退出。修正该文件之前,安装会被拦截。 + 摘要解读: - `Failed` 统计的是发现结果达到或超过当前阈值的 skills 数量。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit.md index a63aa5839..10484e32a 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/audit.md @@ -210,7 +210,7 @@ skillshare install /path/to/skill --skip-audit # Bypasses scanning (use with caution) ``` -`--force` 会覆盖阻断决策。`--skip-audit` 会为该 install 命令禁用扫描。 +`--force` 会覆盖由发现项造成的阻断决策;扫描无法运行时仍会阻断。`--skip-audit` 会为该 install 命令禁用扫描。 没有可以全局禁用安装时 audit 的配置项。请仅在你确实需要绕过扫描的命令中使用 `--skip-audit`。 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md index beaa72eb4..8e59f2c1c 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -287,7 +287,7 @@ skillshare sync |------|-------|-------------| | `--name ` | | 当只安装了恰好一个 Skill 时,覆盖安装后的名称 | | `--into ` | | 安装到子目录中(例如 `--into frontend` 或 `--into frontend/react`) | -| `--force` | `-f` | 覆盖已存在的 Skill;跳过 audit 拦截和跨路径重复检测 | +| `--force` | `-f` | 覆盖已存在的 Skill;跳过 audit 发现项拦截(扫描失败除外)和跨路径重复检测 | | `--update` | `-u` | 如果已存在则更新(git pull 或重新安装) | | `--branch ` | `-b` | 要安装的 git branch、tag 或 commit SHA(默认:远程默认分支) | | `--track` | `-t` | 为 tracked repo 保留 `.git`。不能与 `--all`、`--yes`、`--skill` 或 `--agent` 同时使用。 | @@ -617,6 +617,7 @@ install-skills: 每个 Skill 在安装期间都会自动扫描安全威胁: - 达到或超过 `audit.block_threshold` 的发现项会**阻止安装**(默认:`CRITICAL`) +- 如果扫描无法运行(例如 `audit-rules.yaml` 含有无效的正则表达式),安装会被拦截并移除。`--force` 无法覆盖;请修正原因或使用 `--skip-audit` - 较低级别的发现项会以警告形式显示,并附带风险评分上下文 - `audit.block_threshold` 只控制拦截级别;它**不会**禁用扫描本身 - 没有可以永久跳过 audit 的配置开关;需要时请对单条命令使用 `--skip-audit` @@ -646,7 +647,7 @@ skillshare install suspicious-skill --threshold high skillshare install suspicious-skill -T h ``` -使用 `--force` 覆盖拦截判定,或使用 `--skip-audit` 完全绕过扫描。扫描细节参见 [audit](/docs/reference/commands/audit)。 +使用 `--force` 覆盖由发现项造成的拦截判定,或使用 `--skip-audit` 完全绕过扫描。扫描细节参见 [audit](/docs/reference/commands/audit)。 安装判定使用的是**发现项严重级别 vs 阈值**。风险评分/标签仅作为上下文提供参考,本身并不会阻止安装。默认情况下,audit 发现项会以精简摘要形式显示(按严重级别和消息分组)。使用 `--audit-verbose` 可查看完整列表。 @@ -656,6 +657,7 @@ Tracked repo 使用相同的阈值模型,但扫描范围和失败处理更加 - 首次 `--track` 安装会扫描**整个克隆下来的仓库**(而不仅仅是某一个 Skill 文件夹) - 达到/超过阈值的发现项会阻止安装,除非使用了 `--force` +- 扫描无法运行时同样会阻止安装,即使使用了 `--force` - 首次安装被阻止时,skillshare 会自动从 source 中移除已克隆的仓库 - 如果自动清理失败,install 会返回明确的错误,并提示你手动移除该路径 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index d15121943..69cf7a40a 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -52,7 +52,7 @@ skillshare sync 4. 使用当前 install 阈值(`audit.block_threshold` 或 `--threshold`)对整个仓库进行安全审计 5. 嵌套 Skill 会为 AI CLI 扁平化处理 -如果发现的问题达到阈值,安装会被阻止,除非使用 `--force`。被阻止时,skillshare 会自动移除已克隆的仓库;若清理失败,命令会报告确切路径以便手动清理。 +如果发现的问题达到阈值,安装会被阻止,除非使用 `--force`。扫描无法运行时同样会被阻止,即使使用了 `--force`。被阻止时,skillshare 会自动移除已克隆的仓库;若清理失败,命令会报告确切路径以便手动清理。 --- diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md index 9902bb524..21b8a0df7 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit-rules.md @@ -269,6 +269,8 @@ skillshare audit # Check a specific skill skillshare audit --json | jq '.skills[].findings' # Inspect findings programmatically ``` +如果規則檔無法讀取、解析或編譯(例如 regex 無效),使用它的每次掃描都會回報指出該檔案的掃描錯誤,`audit` 以 `2` 結束。修正該檔案前,安裝會被阻擋。 + 摘要解讀: - `Failed` 計算的是發現項目達到或超過目前門檻的 skills。 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit.md index ed0961fa0..3d9d2c435 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/audit.md @@ -210,7 +210,7 @@ skillshare install /path/to/skill --skip-audit # Bypasses scanning (use with caution) ``` -`--force` 會覆蓋阻擋決策。`--skip-audit` 會停用該次安裝指令的掃描。 +`--force` 會覆蓋由發現項目造成的阻擋決策;掃描無法執行時仍會阻擋。`--skip-audit` 會停用該次安裝指令的掃描。 沒有任何 config flag 可以全域停用安裝時的 audit。請只在你確實想略過掃描的指令上使用 `--skip-audit`。 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md index 3d27ac8c9..7cc892798 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -287,7 +287,7 @@ skillshare sync |------|-------|-------------| | `--name ` | | 只安裝一個 skill 時覆寫其安裝名稱 | | `--into ` | | 安裝到子目錄中(例如 `--into frontend` 或 `--into frontend/react`) | -| `--force` | `-f` | 覆蓋既有 skill;略過 audit 阻擋與跨路徑重複檢查 | +| `--force` | `-f` | 覆蓋既有 skill;略過 audit 發現項目的阻擋(掃描失敗除外)與跨路徑重複檢查 | | `--update` | `-u` | 若已存在則更新(git pull 或重新安裝) | | `--branch ` | `-b` | 要安裝的 git branch、tag 或 commit SHA(預設:remote 的預設分支) | | `--track` | `-t` | 保留 tracked repos 的 `.git`。不能與 `--all`、`--yes`、`--skill` 或 `--agent` 同時使用。 | @@ -617,6 +617,7 @@ install-skills: 每個 skill 在安裝時都會自動掃描安全威脅: - 達到或超過 `audit.block_threshold` 的發現會**阻擋安裝**(預設:`CRITICAL`) +- 如果掃描無法執行(例如 `audit-rules.yaml` 含有無效的 regex),安裝會被阻擋並移除。`--force` 無法覆寫;請修正原因或使用 `--skip-audit` - 較低等級的發現會以警告顯示,並包含風險分數的說明 - `audit.block_threshold` 只控制阻擋等級;它**不會**停用掃描 - 沒有設定開關能永久跳過 audit;需要時請針對單次指令使用 `--skip-audit` @@ -646,7 +647,7 @@ skillshare install suspicious-skill --threshold high skillshare install suspicious-skill -T h ``` -用 `--force` 覆寫阻擋決定,或用 `--skip-audit` 完全略過掃描。掃描細節見 [audit](/docs/reference/commands/audit)。 +用 `--force` 覆寫由發現項目造成的阻擋決定,或用 `--skip-audit` 完全略過掃描。掃描細節見 [audit](/docs/reference/commands/audit)。 Install 的決定使用**發現的嚴重程度 vs 門檻**。風險分數/標籤僅作為情境參考,本身不會阻擋安裝。預設情況下,audit 的發現會以精簡摘要顯示(依嚴重程度與訊息分組)。用 `--audit-verbose` 可查看完整清單。 @@ -656,6 +657,7 @@ Tracked repos 使用相同的門檻模型,但掃描範圍與失敗處理更嚴 - 全新的 `--track` 安裝會掃描**整個 clone 的 repository**(而不只是一個 skill 資料夾) - 達到或超過門檻的發現會阻擋安裝,除非使用 `--force` +- 掃描無法執行時同樣會阻擋安裝,即使使用 `--force` - 若全新安裝被阻擋,skillshare 會自動從 source 中移除已 clone 的 repo - 若自動清理失敗,install 會回傳明確錯誤,並告知你需要手動移除該路徑 diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md index 788cb7766..3829c2e4b 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/understand/tracked-repositories.md @@ -52,7 +52,7 @@ skillshare sync 4. 整個 repo 會用當前生效的安裝門檻(`audit.block_threshold` 或 `--threshold`)進行安全稽核 5. 巢狀 skills 會被扁平化,供 AI CLI 使用 -若發現項目達到門檻,安裝會被封鎖,除非使用 `--force`。被封鎖時,skillshare 會自動移除已 clone 的 repo;若清理失敗,指令會回報確切路徑供手動清理。 +若發現項目達到門檻,安裝會被封鎖,除非使用 `--force`。掃描無法執行時同樣會被封鎖,即使使用 `--force`。被封鎖時,skillshare 會自動移除已 clone 的 repo;若清理失敗,指令會回報確切路徑供手動清理。 ---