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

> Learn to use custom YARA rules with SkillSpector. Guide shows how to pass your rules directory to the CLI for enhanced analysis. Improve security scans.

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

---

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

```bash
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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) validates the path and stores it in the execution state under `state["yara_rules_dir"]`.

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

```yara
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`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py)**: Parses the `--yara-rules-dir` argument and writes it to the runtime state object.

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

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

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