* 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
22 KiB
sidebar_position
| sidebar_position |
|---|
| 4 |
audit rules
Browse, enable, disable, and customize audit rules.
skillshare audit rules # Interactive TUI rule browser
skillshare audit rules --no-tui # Plain text table
skillshare audit rules --pattern credential-access # Filter by pattern
skillshare audit rules --severity high # Filter by severity
skillshare audit rules --disabled # Show only disabled rules
skillshare audit rules --format json # JSON output
skillshare audit rules disable prompt-injection-0 # Disable single rule
skillshare audit rules disable --pattern credential-access # Disable entire group
skillshare audit rules enable prompt-injection-0 # Re-enable rule
skillshare audit rules enable --pattern credential-access # Re-enable group
skillshare audit rules severity destructive-commands-2 medium # Downgrade one rule
skillshare audit rules severity --pattern destructive-commands low # Downgrade entire group
skillshare audit rules reset # Remove all custom rules, restore defaults
skillshare audit rules init # Create starter audit-rules.yaml
skillshare audit rules init -p # Create project-level rules file
Pattern-Level Rules
You can disable or override entire pattern groups in audit-rules.yaml:
rules:
# Disable all credential-access rules
- pattern: credential-access
enabled: false
# But keep .env detection
- id: credential-access-env-file
enabled: true
# Downgrade all destructive-commands to MEDIUM
- pattern: destructive-commands
severity: MEDIUM
Pattern-level entries use pattern without id. Merge order: pattern-level rules apply first, then id-level rules can override individual entries within a disabled group.
Custom Rules
You can add, override, or disable audit rules using YAML files. Rules are merged in order: built-in → global user → project user.
Use --init-rules (or audit rules init) to create a starter file with commented examples:
skillshare audit --init-rules # Create global rules file
skillshare audit -p --init-rules # Create project rules file
File Locations
| Scope | Path |
|---|---|
| Global | ~/.config/skillshare/audit-rules.yaml |
| Project | .skillshare/audit-rules.yaml |
Format
rules:
# Add a new rule
- id: my-custom-rule
severity: HIGH
pattern: custom-check
message: "Custom pattern detected"
regex: 'DANGEROUS_PATTERN'
# Add a rule with an exclude (suppress matches on certain lines)
- id: url-check
severity: MEDIUM
pattern: url-usage
message: "External URL detected"
regex: 'https?://\S+'
exclude: 'https?://(localhost|127\.0\.0\.1)'
# Override an existing built-in rule (match by id)
- id: destructive-commands-2
severity: MEDIUM
pattern: destructive-commands
message: "Sudo usage (downgraded to MEDIUM)"
regex: '(?i)\bsudo\s+'
# Disable a built-in rule
- id: insecure-http-0
enabled: false
# Disable the dangling-link structural check
- id: dangling-link
enabled: false
Fields
| Field | Required | Description |
|---|---|---|
id |
Yes | Stable identifier. Matching IDs override built-in rules. |
severity |
Yes* | CRITICAL, HIGH, MEDIUM, LOW, or INFO |
pattern |
Yes* | Rule category name (e.g., prompt-injection) |
message |
Yes* | Human-readable description shown in findings |
regex |
Yes* | Regular expression to match against each line |
confidence |
No | Confidence between 0 and 1; defaults to 0.95 |
exclude |
No | If a line matches both regex and exclude, the finding is suppressed |
files |
No | File glob patterns that limit where the rule applies; see File Applicability. |
enabled |
No | Set to false to disable a rule. Only id is required when disabling. |
*Required unless enabled: false.
Merge Semantics
Each layer (global, then project) is applied on top of the previous:
- Same
id+enabled: false→ disables the rule - Same
id+regex→ replaces the entire rule;severityorconfidencealone overrides that field - New
id→ appends as a custom rule patternonly (noid) +enabled: false→ disables all rules matching that patternpatternonly +severityorconfidence→ overrides that field for all matching rules- Pattern then id → id-level entries can re-enable individual rules within a disabled pattern group
Practical Templates
Use this as a starting point for real-world policy tuning:
rules:
# Downgrade hardcoded-secret to MEDIUM for educational/reference skills
- pattern: hardcoded-secret
severity: MEDIUM
# Override built-in suspicious-fetch with internal allowlist
- id: suspicious-fetch-0
severity: MEDIUM
pattern: suspicious-fetch
message: "External URL used in command context"
regex: '(?i)(curl|wget|invoke-webrequest|iwr)\s+https?://'
exclude: '(?i)https?://(localhost|127\.0\.0\.1|artifacts\.company\.internal|registry\.company\.internal)'
# Governance exception: disable noisy insecure-http signal
- id: insecure-http-0
enabled: false
Getting Started with init
audit rules init (or audit --init-rules) creates a starter audit-rules.yaml with commented examples you can uncomment and adapt:
skillshare audit rules init # → ~/.config/skillshare/audit-rules.yaml
skillshare audit rules init -p # → .skillshare/audit-rules.yaml
The generated file looks like this:
# Custom audit rules for skillshare.
# Rules are merged on top of built-in rules in order:
# built-in → global (~/.config/skillshare/audit-rules.yaml)
# → project (.skillshare/audit-rules.yaml)
#
# Each rule needs: id, severity, pattern, message, regex.
# Optional: exclude (suppress match), files (scope), enabled (false to disable).
rules:
# Example: flag TODO comments as informational
# - id: flag-todo
# severity: MEDIUM
# pattern: todo-comment
# message: "TODO comment found"
# regex: '(?i)\bTODO\b'
# Example: disable a built-in rule by id
# - id: insecure-http-0
# enabled: false
# Example: disable the dangling-link structural check
# - id: dangling-link
# enabled: false
# Example: override a built-in rule (match by id, change severity)
# - id: destructive-commands-2
# severity: MEDIUM
# pattern: destructive-commands
# message: "Sudo usage (downgraded)"
# regex: '(?i)\bsudo\s+'
If the file already exists, init exits with an error — it never overwrites existing rules.
Workflow: Fixing a False Positive
A common reason to customize rules is when a legitimate skill triggers a built-in rule. Here's a step-by-step example:
1. Run audit and see the false positive:
$ skillshare audit ci-helper
Audit ~/.config/skillshare/skills
global · blocks at CRITICAL · policy DEFAULT / dedupe:GLOBAL / analyzers:ALL
HIGH Sudo escalation SKILL.md:42
destructive-commands-2 / static
"sudo apt-get install -y jq"
Risk HIGH 15/100
Auditable 100%
! ci-helper has findings below CRITICAL · 0.2s
2. Identify the rule ID from the built-in rules table:
The pattern destructive-commands with sudo matches rule destructive-commands-2.
3. Create a custom rules file (if you haven't already):
skillshare audit rules init
4. Add a rule override to suppress or downgrade:
# ~/.config/skillshare/audit-rules.yaml
rules:
# Downgrade sudo to MEDIUM for CI automation skills
- id: destructive-commands-2
severity: MEDIUM
pattern: destructive-commands
message: "Sudo usage (downgraded for CI automation)"
regex: '(?i)\bsudo\s+'
Or disable it entirely:
rules:
- id: destructive-commands-2
enabled: false
5. Re-run audit to confirm:
$ skillshare audit ci-helper
Audit ~/.config/skillshare/skills
global · blocks at CRITICAL · policy DEFAULT / dedupe:GLOBAL / analyzers:ALL
✓ No issues found in ci-helper · 0.1s # Now passes (or shows MEDIUM instead of HIGH)
Validate Changes
After editing rules, re-run audit to verify:
skillshare audit # Check all skills
skillshare audit <name> # 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:
Failedcounts skills with findings at or above the active threshold.Warningcounts skills with findings below threshold but above clean (for exampleHIGH/MEDIUM/LOW/INFOwhen threshold isCRITICAL).
Built-in Rule IDs
Use id values to override or disable specific built-in rules:
Source of truth for regex-based rules:
internal/audit/rules.yaml
The file-level whitespace-padding detector is also registered in rules.yaml. Its thresholds and exemptions are implemented in Go; configure its enabled state, severity or confidence without regex or exclude. See Whitespace Padding. Rules for this ID that set regex or exclude are rejected.
:::note Structural, tier, and cross-skill checks
dangling-link, reference-escapes-root, reference-check-incomplete, content-tampered, content-oversize, content-missing, and content-unexpected are structural checks (filesystem lookups and hash comparisons, not regex). low-analyzability is an analyzability finding generated from the Analyzability Score. tier-stealth, tier-destructive-network, tier-network-heavy, tier-interpreter, and tier-interpreter-network are tier combination findings generated from Command Safety Tiering profiles. cross-skill-* findings are generated from Cross-Skill Interaction Detection. Header checks also generate disguised-executable, python-bytecode, executable-artifact, archive-artifact, and uncertain-header findings described in Executable and archive headers. All of these appear in the table below but are not defined in rules.yaml.
bundled-* rules are structured JSON checks under structure, registered for listing, disabling, and severity overrides. Their metadata regex never matches text; see bundled hooks and settings.
:::
| ID | Pattern | Severity |
|---|---|---|
bundled-hook-command |
bundled-hook-command | MEDIUM |
bundled-network-command |
bundled-network-command | HIGH |
bundled-remote-post |
bundled-remote-post | HIGH |
bundled-permission |
bundled-permission | HIGH |
bundled-helper-command |
bundled-helper-command | HIGH |
bundled-config-unparsed |
bundled-config-unparsed | INFO |
prompt-injection-0 |
prompt-injection | CRITICAL |
prompt-injection-1 |
prompt-injection | CRITICAL |
prompt-injection-2 |
prompt-injection | HIGH |
prompt-injection-3 |
prompt-injection | CRITICAL |
prompt-injection-4 |
prompt-injection | CRITICAL |
prompt-injection-5 |
prompt-injection | HIGH |
hidden-unicode-1 |
invisible-payload | CRITICAL |
data-exfiltration-0 |
data-exfiltration | CRITICAL |
data-exfiltration-1 |
data-exfiltration | CRITICAL |
data-exfiltration-2 |
data-exfiltration | MEDIUM |
data-exfiltration-3 |
data-exfiltration | HIGH |
credential-access-ssh-private-key |
credential-access | CRITICAL / HIGH (context) |
credential-access-env-file |
credential-access | CRITICAL / HIGH (context) |
credential-access-aws-credentials |
credential-access | CRITICAL / HIGH (context) |
credential-access-etc-shadow |
credential-access | CRITICAL / HIGH (context) |
credential-access-git-credentials |
credential-access | CRITICAL / HIGH (context) |
credential-access-netrc |
credential-access | CRITICAL / HIGH (context) |
credential-access-gnupg |
credential-access | CRITICAL / HIGH (context) |
credential-access-kube-config |
credential-access | CRITICAL / HIGH (context) |
credential-access-vault-token |
credential-access | CRITICAL / HIGH (context) |
credential-access-terraform-creds |
credential-access | CRITICAL / HIGH (context) |
credential-access-gnome-keyring |
credential-access | CRITICAL / HIGH (context) |
credential-access-npmrc |
credential-access | CRITICAL / HIGH (context) |
credential-access-pypirc |
credential-access | CRITICAL / HIGH (context) |
credential-access-gem-credentials |
credential-access | CRITICAL / HIGH (context) |
credential-access-ssl-private |
credential-access | CRITICAL / HIGH (context) |
credential-access-ssh-host-key |
credential-access | CRITICAL / HIGH (context) |
credential-access-pgpass |
credential-access | CRITICAL / HIGH (context) |
credential-access-mysql-cnf |
credential-access | CRITICAL / HIGH (context) |
credential-access-etc-passwd |
credential-access | MEDIUM |
credential-access-azure-creds |
credential-access | HIGH |
credential-access-gcloud-creds |
credential-access | HIGH |
credential-access-docker-config |
credential-access | HIGH |
credential-access-gh-cli-token |
credential-access | HIGH |
credential-access-password-store |
credential-access | HIGH |
credential-access-macos-keychain-user |
credential-access | HIGH |
credential-access-macos-keychain-sys |
credential-access | HIGH |
credential-access-terraformrc |
credential-access | HIGH |
credential-access-cargo-credentials |
credential-access | HIGH |
credential-access-op-cli |
credential-access | HIGH |
credential-access-age-keys |
credential-access | HIGH |
credential-access-shell-history |
credential-access | LOW |
credential-access-openvpn |
credential-access | LOW |
credential-access-auth-log |
credential-access | INFO |
credential-access-unknown-dotdir |
credential-access | INFO |
Note: Each credential entry above also generates variant IDs per access method:
-copy,-redirect,-dd,-exfil(e.g.,credential-access-ssh-private-key-copy). To disable a specific variant, use its full ID in youraudit-rules.yaml.
| ID | Pattern | Severity |
|---|---|---|
hidden-unicode-0 |
hidden-unicode | HIGH |
hidden-unicode-2 |
hidden-unicode | HIGH |
config-manipulation-0 |
config-manipulation | HIGH |
anti-refusal-0 |
anti-refusal | HIGH |
prompt-leakage-0 |
prompt-leakage | HIGH |
memory-poisoning-0 |
memory-poisoning | HIGH |
agent-snooping-0 |
agent-snooping | HIGH |
persistence-0 |
persistence | HIGH |
hidden-comment-injection-1 |
hidden-comment-injection | HIGH |
self-propagation-0 |
self-propagation | HIGH |
destructive-commands-0 |
destructive-commands | HIGH |
destructive-commands-1 |
destructive-commands | HIGH |
destructive-commands-2 |
destructive-commands | HIGH |
destructive-commands-3 |
destructive-commands | HIGH |
destructive-commands-4 |
destructive-commands | HIGH |
dynamic-code-exec-0 |
dynamic-code-exec | HIGH |
dynamic-code-exec-1 |
dynamic-code-exec | HIGH |
shell-execution-0 |
shell-execution | HIGH |
hidden-comment-injection-0 |
hidden-comment-injection | HIGH |
obfuscation-0 |
obfuscation | HIGH |
fetch-with-pipe-0 |
fetch-with-pipe | HIGH |
fetch-with-pipe-1 |
fetch-with-pipe | HIGH |
fetch-with-pipe-2 |
fetch-with-pipe | HIGH |
hardcoded-secret-0 |
hardcoded-secret | HIGH |
hardcoded-secret-1 |
hardcoded-secret | HIGH |
hardcoded-secret-2 |
hardcoded-secret | HIGH |
hardcoded-secret-3 |
hardcoded-secret | HIGH |
hardcoded-secret-4 |
hardcoded-secret | HIGH |
hardcoded-secret-5 |
hardcoded-secret | HIGH |
hardcoded-secret-6 |
hardcoded-secret | HIGH |
hardcoded-secret-7 |
hardcoded-secret | HIGH |
hardcoded-secret-8 |
hardcoded-secret | HIGH |
hardcoded-secret-9 |
hardcoded-secret | HIGH |
data-uri-0 |
data-uri | MEDIUM |
escape-obfuscation-0 |
escape-obfuscation | MEDIUM |
whitespace-padding |
whitespace-padding | MEDIUM (HIGH: ≥40 blank lines before nonblank text) |
suspicious-fetch-0 |
suspicious-fetch | MEDIUM |
ip-address-url-0 |
ip-address-url | MEDIUM |
hidden-unicode-3 |
hidden-unicode | MEDIUM |
untrusted-install-0 |
untrusted-install | MEDIUM |
untrusted-install-1 |
untrusted-install | MEDIUM |
insecure-http-0 |
insecure-http | LOW |
external-link-0 |
external-link | LOW |
dangling-link |
dangling-link | LOW |
reference-escapes-root |
reference-escapes-root | HIGH |
reference-check-incomplete |
reference-check-incomplete | LOW |
content-tampered |
content-tampered | MEDIUM |
content-oversize |
content-oversize | MEDIUM |
content-missing |
content-missing | LOW |
content-unexpected |
content-unexpected | LOW |
shell-chain-0 |
shell-chain | INFO |
low-analyzability |
low-analyzability | INFO |
tier-stealth |
tier-stealth | CRITICAL |
tier-destructive-network |
tier-destructive-network | HIGH |
tier-network-heavy |
tier-network-heavy | MEDIUM |
tier-interpreter |
tier-interpreter | INFO |
tier-interpreter-network |
tier-interpreter-network | MEDIUM |
cross-skill-exfiltration |
cross-skill-exfiltration | HIGH |
cross-skill-privilege-network |
cross-skill-privilege-network | MEDIUM |
cross-skill-stealth |
cross-skill-stealth | HIGH |
cross-skill-cred-interpreter |
cross-skill-cred-interpreter | MEDIUM |
disguised-executable |
disguised-executable | HIGH |
python-bytecode |
python-bytecode | HIGH |
executable-artifact |
executable-artifact | MEDIUM |
archive-artifact |
archive-artifact | INFO |
uncertain-header |
uncertain-header | INFO |
ssrf-metadata-0 |
ssrf-metadata | CRITICAL / HIGH (context) |
ssrf-internal-0 |
ssrf-internal | MEDIUM |
ssrf-dynamic-0 |
ssrf-dynamic | MEDIUM |
unsafe-deserialization-python |
unsafe-deserialization | HIGH |
unsafe-deserialization-yaml |
unsafe-deserialization | HIGH |
unsafe-deserialization-torch |
unsafe-deserialization | HIGH |
unsafe-deserialization-php |
unsafe-deserialization | HIGH |
unsafe-deserialization-ruby |
unsafe-deserialization | HIGH |
unsafe-deserialization-js |
unsafe-deserialization | HIGH |
In audit rules --format json, rules marked context above carry "severityContext": "python-inert" while they keep their built-in CRITICAL severity and regex. Setting a severity or replacing the regex removes it, because the downgrade no longer applies.
Subcommands
| Subcommand | Description |
|---|---|
rules |
Browse, enable, and disable audit rules |
rules disable <id> |
Disable a single rule by ID |
rules disable --pattern <p> |
Disable all rules matching a pattern |
rules enable <id> |
Re-enable a single rule by ID |
rules enable --pattern <p> |
Re-enable all rules matching a pattern |
rules severity <id> <level> |
Override severity for a single rule |
rules severity --pattern <p> <level> |
Override severity for all rules in a pattern group |
rules reset |
Remove all custom rules (restore built-in defaults) |
rules init |
Create a starter audit-rules.yaml (same as audit --init-rules) |
See Also
audit— Main audit command reference- Audit Engine — How the engine works (threat model, risk scoring, tiering)
- Securing Your Skills — Security guide for teams
- CI/CD Skill Validation — Pipeline automation recipe
File Applicability
The optional files list limits a rule to matching paths. It uses Go path.Match syntax (*, ?, character classes). A glob without /, such as *.py, matches a basename at any depth. A glob with /, such as scripts/*.php, matches the whole path relative to the scanned skill root; * does not cross /. Single-file scans use the basename; raw-content scans use the supplied filename. Matching is case-insensitive. This field filters files already admitted by the scanner; it does not collect additional file types.
Absolute paths, empty globs, empty/dot/parent path segments, backslashes, colons, malformed character classes, and recursive ** are rejected, including in disabled rules and unmatched overrides. Omitted files preserves inherited applicability; an explicit files: [] clears it. ID and pattern overrides support this field; ID overrides take precedence. A full regex replacement replaces the whole rule, including applicability and built-in call inspection. audit rules --format json includes the effective files list when nonempty.
rules:
- id: unsafe-deserialization-python
files: ['*.py', 'scripts/*.txt']