diff --git a/cmd/skillshare/audit.go b/cmd/skillshare/audit.go index 4c291fb39..344edb6d6 100644 --- a/cmd/skillshare/audit.go +++ b/cmd/skillshare/audit.go @@ -37,8 +37,9 @@ type auditOptions struct { Yes bool NoTUI bool Threshold string - Profile string // --profile: default/strict/permissive - Dedupe string // --dedupe: legacy/global + Profile string // --profile: default/strict/permissive + Dedupe string // --dedupe: legacy/global + Analyzers []string // --analyzer: repeatable allowlist } // isStructured returns true if the output format is machine-readable (json/sarif/markdown). @@ -72,6 +73,7 @@ type auditRunSummary struct { AvgAnalyzability float64 `json:"avgAnalyzability"` PolicyProfile string `json:"policyProfile,omitempty"` PolicyDedupe string `json:"policyDedupe,omitempty"` + PolicyAnalyzers []string `json:"policyAnalyzers,omitempty"` } func (s auditRunSummary) toMarkdownOptions() audit.MarkdownOptions { @@ -163,6 +165,7 @@ func cmdAudit(args []string) error { defaultThreshold string configProfile string configDedupe string + configAnalyzers []string cfgPath string ) @@ -185,6 +188,7 @@ func cmdAudit(args []string) error { defaultThreshold = rt.config.Audit.BlockThreshold configProfile = rt.config.Audit.Profile configDedupe = rt.config.Audit.DedupeMode + configAnalyzers = rt.config.Audit.EnabledAnalyzers cfgPath = config.ProjectConfigPath(cwd) } else { cfg, err := config.Load() @@ -195,18 +199,22 @@ func cmdAudit(args []string) error { defaultThreshold = cfg.Audit.BlockThreshold configProfile = cfg.Audit.Profile configDedupe = cfg.Audit.DedupeMode + configAnalyzers = cfg.Audit.EnabledAnalyzers cfgPath = config.ConfigPath() } policy := audit.ResolvePolicy(audit.PolicyInputs{ - Profile: opts.Profile, - Threshold: opts.Threshold, - Dedupe: opts.Dedupe, - ConfigProfile: configProfile, - ConfigThreshold: defaultThreshold, - ConfigDedupe: configDedupe, + Profile: opts.Profile, + Threshold: opts.Threshold, + Dedupe: opts.Dedupe, + EnabledAnalyzers: opts.Analyzers, + ConfigProfile: configProfile, + ConfigThreshold: defaultThreshold, + ConfigDedupe: configDedupe, + ConfigAnalyzers: configAnalyzers, }) threshold := policy.Threshold + registry := audit.DefaultRegistry().ForPolicy(policy) var ( results []*audit.Result @@ -218,13 +226,13 @@ func cmdAudit(args []string) error { switch { case !hasTargets: - results, summary, err = auditInstalled(sourcePath, modeString(mode), projectRoot, threshold, opts) + results, summary, err = auditInstalled(sourcePath, modeString(mode), projectRoot, threshold, opts, registry) case isSinglePath: - results, summary, err = auditPath(opts.Targets[0], modeString(mode), projectRoot, threshold, opts.Format) + results, summary, err = auditPath(opts.Targets[0], modeString(mode), projectRoot, threshold, opts.Format, registry) case isSingleName: - results, summary, err = auditSkillByName(sourcePath, opts.Targets[0], modeString(mode), projectRoot, threshold, opts.Format) + results, summary, err = auditSkillByName(sourcePath, opts.Targets[0], modeString(mode), projectRoot, threshold, opts.Format, registry) default: - results, summary, err = auditFiltered(sourcePath, opts.Targets, opts.Groups, modeString(mode), projectRoot, threshold, opts) + results, summary, err = auditFiltered(sourcePath, opts.Targets, opts.Groups, modeString(mode), projectRoot, threshold, opts, registry) } if err != nil { logAuditOp(cfgPath, rest, summary, start, err, false) @@ -244,6 +252,7 @@ func cmdAudit(args []string) error { summary.PolicyProfile = string(policy.Profile) summary.PolicyDedupe = string(policy.DedupeMode) + summary.PolicyAnalyzers = policy.EnabledAnalyzers blocked := summary.Failed > 0 logAuditOp(cfgPath, rest, summary, start, nil, blocked) @@ -356,6 +365,17 @@ func parseAuditArgs(args []string) (auditOptions, bool, error) { default: return opts, false, fmt.Errorf("unknown dedupe mode: %s (supported: legacy, global)", args[i]) } + case "--analyzer": + if i+1 >= len(args) { + return opts, false, fmt.Errorf("%s requires a value (static, dataflow, tier, integrity, structure, cross-skill)", arg) + } + i++ + switch args[i] { + case "static", "dataflow", "tier", "integrity", "structure", "cross-skill": + opts.Analyzers = append(opts.Analyzers, args[i]) + default: + return opts, false, fmt.Errorf("unknown analyzer: %s (supported: static, dataflow, tier, integrity, structure, cross-skill)", args[i]) + } default: if strings.HasPrefix(arg, "-") { return opts, false, fmt.Errorf("unknown option: %s", arg) @@ -449,7 +469,17 @@ func resolveSkillPath(sourcePath, name string) string { return "" } -func scanSkillPath(skillPath, projectRoot string) (*audit.Result, error) { +func scanSkillPath(skillPath, projectRoot string, reg ...*audit.Registry) (*audit.Result, error) { + var registry *audit.Registry + if len(reg) > 0 { + registry = reg[0] + } + if registry != nil { + if projectRoot != "" { + return audit.ScanSkillFilteredForProject(skillPath, projectRoot, registry) + } + return audit.ScanSkillFiltered(skillPath, registry) + } if projectRoot != "" { return audit.ScanSkillForProject(skillPath, projectRoot) } @@ -467,13 +497,13 @@ func toAuditInputs(skills []struct { return inputs } -func scanPathTarget(targetPath, projectRoot string) (*audit.Result, error) { +func scanPathTarget(targetPath, projectRoot string, reg ...*audit.Registry) (*audit.Result, error) { info, err := os.Stat(targetPath) if err != nil { return nil, err } if info.IsDir() { - return scanSkillPath(targetPath, projectRoot) + return scanSkillPath(targetPath, projectRoot, reg...) } if projectRoot != "" { return audit.ScanFileForProject(targetPath, projectRoot) @@ -481,7 +511,7 @@ func scanPathTarget(targetPath, projectRoot string) (*audit.Result, error) { return audit.ScanFile(targetPath) } -func auditInstalled(sourcePath, mode, projectRoot, threshold string, opts auditOptions) ([]*audit.Result, auditRunSummary, error) { +func auditInstalled(sourcePath, mode, projectRoot, threshold string, opts auditOptions, reg *audit.Registry) ([]*audit.Result, auditRunSummary, error) { jsonOutput := opts.isStructured() base := auditRunSummary{ Scope: "all", @@ -531,7 +561,7 @@ func auditInstalled(sourcePath, mode, projectRoot, threshold string, opts auditO onDone := func() { progressBar.Increment() } - scanResults := audit.ParallelScan(toAuditInputs(skillPaths), projectRoot, onDone) + scanResults := audit.ParallelScan(toAuditInputs(skillPaths), projectRoot, onDone, reg) progressBar.Stop() if !jsonOutput { fmt.Println() @@ -578,7 +608,7 @@ func auditInstalled(sourcePath, mode, projectRoot, threshold string, opts auditO return results, summary, nil } -func auditFiltered(sourcePath string, names, groups []string, mode, projectRoot, threshold string, opts auditOptions) ([]*audit.Result, auditRunSummary, error) { +func auditFiltered(sourcePath string, names, groups []string, mode, projectRoot, threshold string, opts auditOptions, reg *audit.Registry) ([]*audit.Result, auditRunSummary, error) { jsonOutput := opts.isStructured() base := auditRunSummary{ Scope: "filtered", @@ -663,7 +693,7 @@ func auditFiltered(sourcePath string, names, groups []string, mode, projectRoot, onDone := func() { progressBar.Increment() } - scanResults := audit.ParallelScan(toAuditInputs(matched), projectRoot, onDone) + scanResults := audit.ParallelScan(toAuditInputs(matched), projectRoot, onDone, reg) progressBar.Stop() if !jsonOutput { fmt.Println() @@ -709,7 +739,7 @@ func auditFiltered(sourcePath string, names, groups []string, mode, projectRoot, return results, summary, nil } -func auditSkillByName(sourcePath, name, mode, projectRoot, threshold, format string) ([]*audit.Result, auditRunSummary, error) { +func auditSkillByName(sourcePath, name, mode, projectRoot, threshold, format string, reg *audit.Registry) ([]*audit.Result, auditRunSummary, error) { summary := auditRunSummary{ Scope: "single", Skill: name, @@ -728,7 +758,7 @@ func auditSkillByName(sourcePath, name, mode, projectRoot, threshold, format str } start := time.Now() - result, err := scanSkillPath(skillPath, projectRoot) + result, err := scanSkillPath(skillPath, projectRoot, reg) if err != nil { return nil, summary, fmt.Errorf("scan error: %w", err) } @@ -755,7 +785,7 @@ func auditSkillByName(sourcePath, name, mode, projectRoot, threshold, format str return []*audit.Result{result}, summary, nil } -func auditPath(rawPath, mode, projectRoot, threshold, format string) ([]*audit.Result, auditRunSummary, error) { +func auditPath(rawPath, mode, projectRoot, threshold, format string, reg *audit.Registry) ([]*audit.Result, auditRunSummary, error) { absPath, err := filepath.Abs(rawPath) if err != nil { absPath = rawPath @@ -769,7 +799,7 @@ func auditPath(rawPath, mode, projectRoot, threshold, format string) ([]*audit.R } start := time.Now() - result, err := scanPathTarget(absPath, projectRoot) + result, err := scanPathTarget(absPath, projectRoot, reg) if err != nil { return nil, summary, fmt.Errorf("scan error: %w", err) } @@ -1206,6 +1236,8 @@ Options: (also supports c|h|m|l|i) --profile

Audit profile preset: default, strict, permissive --dedupe Dedup mode: legacy (default), global + --analyzer Only run specified analyzer (repeatable) + IDs: static, dataflow, tier, integrity, structure, cross-skill --format Output format: text (default), json, sarif, markdown --json Output JSON (deprecated: use --format json) --quiet, -q Only show skills with findings + summary (skip clean ✓ lines) diff --git a/cmd/skillshare/audit_project.go b/cmd/skillshare/audit_project.go index 04bc5fba8..1eac56a4a 100644 --- a/cmd/skillshare/audit_project.go +++ b/cmd/skillshare/audit_project.go @@ -22,10 +22,10 @@ func cmdAuditProject(root, specificSkill string) (auditRunSummary, bool, error) } if specificSkill != "" { - _, summary, err := auditSkillByName(rt.sourcePath, specificSkill, "project", root, threshold, formatText) + _, summary, err := auditSkillByName(rt.sourcePath, specificSkill, "project", root, threshold, formatText, nil) return summary, summary.Failed > 0, err } - _, summary, err := auditInstalled(rt.sourcePath, "project", root, threshold, auditOptions{}) + _, summary, err := auditInstalled(rt.sourcePath, "project", root, threshold, auditOptions{}, nil) return summary, summary.Failed > 0, err } diff --git a/internal/audit/parallel.go b/internal/audit/parallel.go index 1f7fc62b5..26dbff0bc 100644 --- a/internal/audit/parallel.go +++ b/internal/audit/parallel.go @@ -36,12 +36,17 @@ type ScanOutput struct { // projectRoot being empty means global mode; non-empty means project mode. // onDone is called after each skill finishes (nil-safe); use it to drive a progress bar. // Returns []ScanOutput aligned by index with the input slice. -func ParallelScan(skills []SkillInput, projectRoot string, onDone func()) []ScanOutput { +func ParallelScan(skills []SkillInput, projectRoot string, onDone func(), reg ...*Registry) []ScanOutput { outputs := make([]ScanOutput, len(skills)) if len(skills) == 0 { return outputs } + var registry *Registry + if len(reg) > 0 { + registry = reg[0] + } + sem := make(chan struct{}, workerCount()) var wg sync.WaitGroup @@ -54,10 +59,18 @@ func ParallelScan(skills []SkillInput, projectRoot string, onDone func()) []Scan start := time.Now() var res *Result var err error - if projectRoot != "" { - res, err = ScanSkillForProject(path, projectRoot) + if registry != nil { + if projectRoot != "" { + res, err = ScanSkillFilteredForProject(path, projectRoot, registry) + } else { + res, err = ScanSkillFiltered(path, registry) + } } else { - res, err = ScanSkill(path) + if projectRoot != "" { + res, err = ScanSkillForProject(path, projectRoot) + } else { + res, err = ScanSkill(path) + } } outputs[idx] = ScanOutput{ Result: res, diff --git a/internal/config/config.go b/internal/config/config.go index cbd7c6519..cc6434b34 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -21,9 +21,10 @@ type TargetConfig struct { // AuditConfig holds security audit policy settings. type AuditConfig struct { - BlockThreshold string `yaml:"block_threshold,omitempty"` // CRITICAL/HIGH/MEDIUM/LOW/INFO - Profile string `yaml:"profile,omitempty"` // default/strict/permissive - DedupeMode string `yaml:"dedupe_mode,omitempty"` // legacy/global + BlockThreshold string `yaml:"block_threshold,omitempty"` // CRITICAL/HIGH/MEDIUM/LOW/INFO + Profile string `yaml:"profile,omitempty"` // default/strict/permissive + DedupeMode string `yaml:"dedupe_mode,omitempty"` // legacy/global + EnabledAnalyzers []string `yaml:"enabled_analyzers,omitempty"` // allowlist; empty = all } // LogConfig holds log retention settings. diff --git a/internal/server/handler_audit.go b/internal/server/handler_audit.go index 1aaf68df7..af9c17856 100644 --- a/internal/server/handler_audit.go +++ b/internal/server/handler_audit.go @@ -356,6 +356,7 @@ func (s *Server) auditPolicy() audit.Policy { in.ConfigThreshold = s.cfg.Audit.BlockThreshold in.ConfigProfile = s.cfg.Audit.Profile in.ConfigDedupe = s.cfg.Audit.DedupeMode + in.ConfigAnalyzers = s.cfg.Audit.EnabledAnalyzers if s.IsProjectMode() && s.projectCfg != nil { if s.projectCfg.Audit.BlockThreshold != "" { in.ConfigThreshold = s.projectCfg.Audit.BlockThreshold @@ -366,6 +367,9 @@ func (s *Server) auditPolicy() audit.Policy { if s.projectCfg.Audit.DedupeMode != "" { in.ConfigDedupe = s.projectCfg.Audit.DedupeMode } + if len(s.projectCfg.Audit.EnabledAnalyzers) > 0 { + in.ConfigAnalyzers = s.projectCfg.Audit.EnabledAnalyzers + } } return audit.ResolvePolicy(in) } diff --git a/schemas/config.schema.json b/schemas/config.schema.json index 2bfd29634..65a873b5e 100644 --- a/schemas/config.schema.json +++ b/schemas/config.schema.json @@ -102,6 +102,15 @@ "description": "Finding deduplication mode. 'legacy' keeps existing behavior; 'global' applies full composite-key deduplication.", "enum": ["legacy", "global"], "default": "legacy" + }, + "enabled_analyzers": { + "type": "array", + "description": "Analyzer allowlist. Only listed analyzers will run. Empty or omitted means all analyzers are enabled.", + "items": { + "type": "string", + "enum": ["static", "dataflow", "tier", "integrity", "structure", "cross-skill"] + }, + "uniqueItems": true } } }, diff --git a/schemas/project-config.schema.json b/schemas/project-config.schema.json index d84748e23..39f1e3b41 100644 --- a/schemas/project-config.schema.json +++ b/schemas/project-config.schema.json @@ -93,6 +93,15 @@ "description": "Finding deduplication mode. 'legacy' keeps existing behavior; 'global' applies full composite-key deduplication.", "enum": ["legacy", "global"], "default": "legacy" + }, + "enabled_analyzers": { + "type": "array", + "description": "Analyzer allowlist. Only listed analyzers will run. Empty or omitted means all analyzers are enabled.", + "items": { + "type": "string", + "enum": ["static", "dataflow", "tier", "integrity", "structure", "cross-skill"] + }, + "uniqueItems": true } } }, diff --git a/website/docs/reference/commands/audit.md b/website/docs/reference/commands/audit.md index ba947ea71..5b35bf831 100644 --- a/website/docs/reference/commands/audit.md +++ b/website/docs/reference/commands/audit.md @@ -22,6 +22,10 @@ skillshare audit -p # Scan project skills skillshare audit --quiet # Only show skills with findings skillshare audit --yes # Skip large-scan confirmation skillshare audit --no-tui # Plain text output (no interactive TUI) +skillshare audit --profile strict # Use strict profile (block on HIGH+) +skillshare audit --dedupe global # Full composite-key deduplication +skillshare audit --analyzer static # Run only the static analyzer +skillshare audit --analyzer static --analyzer dataflow # Multiple analyzers ``` ## Why Security Scanning Matters @@ -486,6 +490,74 @@ The TUI activates automatically when all conditions are met: interactive termina When scanning more than 1,000 skills in an interactive terminal, the command prompts for confirmation before proceeding. Use `--yes` to skip this prompt in TTY environments (e.g., local automation scripts). In CI/CD pipelines (non-TTY), the prompt is automatically skipped. +## Policy & Profiles + +The audit command supports **policy-driven** configuration through profiles, deduplication modes, and analyzer selection. These can be set via CLI flags, project config, or global config. + +### Profiles + +Profiles are presets that set sensible defaults for threshold and deduplication: + +| Profile | Threshold | Dedupe | Use case | +|---------|-----------|--------|----------| +| `default` | `CRITICAL` | `global` | Standard behavior — block only critical threats | +| `strict` | `HIGH` | `global` | Security-conscious teams — block high+ threats | +| `permissive` | `CRITICAL` | `legacy` | Advisory-only — minimal blocking, no global dedup | + +```bash +skillshare audit --profile strict # Block on HIGH+, global dedup +skillshare audit --profile permissive # Advisory mode +``` + +Explicit flags always override profile defaults: + +```bash +skillshare audit --profile strict --threshold medium # strict profile but block on MEDIUM+ +``` + +### Deduplication + +When the same finding is detected by multiple analyzers (e.g., both static and dataflow), deduplication removes redundant entries: + +| Mode | Behavior | +|------|----------| +| `global` | Full composite-key dedup across all findings (default) | +| `legacy` | Per-analyzer dedup only (pre-v0.16.9 behavior) | + +### Analyzer Selection + +By default all analyzers run. Use `--analyzer` to run only specific ones: + +```bash +skillshare audit --analyzer static # Static pattern matching only +skillshare audit --analyzer static --analyzer dataflow # Multiple analyzers +``` + +| Analyzer | Scope | Description | +|----------|-------|-------------| +| `static` | Per-file | Regex-based pattern matching against audit rules | +| `dataflow` | Per-file | Taint tracking for shell scripts and markdown code blocks | +| `tier` | Per-skill | Capability tier combination risk analysis | +| `integrity` | Per-skill | Content hash verification (`file_hashes` in SKILL.md) | +| `structure` | Per-skill | Dangling markdown link detection | +| `cross-skill` | Bundle | Cross-skill exfiltration and privilege escalation analysis | + +You can also set this in config: + +```yaml +audit: + enabled_analyzers: [static, dataflow] +``` + +### Precedence + +Settings resolve in this order (first non-empty wins): + +1. CLI flags (`--profile`, `--threshold`, `--dedupe`, `--analyzer`) +2. Project config (`.skillshare/config.yaml`) +3. Global config (`~/.config/skillshare/config.yaml`) +4. Profile defaults + ## Automatic Scanning ### Install-time @@ -604,6 +676,28 @@ skillshare audit --json | jq '.skills[] | {name: .skillName, score: .riskScore, skillshare audit --json | jq '[.skills[].findings[].severity] | group_by(.) | map({(.[0]): length}) | add' ``` +### Finding Schema + +Each finding in JSON/SARIF output includes: + +| Field | Type | Description | +|-------|------|-------------| +| `severity` | string | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO` | +| `pattern` | string | Pattern category (e.g., `data-exfiltration`, `shell-execution`) | +| `message` | string | Human-readable description | +| `file` | string | Relative file path | +| `line` | int | Line number (0 if not applicable) | +| `snippet` | string | Matched code snippet | +| `ruleId` | string | Unique rule identifier (e.g., `data-exfiltration-0`) | +| `analyzer` | string | Source analyzer: `static`, `dataflow`, `tier`, `integrity`, `structure`, `cross-skill` | +| `category` | string | Threat category: `injection`, `exfiltration`, `credential`, `obfuscation`, `privilege`, `integrity`, `structure`, `risk` | +| `confidence` | float | Confidence score (0–1). Static: 0.95, Dataflow: 0.85 | +| `fingerprint` | string | Stable SHA-256 hash for deduplication and tracking | + +Fields `ruleId`, `analyzer`, `category`, `confidence`, and `fingerprint` are omitted from JSON when empty (backward compatible). + +In SARIF output, `ruleId` maps to the SARIF `ruleId` field, and `fingerprint` is included in the `fingerprints` property of each result. + ### GitHub Actions Example ```yaml @@ -1142,6 +1236,9 @@ Source of truth for regex-based rules: | `-p`, `--project` | Scan project-level skills | | `-g`, `--global` | Scan global skills | | `--threshold` ``, `-T` `` | Block threshold: `critical`\|`high`\|`medium`\|`low`\|`info` (shorthand: `c`\|`h`\|`m`\|`l`\|`i`, plus `crit`, `med`) | +| `--profile` `

` | Audit profile preset: `default`, `strict`, `permissive` | +| `--dedupe` `` | Dedup mode: `legacy`, `global` (default) | +| `--analyzer` `` | Only run specified analyzer (repeatable). IDs: `static`, `dataflow`, `tier`, `integrity`, `structure`, `cross-skill` | | `--format` `` | Output format: `text` (default), `json`, `sarif`, `markdown` | | `--json` | Output JSON (**deprecated**: use `--format json`) | | `--yes`, `-y` | Skip large-scan confirmation prompt (auto-confirms) | diff --git a/website/docs/reference/targets/configuration.md b/website/docs/reference/targets/configuration.md index dd1913072..319d669e6 100644 --- a/website/docs/reference/targets/configuration.md +++ b/website/docs/reference/targets/configuration.md @@ -371,11 +371,29 @@ Security audit configuration. ```yaml audit: block_threshold: CRITICAL + profile: default + dedupe_mode: global + enabled_analyzers: [static, dataflow, tier, integrity] ``` | Field | Values | Default | Description | |-------|--------|---------|-------------| | `block_threshold` | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO` | `CRITICAL` | Minimum severity to block `skillshare install` | +| `profile` | `default`, `strict`, `permissive` | `default` | Audit profile preset (sets defaults for threshold and dedupe) | +| `dedupe_mode` | `legacy`, `global` | `global` | Finding deduplication mode | +| `enabled_analyzers` | Array of analyzer IDs | *(all)* | Allowlist of analyzers to run (omit for all) | + +**Profiles** set sensible defaults that can be overridden by explicit field values: + +| Profile | Threshold | Dedupe | Description | +|---------|-----------|--------|-------------| +| `default` | `CRITICAL` | `global` | Same as current behavior | +| `strict` | `HIGH` | `global` | Stricter blocking for security-conscious teams | +| `permissive` | `CRITICAL` | `legacy` | Advisory-only, minimal blocking | + +**Analyzer IDs:** `static`, `dataflow`, `tier`, `integrity`, `structure`, `cross-skill` + +**Precedence:** CLI flags → project config → global config → profile defaults. - `block_threshold` only controls when install is **blocked** — scanning always runs - Use `--skip-audit` to bypass scanning for a single install @@ -410,9 +428,10 @@ skills: source: github.com/team/skills tracked: true # Cloned with git history -# Audit — same as global +# Audit — same fields as global audit: block_threshold: HIGH + profile: strict ``` ### `targets` (project)