How to Use Custom YARA Rules with SkillSpector CLI: A Complete Guide

Supply a directory containing .yar or .yara files to the SkillSpector CLI using the --yara-rules-dir flag to augment the built-in security scanning rules without modifying the core repository.

SkillSpector is an open-source security scanning tool by NVIDIA that uses YARA rules to detect malware, webshells, and other threats in AI skill repositories. While the tool ships with curated default signatures located in src/skillspector/yara_rules/, security teams often need to add proprietary detection logic for internal threats. This guide explains how to load and execute custom YARA rules with SkillSpector CLI while keeping the built-in rule sets intact.

How Custom YARA Rules Work in SkillSpector

The Rule Loading Architecture

When you invoke the SkillSpector CLI with the --yara-rules-dir argument, the path is parsed in src/skillspector/cli.py and stored in the execution state as state["yara_rules_dir"]. During the analysis phase, the YARA analyzer node in src/skillspector/nodes/analyzers/static_yara.py calls static_yara._load_rules(extra_dir) to combine built-in and custom rules.

The _load_rules function performs four critical operations:

1. Collects all rule files from the built-in directory (src/skillspector/yara_rules/) and your specified extra directory
2. Builds a deterministic namespace map to prevent rule name collisions
3. Hashes the file list to cache compiled rules for performance
4. Compiles the rules using bulk-compile when possible, falling back to per-file compilation when necessary

Rule Compilation and Caching

SkillSpector optimizes scanning performance by caching compiled YARA rules. The system generates a hash of the rule file list to determine if recompilation is necessary. If your custom rules haven't changed since the last scan, SkillSpector uses the cached compiled version instead of recompiling from source.

Step-by-Step Guide to Using Custom YARA Rules with SkillSpector CLI

Follow these steps to integrate your own threat detection signatures:

1. Create a directory on your local filesystem to store your custom rule files
2. Add YARA rules with .yar or .yara extensions to this directory
3. Pass the directory path to SkillSpector using the --yara-rules-dir flag when running a scan

Each compiled rule is applied to every scanned artifact, with findings reported according to the rule's category, severity, confidence, and description metadata fields.

Practical Code Examples

Command-Line Usage

Run a SkillSpector scan on a skill repository while loading your custom YARA rules:

# Directory that holds your custom YARA files

CUSTOM_RULES=/home/user/my_yara_rules

# Run a SkillSpector scan on a skill repository, adding your rules

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

Programmatic API Usage

You can also invoke SkillSpector programmatically from Python:

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

# Prepare arguments (the same as the CLI)

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

# Run the tool programmatically

skill_spector_main(args)

Writing Compatible YARA Rules

Create rule files that SkillSpector can properly categorize and prioritize:

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

Place this file in your custom directory and invoke SkillSpector with the --yara-rules-dir flag. The finding will appear as YARA rule 'EvilProcess' with severity HIGH and the specified confidence score.

Built-In vs Custom Rule Integration

SkillSpector ships with four built-in rule sets in src/skillspector/yara_rules/:

• webshells.yar – Detects web shell artifacts
• malware.yar – General malware signatures
• cryptominers.yar – Cryptocurrency mining detection
• hacktools.yar – Penetration testing and hacking tool signatures

When you specify a custom rules directory, SkillSpector compiles these built-in rules alongside your custom signatures. You do not need to modify the built-in files in the repository; the tool merges both sources automatically during the _load_rules execution.

Performance and Caching Considerations

The YARA analyzer implements intelligent caching to avoid recompiling rules on every scan. It generates a hash of the rule file list from both the built-in directory and your custom directory. If the hash matches a previous execution, SkillSpector loads the pre-compiled rules from cache rather than recompiling, significantly reducing startup time for repeated scans.

Summary

• SkillSpector supports custom YARA rules via the --yara-rules-dir CLI flag without modifying built-in rule files
• Custom rules are stored in state["yara_rules_dir"] and processed by _load_rules() in static_yara.py
• Rule compilation uses deterministic namespace mapping and hash-based caching for performance optimization
• YARA rules must include meta fields (category, severity, confidence, description) for proper finding classification
• Both .yar and .yara file extensions are supported in custom rule directories

Frequently Asked Questions

What file extensions are supported for custom YARA rules?

SkillSpector recognizes files with .yar and .yara extensions when scanning your custom rules directory. The _load_rules function in src/skillspector/nodes/analyzers/static_yara.py filters for these specific extensions when collecting rule files from both the built-in directory and your custom directory.

Can I override built-in rules with custom YARA rules in SkillSpector?

No, you cannot override built-in rules by name. SkillSpector compiles custom rules alongside the built-in rules from src/skillspector/yara_rules/ using namespace isolation to prevent collisions. If you need to disable specific built-in detections, you must modify the rule files directly in the repository rather than using the --yara-rules-dir flag.

How does SkillSpector handle YARA rule compilation errors?

If bulk compilation fails, the _load_rules function falls back to per-file compilation to isolate problematic rules. Rules that fail to compile are skipped, and the scan continues with valid rules. Check the scan output for warnings about specific rule files that could not be compiled.

Where are the compiled YARA rules cached?

SkillSpector caches compiled rules in memory during the execution session based on a hash of the rule file list. The cache is not persisted to disk between separate CLI invocations; however, within a single scan session, the compiled rules are reused across all analyzed artifacts to improve performance.

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