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

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.

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:

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

When you provide the --yara-rules-dir argument, the CLI entry point in 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.

Rule Loading and Compilation in static_yara.py

The analyzer node in 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:

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

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:

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.
• The _load_rules function in 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, 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. These rules are always loaded and merged with your custom rules during every scan execution.

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