merge: sync with NVIDIA/SkillSpector 2.12.0

.claude/rules/allowed-tools-separator.md

@@ -4,10 +4,9 @@ paths:
   - "src/skillspector/nodes/analyzers/mcp_least_privilege.py"
 ---
 
-# `allowed-tools` separator — known deviation, do not fix in passing
+# `allowed-tools` scoped syntax — known defect, do not fix in passing
 
-- Both files split the Agent Skills `allowed-tools` frontmatter field on **commas** (`build_context.py:304`, `mcp_least_privilege.py:143`). The specification defines it as **space**-separated. This is a known, deliberate deviation — not an oversight.
-- **Do not change it as part of unrelated work.** Correcting the separator changes findings on inputs scanned today, which violates the repo's behavior-preservation constraint. It needs its own decision, changelog entry, and version bump.
-- Neither call site has direct test coverage, so a change here fails silently in the suite. Downstream consumers are `_map_allowed_tools_to_categories` and the `has_declaration` branch (`mcp_least_privilege.py:190`, `:334`), which drive LP1, LP3, and LP4.
-- Reopen conditions, blast radius, and the migration checklist: `docs/MULTI_FRAMEWORK_SKILL_ANALYSIS.md` § Known deviation.
-- A second, independent defect lives here: scoped syntax (`Bash(git:*)`) does not match `_TOOL_TO_CAPABILITY` even with correct whitespace splitting. Fixing one does not fix the other.
+- Scoped tool syntax (`Bash(git:*)`) does not map to a capability: `_map_allowed_tools_to_categories` looks the whole token up in `_TOOL_TO_CAPABILITY`, so it matches nothing. A skill declaring only scoped tools has a declaration and an empty capability set, which drives LP1, LP3 and LP4.
+- **Do not change it as part of unrelated work.** Extracting the base tool name changes findings on inputs scanned today, which violates the repo's behavior-preservation constraint. It needs its own decision and changelog entry.
+- The separator is no longer a deviation. Both parsers split on whitespace, or on commas when the value contains one, since upstream `1b87593`. Do not "restore" comma-only splitting.
+- Background: `docs/MULTI_FRAMEWORK_SKILL_ANALYSIS.md` § Closed deviation.

.claude/rules/analyzers.md

@@ -6,15 +6,17 @@ paths:
 
 # Analyzer nodes
 
-Full walkthrough: `docs/DEVELOPMENT.md` §9. Signatures and the registration facts that doc omits:
+Full walkthrough: `docs/DEVELOPMENT.md` §9, whose registration steps are upstream text that still describes hand-editing `__init__.py` — that part is stale, and the bullets below win. Signatures and registration:
 
 - A node is `node(state: SkillspectorState) -> AnalyzerNodeResponse`, returning `{"findings": list[Finding]}`.
 - A static pattern module exposes `analyze(content: str, file_path: str, file_type: str) -> list[AnalyzerFinding]` and is driven by `static_runner.run_static_patterns`. Take category and remediation text from `pattern_defaults`.
-- Registering means editing `nodes/analyzers/__init__.py` twice, in the same relative order: append the id to `ANALYZER_NODE_IDS` and add the matching key to `ANALYZER_NODES`. `graph.py` needs no change — its edges are generated from `ANALYZER_NODE_IDS` in a loop.
-- Then update `EXPECTED_ANALYZER_NODE_IDS` in `tests/nodes/analyzers/test_registry.py`. It is an exact, order-sensitive list asserted for equality; a new id in the wrong position fails the suite.
+- Registering is discovery, not an edit (upstream `837d100`, in since the 2.12.0 sync): `nodes/analyzers/__init__.py` imports every non-package module beside it and registers the ones exposing a module-level `ANALYZER_ID` and a callable `node`. Never hand-edit that file — it is upstream's whole. A module that fails to import does not raise at load time: it lands in `ANALYZER_LOAD_ERRORS`, the analyzer is absent from the graph, and `finalize_inspection_ledger` reports it as an `ANALYZER_LOAD_ERROR` ledger event (upstream `dbcb3c5`). So a new analyzer that finds nothing may never have been imported — read the scan's `analysis_completeness` before debugging its Rules.
+- Registry order is `pkgutil` order, not a curated one. Nothing may depend on it.
+- Then add the id to `EXPECTED_ANALYZER_NODE_IDS` in `tests/nodes/analyzers/test_registry.py`. It is compared as a set; a missing id still fails the suite.
+- `graph.py` skips a discovered module whose `is_available()` returns false, or whose `requires_api_key` is true with no LLM configured. A fork Analyzer declares neither — its gates live inside `node`, below.
 - `guard_analyzer_node` wraps every node and converts any exception into `{"findings": []}` plus a `"failed"` ledger status. A broken analyzer will not fail the run or a test that only checks `graph.invoke()` succeeded — assert on findings directly.
 - Adding the id to `_MODEL_SLOTS` in `constants.py` is optional and only enables the `SKILLSPECTOR_MODEL_<SLOT>` override; an unlisted id falls back to `model_config["default"]`.
