Red Widow

VSIX, IDE extension, and AI developer workflow security scanner.

Red Widow answers one question: can this developer workflow change reach secrets, commands, or trusted tools before it reaches developers or CI?

The main path is simple: gate repo workflow risk, approve exact extension packages, and enforce the same decision in CI. Red Widow inspects VS Code-compatible extension recommendations, checked-in VSIX packages, MCP/tasks/debug/settings/rules/hooks for VS Code, Cursor, and Windsurf, lockfiles, policy files, and SARIF output for CI. Lower-level scan, diff, dynamic sandbox, and agent canary commands are available when you need deeper proof.

The static scanner is intentionally dependency-free at runtime. Dynamic sandbox runs require Node.js because Red Widow executes extension activation code through an instrumented Node harness.

Start Here: Gate A Repo Before Extension Or AI-IDE Changes Land

For day-to-day repo checks, use the gate. It scans the current workspace's .vscode/extensions.json, resolves recommended extensions from the VS Code Marketplace or OpenVSX, caches downloaded VSIX packages under .red-widow/, and scans any checked-in .vsix files it finds:

red-widow gate
red-widow approve
red-widow approve --reviewed-by security@example.com
red-widow gate --policy examples/policy.example.json
red-widow gate --json

The gate prints PASS, REVIEW, or BLOCK, followed by the next action and the surfaces it inspected or skipped.

The same gate also auto-detects VS Code-compatible AI-IDE workflow config in the workspace, including .vscode/mcp.json, VS Code tasks/debug/settings, Cursor/Windsurf MCP config, agent rules, AGENTS.md, Windsurf hooks, and Windsurf ignore config. Harmless config discovery is reported as inventory; concrete executable paths such as shell hooks, shell-wrapped MCP servers, non-HTTPS remote MCP URLs, curl-to-shell tasks, or broad env-file exposure can block.

Before push or in CI, make review items blocking:

red-widow gate --policy examples/policy.example.json --fail-on-review

Use the first-party GitHub Action in CI:

- uses: red-widow/red-widow@v1
  with:
    workspace: .
    policy: examples/policy.example.json
    offline: "true"
    strict: "true"
    fail-on-review: "true"
    upload-sarif: "true"

Offline CI does not download marketplace packages. It gates repo config, checked-in non-ignored VSIX packages, lockfile drift, and unresolved recommendations. With fail-on-review: "true", unresolved recommendations block the run; set offline: "false" when CI is allowed to download and inspect recommended marketplace packages.

Stay local-only when you do not want network access:

red-widow gate --offline

red-widow approve writes red-widow.lock.json for the resolved packages from the current gate run. Future red-widow gate runs use that lockfile automatically and flag version or package-hash drift.

Scan a specific VSIX or unpacked extension:

red-widow ./extension.vsix
red-widow ./unpacked-extension-directory

Compare an extension update:

red-widow --diff ./old.vsix ./new.vsix

Audit installed extensions:

red-widow --installed
red-widow --installed --format inventory

Audit the local machine's installed extensions plus global Cursor/Windsurf MCP config:

red-widow gate --installed
red-widow inventory --format json

Export approved extensions into VS Code enterprise extensions.allowed policy:

red-widow export vscode-allowed --lockfile red-widow.lock.json --format settings-json

Run Red Widow inside VS Code with the editor extension in vscode-extension/. The extension runs the local CLI, shows the gate decision in the status bar, and adds Problems diagnostics for blocking and review findings. It runs the gate offline by default unless redWidow.offline is disabled. See docs/vscode-extension.md.

Run a VSIX in a canary sandbox:

red-widow run ./extension.vsix --sandbox

Seed and check an AI coding-agent canary run:

red-widow agent seed /private/tmp/red-widow-agent-probe
red-widow agent show /private/tmp/red-widow-agent-probe
red-widow agent check ./agent-transcript.txt --workspace /private/tmp/red-widow-agent-probe

agent seed and agent show redact the canary marker by default so CI logs do not accidentally expose it. Use --reveal-marker only for local manual probes.

Recommended extension IDs that cannot be resolved from an installed/local copy, the lockfile, VS Code Marketplace, or OpenVSX produce REVIEW by default. Use --fail-on-review when CI should block unresolved recommendations.

Useful advanced commands:

