# How to Add Custom YARA Rules to SkillSpector Scans: A Complete Guide

> Learn to add custom YARA rules to SkillSpector scans using the --yara-rules-dir flag. Enhance your security analysis with tailored detection capabilities.

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

---

**Add custom YARA rules to SkillSpector by storing your `.yar` files in a directory and passing it via the `--yara-rules-dir` flag; the scanner automatically merges these with built-in rules from `src/skillspector/yara_rules/` and compiles them before execution.**

SkillSpector, NVIDIA's open-source security scanning framework, ships with a comprehensive set of built-in YARA rules for detecting malicious patterns in skills and applications. While these defaults cover common threats, security teams frequently need to add custom YARA rules to detect proprietary indicators of compromise or domain-specific malware signatures. This guide demonstrates how to extend SkillSpector's static analysis pipeline using the exact implementation details from the source code.

## Step-by-Step: Adding Custom YARA Rules to SkillSpector

### 1. Create Your Custom Rules Directory

Begin by creating a dedicated directory to store your YARA signature files. SkillSpector recognizes rule files with the `.yar` or `.yara` extension.

```bash
mkdir -p my_custom_rules

```

### 2. Write Valid YARA Rules

Create one or more rule files within your directory. Each file can contain multiple rules following standard YARA syntax. Include descriptive metadata (category, severity, confidence) to ensure findings are properly categorized in the final SARIF report.

### 3. Invoke SkillSpector with the Custom Rules Path

Pass your directory to the CLI using the `--yara-rules-dir` option:

```bash
skillspector scan ./my-skill/ --yara-rules-dir ./my_custom_rules

```

## How SkillSpector Processes Custom YARA Rules

According to the NVIDIA/SkillSpector source code, custom rule integration follows a specific pipeline involving state management and lazy compilation.

**State Initialization in [`cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/cli.py)**

When you provide the `--yara-rules-dir` argument, the CLI entry point in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) stores the absolute path in the graph state under the key `yara_rules_dir`. The state schema is formally defined in [`src/skillspector/state.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/state.py).

**Rule Loading and Compilation in [`static_yara.py`](https://github.com/NVIDIA/SkillSpector/blob/main/static_yara.py)**

The analyzer node in [`src/skillspector/nodes/analyzers/static_yara.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/analyzers/static_yara.py) executes the `_load_rules` function, which performs the following operations:

- **Source Aggregation**: It collects built-in rules from the internal `_BUILTIN_RULES_DIR` (pointing to `src/skillspector/yara_rules/`) and merges them with your user-provided directory.
- **Content Hashing**: It computes a content hash of all rule files to enable caching and avoid unnecessary recompilation.
- **Compilation Strategy**: It attempts to compile all rules as a single batch for performance. If bulk compilation fails, it automatically falls back to per-file compilation to isolate problematic syntax.
- **Execution**: It runs the compiled rules against each artifact and returns findings for inclusion in the security report.

If your specified directory does not exist, SkillSpector logs a warning and continues with only the built-in rules, ensuring scan continuity.

## Command-Line Usage Example

The following workflow demonstrates creating a custom rule and executing a scan:

```bash

# Create directory for custom rules

mkdir -p my_yara_rules

# Create a rule file (my_yara_rules/malicious_code.yar)

# rule MaliciousCode {

#     meta:

#         category = "malware"

#         severity = "CRITICAL"

#         confidence = 0.9

#         description = "Detects known malicious patterns"

#     strings:

#         $s1 = "bad_function" nocase

#     condition:

#         any of them

# }

# Run SkillSpector with custom rules

skillspector scan ./my-skill/ --yara-rules-dir ./my_yara_rules

```

## Programmatic API Integration

You can also add custom YARA rules when invoking SkillSpector programmatically from Python:

```python
from pathlib import Path
from skillspector.cli import _scan_state, graph
from skillspector.format import FormatChoice

# Build state with absolute path to custom rules

state = _scan_state(
    input_path="./my-skill/",
    format=FormatChoice.terminal,
    no_llm=False,
    yara_rules_dir=str(Path("./my_yara_rules").resolve()),
)

# Execute the analysis graph

result = graph.invoke(state)

# Access findings from your custom rules

print(result.get("sarif_report"))

```

## Sample Custom YARA Rule

Here is a production-ready example of a custom rule file that detects cryptomining code patterns:

```yara
rule CryptoMiner {
    meta:
        category    = "cryptominer"
        severity    = "HIGH"
        confidence  = 0.95
        description = "Detects known cryptomining code snippets"
    strings:
        $s1 = "CryptoNight" nocase
        $s2 = "miner" nocase
    condition:
        any of ($s*)
}

```

Save this content as `my_yara_rules/crypto_miner.yar` within your custom rules directory.

## Summary

- **Custom rules** are added via the `--yara-rules-dir` CLI flag, which stores the path in the graph state as `yara_rules_dir` in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py).
- 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) merges your rules with the built-in set from `_BUILTIN_RULES_DIR` and handles compilation.
- **Caching** is implemented via content hashing to optimize performance across repeated scans.
- **Fallback behavior** ensures scans continue with built-in rules if your custom directory is missing or inaccessible.
- Both **CLI** and **programmatic** APIs support custom YARA rule integration through the same underlying state mechanism.

## Frequently Asked Questions

### What happens if my custom YARA rules directory does not exist?

SkillSpector logs a warning message and proceeds with the scan using only the built-in rules from `src/skillspector/yara_rules/`. The scan does not fail, ensuring operational continuity while alerting you to the configuration issue.

### Can I use multiple custom YARA rule directories in a single scan?

The current implementation accepts a single directory path via the `--yara-rules-dir` parameter. To utilize multiple sources, consolidate your `.yar` and `.yara` files into a single directory structure before invoking the scanner.

### How does SkillSpector handle compilation errors in custom YARA rules?

According to the source code 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 implements a resilience strategy: it first attempts to compile all rules in bulk, and if that fails, it automatically falls back to per-file compilation. This allows valid rules to execute while isolating files with syntax errors.

### Where are the built-in YARA rules located in the SkillSpector repository?

The built-in rule set ships with the project in `src/skillspector/yara_rules/` and is referenced internally via the `_BUILTIN_RULES_DIR` constant within [`static_yara.py`](https://github.com/NVIDIA/SkillSpector/blob/main/static_yara.py). These rules are always loaded and merged with your custom rules during every scan execution.