-- Every analyzer runs on every scan — `build_context` fans out to all of them unconditionally. An analyzer that should only apply to certain inputs must return early on its own gate.
+- Every wired analyzer runs on every scan — `build_context` fans out to all of them unconditionally. An analyzer that should only apply to certain inputs must return early on its own gate.
 - Two gates, and only two, return bare `{"findings": []}` (ADR 0002): a **Framework** mismatch, and a **default-off configuration gate** whose default is the absence of a request — today only `--spec-checks off`, which `structure_agent_skills_spec` answers with silence. A gate that is a *request* the user made is not one of them: `--no-llm` turns an analyzer that would have run off, and the semantic analyzers report that as `disabled` with `LedgerReason.DISABLED_BY_CONFIGURATION`. Read the ADR before adding a third; the cost that decides it is that any status row reaches `analysis_completeness`, which the Behavior Snapshot projects.
 - Past whichever gate applies, the analyzer reports a status on every input: applicability is one named predicate, the gate tests its result for emptiness, the planned work derives from that same result, and an empty result emits `not_applicable` with `LedgerReason.NO_APPLICABLE_FILES` and no ledger event. Two expressions for "applicable" is the defect ADR 0006 records.
 - **No analyzer may encode run configuration into a `Finding`.** `suppression.finding_fingerprint` hashes **every** field of the payload — `confidence` and `tags` included — so a Finding that says "this run was configured such-and-such" fingerprints one defect two ways, and a committed baseline stops suppressing when the command line changes. Carry the signal in graph state instead, the way `unscored_rule_ids` carries `--spec-checks`. This is the analyzer-facing half of the rule stated in `.claude/rules/suppression.md`, which is scoped to `suppression.py` and so never loads here; both halves are one rule. A run-scoped state key needs a reducer before a *second* analyzer may write it — the parallel fan-out rejects a concurrent write to a bare channel outside any node, where `guard_analyzer_node` cannot catch it.

.claude/rules/pi-extension.md

@@ -1,9 +1,12 @@
 ---
 paths:
   - "extensions/*.ts"
+  - ".opencode/tools/*.ts"
 ---
 
-# Pi extension
+# Pi and OpenCode extensions
+
+Two extensions, one security contract. The helper names below are Pi's; the OpenCode tool under `.opencode/tools/` keeps the same contract under its own names: `redact()` on both streams, `SKILLSPECTOR_BIN` first in binary resolution, `noLlm` defaulting to true.
 
 - Subprocess calls go through `pi.exec(bin, argsArray, {...})` with an argument **array**. Never build a shell string — there is no shell in this path and adding one reintroduces injection.
 - Both `stdout` and `stderr` must pass through `redactSecrets()` before being returned to the caller.

.claude/rules/tests.md

@@ -5,7 +5,7 @@ paths:
 
 # Test markers
 
-- `pyproject.toml` sets `addopts = "-m 'not integration and not provider'"`, so anything carrying those markers is deselected by default. Run them with `make test-integration` / `make test-provider [openai|anthropic|nv_build]`.
+- `pyproject.toml` sets `addopts = "-m 'not integration and not provider'"`, so anything carrying those markers is deselected by default. Run them with `make test-integration` / `make test-provider [openai|anthropic|nv_build|gemini]`.
 - `tests/integration/conftest.py` auto-applies `pytest.mark.integration` to every test under that path, which cuts both ways. **Never put a unit test there** — it is marked by location and silently deselected from the default run. **Anywhere else, mark explicitly** — a live-LLM or live-provider test written under `tests/unit/` or `tests/nodes/` runs unmarked in default CI and will call a real provider.
 - Use the module-level form for explicit marking: `pytestmark = [pytest.mark.provider]` (see `tests/provider/test_provider_endpoint.py`). Existing examples outside the marker directories: `tests/nodes/analyzers/test_semantic_developer_intent.py`, `tests/test_mcp_tool_poisoning.py`.
 - `asyncio_mode = "auto"` — `async def test_*` needs no `@pytest.mark.asyncio`.