red-widow ./extension.vsix --format json
red-widow ./extension.vsix --fail-on high
red-widow ./extension.vsix --write-lockfile extensions.lock.json
red-widow ./extension.vsix --lockfile extensions.lock.json
red-widow approve --json
red-widow approve --lockfile red-widow.lock.json
red-widow inventory --format markdown
red-widow export vscode-allowed --format json
red-widow gate --workspace .
red-widow gate --offline
red-widow gate --strict --offline
red-widow gate --installed --policy examples/policy.example.json
red-widow gate --installed --extension-root ./extensions
red-widow gate --recommendations .vscode/extensions.json
red-widow --installed --policy examples/policy.example.json
red-widow --installed --policy examples/policy.example.json --format sarif
red-widow --installed --format markdown
red-widow run ./extension.vsix --sandbox --keep-run
red-widow run ./extension.vsix --sandbox --format json
red-widow agent seed /private/tmp/red-widow-agent-probe --format json
red-widow agent show /private/tmp/red-widow-agent-probe --reveal-marker
red-widow agent check ./agent-transcript.txt --workspace /private/tmp/red-widow-agent-probe --format json

Create and use a baseline so CI reports only new risk:

red-widow --installed --policy examples/policy.example.json --write-baseline extensions.baseline.json
red-widow --installed --policy examples/policy.example.json --baseline extensions.baseline.json

When running from a checkout instead of an installed package, replace red-widow with:

python3 -m red_widow

Release instructions live in docs/release.md. Red Widow is intended to publish through PyPI Trusted Publishing from GitHub Releases, not through long-lived local PyPI tokens.

The dynamic sandbox creates a fake workspace with canary secrets, loads the extension activation entry point through an instrumented Node harness, blocks process and network calls, and reports proof when an extension reads canary files, spawns a process, sends terminal commands, touches canary environment values, creates unsafe webviews, or attempts to send canary material outbound.

Safety note: the dynamic runner is an instrumented canary harness, not an operating-system or VM sandbox. Run unknown hostile packages inside an isolated CI worker, container, or virtual machine.

For explicit target lists, use --continue-on-error to keep scanning after a malformed package. Installed-extension scans continue by default and return status 1 if any target could not be parsed.

Use gate --strict in CI when malformed packages or scan truncation warnings should block as incomplete static coverage. Use run --strict when dynamic harness errors should block canary sandbox runs. The first-party GitHub Action currently runs gate and inventory; it does not run the dynamic sandbox. Workspace gate discovery respects the workspace .gitignore; pass an ignored VSIX explicitly when you want to scan it anyway.

Exit codes are stable for CI:

• 0: scan passed, or findings are report-only under the selected options.
• 1: scan/runtime error, malformed target, or dynamic harness error.
• 2: policy violation, lockfile violation, --fail-on threshold, gate block, --fail-on-review, or dynamic block.

Demo a Faulty VSIX

Build a deterministic intentionally faulty fixture:

python3 examples/build_faulty_vsix.py /private/tmp/red-widow-faulty.vsix

Run static and dynamic proof:

python3 -m red_widow /private/tmp/red-widow-faulty.vsix
python3 -m red_widow run /private/tmp/red-widow-faulty.vsix --sandbox

The generated fixture includes bundled secrets, a lifecycle script, a native binary, child process usage, terminal command injection, env sweeping, webview script/message behavior, a download-write-execute path, and canary exfiltration code. It is meant for local demos and tests, not for publishing.

What It Checks

