# How to Configure SkillSpector to Use a Custom YARA Rules Directory

> Learn how to configure SkillSpector using the yara rules dir flag to load your custom YARA rules for enhanced security scans. Speed up threat detection today.

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

---

**Use the `--yara-rules-dir` CLI flag to specify a directory containing your `.yar` or `.yara` files, and SkillSpector will automatically load them alongside its built-in rules during the security scan.**

NVIDIA's SkillSpector is an open-source security scanner designed to analyze AI skill code for vulnerabilities using static analysis. While the tool includes a default set of YARA rules located in `src/skillspector/yara_rules/`, security teams often need to detect organization-specific patterns or proprietary threat signatures. Configuring SkillSpector to use a custom YARA rules directory allows you to extend detection capabilities without modifying the core codebase.

## Using the --yara-rules-dir CLI Flag

The primary method to configure a custom YARA rules directory is through the command-line interface. When executing the `scan` command, append the `--yara-rules-dir` option followed by the absolute or relative path to your rule files.

SkillSpector accepts any directory containing files with the `.yar` or `.yara` extension. The scanner ingests these rules in addition to—not instead of—the built-in rules packaged with the repository.

```bash
skill-spector scan /path/to/skill \
    --yara-rules-dir /my/custom/yara_rules

```

### Combining with Output Formats

You can combine this flag with other CLI options such as `--format json` or `--format sarif` to generate findings in your preferred format:

```bash
skill-spector scan my_skill_repo \
    --yara-rules-dir ./my_yara_rules \
    --format sarif > findings.sarif

```

## How Custom Rules Are Loaded and Compiled

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 `static_yara` analyzer handles custom rule loading through the `_load_rules(extra_dir)` function. The process follows four distinct phases:

### 1. Rule Collection and Namespacing

The loader first **collects** all `*.yar` and `*.yara` files from both the built-in directory and your custom directory. To prevent naming collisions, SkillSpector generates namespaces automatically from the file names. If a name clash occurs between custom and built-in rules, the system uses the `parent/name` format to ensure uniqueness.

### 2. Compilation Caching

Before execution, SkillSpector **hashes** the complete list of rule files to create a cache key. If the directory contents haven't changed since the last scan, the analyzer reuses the cached compilation instead of recompiling, significantly improving performance on subsequent runs.

### 3. Rule Compilation

The system **compiles** all collected rules into a single `yara.Rules` object. This compilation step validates syntax and optimizes the rules for matching against extracted component files.

### 4. Execution and Findings Generation

Finally, the analyzer **runs** the compiled rules against every component file that SkillSpector extracts, producing `AnalyzerFinding` objects containing rule IDs, severity levels, and line numbers. These findings are subsequently reported in SARIF or JSON output formats.

## Implementation Details in the Source Code

The configuration flows through three critical files in the NVIDIA/SkillSpector repository.

### CLI Argument Parsing (src/skillspector/cli.py)

In [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), the `--yara-rules-dir` flag is defined as a `typer.Option` that accepts a `Path` object. Once parsed, the resolved path is stored in the runtime state under the key `yara_rules_dir`:

```python
yara_rules_dir: Annotated[
    Path,
    typer.Option(
        "--yara-rules-dir",
        help="Directory containing additional YARA rule files (.yar/.yara) to load alongside built‑in rules.",
    ),
] = None

# Later in the execution flow...

if yara_rules_dir is not None:
    state["yara_rules_dir"] = str(yara_rules_dir.resolve())

```

### State Management (src/skillspector/state.py)

The `SkillspectorState` type defined in [`src/skillspector/state.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/state.py) maintains the `yara_rules_dir` entry throughout the scanning lifecycle. This state object passes the configuration from the CLI layer to the analysis nodes.

### Rule Loading Logic (src/skillspector/nodes/analyzers/static_yara.py)

The `static_yara` node retrieves the directory path from the state and initializes the rule loading:

```python
extra_dir_str: str | None = state.get("yara_rules_dir")
extra_dir = Path(extra_dir_str) if extra_dir_str else None
rules = _load_rules(extra_dir)

```

If the specified directory does not exist, SkillSpector logs a warning and proceeds with only the built-in rules, ensuring the scan continues without critical failure.

## Verifying Custom Rule Loading

To confirm your custom rules are active, you can programmatically invoke the `static_yara` node directly with a custom rules directory:

```python
from skillspector.nodes.analyzers import static_yara

state = {
    "components": ["example.py"],
    "file_cache": {"example.py": "import os\n# malicious pattern"},

    "yara_rules_dir": "./my_yara_rules",
}
result = static_yara.node(state)
print(result["findings"])

```

If your custom rules contain patterns matching the analyzed code, the output will include `AnalyzerFinding` objects that are subsequently incorporated into the SARIF or JSON output.

## Summary

- **Use `--yara-rules-dir`** followed by your directory path to load custom YARA rules alongside built-in signatures.
- **Rule namespaces** are automatically generated from file names to prevent collisions between custom and built-in rules.
- **Compilation caching** hashes the rule file list to reuse compiled rules when directory contents remain unchanged.
- **Graceful degradation** occurs if the custom directory is missing; SkillSpector logs a warning and continues with built-in rules only.
- **Implementation** spans three key files: [`cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/cli.py) for argument parsing, [`state.py`](https://github.com/NVIDIA/SkillSpector/blob/main/state.py) for runtime storage, and [`static_yara.py`](https://github.com/NVIDIA/SkillSpector/blob/main/static_yara.py) for rule compilation and execution.

## Frequently Asked Questions

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

SkillSpector validates the path during the loading phase in [`src/skillspector/nodes/analyzers/static_yara.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/analyzers/static_yara.py). If the specified directory does not exist, the tool logs a warning message and proceeds with the scan using only the built-in rules from `src/skillspector/yara_rules/`. The scan will not fail, but your custom signatures will not be applied.

### Can I replace the built-in rules entirely with my own custom rules?

No, the `--yara-rules-dir` flag is designed to supplement, not replace, the built-in rule set. SkillSpector always loads its internal rules from `src/skillspector/yara_rules/` and merges them with your custom rules. To exclude specific built-in rules, you would need to modify the source code or filter the results during post-processing.

### What file extensions does SkillSpector recognize for YARA rules?

The analyzer specifically looks for files ending with `.yar` or `.yara` in the `_load_rules` function. Any other file extensions in your custom directory will be ignored during the rule collection phase. Ensure your rule files use these standard extensions to be included in the compilation.

### How does SkillSpector handle rule name conflicts between custom and built-in rules?

The `_load_rules` function automatically generates namespaces based on file names. If two rules share the same name, the system uses a `parent/name` format to differentiate them, ensuring that custom rules do not collide with built-in signatures or vice versa during the compilation phase.