.env.example

@@ -2,9 +2,20 @@ ENV=dev                                                         # options: dev|s
 
 # Active LLM provider.  Selects which provider answers credentials,
 # metadata, and default-model lookups.  Leave unset to default to nv_build.
-# Options: openai | anthropic | anthropic_proxy | nv_build
+# Options: openai | anthropic | anthropic_proxy | bedrock | nv_build |
+#          ollama | azure_openai | openai_compatible | gemini | claude_cli |
+#          gemini_cli | opencode_cli
+# codex_cli is registered but disabled: its read-only sandbox permits host-file reads.
 SKILLSPECTOR_PROVIDER=
 
+# Aggregate deadline for one complete scan workflow. Defaults to 600 seconds;
+# override this positive finite value when a different limit is required.
+# SKILLSPECTOR_MAX_WORKFLOW_SECONDS=600
+
+# Static analysis per artifact defaults to 300 seconds, capped by the remaining
+# workflow time. Set a positive finite value before starting the process.
+# SKILLSPECTOR_MAX_STATIC_ANALYSIS_SECONDS_PER_ARTIFACT=300
+
 # Provider credentials — set the one matching SKILLSPECTOR_PROVIDER (or
 # leave SKILLSPECTOR_PROVIDER unset and set NVIDIA_INFERENCE_KEY for the
 # default nv_build path).
@@ -18,8 +29,17 @@ NVIDIA_INFERENCE_KEY=
 OPENAI_API_KEY=
 OPENAI_BASE_URL=
 # Optional provider- and model-dependent reasoning-effort setting. Non-empty values
-# are trimmed and passed through unchanged; unset or blank uses the provider default.
+# are trimmed and passed through unchanged. Unset or blank sends high for nv_build
+# with z-ai/glm-5.3; other provider/model combinations keep their endpoint defaults.
 SKILLSPECTOR_REASONING_EFFORT=
+# Optional language for human-readable LLM finding text. Machine-readable values
+# such as rule IDs and severity values remain unchanged.
+SKILLSPECTOR_OUTPUT_LANGUAGE=
+# Optional sampling controls. Temperature is supported by hosted providers;
+# seed is forwarded only to OpenAI-compatible and Azure OpenAI endpoints.
+# Unset or blank values preserve provider defaults.
+SKILLSPECTOR_TEMPERATURE=                                    # range: 0..1
+SKILLSPECTOR_SEED=                                           # integer
 
 # For SKILLSPECTOR_PROVIDER=anthropic.
 ANTHROPIC_API_KEY=
@@ -31,6 +51,36 @@ ANTHROPIC_PROXY_API_KEY=
 # ANTHROPIC_PROXY_API_VERSION=vertex-2023-10-16                 # optional; defaults to vertex-2023-10-16
 # SKILLSPECTOR_SSL_VERIFY=false                                 # set to false for internal/self-signed CAs
 
+# For SKILLSPECTOR_PROVIDER=gemini (Google Cloud ADC / Workload Identity).
+# Requires GOOGLE_CLOUD_PROJECT; GOOGLE_CLOUD_LOCATION defaults to global.
+# Local use: gcloud auth application-default login (configure quota project with: gcloud auth application-default set-quota-project PROJECT_ID)
+# Kubernetes/GKE: configure Workload Identity (leave GOOGLE_APPLICATION_CREDENTIALS unset)
+# Note: regional endpoints alone do not guarantee data residency; global does not support residency.
+GOOGLE_CLOUD_PROJECT=
+# GOOGLE_CLOUD_LOCATION=global                                  # optional; e.g. global, us, eu, us-central1
+# GOOGLE_APPLICATION_CREDENTIALS=                               # optional; path to Workload/Workforce Identity Federation config JSON
+
+# For SKILLSPECTOR_PROVIDER=bedrock. AWS_PROFILE is optional; when unset,
+# boto3 uses its standard credential chain. AWS_REGION defaults to us-west-2.
+# AWS_PROFILE=
+# AWS_REGION=us-west-2
+
+# For SKILLSPECTOR_PROVIDER=ollama. No API key is required.
+# OLLAMA_BASE_URL=http://localhost:11434/v1                     # optional; shown default
+
+# For SKILLSPECTOR_PROVIDER=azure_openai.
+AZURE_OPENAI_API_KEY=
+AZURE_OPENAI_ENDPOINT=
+# AZURE_OPENAI_DEPLOYMENT=                                      # optional; defaults to the model label
+# AZURE_OPENAI_API_VERSION=2024-06-01                           # optional; shown default
+
+# For SKILLSPECTOR_PROVIDER=openai_compatible.
+SKILLSPECTOR_COMPAT_API_KEY=
+SKILLSPECTOR_COMPAT_BASE_URL=
+
+# claude_cli, gemini_cli, and opencode_cli use their CLI's existing local
+# authentication session and do not need an API key here.
+
 # SkillSpector config
 SKILLSPECTOR_MODEL=                                             # leave empty to use the active provider's bundled default (see README); set to override (e.g. gpt-5.2)
 # SKILLSPECTOR_MODEL_REGISTRY=./model_registry.yaml             # optional override; defaults to each provider's bundled YAML in src/skillspector/providers/

