red-widow 0.1.0__tar.gz

red_widow-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Red Widow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

red_widow-0.1.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.4
+Name: red-widow
+Version: 0.1.0
+Summary: VSIX, IDE extension, and AI developer workflow security scanner.
+Author: Red Widow contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/duriantaco/red-widow
+Project-URL: Repository, https://github.com/duriantaco/red-widow
+Project-URL: Issues, https://github.com/duriantaco/red-widow/issues
+Keywords: ai-security,developer-security,ide-security,supply-chain-security,vscode,vsix
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/red-widow.png" alt="Red Widow logo - VSIX and IDE extension security scanner" width="900">
+</p>
+
+<h1 align="center">Red Widow</h1>
+
+<p align="center">
+  <strong>VSIX, IDE extension, and AI developer workflow security scanner.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
+  <a href="#license"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-black"></a>
+  <a href="#what-it-checks"><img alt="VSIX scanner" src="https://img.shields.io/badge/VSIX-scanner-red"></a>
+  <a href="#policy-format"><img alt="Policy as code" src="https://img.shields.io/badge/policy-as--code-blue"></a>
+  <a href="#what-it-checks"><img alt="SARIF supported" src="https://img.shields.io/badge/SARIF-supported-brightgreen"></a>
+  <a href="#contributing"><img alt="Contributions welcome" src="https://img.shields.io/badge/contributions-welcome-orange"></a>
+</p>
+
+`red-widow` is an open-source security scanner for VS Code-compatible IDE
+extensions, VSIX packages, and developer workflow attack surfaces. It can inspect
+`.vsix` packages, unpacked extension directories, locally installed extensions,
+extension update diffs, lockfiles, policy files, inventory reports, and SARIF
+output for CI.
+
+Use Red Widow to find risky IDE extension behavior before it reaches developer
+machines: bundled secrets, broad activation events, native binaries,
+`child_process` usage, VS Code webview and terminal API abuse, environment
+variable sweeping, executable download chains, sensitive local path access,
+suspicious network domains, and dynamic canary exfiltration attempts.
+
+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.
+
+## Usage
+
+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:
+
+```bash
+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 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:
+
+```bash
+red-widow gate --policy examples/policy.example.json --fail-on-review
+```
+
+Use the first-party GitHub Action in CI:
+
+```yaml
+- uses: red-widow/red-widow@v1
+  with:
+    workspace: .
+    policy: examples/policy.example.json
+    offline: "true"
+    fail-on-review: "true"
+    upload-sarif: "true"
+```
+
+Stay local-only when you do not want network access:
+
+```bash
+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:
+
+```bash
+red-widow ./extension.vsix
+red-widow ./unpacked-extension-directory
+```
+
+Compare an extension update:
+
+```bash
+red-widow --diff ./old.vsix ./new.vsix
+```
+
+Audit installed extensions:
+
+```bash
+red-widow --installed
+red-widow --installed --format inventory
+```
+
+Audit the local machine's installed extensions plus global Cursor/Windsurf MCP
+config:
+
+```bash
+red-widow gate --installed
+red-widow inventory --format json
+```
+
+Export approved extensions into VS Code enterprise `extensions.allowed` policy:
+
+```bash
+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/`](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. See [`docs/vscode-extension.md`](docs/vscode-extension.md).
+
+Run a VSIX in a canary sandbox:
+
+```bash
+red-widow run ./extension.vsix --sandbox
+```
+
+Seed and check an AI coding-agent canary run:
+
+```bash
+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:
+
+```bash
+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 --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:
+
+```bash
+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:
+
+```bash
+python3 -m red_widow
+```
+
+Release instructions live in [`docs/release.md`](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.
+
+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:
+
+```bash
+python3 examples/build_faulty_vsix.py /private/tmp/red-widow-faulty.vsix
+```
+
+Run static and dynamic proof:
+
+```bash
+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.
+
+```json
+{
+  "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
+
+```json
+{
+  "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](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](LICENSE).