How to Run SkillSpector in Offline or Air-Gapped Environments: Complete Guide

SkillSpector operates fully without network access by automatically falling back to built-in static vulnerability lists when external APIs are unreachable and disabling LLM analysis with the --no-llm flag.

Running NVIDIA/SkillSpector in offline or air-gapped environments requires no special configuration because the tool is architected to separate core static analysis from optional network-dependent features. When external connectivity is unavailable, SkillSpector automatically switches to offline-compatible modes while maintaining full scanning capability for supply-chain and code security issues.

Understanding SkillSpector's Network Architecture

SkillSpector divides its analysis pipeline into three distinct components, each with different network requirements. This design ensures that static analysis—the core security engine—never requires external connectivity, while optional features gracefully degrade when network access is unavailable.

Static Pattern Matching (No Network Required)

The foundation of SkillSpector's scanning capability operates entirely locally. This includes regex pattern matching, AST traversal, YARA rules, and supply-chain static lists. These analyzers run completely within the host environment without attempting external connections, making them always available in air-gapped installations.

OSV.dev Live Lookup with Automatic Fallback

The SC4 analyzer (Supply Chain Component 4) typically queries https://api.osv.dev for up-to-date CVE data during scans. However, according to the source code in src/skillspector/nodes/analyzers/static_patterns_supply_chain.py, the tool implements a robust fallback mechanism: when the HTTPS request fails due to network isolation, the analyzer automatically calls _sc4_from_fallback() to emit findings from a built-in static vulnerability list (_FALLBACK_VULNERABLE_*).

This fallback path ensures that high-severity supply-chain issues are still detected even without live data, though the static list is deliberately smaller than the live database.

Optional LLM Analysis (Network Required)

LLM-based semantic analysis requires an outbound API connection to the configured provider. Unlike the OSV lookup, this feature has no offline fallback and must be explicitly disabled when running air-gapped.

How Offline Mode Activates Automatically

SkillSpector does not require a specific --offline flag. Instead, the network failure detection in src/skillspector/nodes/analyzers/osv_client.py handles the transition automatically:

1. The OSV client attempts a POST to https://api.osv.dev/v1/querybatch at runtime.
2. On timeout, connection error, or any non-200 response, the client records the failure.
3. The function was_osv_reachable() returns False, signaling the SC4 analyzer to use the static fallback.

Simply ensuring the host cannot reach api.osv.dev—whether through physical disconnection, firewall rules, or sandboxed execution—automatically triggers SkillSpector's offline mode.

Running SkillSpector in Air-Gapped Environments

To guarantee zero external network traffic while maintaining full scanning capability, disable the LLM analyzer and rely on the automatic OSV fallback.

Command Line Execution

Use the --no-llm flag to prevent any outbound API calls for semantic analysis:

# Scan with static analysis only (recommended for air-gapped environments)

skillspector scan ./my-skill/ --no-llm

The static analysis engine will execute normally, and the OSV client will automatically fall back to the built-in vulnerability list if it cannot reach the external API.

Docker Deployment Without Network Access

For containerized deployments in isolated environments, build the image once on a machine with internet access, then transfer and run it without network connectivity:

# Build on connected machine

make docker-build

# Run on air-gapped host with network disabled

docker run --rm \
  -v "$PWD:/scan" \
  --network none \
  skillspector scan /scan --no-llm

The --network none flag enforces the offline guarantee at the container runtime level, ensuring no accidental external connections.

Verifying Offline Operation

To confirm that SkillSpector is operating in offline mode and using the fallback vulnerability list, you can check the OSV reachability status programmatically:

from skillspector.nodes.analyzers.osv_client import was_osv_reachable

print("OSV reachable:", was_osv_reachable())

# Expected output in offline mode: OSV reachable: False

When running the scan, observe the logs for warnings indicating the fallback to static vulnerability lists—these confirm that static_patterns_supply_chain.py has invoked _sc4_from_fallback() due to the unavailable network.

Summary

• SkillSpector separates static analysis (always local) from optional network features (OSV live lookup and LLM analysis).
• Automatic fallback: When api.osv.dev is unreachable, the SC4 analyzer in src/skillspector/nodes/analyzers/static_patterns_supply_chain.py automatically switches to the built-in static vulnerability list via _sc4_from_fallback().
• Disable LLM: Use --no-llm to guarantee no outbound API calls, as the LLM analyzer has no offline capability.
• Docker support: Build images on connected hosts, then run with --network none for complete isolation.
• No special flags needed: The tool detects network unavailability through was_osv_reachable() in src/skillspector/nodes/analyzers/osv_client.py and adapts automatically.

Frequently Asked Questions

Does SkillSpector require internet access to function?

No. SkillSpector's core security scanning functionality—including regex pattern matching, AST analysis, YARA rules, and supply-chain static analysis—operates entirely without network access. The tool only requires internet connectivity for optional features like live OSV vulnerability lookups (which fall back to static lists when offline) and LLM-based semantic analysis (which can be disabled).

What vulnerabilities are detected when running SkillSpector offline?

When operating offline, SkillSpector detects vulnerabilities from two sources: static pattern matching (covering regex signatures, AST patterns, and YARA rules) and the built-in fallback vulnerability list (_FALLBACK_VULNERABLE_*) in the SC4 analyzer. While this static list is smaller than the live OSV database, it deliberately includes high-severity supply-chain issues to minimize false negatives in air-gapped environments.

How do I completely disable network access for LLM analysis?

Explicitly pass the --no-llm flag when executing the scan command. This prevents SkillSpector from attempting any outbound connections to configured LLM providers, ensuring that only local static analysis runs. Unlike the OSV lookup, which has an automatic fallback, the LLM analyzer must be manually disabled because it cannot function without network access.

Can I use Docker to run SkillSpector in an air-gapped environment?

Yes. Build the Docker image on a machine with internet access using make docker-build, transfer the image to your isolated environment, and run it with the --network none flag combined with --no-llm. This configuration ensures the container has no network interface and cannot attempt external connections, making it suitable for high-security air-gapped deployments.

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