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

> Learn to use custom YARA rules with SkillSpector CLI. Enhance security scanning by pointing to your rule directory with the yara rules dir flag, without altering the core repository. Maximize your security insights.

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

---

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

```bash

# 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:

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

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