feat(audit): wire --analyzer CLI flag, config field, and update docs

- Add EnabledAnalyzers []string to AuditConfig struct
- Add enabled_analyzers to both JSON schemas (config + project)
- Parse --analyzer repeatable flag in audit command
- Wire config → PolicyInputs → Registry for all scan paths
  (ParallelScan, single skill, single path, filtered)
- Add PolicyAnalyzers to JSON summary output
- Server handler also reads config enabled_analyzers
- Update audit.md: Policy & Profiles section, Finding Schema table,
  --profile/--dedupe/--analyzer in Options table and examples
- Update configuration.md: expanded audit section with all new fields,
  profile table, analyzer IDs, precedence rules
This commit is contained in:
Willie
2026-03-03 16:08:11 +08:00
parent adae3ee0de
commit d1e7f6558a
9 changed files with 217 additions and 33 deletions
+55 -23
View File
@@ -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 <p> Audit profile preset: default, strict, permissive
--dedupe <mode> Dedup mode: legacy (default), global
--analyzer <id> Only run specified analyzer (repeatable)
IDs: static, dataflow, tier, integrity, structure, cross-skill
--format <f> 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)
+2 -2
View File
@@ -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
}
+17 -4
View File
@@ -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,
+4 -3
View File
@@ -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.
+4
View File
@@ -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)
}
+9
View File
@@ -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
}
}
},
+9
View File
@@ -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
}
}
},
+97
View File
@@ -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>`, `-T` `<t>` | Block threshold: `critical`\|`high`\|`medium`\|`low`\|`info` (shorthand: `c`\|`h`\|`m`\|`l`\|`i`, plus `crit`, `med`) |
| `--profile` `<p>` | Audit profile preset: `default`, `strict`, `permissive` |
| `--dedupe` `<mode>` | Dedup mode: `legacy`, `global` (default) |
| `--analyzer` `<id>` | Only run specified analyzer (repeatable). IDs: `static`, `dataflow`, `tier`, `integrity`, `structure`, `cross-skill` |
| `--format` `<f>` | Output format: `text` (default), `json`, `sarif`, `markdown` |
| `--json` | Output JSON (**deprecated**: use `--format json`) |
| `--yes`, `-y` | Skip large-scan confirmation prompt (auto-confirms) |
@@ -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)