Files
skillshare/internal/install/install_audit.go
T
Willie 08ecb7afad 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
2026-11-13 15:14:05 +08:00

557 lines
19 KiB
Go

package install
import (
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"skillshare/internal/audit"
"skillshare/internal/sourcewalk"
)
// Audit rollback resets the whole checkout, so followed user repositories
// must be clean before pulling even when their edits do not conflict upstream.
func checkFollowedCheckoutClean(repoPath string, opts InstallOptions) error {
checkout, followed := opts.SourceFollow.Resolve(repoPath)
if !followed {
return nil
}
status, err := gitOutput(checkout, "status", "--porcelain")
if err != nil {
return fmt.Errorf("cannot check Git status of followed checkout %s; resolve the status error and commit or stash changes before updating: %w", checkout, err)
}
if status != "" {
return fmt.Errorf("uncommitted changes in followed checkout %s: commit or stash them before updating", checkout)
}
return nil
}
// auditInstalledResource runs the audit gate shared by skill and agent installs.
// scan performs the actual scan; cleanupOnBlock removes the installed artifact
// when the scan fails, or when findings at/above threshold fire and --force is
// not set.
func auditInstalledResource(
destPath string,
result *InstallResult,
opts InstallOptions,
scan func() (*audit.Result, error),
cleanupOnBlock func() error,
) error {
if opts.SkipAudit {
result.AuditSkipped = true
result.AuditThreshold = opts.AuditThreshold
result.Warnings = append(result.Warnings, "audit skipped (--skip-audit)")
return nil
}
threshold, err := audit.NormalizeThreshold(opts.AuditThreshold)
if err != nil {
threshold = audit.DefaultThreshold()
}
result.AuditThreshold = threshold
scanResult, err := scan()
if err != nil {
return scanFailedError(destPath, err, cleanupOnBlock)
}
result.AuditRiskScore = scanResult.RiskScore
result.AuditRiskLabel = scanResult.RiskLabel
if result.AuditRiskLabel == "" && len(scanResult.Findings) == 0 {
result.AuditRiskLabel = "CLEAN"
}
scanResult.Threshold = threshold
acceptRoot, acceptPath := opts.auditAcceptTarget(destPath)
ApplyAcceptedFindings(acceptRoot, acceptPath, scanResult)
scanResult.IsBlocked = scanResult.HasSeverityAtOrAbove(threshold)
if len(scanResult.Findings) == 0 {
return nil
}
for _, f := range scanResult.Findings {
result.Warnings = append(result.Warnings, auditFindingWarning(f))
}
if scanResult.IsBlocked && !opts.AuditOverride {
details := blockedFindingDetails(scanResult.Findings, threshold)
if cleanupErr := cleanupOnBlock(); cleanupErr != nil {
return fmt.Errorf(
"security audit failed — findings at/above %s detected:\n%s\n\nAutomatic cleanup failed for %s: %v\nManual removal is required: %w",
threshold,
strings.Join(details, "\n"),
destPath,
cleanupErr,
audit.ErrBlocked,
)
}
return fmt.Errorf(
"security audit failed — findings at/above %s detected:\n%s\n\nUse --force to override or --skip-audit to bypass scanning: %w",
threshold,
strings.Join(details, "\n"),
audit.ErrBlocked,
)
}
if scanResult.IsBlocked && opts.AuditOverride {
result.Warnings = append(result.Warnings,
fmt.Sprintf("audit findings at/above block threshold (%s); proceeding due to --force", threshold))
result.Warnings = append(result.Warnings, recordAcceptedWarning(acceptRoot, acceptPath, scanResult, threshold)...)
} else if !scanResult.IsBlocked {
result.Warnings = append(result.Warnings,
fmt.Sprintf("audit findings detected, but none at/above block threshold (%s)", threshold))
}
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 != "" {
return audit.ScanSkillForProject(destPath, opts.AuditProjectRoot, opts.SourceFollow)
}
return audit.ScanSkillWithFollow(destPath, opts.SourceFollow)
}
cleanup := func() error { return removeAll(destPath) }
return auditInstalledResource(destPath, result, opts, scan, cleanup)
}
func auditInstalledAgent(destFile string, result *InstallResult, opts InstallOptions) error {
scan := func() (*audit.Result, error) {
if opts.AuditProjectRoot != "" {
return audit.ScanFileForProject(destFile, opts.AuditProjectRoot)
}
return audit.ScanFile(destFile)
}
// Agents are single .md files. After removing the file, walk up any
// newly-empty parent directories (e.g. into-subdir) so a blocked install
// leaves nothing behind.
cleanup := func() error {
if err := removeAll(destFile); err != nil {
return err
}
cleanEmptyInstallParents(destFile, opts.SourceDir)
return nil
}
return auditInstalledResource(destFile, result, opts, scan, cleanup)
}
func cleanEmptyInstallParents(path, stopAt string) {
stopAt = filepath.Clean(stopAt)
dir := filepath.Dir(filepath.Clean(path))
for dir != stopAt && dir != "." && dir != "/" {
entries, err := os.ReadDir(dir)
if err != nil || len(entries) > 0 {
break
}
_ = os.Remove(dir)
dir = filepath.Dir(dir)
}
}
// 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 or a failed scan, the repo directory is
// removed.
func auditTrackedRepo(repoPath string, result *TrackedRepoResult, opts InstallOptions) error {
if opts.SkipAudit {
result.AuditSkipped = true
result.AuditThreshold = opts.AuditThreshold
result.Warnings = append(result.Warnings, "audit skipped (--skip-audit)")
return nil
}
threshold, err := audit.NormalizeThreshold(opts.AuditThreshold)
if err != nil {
threshold = audit.DefaultThreshold()
}
result.AuditThreshold = threshold
var scanResult *audit.Result
if opts.AuditProjectRoot != "" {
scanResult, err = audit.ScanSkillForProject(repoPath, opts.AuditProjectRoot, opts.SourceFollow)
} else {
scanResult, err = audit.ScanSkillWithFollow(repoPath, opts.SourceFollow)
}
if err != nil {
return scanFailedError(repoPath, err, func() error { return removeAll(repoPath) })
}
result.AuditRiskScore = scanResult.RiskScore
result.AuditRiskLabel = scanResult.RiskLabel
if result.AuditRiskLabel == "" && len(scanResult.Findings) == 0 {
result.AuditRiskLabel = "CLEAN"
}
scanResult.Threshold = threshold
acceptRoot, acceptPath := opts.auditAcceptTarget(repoPath)
ApplyAcceptedFindings(acceptRoot, acceptPath, scanResult)
scanResult.IsBlocked = scanResult.HasSeverityAtOrAbove(threshold)
if len(scanResult.Findings) == 0 {
return nil
}
for _, f := range scanResult.Findings {
result.Warnings = append(result.Warnings, auditFindingWarning(f))
}
if scanResult.IsBlocked && !opts.AuditOverride {
details := blockedFindingDetails(scanResult.Findings, threshold)
if removeErr := removeAll(repoPath); removeErr != nil {
return fmt.Errorf(
"security audit failed — findings at/above %s detected in tracked repository:\n%s\n\nAutomatic cleanup failed for %s: %v\nManual removal is required: %w",
threshold,
strings.Join(details, "\n"),
repoPath,
removeErr,
audit.ErrBlocked,
)
}
return fmt.Errorf(
"security audit failed — findings at/above %s detected in tracked repository:\n%s\n\nUse --force to override or --skip-audit to bypass scanning: %w",
threshold,
strings.Join(details, "\n"),
audit.ErrBlocked,
)
}
if scanResult.IsBlocked && opts.AuditOverride {
result.Warnings = append(result.Warnings,
fmt.Sprintf("audit findings at/above block threshold (%s); proceeding due to --force", threshold))
result.Warnings = append(result.Warnings, recordAcceptedWarning(acceptRoot, acceptPath, scanResult, threshold)...)
} else if !scanResult.IsBlocked {
result.Warnings = append(result.Warnings,
fmt.Sprintf("audit findings detected, but none at/above block threshold (%s)", threshold))
}
return nil
}
// RollbackState says what the audit gate did to the checkout when it blocked.
type RollbackState int
const (
// RolledBack means the checkout is back at the pre-pull commit.
RolledBack RollbackState = iota
// RollbackUnavailable means no pre-pull commit was known.
RollbackUnavailable
// RollbackFailed means the reset failed and pulled content may remain.
RollbackFailed
// CheckoutUnchanged means only an isolated candidate was changed.
CheckoutUnchanged
)
// AuditGate is the fail-closed audit of a git checkout that has just been
// pulled. A candidate is discarded on block; a live checkout is reset.
type AuditGate struct {
SourceDir string // root the accepted findings are stored under
RepoPath string
AcceptPath string // path the accepted findings are keyed on; RepoPath when empty
BeforeHash string // pre-pull commit; without it nothing is let through
Candidate bool // isolated checkout: rejection must not reset the live repo
Threshold string
ProjectRoot string // non-empty scans with the project's audit rules
Follow *sourcewalk.Follow
// Override lets findings at/above the threshold through (--force). A scan
// that could not run stays blocked: "I accept these findings" is not the
// same as "I could not be told any".
Override bool
// Confirm is asked once when findings would block and Override is unset.
// Nil, false or an error blocks.
Confirm func(*AuditGateResult) (bool, error)
}
// AuditGateResult is what the scan found. It is also returned next to an
// *AuditGateError when findings blocked.
type AuditGateResult struct {
Audit *audit.Result
Threshold string // normalized
AcceptedSkipped int // findings an earlier override accepted
Overridden bool // blocking findings were let through
}
// AuditGateError reports a blocked update. It wraps audit.ErrBlocked.
type AuditGateError struct {
ScanErr error // the scan could not run; nil when findings blocked
Threshold string
BeforeHash string
Rollback RollbackState
ResetErr error // set when Rollback is RollbackFailed
}
// RollbackNote describes the state of the checkout after the block.
func (e *AuditGateError) RollbackNote() string {
switch e.Rollback {
case CheckoutUnchanged:
return "candidate rejected; checkout unchanged"
case RollbackUnavailable:
return "rollback commit unavailable, update aborted and repository state is unknown"
case RollbackFailed:
return fmt.Sprintf("WARNING: rollback also failed: %v — malicious content may remain", e.ResetErr)
}
return "rolled back"
}
func (e *AuditGateError) Error() string {
return e.message("security audit failed") + ": " + audit.ErrBlocked.Error()
}
// message words the block starting with subject, e.g. "security audit failed".
func (e *AuditGateError) message(subject string) string {
head := fmt.Sprintf("%s — findings at/above %s detected", subject, e.Threshold)
if e.ScanErr != nil {
head = fmt.Sprintf("%s: %v", subject, e.ScanErr)
}
switch e.Rollback {
case CheckoutUnchanged:
return head + " — " + e.RollbackNote() + " (use --skip-audit to bypass)"
case RollbackUnavailable:
return subject + " — " + e.RollbackNote()
case RollbackFailed:
return head + "; " + e.RollbackNote()
}
return head + " — rolled back (use --skip-audit to bypass)"
}
func (e *AuditGateError) Unwrap() error { return audit.ErrBlocked }
// Run scans the checkout and decides whether the pulled content stays.
func (g AuditGate) Run() (*AuditGateResult, error) {
threshold, err := audit.NormalizeThreshold(g.Threshold)
if err != nil {
threshold = audit.DefaultThreshold()
}
if g.BeforeHash == "" {
return nil, &AuditGateError{Threshold: threshold, Rollback: RollbackUnavailable}
}
acceptPath := g.AcceptPath
if acceptPath == "" {
acceptPath = g.RepoPath
}
if g.Candidate {
if err := prepareCandidateAudit(g.SourceDir, acceptPath, g.RepoPath); err != nil {
return nil, g.block(&AuditGateError{ScanErr: err, Threshold: threshold})
}
}
var scanResult *audit.Result
if g.ProjectRoot != "" {
scanResult, err = audit.ScanSkillForProject(g.RepoPath, g.ProjectRoot, g.Follow)
} else {
scanResult, err = audit.ScanSkillWithFollow(g.RepoPath, g.Follow)
}
if err != nil {
return nil, g.block(&AuditGateError{ScanErr: err, Threshold: threshold})
}
res := &AuditGateResult{Audit: scanResult, Threshold: threshold}
res.AcceptedSkipped = ApplyAcceptedFindings(g.SourceDir, acceptPath, scanResult)
if !scanResult.HasSeverityAtOrAbove(threshold) {
return res, nil
}
if g.Override {
res.Overridden = true
return res, nil
}
var confirmErr error
if g.Confirm != nil {
ok, err := g.Confirm(res)
if err == nil && ok {
res.Overridden = true
return res, nil
}
confirmErr = err
}
blocked := g.block(&AuditGateError{Threshold: threshold})
if confirmErr != nil {
return res, fmt.Errorf("%w (confirmation failed: %v)", blocked, confirmErr)
}
return res, blocked
}
// block rejects a candidate or resets a live checkout, and records the outcome.
func (g AuditGate) block(e *AuditGateError) *AuditGateError {
e.BeforeHash = g.BeforeHash
if g.Candidate {
e.Rollback = CheckoutUnchanged
return e
}
if err := gitResetHard(g.RepoPath, g.BeforeHash); err != nil {
e.Rollback, e.ResetErr = RollbackFailed, err
}
return e
}
// blockedDetailsError lists the blocked findings and names the override flags.
func blockedDetailsError(e *AuditGateError, res *AuditGateResult, subject string) error {
note := "rolled back to " + shortHash(e.BeforeHash)
if e.Rollback == CheckoutUnchanged {
note = e.RollbackNote()
}
return fmt.Errorf(
"%s (%s):\n%s\n\nUse --force to override or --skip-audit to bypass scanning: %w",
subject,
note,
strings.Join(blockedFindingDetails(res.Audit.Findings, e.Threshold), "\n"),
audit.ErrBlocked,
)
}
// auditGateFailClosed gates a pulled non-tracked skill checkout (update and
// relock). The dashboard reads "post-update audit failed" as "force will not
// help", so this wording stays separate from AuditGateError's.
func auditGateFailClosed(sourceDir, repoPath, beforeHash, threshold, projectRoot string, auditOverride bool, follow ...*sourcewalk.Follow) (*audit.Result, error) {
gate := AuditGate{
SourceDir: sourceDir,
RepoPath: repoPath,
BeforeHash: beforeHash,
Threshold: threshold,
ProjectRoot: projectRoot,
Override: auditOverride,
}
if len(follow) > 0 {
gate.Follow = follow[0]
}
res, err := gate.Run()
var blocked *AuditGateError
switch {
case err == nil:
return res.Audit, nil
case !errors.As(err, &blocked):
return nil, err
case blocked.ScanErr != nil || blocked.Rollback == RollbackUnavailable:
return nil, fmt.Errorf("%s: %w", blocked.message("post-update audit failed"), audit.ErrBlocked)
case blocked.Rollback == RolledBack:
return nil, blockedDetailsError(blocked, res,
fmt.Sprintf("post-update audit failed — findings at/above %s detected", blocked.Threshold))
}
return nil, fmt.Errorf("post-update audit found findings at/above %s; %s: %w", blocked.Threshold, blocked.RollbackNote(), audit.ErrBlocked)
}
// auditTrackedRepoUpdate audits an isolated candidate and publishes only its
// approved revision. Accepted findings are recorded only after publication.
func auditTrackedRepoUpdate(candidate *GitUpdateCandidate, result *TrackedRepoResult, opts InstallOptions) error {
repoPath, beforeHash := candidate.Path, candidate.BeforeHash
revision, err := getGitFullHash(repoPath)
if err != nil {
return err
}
if opts.SkipAudit {
result.AuditSkipped = true
result.AuditThreshold = opts.AuditThreshold
result.Warnings = append(result.Warnings, "audit skipped (--skip-audit)")
return candidate.Publish(revision)
}
if opts.OnProgress != nil {
opts.OnProgress("Auditing update candidate...")
}
acceptRoot, acceptPath := opts.auditAcceptTarget(candidate.repoPath)
res, err := AuditGate{
SourceDir: acceptRoot,
RepoPath: repoPath,
AcceptPath: acceptPath,
BeforeHash: beforeHash,
Candidate: true,
Threshold: opts.AuditThreshold,
ProjectRoot: opts.AuditProjectRoot,
Follow: opts.SourceFollow,
Override: opts.AuditOverride,
}.Run()
if err != nil {
var blocked *AuditGateError
// The CLI reads "tracked repository" from these to word its summary.
if errors.As(err, &blocked) && blocked.ScanErr == nil && blocked.Rollback == CheckoutUnchanged {
return blockedDetailsError(blocked, res,
fmt.Sprintf("security audit failed — findings at/above %s detected in tracked repository", blocked.Threshold))
}
return err
}
if err := candidate.Publish(revision); err != nil {
return fmt.Errorf("failed to publish audited update: %w", err)
}
threshold, scanResult := res.Threshold, res.Audit
result.AuditThreshold = threshold
result.AuditRiskScore = scanResult.RiskScore
result.AuditRiskLabel = scanResult.RiskLabel
if result.AuditRiskLabel == "" && len(scanResult.Findings) == 0 {
result.AuditRiskLabel = "CLEAN"
}
if len(scanResult.Findings) == 0 {
return nil
}
for _, f := range scanResult.Findings {
result.Warnings = append(result.Warnings, auditFindingWarning(f))
}
if res.Overridden {
result.Warnings = append(result.Warnings,
fmt.Sprintf("audit findings at/above block threshold (%s); proceeding due to --force", threshold))
result.Warnings = append(result.Warnings, recordAcceptedWarning(acceptRoot, acceptPath, scanResult, threshold)...)
} else {
result.Warnings = append(result.Warnings,
fmt.Sprintf("audit findings detected, but none at/above block threshold (%s)", threshold))
}
return nil
}
// recordAcceptedWarning persists the findings a --force override just accepted
// and returns a warning line describing the outcome.
func recordAcceptedWarning(sourceDir, path string, res *audit.Result, threshold string) []string {
n, err := RecordAcceptedFindings(sourceDir, path, res, threshold)
if err != nil {
return []string{fmt.Sprintf("failed to record accepted findings: %v", err)}
}
if n == 0 {
return nil
}
return []string{fmt.Sprintf("recorded %d accepted finding(s); future updates won't block on them", n)}
}
// auditFindingWarning formats one finding as an install warning.
func auditFindingWarning(f audit.Finding) string {
msg := fmt.Sprintf("audit %s: %s (%s:%d)", f.Severity, f.ExplainedMessage(), f.File, f.Line)
if f.Acknowledged {
msg += " (accepted earlier)"
}
if f.Snippet != "" {
msg += fmt.Sprintf("\n %q", f.Snippet)
}
return msg
}
func blockedFindingDetails(findings []audit.Finding, threshold string) []string {
var details []string
for _, f := range findings {
if f.Acknowledged {
continue
}
if audit.SeverityRank(f.Severity) <= audit.SeverityRank(threshold) {
detail := fmt.Sprintf(" %s: %s (%s:%d)", f.Severity, f.ExplainedMessage(), f.File, f.Line)
if f.Snippet != "" {
detail += fmt.Sprintf("\n %q", f.Snippet)
}
details = append(details, detail)
}
}
return details
}
// isGitInstalled checks if git command is available