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

To use custom YARA rules with SkillSpector, create a directory containing your .yar or .yara files and pass it to the CLI using the --yara-rules-dir flag, which merges your rules with the built-in set during analysis.

SkillSpector is an open-source security scanning tool by NVIDIA that analyzes code repositories for vulnerabilities and malicious patterns. While it ships with curated YARA rules for detecting webshells, malware, and crypto-miners, security teams often need to augment these with proprietary signatures. The tool provides a clean extension mechanism that keeps built-in rules intact while integrating your custom threat intelligence.

How Custom YARA Rules Work in SkillSpector

SkillSpector separates built-in rules from user-provided extensions to ensure clean updates and version control. The built-in rules reside in src/skillspector/yara_rules/ and include signatures for common threats like webshells and hacktools.

When you specify a custom rules directory, the YARA analyzer node executes a merging workflow defined in src/skillspector/nodes/analyzers/static_yara.py. The _load_rules() function collects files from both locations, builds a deterministic namespace map, hashes the combined file list for caching, and compiles everything into a single rule set. This compiled set is then applied to every artifact scanned during the analysis pipeline.

Step-by-Step: Loading Custom YARA Rules

Follow this workflow to integrate your own threat signatures without modifying the core installation.

1. Create Your Custom Rules Directory

Create a directory anywhere on your filesystem and populate it with YARA rule files. SkillSpector recognizes files ending in .yar or .yara.

mkdir ~/my_custom_rules
vim ~/my_custom_rules/enterprise_threats.yar

2. Pass the Directory via CLI

Use the --yara-rules-dir flag when invoking the scan command. The CLI handler in src/skillspector/cli.py validates the path and stores it in the execution state under state["yara_rules_dir"].

skillspector scan /path/to/target_skill \
    --yara-rules-dir ~/my_custom_rules \
    --output-format sarif

3. Rule Compilation and Execution

During analysis, the static YARA analyzer reads the stored path and calls _load_rules(extra_dir) with your directory as the argument. The function performs four key operations:

• Collection: Gathers all .yar and .yara files from both the built-in directory and your custom directory
• Namespacing: Builds a deterministic namespace map to prevent rule collisions
• Caching: Computes a hash of the file list to cache compiled rules for performance
• Compilation: Uses bulk compilation when possible, falling back to per-file compilation if necessary

Custom YARA Rule Requirements

SkillSpector extracts specific metadata fields from your YARA rules to populate its findings reports. Structure your rules to include these meta fields for proper categorization.

Required Metadata Fields

• category: Classification of the threat (e.g., "malware", "webshell")
• severity: Risk level such as "HIGH", "MEDIUM", or "LOW"
• confidence: Numeric score between 0 and 1 indicating detection confidence
• description: Human-readable explanation of what the rule detects

Example Custom Rule

Create a file named evil.yar in your custom directory:

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

When this rule matches, SkillSpector reports a finding with the rule name "EvilProcess", severity "HIGH", and the associated metadata.

Implementation Details

The custom rule integration relies on three core components working together.

src/skillspector/cli.py: Parses the --yara-rules-dir argument and writes it to the runtime state object.

src/skillspector/state.py: Maintains the mutable execution state including the yara_rules_dir field that persists across the analysis pipeline.

src/skillspector/nodes/analyzers/static_yara.py: Contains the _load_rules() implementation that handles the actual compilation. According to the NVIDIA/SkillSpector source code, this module implements deterministic ordering to ensure consistent rule evaluation and uses file hashing to avoid recompiling unchanged rule sets.

The built-in rule sets located in src/skillspector/yara_rules/ include webshells.yar, malware.yar, cryptominers.yar, and hacktools.yar, which remain untouched during custom rule loading.

Programmatic Usage Examples

You can also invoke SkillSpector with custom rules directly from Python code.

Python API Usage

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

# Prepare arguments matching CLI syntax

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

# Execute the scan programmatically

skill_spector_main(args)

Command-Line with Environment Variables

export CUSTOM_RULES=/home/user/enterprise_signatures
skillspector scan ./skill_repository \
    --yara-rules-dir $CUSTOM_RULES \
    --verbose

Summary

• Use --yara-rules-dir to specify a directory containing .yar or .yara files without modifying built-in rules.
• Metadata matters: Include category, severity, confidence, and description fields in your YARA rules for proper report generation.
• Implementation location: The core logic resides in src/skillspector/nodes/analyzers/static_yara.py, specifically the _load_rules() function.
• State management: The CLI stores your custom path in state["yara_rules_dir"] for access by the analyzer node.
• Caching: SkillSpector hashes rule files to cache compiled versions, improving performance on subsequent scans.

Frequently Asked Questions

Can I modify the built-in YARA rules in SkillSpector?

No, you should not modify the built-in rule files in src/skillspector/yara_rules/. Instead, use the --yara-rules-dir flag to supply additional rules. This approach preserves your customizations when updating SkillSpector to newer versions and keeps the built-in curated sets intact.

What metadata fields does SkillSpector extract from YARA rules?

SkillSpector specifically extracts four metadata fields: category for threat classification, severity for risk level (e.g., "HIGH", "MEDIUM"), confidence as a numeric score between 0 and 1, and description for the finding explanation. These appear in the final SARIF or text output reports.

How does SkillSpector cache compiled YARA rules?

The _load_rules() function in static_yara.py computes a hash of the combined file list from both built-in and custom directories. If the hash matches a previous compilation, SkillSpector reuses the cached compiled rules rather than recompiling, significantly improving scan startup times for large rule sets.

Does SkillSpector support recursive subdirectories in custom rule directories?

The implementation collects all rule files from the specified custom directory. While the source code handles file collection and namespacing, you should verify the specific version's behavior regarding nested directories, as the standard implementation focuses on flat file collections within the specified path.

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