fix: support OpenAI-compatible LLM endpoints (#103)

Allow explicit provider selection to override model-name inference so custom OpenAI-compatible models are not misrouted to Gemini.

Author: vineethsai7

.env.example

@@ -5,6 +5,12 @@
 # SKILL_SCANNER_LLM_API_KEY=your_api_key
 # SKILL_SCANNER_LLM_MODEL=claude-3-5-sonnet-20241022
 
+# OpenAI-compatible custom endpoint
+# SKILL_SCANNER_LLM_API_KEY=your_custom_provider_key
+# SKILL_SCANNER_LLM_PROVIDER=openai
+# SKILL_SCANNER_LLM_MODEL=Cloud-Gemini-3.1-Pro
+# SKILL_SCANNER_LLM_BASE_URL=https://your.internal.llm/v1
+
 # Azure OpenAI
 # SKILL_SCANNER_LLM_API_KEY=your_azure_key
 # SKILL_SCANNER_LLM_MODEL=azure/gpt-4.1

docs/reference/cli-command-reference.md

@@ -35,8 +35,7 @@ Flags shared by `scan` and `scan-all`:
 | `--enable-meta` | off | Enable the meta (cross-correlation) analyzer |
 | `--fail-on-findings` | off | Exit non-zero if critical or high findings are reported; equivalent to `--fail-on-severity high` (CI gate) |
 | `--fail-on-severity LEVEL` | off | Exit non-zero if findings at or above LEVEL exist (critical, high, medium, low, info) |
-| `--lenient` | off | Tolerate malformed skills: coerce bad fields, fill defaults, and continue instead of failing. When `SKILL.md` is absent, falls back to scanning `.md` files in the directory |
-| `--skill-file FILENAME` | `SKILL.md` | Custom metadata filename to use instead of `SKILL.md` |
+| `--lenient` | off | Tolerate malformed YAML / missing fields: coerce bad fields, fill defaults, and continue instead of failing. Binary and non-UTF-8 files always fail. |
 | `--detailed` | off | Include full evidence in output |
 | `--compact` | off | Minimize output (JSON: no pretty-print) |
 | `--verbose` | off | Verbose logging |
@@ -50,7 +49,8 @@ Command: `python -m skill_scanner.cli.cli --help`
 
 ```text
 usage: cli.py [-h] [--version]
-              {scan,scan-all,list-analyzers,validate-rules,generate-policy,configure-policy,interactive} ...
+              {scan,scan-all,list-analyzers,validate-rules,generate-policy,configure-policy,interactive}
+              ...
 
 Skill Scanner - Security scanner for agent skills packages
 
@@ -104,10 +104,11 @@ usage: cli.py scan [-h] [--format {summary,json,markdown,table,sarif,html}]
                    [--vt-upload-files] [--use-aidefense]
                    [--aidefense-api-key AIDEFENSE_API_KEY]
                    [--aidefense-api-url AIDEFENSE_API_URL]
-                   [--llm-provider {anthropic,openai}]
+                   [--llm-provider {anthropic,openai,openai-compatible}]
                    [--llm-consensus-runs N] [--llm-max-tokens N]
                    [--use-trigger] [--enable-meta] [--policy PRESET_OR_PATH]
-                   [--lenient] [--custom-rules PATH] [--taxonomy PATH]
+                   [--lenient] [--skill-file FILENAME] [--custom-rules PATH]
+                   [--rule-packs PACK [PACK ...]] [--taxonomy PATH]
                    [--threat-mapping PATH]
                    skill_directory
 
@@ -121,7 +122,8 @@ options:
                         multiple times to produce several reports in one run,
                         e.g. --format markdown --format sarif. Use 'sarif' for
                         GitHub Code Scanning, 'html' for interactive report.
-  --output, -o OUTPUT   Default output file path (overridden by --output-<fmt>
+  --output OUTPUT, -o OUTPUT
+                        Default output file path (overridden by --output-<fmt>
                         for a specific format)
   --output-json OUTPUT_JSON
                         Write JSON report to this file
@@ -157,8 +159,9 @@ options:
                         AI Defense API key (or set AI_DEFENSE_API_KEY)
   --aidefense-api-url AIDEFENSE_API_URL
                         AI Defense API URL (optional, defaults to US region)
-  --llm-provider {anthropic,openai}
-                        LLM provider
+  --llm-provider {anthropic,openai,openai-compatible}
+                        LLM provider shortcut or explicit OpenAI-compatible
+                        override
   --llm-consensus-runs N
                         Run LLM analysis N times and keep only findings with
                         majority agreement (reduces false positives, increases
@@ -171,9 +174,19 @@ options:
                         Scan policy: preset name (strict, balanced,
                         permissive) or path to custom YAML
   --lenient             Tolerate malformed skills: coerce bad fields, fill
-                        defaults, and continue instead of failing
+                        defaults, and continue instead of failing. When
+                        SKILL.md is absent, falls back to scanning .md files
+                        in the directory as instruction bodies (supports non-
+                        Codex/Cursor formats such as Claude Code commands).
+  --skill-file FILENAME
+                        Custom metadata filename to use instead of SKILL.md
+                        (e.g. README.md)
   --custom-rules PATH   Path to directory containing custom YARA rules (.yara
                         files)
+  --rule-packs PACK [PACK ...]
+                        Additional signature rule packs to enable (e.g.
+                        'atr'). Use '--rule-packs list' to show available
+                        packs.
   --taxonomy PATH       Path to custom taxonomy JSON/YAML (overrides
                         SKILL_SCANNER_TAXONOMY_PATH)
   --threat-mapping PATH
@@ -206,11 +219,12 @@ usage: cli.py scan-all [-h] [--recursive] [--check-overlap]
                        [--use-aidefense]
                        [--aidefense-api-key AIDEFENSE_API_KEY]
                        [--aidefense-api-url AIDEFENSE_API_URL]
-                       [--llm-provider {anthropic,openai}]
+                       [--llm-provider {anthropic,openai,openai-compatible}]
                        [--llm-consensus-runs N] [--llm-max-tokens N]
                        [--use-trigger] [--enable-meta]
                        [--policy PRESET_OR_PATH] [--lenient]
-                       [--custom-rules PATH] [--taxonomy PATH]
+                       [--skill-file FILENAME] [--custom-rules PATH]
+                       [--rule-packs PACK [PACK ...]] [--taxonomy PATH]
                        [--threat-mapping PATH]
                        skills_directory
 
@@ -226,7 +240,8 @@ options:
                         multiple times to produce several reports in one run,
                         e.g. --format markdown --format sarif. Use 'sarif' for
                         GitHub Code Scanning, 'html' for interactive report.
-  --output, -o OUTPUT   Default output file path (overridden by --output-<fmt>
+  --output OUTPUT, -o OUTPUT
+                        Default output file path (overridden by --output-<fmt>
                         for a specific format)
   --output-json OUTPUT_JSON
                         Write JSON report to this file
@@ -262,8 +277,9 @@ options:
                         AI Defense API key (or set AI_DEFENSE_API_KEY)
   --aidefense-api-url AIDEFENSE_API_URL
                         AI Defense API URL (optional, defaults to US region)
-  --llm-provider {anthropic,openai}
-                        LLM provider
+  --llm-provider {anthropic,openai,openai-compatible}
+                        LLM provider shortcut or explicit OpenAI-compatible
+                        override
   --llm-consensus-runs N
                         Run LLM analysis N times and keep only findings with
                         majority agreement (reduces false positives, increases
@@ -276,9 +292,19 @@ options:
                         Scan policy: preset name (strict, balanced,
                         permissive) or path to custom YAML
   --lenient             Tolerate malformed skills: coerce bad fields, fill
-                        defaults, and continue instead of failing
+                        defaults, and continue instead of failing. When
+                        SKILL.md is absent, falls back to scanning .md files
+                        in the directory as instruction bodies (supports non-
+                        Codex/Cursor formats such as Claude Code commands).
+  --skill-file FILENAME
+                        Custom metadata filename to use instead of SKILL.md
+                        (e.g. README.md)
   --custom-rules PATH   Path to directory containing custom YARA rules (.yara
                         files)
+  --rule-packs PACK [PACK ...]
+                        Additional signature rule packs to enable (e.g.
+                        'atr'). Use '--rule-packs list' to show available
+                        packs.
   --taxonomy PATH       Path to custom taxonomy JSON/YAML (overrides
                         SKILL_SCANNER_TAXONOMY_PATH)
   --threat-mapping PATH
@@ -320,7 +346,8 @@ usage: cli.py generate-policy [-h] [--output OUTPUT]
 
 options:
   -h, --help            show this help message and exit
-  --output, -o OUTPUT   Output file path
+  --output OUTPUT, -o OUTPUT
+                        Output file path
   --preset {strict,balanced,permissive}
                         Base preset
 ```
@@ -338,9 +365,11 @@ Command: `python -m skill_scanner.cli.cli configure-policy --help`
 usage: cli.py configure-policy [-h] [--output OUTPUT] [--input INPUT]
 
 options:
-  -h, --help           show this help message and exit
-  --output, -o OUTPUT  Output file path
-  --input, -i INPUT    Load existing policy YAML for editing
+  -h, --help            show this help message and exit
+  --output OUTPUT, -o OUTPUT
+                        Output file path
+  --input INPUT, -i INPUT
+                        Load existing policy YAML for editing
 ```
 
 </details>

docs/reference/configuration-reference.md

@@ -25,6 +25,7 @@ Primary settings for the LLM semantic analyzer.
 |---|---|---|
 | `SKILL_SCANNER_LLM_API_KEY` | Primary API key for LLM analyzer and meta fallback. **(required)** | `sk-ant-...` |
 | `SKILL_SCANNER_LLM_MODEL` | Primary model identifier for semantic analysis. | `anthropic/claude-sonnet-4-20250514` |
+| `SKILL_SCANNER_LLM_PROVIDER` | Optional provider override, including OpenAI-compatible custom endpoint routing. | `openai` |
 | `SKILL_SCANNER_LLM_BASE_URL` | Optional custom endpoint base URL for provider routing. | `https://api.openai.com/v1` |
 | `SKILL_SCANNER_LLM_API_VERSION` | Optional API version for providers that require one. | `2024-02-15-preview` |
 | `SKILL_SCANNER_LLM_FORCE_JSON_OBJECT` | Skip json_schema and start in plain JSON mode for incompatible proxies. | `true` |
@@ -120,6 +121,7 @@ Paths, allowlists, and other advanced settings.
 | `SKILL_SCANNER_LLM_BASE_URL` | `.env.example`, `skill_scanner/cli/cli.py`, `skill_scanner/core/analyzer_factory.py`, `skill_scanner/core/analyzers/meta_analyzer.py` |
 | `SKILL_SCANNER_LLM_FORCE_JSON_OBJECT` | `.env.example` |
 | `SKILL_SCANNER_LLM_MODEL` | `.env.example`, `skill_scanner/cli/cli.py`, `skill_scanner/config/config.py`, `skill_scanner/core/analyzer_factory.py`, `skill_scanner/core/analyzers/behavioral_analyzer.py`, `skill_scanner/core/analyzers/llm_analyzer.py`, `skill_scanner/core/analyzers/meta_analyzer.py` |
+| `SKILL_SCANNER_LLM_PROVIDER` | `.env.example`, `skill_scanner/core/analyzer_factory.py`, `skill_scanner/core/analyzers/llm_provider_config.py` |
 | `SKILL_SCANNER_META_LLM_API_KEY` | `.env.example`, `skill_scanner/cli/cli.py`, `skill_scanner/core/analyzers/meta_analyzer.py` |
 | `SKILL_SCANNER_META_LLM_API_VERSION` | `.env.example`, `skill_scanner/cli/cli.py`, `skill_scanner/core/analyzers/meta_analyzer.py` |
 | `SKILL_SCANNER_META_LLM_BASE_URL` | `.env.example`, `skill_scanner/cli/cli.py`, `skill_scanner/core/analyzers/meta_analyzer.py` |

docs/reference/dependencies-and-llm-providers.md

@@ -90,6 +90,7 @@ Set `SKILL_SCANNER_LLM_MODEL` using the provider prefix convention:
 |----------|--------------|-------|
 | Anthropic | `anthropic/claude-sonnet-4-20250514` | Default provider |
 | OpenAI | `openai/gpt-4o` | |
+| OpenAI-compatible custom endpoint | `Cloud-Gemini-3.1-Pro` with `SKILL_SCANNER_LLM_PROVIDER=openai` | Uses `SKILL_SCANNER_LLM_BASE_URL` |
 | AWS Bedrock | `bedrock/anthropic.claude-sonnet-4-20250514-v1:0` | Requires `[bedrock]` extra or API key |
 | Google Vertex AI | `vertex_ai/gemini-2.5-pro` | Requires `[vertex]` extra |
 | Google AI Studio | `gemini/gemini-2.5-flash` | Requires `[google]` extra |
@@ -102,6 +103,7 @@ Set `SKILL_SCANNER_LLM_MODEL` using the provider prefix convention:
 |----------|-------------|-------------------|
 | Anthropic | API key | `SKILL_SCANNER_LLM_API_KEY` |
 | OpenAI | API key | `SKILL_SCANNER_LLM_API_KEY` |
+| OpenAI-compatible custom endpoint | API key + endpoint | `SKILL_SCANNER_LLM_API_KEY`, `SKILL_SCANNER_LLM_PROVIDER=openai`, `SKILL_SCANNER_LLM_BASE_URL` |
 | AWS Bedrock (API key) | API key | `SKILL_SCANNER_LLM_API_KEY` |
 | AWS Bedrock (IAM) | AWS credentials | `AWS_REGION`, `AWS_PROFILE` (optional: `AWS_SESSION_TOKEN`) |
 | Google Vertex AI | Service account | `GOOGLE_APPLICATION_CREDENTIALS` |

docs/user-guide/installation-and-configuration.md

@@ -51,6 +51,7 @@ You only need to set these if you're using the corresponding features. Click a s
 <summary>Core LLM</summary>
 
 - `SKILL_SCANNER_LLM_API_KEY`
+- `SKILL_SCANNER_LLM_PROVIDER` — set to `openai` for OpenAI-compatible custom endpoints when the model name is not enough to infer routing
 - `SKILL_SCANNER_LLM_MODEL`
 - `SKILL_SCANNER_LLM_BASE_URL`
 - `SKILL_SCANNER_LLM_API_VERSION`

examples/llm_analyzer_example.py

@@ -26,6 +26,9 @@
 Prerequisites:
     export SKILL_SCANNER_LLM_API_KEY="your_key"
     export SKILL_SCANNER_LLM_MODEL="claude-3-5-sonnet-20241022"  # or gpt-4o
+    # For OpenAI-compatible custom endpoints:
+    # export SKILL_SCANNER_LLM_PROVIDER="openai"
+    # export SKILL_SCANNER_LLM_BASE_URL="https://your.internal.llm/v1"
     pip install cisco-ai-skill-scanner[llm]
 
 Usage:
@@ -40,7 +43,7 @@
 from skill_scanner.core.analyzers.static import StaticAnalyzer
 
 try:
-    from skill_scanner.core.analyzers.llm_analyzer import LLMAnalyzer, LLMProvider
+    from skill_scanner.core.analyzers.llm_analyzer import LLMAnalyzer
 
     LLM_AVAILABLE = True
 except ImportError:
@@ -69,12 +72,19 @@ def main():
         return 1
 
     model = os.getenv("SKILL_SCANNER_LLM_MODEL", "claude-3-5-sonnet-20241022")
+    provider = os.getenv("SKILL_SCANNER_LLM_PROVIDER")
+    base_url = os.getenv("SKILL_SCANNER_LLM_BASE_URL")
+    api_version = os.getenv("SKILL_SCANNER_LLM_API_VERSION")
 
     print(f"{'=' * 60}")
     print("LLM Analyzer Example")
     print(f"{'=' * 60}")
     print(f"Skill: {skill_path}")
     print(f"Model: {model}")
+    if provider:
+        print(f"Provider: {provider}")
+    if base_url:
+        print(f"Base URL: {base_url}")
     print()
 
     # Scan with static analyzer only
@@ -88,7 +98,13 @@ def main():
 
     # Scan with LLM analyzer
     print("Step 2: Scanning with LLM Analyzer...")
-    llm_analyzer = LLMAnalyzer(model=model, api_key=api_key)
+    llm_analyzer = LLMAnalyzer(
+        model=model,
+        api_key=api_key,
+        provider=provider,
+        base_url=base_url,
+        api_version=api_version,
+    )
     llm_scanner = SkillScanner(analyzers=[llm_analyzer])
     llm_result = llm_scanner.scan_skill(skill_path)
 

scripts/generate_reference_docs.py

@@ -391,6 +391,7 @@ def _describe_env_var(var: str) -> str:
     descriptions = {
         "SKILL_SCANNER_LLM_API_KEY": "Primary API key for LLM analyzer and meta fallback.",
         "SKILL_SCANNER_LLM_MODEL": "Primary model identifier for semantic analysis.",
+        "SKILL_SCANNER_LLM_PROVIDER": "Optional provider override, including OpenAI-compatible custom endpoint routing.",
         "SKILL_SCANNER_LLM_BASE_URL": "Optional custom endpoint base URL for provider routing.",
         "SKILL_SCANNER_LLM_API_VERSION": "Optional API version for providers that require one.",
         "SKILL_SCANNER_LLM_FORCE_JSON_OBJECT": "Skip json_schema and start in plain JSON mode for incompatible proxies.",
@@ -425,6 +426,7 @@ def _describe_env_var(var: str) -> str:
         [
             "SKILL_SCANNER_LLM_API_KEY",
             "SKILL_SCANNER_LLM_MODEL",
+            "SKILL_SCANNER_LLM_PROVIDER",
             "SKILL_SCANNER_LLM_BASE_URL",
             "SKILL_SCANNER_LLM_API_VERSION",
             "SKILL_SCANNER_LLM_FORCE_JSON_OBJECT",
@@ -484,6 +486,7 @@ def _describe_env_var(var: str) -> str:
 _ENV_VAR_EXAMPLES: dict[str, str] = {
     "SKILL_SCANNER_LLM_API_KEY": "sk-ant-...",
     "SKILL_SCANNER_LLM_MODEL": "anthropic/claude-sonnet-4-20250514",
+    "SKILL_SCANNER_LLM_PROVIDER": "openai",
     "SKILL_SCANNER_LLM_BASE_URL": "https://api.openai.com/v1",
     "SKILL_SCANNER_LLM_API_VERSION": "2024-02-15-preview",
     "SKILL_SCANNER_LLM_FORCE_JSON_OBJECT": "true",

skill_scanner/cli/cli.py

@@ -799,7 +799,12 @@ def _add_common_scan_flags(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--use-aidefense", action="store_true", help="Enable AI Defense analyzer (requires API key)")
     parser.add_argument("--aidefense-api-key", help="AI Defense API key (or set AI_DEFENSE_API_KEY)")
     parser.add_argument("--aidefense-api-url", help="AI Defense API URL (optional, defaults to US region)")
-    parser.add_argument("--llm-provider", choices=["anthropic", "openai"], default="anthropic", help="LLM provider")
+    parser.add_argument(
+        "--llm-provider",
+        choices=["anthropic", "openai", "openai-compatible"],
+        default=None,
+        help="LLM provider shortcut or explicit OpenAI-compatible override",
+    )
     parser.add_argument(
         "--llm-consensus-runs",
         type=int,

skill_scanner/core/analyzer_factory.py

@@ -142,22 +142,27 @@ def build_analyzers(
         try:
             from .analyzers.llm_analyzer import LLMAnalyzer
 
-            model = llm_model or os.getenv("SKILL_SCANNER_LLM_MODEL") or "claude-3-5-sonnet-20241022"
+            env_model = os.getenv("SKILL_SCANNER_LLM_MODEL")
+            model = llm_model or env_model
             key = llm_api_key or os.getenv("SKILL_SCANNER_LLM_API_KEY")
             base_url = llm_base_url or os.getenv("SKILL_SCANNER_LLM_BASE_URL")
             api_version = llm_api_version or os.getenv("SKILL_SCANNER_LLM_API_VERSION")
+            provider = llm_provider or os.getenv("SKILL_SCANNER_LLM_PROVIDER")
             extra_kwargs: dict = {}
             effective_max_tokens = (
                 llm_max_tokens if llm_max_tokens is not None else policy.llm_analysis.max_output_tokens
             )
             if effective_max_tokens is not None:
                 extra_kwargs["max_tokens"] = effective_max_tokens
-            if llm_provider and not llm_model and not os.getenv("SKILL_SCANNER_LLM_MODEL"):
-                llm = LLMAnalyzer(provider=llm_provider, policy=policy, **extra_kwargs)
-            else:
-                llm = LLMAnalyzer(
-                    model=model, api_key=key, base_url=base_url, api_version=api_version, policy=policy, **extra_kwargs
-                )
+            llm = LLMAnalyzer(
+                model=model,
+                api_key=key,
+                base_url=base_url,
+                api_version=api_version,
+                provider=provider,
+                policy=policy,
+                **extra_kwargs,
+            )
             if llm_consensus_runs > 1:
                 llm.consensus_runs = llm_consensus_runs
             analyzers.append(llm)