Area	What Red Widow Looks For
Manifest behavior	Activation events, broad * activation, workspace extension host usage, and package lifecycle scripts.
Secrets	Private keys, GitHub/OpenAI/AWS/Slack/npm tokens, and generic secret assignments.
Bundled credential files	Files such as .env, .npmrc, .netrc, .git-credentials, SSH keys, and cloud credential files.
Process execution	Node process execution APIs such as child_process, exec, spawn, fork, and sync variants.
Terminal APIs	createTerminal().sendText(...) paths that can inject commands into an integrated terminal.
Webviews	Script-enabled webviews, missing strict CSP, and onDidReceiveMessage handlers that need validation.
Environment access	Broad process.env enumeration or dynamic indexing that can sweep developer secrets.
Executable download chains	Runtime source files that combine network access, filesystem writes, and process execution.
Workspace trust	Risky runtime behavior without an apparent vscode.workspace.isTrusted gate, missing capabilities.untrustedWorkspaces, and unrestricted execution-sensitive settings.
VS Code MCP	.vscode/mcp.json local MCP stdio commands, remote MCP URLs, secret-like env usage, env files, and shell-wrapper command paths.
VS Code repo execution config	.vscode/tasks.json, .vscode/launch.json, and .vscode/settings.json commands, shell chains, env files, and sensitive file references.
Language model tools	VSIX contributes.languageModelTools, broad tool descriptions, and tool implementations that combine local data reads with network/process/terminal output.
Cursor/Windsurf MCP	Local MCP stdio commands, remote MCP URLs, secret-like env usage, env files, and shell-wrapper command paths.
AI agent rules	Risky instructions in .cursor/rules, .cursorrules, AGENTS.md, and Windsurf rules or workflows.
Windsurf hooks	Shell commands configured in .windsurf/hooks.json.
Windsurf ignore config	.codeiumignore patterns that re-include sensitive-looking files.
Local credential access	References to sensitive paths and variables such as .ssh, .git-credentials, id_rsa, cloud tokens, and credential environment variables.
Network endpoints	Runtime HTTP/HTTPS domains embedded in extension source files.
Native and script content	Native binaries such as .node, .so, .dll, .dylib, .exe, plus bundled shell scripts.
Obfuscation	Large minified JavaScript lines, eval, atob, new Function, String.fromCharCode, and large base64-like blobs.
Update diffs	Newly added findings, domains, native binaries, and activation-event changes between extension versions.
Dynamic sandbox proof	Canary file/env reads, terminal sendText calls, unsafe webview behavior, process-spawn attempts, outbound network access, and outbound canary exfiltration attempts.
AI coding-agent proof	Canary workspaces with untrusted prompt-injection content plus transcript/tool-trace checks for canary disclosure, sensitive file reads, unsafe commands, and outbound exfil paths.
Gate checks	Local VSIX packages, installed extensions, marketplace-resolved recommendations, and unresolved VS Code extension recommendations before they land in a repo or CI workflow.

Policy Format

Policy files are JSON and can allow or block extension IDs, publishers, domains, and specific scanner rules.

{
  "maxSeverity": "medium",
  "maxRiskScore": 9,
  "allowExtensions": ["esbenp.prettier-vscode", "github.*"],
  "blockExtensions": ["unknown.*"],
  "allowPublishers": ["GitHub", "ms-python"],
  "blockPublishers": ["suspicious-publisher"],
  "allowDomains": ["*.microsoft.com", "*.github.com"],
  "blockDomains": ["*.example"],
  "allowActivationStar": false,
  "allowNativeBinaries": false,
  "denyFindings": ["child-process-use", "private-key", "github-token"],
  "exceptions": [
    {
      "extension": "ms-python.*",
      "version": "2026.*",
      "ruleId": "native-binary",
      "scope": "dependency",
      "reason": "Approved bundled helper binaries."
    },
    {
      "extension": "github.*",
      "ruleId": "domain-blocked",
      "domain": "*.github.com",
      "reason": "Approved service domain."
    }
  ]
}

If a policy is passed and violations are found, red-widow exits with status 2.

Findings include metadata for triage:

• confidence: how reliable the signal is.
• blocking: whether the rule is strong enough to block by default.
• scope: source, dependency, documentation, test, example, generated, manifest, config, or asset.
• remediation: suggested review or cleanup action.

Lockfile Format

{
  "lockfileVersion": 2,
  "allowedExtensions": {
    "publisher.extension-name": {
      "version": "1.0.0",
      "sha256": "package-or-directory-digest",
      "source": "marketplace",
      "marketplaceSource": "openvsx",
      "sourceUrl": "https://open-vsx.org/api/publisher/extension-name/file/publisher.extension-name.vsix",
      "publisher": "publisher",
      "name": "extension-name",
      "approvedBy": "security@example.com",
      "reviewedBy": "security@example.com",
      "reviewedAt": "2026-05-06T00:00:00Z"
    }
  }
}

For directories, the digest is deterministic over relative file paths and file contents. For .vsix files, the digest is the package SHA-256. Older lockfiles with only allowedExtensions remain valid; Red Widow validates extension ID, version, and package digest.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for the development workflow, test commands, and the current contribution priorities.

What Red Widow needs most right now:

Need	Examples
Scanner fixtures	Safe intentionally risky VSIX samples for secrets, lifecycle scripts, native binaries, obfuscation, and network endpoints.
Detection coverage	More VSIX, extension manifest, MCP, CI workflow, and devcontainer risk checks.
False-positive reduction	Better scoping for generated files, dependencies, docs, tests, and examples.
Packaging and CI	Wheel/sdist smoke tests, GitHub Action examples, SARIF upload examples, and release automation.
Documentation	Real-world usage examples for policy, lockfiles, baselines, inventory, and update diffs.

License

MIT. See LICENSE.