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

> Learn to configure custom YARA rules for NVIDIA SkillSpector using the --yara-rules-dir flag. Enhance your malware analysis by adding your own detection patterns without altering default rules.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-06-24

---

**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`](https://github.com/NVIDIA/SkillSpector/blob/main/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`](https://github.com/NVIDIA/SkillSpector/blob/main/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.

```bash
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`):

```yara
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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) validates the path and writes it to the execution state.

```bash
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:

```python
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`](https://github.com/NVIDIA/SkillSpector/blob/main/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.