Files
skillshare/website/docs/reference/commands/audit-rules.md
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

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; severity or confidence alone overrides that field
  • New id → appends as a custom rule
  • pattern only (no id) + enabled: false → disables all rules matching that pattern
  • pattern only + severity or confidence → 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:

  • Failed counts skills with findings at or above the active threshold.
  • Warning counts skills with findings below threshold but above clean (for example HIGH/MEDIUM/LOW/INFO when threshold is CRITICAL).

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 your audit-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

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']