How to Configure SkillSpector to Use a Custom YARA Rules Directory

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.

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:

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

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

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:

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 for argument parsing, state.py for runtime storage, and 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}