How to Configure Custom YARA Rules for SkillSpector: A Complete Guide

SkillSpector allows you to augment its built-in YARA detection by passing a custom directory via the --yara-rules-dir flag, which the static_yara analyzer merges with default rules in src/skillspector/yara_rules/ without modifying the original files.

NVIDIA's SkillSpector provides static analysis for AI skill repositories using YARA rules to detect webshells, malware, and crypto-miners. While the tool ships with curated detection signatures, security teams often need to configure custom YARA rules for SkillSpector to match organization-specific threats or internal compliance requirements. The architecture maintains separation between built-in and custom rules, ensuring updates to the base rule set never overwrite your custom signatures.

Understanding the YARA Rule Architecture

SkillSpector implements a layered rule system that combines built-in detection signatures with user-supplied custom rules at runtime.

Built-in Rules Location

The default YARA signatures reside in src/skillspector/yara_rules/ and include:

• webshells.yar – Detection for web shell patterns
• malware.yar – General malware signatures
• cryptominers.yar – Cryptocurrency mining detection
• hacktools.yar – Penetration testing tool signatures

The _load_rules Function

The core compilation logic lives in src/skillspector/nodes/analyzers/static_yara.py. When the analyzer initializes, it calls _load_rules(extra_dir) where extra_dir corresponds to the path stored in state["yara_rules_dir"] (defined in src/skillspector/state.py).

This function performs four critical operations:

1. Collects rule files from both the built-in directory and your custom directory
2. Builds a deterministic namespace map to prevent rule name collisions
3. Hashes the complete file list to cache compiled rules for performance
4. Compiles rules using bulk-compile when possible, falling back to per-file compilation for compatibility

Step-by-Step Configuration Guide

Follow this workflow to add custom YARA rules without altering the SkillSpector installation.

Step 1: Create Your Custom Rule Directory

Create a dedicated directory anywhere on your filesystem to hold additional rule files. SkillSpector recognizes files with .yar or .yara extensions.

mkdir -p /path/to/custom_yara_rules

Step 2: Write Your YARA Rules

Create rule files with appropriate meta fields for SkillSpector integration. The analyzer specifically extracts category, severity, confidence, and description from the rule metadata to populate findings.

Example rule structure (custom_rules/evil.yar):

rule EvilProcess
{
    meta:
        category = "malware"
        severity = "HIGH"
        confidence = 0.9
        description = "Detects suspicious process name"
    strings:
        $proc = "evil.exe"
    condition:
        $proc
}

Step 3: Pass the Directory via CLI

Use the --yara-rules-dir argument when invoking SkillSpector. The CLI handler in src/skillspector/cli.py validates the path and writes it to the execution state.

skillspector scan /path/to/skill \
    --yara-rules-dir /path/to/custom_yara_rules \
    --output-format sarif

Step 4: Programmatic API Usage

You can also invoke SkillSpector programmatically from Python using the same argument structure:

from skillspector.cli import main as skill_spector_main
from pathlib import Path

# Prepare arguments matching CLI syntax

args = [
    "scan",
    "/path/to/skill",
    "--yara-rules-dir", str(Path("/path/to/custom_yara_rules")),
    "--output-format", "sarif"
]

# Execute scan

skill_spector_main(args)

Rule Compilation and Caching Mechanism

Understanding how SkillSpector processes rules helps optimize performance for large custom rule sets.

When _load_rules executes, it generates a deterministic hash of all rule file paths and modification times. If the hash matches a previous compilation, SkillSpector loads cached compiled rules instead of recompiling. This cache invalidation strategy ensures that adding, removing, or modifying any .yar file triggers a fresh compilation while providing fast subsequent runs.

The compilation strategy adapts to your Python-YARA installation:

• Bulk-compile: Attempts to compile all rules simultaneously for maximum performance
• Per-file fallback: Compiles individual rules when namespace conflicts or syntax variations require isolation

Each compiled rule applies to every scanned artifact, with findings reporting the extracted metadata fields along with the rule name.

Summary

• Do not modify built-in rules in src/skillspector/yara_rules/; use the --yara-rules-dir flag instead
• Store custom rules as .yar or .yara files in a separate directory with any name
• Include meta fields (category, severity, confidence, description) in your rules for rich reporting
• The _load_rules function in static_yara.py handles deterministic compilation and caching automatically
• The state["yara_rules_dir"] field bridges CLI input and analyzer execution

Frequently Asked Questions

What file extensions does SkillSpector recognize for YARA rules?

SkillSpector recognizes both .yar and .yara extensions when scanning your custom directory. Files with other extensions are ignored during the rule loading process in static_yara._load_rules().

Can I override built-in rules with custom versions?

No. SkillSpector merges custom rules with built-in rules using namespace mapping rather than replacement. If your custom rule has the same name as a built-in rule, the deterministic namespace assignment ensures both rules execute without collision, though you cannot suppress built-in signatures through this mechanism.

How does SkillSpector handle YARA syntax errors in custom rules?

The _load_rules function implements error handling that reports compilation failures on a per-file basis when using per-file fallback mode. If bulk-compile fails, SkillSpector attempts individual compilation to isolate problematic rules, allowing valid rules to load even if one file contains syntax errors.

Where does SkillSpector store compiled rule caches?

SkillSpector computes an MD5 hash of the rule file list and stores the compiled rules in memory during the execution session. There is no persistent disk cache between runs; the hash comparison occurs within the current process to optimize repeated scans during the same invocation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}