How to Reduce False Positives from Static Pattern Matching in SkillSpector

SkillSpector reduces false positives through three built-in filters—safe-container detection, Dockerfile idiom validation, and documentation-example filtering—that downgrade benign matches to low-confidence findings.

SkillSpector's static analyzers scan codebases for risky patterns like tool misuse and privilege escalation, but benign code can trigger false alarms. To reduce false positives from static pattern matching, the NVIDIA repository implements contextual validation helpers that examine surrounding code before reporting a match. These mechanisms distinguish between malicious commands and legitimate Docker operations, cleanup scripts, or tutorial comments.

Built-In False Positive Mitigation Mechanisms

SkillSpector's analyzers in static_patterns_tool_misuse.py and static_patterns_privilege_escalation.py employ three core validation layers that run automatically when patterns match.

Safe-Container Detection

The _is_safe_container_command() helper skips matches that correspond to typical Docker or Podman workflows. Located in static_patterns_tool_misuse.py (lines 77-80), this function checks the surrounding text for known safe container invocations before flagging a pattern as malicious.

When this check returns True, the analyzer caps the confidence score at 0.15 and downgrades the severity to LOW, effectively filtering out benign container operations that resemble dangerous commands.

Safe-Dockerfile Idiom Detection

The _is_safe_dockerfile_idiom() function (lines 82-86 in static_patterns_tool_misuse.py) validates that a match occurs within a Dockerfile context and aligns with a whitelist of harmless idioms. This prevents false positives from common cleanup commands like rm -rf /tmp or base image setup steps that appear destructive but are standard practice.

Documentation-Example Filtering

The _is_documentation_example() helper in static_patterns_privilege_escalation.py (lines 62-73) scans surrounding context for markers such as "example:", "# note:", or code fences (```). This ensures that tutorial comments and documentation snippets mentioning sudo or elevated privileges do not trigger security alerts.

Fine-Tuning Strategies to Reduce False Positives

Beyond the built-in filters, operators can tune the static analysis pipeline through four extension points.

Adjust Confidence Thresholds

Each pattern tuple carries a baseline confidence value (e.g., 0.8 for shell=True patterns). Raising this threshold or adding custom multipliers in the analyzer's loop makes the detector stricter. For example, modifying the adjustment logic to adj = min(confidence, 0.15) for safe matches ensures that even borderline suspicious patterns receive low confidence scores.

Extend Safe-List Helpers

Add regular expressions to the _SAFE_CONTAINER_PATTERNS or _SAFE_DOCKERFILE_PATTERNS tuples in static_patterns_tool_misuse.py to accommodate new tooling conventions. This whitelist approach lets you define domain-specific exceptions without modifying core detection logic.

Enrich Documentation Markers

Expand the doc_indicators tuple in _is_documentation_example() to include project-specific comment patterns like "TODO:", "FIXME:", or custom documentation tags. This prevents flagging of maintenance notes or implementation guides that contain risky-looking code samples.

Implement Per-Skill Whitelists

Leverage the SkillspectorState object to carry user-defined whitelists that the analyzer consults before reporting. By extending state.custom_whitelists and checking it within the analyze functions, teams can silence known-good patterns on a per-skill basis without modifying the core analyzer code.

Practical Code Examples

Adding a New Safe Container Pattern

Extend the safe-list in static_patterns_tool_misuse.py to recognize Kubernetes dry-run commands:

# In static_patterns_tool_misuse.py

_SAFE_CONTAINER_PATTERNS = (
    re.compile(r"docker\s+run\s+.*--rm", re.IGNORECASE),
    # New safe pattern for Kubernetes `kubectl apply` with a dry-run flag

    re.compile(r"kubectl\s+apply\s+.*--dry-run", re.IGNORECASE),
)

Now a line like kubectl apply -f deployment.yaml --dry-run=client will be treated as benign.

Raising Confidence Thresholds

Increase the baseline confidence for the destructive removal pattern to reduce noise:

# Reduce false positives for the generic “rm -rf /” pattern

TM1_PATTERNS = [
    (r"\b(?:rm|shutil\.rmtree)\s*\(?[^)\n]{0,80}['\"]?\s*/\s*['\"]?", 0.85),  # increased from 0.8

    # … other patterns unchanged …

]

A higher base confidence means that even after the safe-list downgrade, the detector requires a stronger signal to surface a warning.

Extending Documentation Detection

Add custom tutorial markers to the documentation filter:

# In static_patterns_privilege_escalation.py

def _is_documentation_example(context: str, file_type: str) -> bool:
    ctx_lower = context.lower()
    doc_indicators = (
        "example:",
        "for example",
        "e.g.",
        "# note:",

        "# warning:",

        "```",
        # New project-specific marker

        "/// tutorial:",
    )
    return any(ind in ctx_lower for ind in doc_indicators)

Any occurrence of /// tutorial: will now suppress a false positive.

Using Per-Skill Whitelists via SkillspectorState

Implement runtime custom whitelisting through the state object:

# In a custom extension module

def node(state: SkillspectorState) -> AnalyzerNodeResponse:
    # Add a file-specific whitelist at runtime

    state.custom_whitelists.setdefault(state.file_path, []).append(
        re.compile(r"my_custom_safe_pattern")
    )
    findings = static_runner.run_static_patterns(state, [sys.modules[__name__]])
    return {"findings": findings}

The analyzer will check state.custom_whitelists before computing confidence, allowing teams to silence known-good patterns on a per-skill basis.

Summary

• Safe-container and Dockerfile idiom detection automatically downgrade benign container operations to low-severity findings.
• Documentation filtering prevents tutorial comments and code examples from triggering alerts.
• Confidence threshold adjustments let you tune the sensitivity of specific pattern matchers.
• Per-skill whitelists via SkillspectorState enable runtime customization without core code changes.

Frequently Asked Questions

What causes false positives in static pattern matching?

False positives occur when a regex pattern matches benign code that superficially resembles malicious behavior. Common examples include Dockerfile cleanup commands that look like destructive rm -rf / operations, or documentation comments that mention sudo for illustrative purposes. SkillSpector's contextual helpers examine surrounding code to distinguish these legitimate patterns from actual security risks.

How does SkillSpector detect safe container commands?

The _is_safe_container_command() function in static_patterns_tool_misuse.py checks matched text against the _SAFE_CONTAINER_PATTERNS tuple, which contains regular expressions for known-safe Docker and Podman invocations. When a match aligns with these patterns, the analyzer reduces the confidence score to 0.15 and assigns a LOW severity, effectively filtering out standard container workflows.

Can I customize confidence thresholds for specific patterns?

Yes, each pattern definition in files like static_patterns_tool_misuse.py includes a baseline confidence value (e.g., 0.8 for shell execution patterns). You can raise this value to make the detector more conservative, or implement conditional logic in the analysis loop that applies additional multipliers based on file type or context. This fine-tuning allows you to balance security coverage against noise levels for your specific codebase.

How do I add project-specific patterns to the whitelist?

Extend the SkillspectorState object's custom_whitelists dictionary at runtime to include file-specific or skill-specific regular expressions. Alternatively, modify the _SAFE_CONTAINER_PATTERNS, _SAFE_DOCKERFILE_PATTERNS, or doc_indicators tuples in the respective analyzer files to include project-specific conventions. Both approaches allow you to maintain clean security reports while preserving the ability to detect genuine risks.

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