RUSC — Reachability-Aware Supply-Chain Security

Find real, reachable vulnerabilities in your Python projects — not just a raw CVE dump.

RUSC combines dependency scanning, static reachability analysis, typosquat detection, and provenance checks to show you which vulnerabilities actually matter in your codebase.

Features

Quick Start

Option A — Try it with sample data (no engine required)

1. Install the extension.
2. Open the RUSC Security panel in the activity bar (shield icon).
3. Press Ctrl+Shift+P → RUSC: Scan Workspace.
4. When the setup wizard opens, choose "Use mock mode (sample data only)".
5. Select any folder — you'll see sample findings immediately.

Option B — Run real scans with the Python engine

1. Install the RUSC Python engine

You need Python 3.11 or later. Install the engine from the engine/ folder inside the extension, or from the project repository:

# From the extension source folder:
pip install -e ./engine

# Or if you downloaded only the engine separately:
pip install rusc-engine

Verify installation:

python -m pipeline --version
# → rusc-engine 0.1.0

2. Configure the extension

Open VS Code Settings and search for rusc, or run RUSC: Configure Engine from the Command Palette. Set:

The setup wizard will verify your Python installation and engine availability automatically.

3. Scan your project

Press Ctrl+Shift+P → RUSC: Scan Workspace, pick a folder, and the engine will:

1. Discover Python dependencies from requirements.txt, pyproject.toml, Pipfile, etc.
2. Query the OSV vulnerability database for known CVEs.
3. Run static reachability analysis to identify which vulnerabilities are actually reachable.
4. Flag typosquatted or suspicious package names.
5. Check provenance and attestations.

Understanding Reachability States

Important: needs review, unknown, degraded, and unsupported are never treated as "not affected". When in doubt, RUSC errs on the side of caution.

Engine Modes

Configure via Settings → search rusc:

Mock mode (default)

Returns hard-coded sample findings covering all 6 reachability states. Not real vulnerability data.
Useful for exploring the UI before installing the engine. All mock results are clearly labelled.

CLI mode

Invokes <engineCliPath> -m pipeline <workspace_path> --format json.
Requires the rusc-engine Python package to be installed and rusc.engineCliPath to point to the correct Python interpreter.

Remote mode

POSTs workspace metadata to <engineRemoteUrl>/api/v1/scan and polls for results.
Requires the RUSC_API_KEY environment variable (never put API keys in VS Code settings).
Shows a consent dialog before the first connection. No source code is ever transmitted.

Security Properties

• No source code execution — the extension only reads manifest filenames; it never runs project scripts.
• Path traversal prevention — engine-provided file paths are validated to stay inside the workspace root before any file is opened.
• No shell injection — CLI engine is spawned with shell: false; arguments are passed as an array.
• No secrets in logs — API keys and passwords are never written to the Output Channel or exported reports.
• Mock data guard — exporting mock findings requires explicit user confirmation; the export file contains a prominent warning.
• Remote consent gate — the Remote engine shows a modal consent dialog before making any network connection.
• Webview hardening — the detail panel uses enableScripts: false, localResourceRoots: [], and a strict Content-Security-Policy.
• Untrusted input — all engine responses, file paths, and package metadata are treated as untrusted.

Running the Extension in Development

git clone <this-repo>
cd <repo-folder>
npm install
npm run compile
# Press F5 in VS Code to launch the Extension Development Host

Project Structure

src/
  extension.ts               Entry point — command registration
  engine/
    ISecurityEngine.ts       Integration contract (interface + types)
    MockEngine.ts            Sample data engine (development/demo)
    CliEngine.ts             CLI process adapter
    RemoteEngine.ts          HTTP/REST adapter
    engineFactory.ts         Reads config, returns the right engine
  domain/
    FindingStore.ts          In-memory findings state
    FilterState.ts           Active filter state
    ScanController.ts        Scan lifecycle orchestration
    WorkspaceDetector.ts     Detects open folder + manifests
    SetupWizard.ts           First-run configuration wizard
    SourceNavigator.ts       Safe file-opening with path validation
  ui/
    FindingsTreeProvider.ts  Sidebar tree view
    FindingDetailPanel.ts    Webview detail panel
    ReportExporter.ts        JSON report export
    RuscOutputChannel.ts     Structured output channel
engine/
  rusc_engine/               Python RUSC engine package
    pipeline.py              Main entry point (python -m pipeline)
    dependency_discovery.py  Reads requirements.txt / pyproject.toml / Pipfile
    sbom_engine.py           SBOM generation (CycloneDX)
    osv_client.py            OSV vulnerability database queries
    reachability.py          Static reachability analysis
    typo_inspector.py        Typosquat detection
    provenance_checker.py    SLSA / PEP 740 attestation checks
    vex_generator.py         VEX document generation
    risk_prioritiser.py      Severity sorting and remediation text

License

MIT — see LICENSE.