.github/workflows/ci.yml

@@ -34,6 +34,7 @@ concurrency:
 env:
   UV_VERSION: "0.10.x"
   PYTHON_VERSION: "3.12"
+  NODE_VERSION: "22.20.0"
   UV_CACHE_DIR: .uv-cache
   UV_LINK_MODE: copy
 
@@ -91,6 +92,20 @@ jobs:
       - run: uv run skillspector --version
       - run: uv run make test-ci
 
+  test-opencode:
+    name: OpenCode TypeScript Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Set up Node.js
+        # Pinned to a full commit SHA (third-party action); comment tracks the tag.
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+      - run: node --test tests/opencode/skillspector_scan_lib.test.ts
+      - name: Run Pi extension security tests
+        run: node --test tests/unit/test_pi_extension.mjs
+
   docker-smoke:
     needs: changes
     if: needs.changes.outputs.docker == 'true'

.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           ref: ${{ github.event.pull_request.merge_commit_sha }}
       - name: Set up uv

.github/workflows/upstream-drift.yml

@@ -129,9 +129,9 @@ jobs:
 
           # Every line of upstream-authored text (commit subjects, path names)
           # reaches this file by redirection, never by command substitution into
-          # a shell string and never through `${{ }}`. It is fenced as code for
-          # the same reason: an unfenced `(#357)` renders as a cross-reference
-          # and would backlink an unrelated fork issue every week.
+          # a shell string and never through an Actions expression. It is fenced
+          # as code for the same reason: an unfenced `(#357)` renders as a
+          # cross-reference and would backlink an unrelated fork issue every week.
           {
             printf '%s\n\n' "$ISSUE_MARKER"
             printf 'Upstream `NVIDIA/SkillSpector` has **%s commit(s)** this fork has not merged.\n' \

.gitignore

@@ -111,3 +111,7 @@ credentials.json
 
 # Agent session scaffolding, not a deliverable
 docs/handoffs/
+# Reports (generated artifacts only — anchored to repo root)
+/report*.md
+/report*.json
+/report*.sarif

.opencode/commands/skillspector.md

@@ -0,0 +1,5 @@
+---
+description: Scan an AI agent skill for security risks with SkillSpector (static analysis by default); use when vetting a skill before install or auditing one in use.
+---
+Scan the skill at $ARGUMENTS with the skillspector_scan tool (static analysis only, no LLM calls).
+To opt into LLM semantic analysis instead, call skillspector_scan with noLlm false and SKILLSPECTOR_PROVIDER/SKILLSPECTOR_MODEL set.

.opencode/tools/skillspector_scan.ts

@@ -0,0 +1,24 @@
+import { tool } from "@opencode-ai/plugin"
+import { execFile } from "node:child_process"
+import fs from "node:fs"
+import { promisify } from "node:util"
+import { executeScan, type RunFile } from "./skillspector_scan_lib.ts"
+
+const runFile = promisify(execFile) as unknown as RunFile
+
+export default tool({
+  description: "Scan an AI agent skill for security risks with SkillSpector. Static analysis only by default; opt into LLM analysis explicitly.",
+  args: {
+    target: tool.schema.string().describe("Skill to scan: local path, .md/.zip file, or Git/file URL"),
+    format: tool.schema.enum(["terminal", "json", "markdown", "sarif"]).default("json").describe("Report format"),
+    noLlm: tool.schema.boolean().default(true).describe("Skip LLM analysis (static checks only). Set false to opt into LLM semantic analysis via SKILLSPECTOR_PROVIDER/SKILLSPECTOR_MODEL"),
+    output: tool.schema.string().optional().describe("Write the report to this file instead of returning it (resolved against the session directory if relative)"),
+  },
+  async execute(args, context) {
+    return executeScan(args, context, {
+      runFile,
+      existsSync: fs.existsSync,
+      lstatSync: fs.lstatSync,
+    })
+  },
+})