Okscanner for VS Code

Upload the current workspace to Okscanner with one click, monitor the scan, and review server-authoritative findings in a native-themed Security Overview and the VS Code Problems panel.

Features

• The application gorilla identifies Okscanner in the activity bar, extension listing and workspace panel. Controls follow the active VS Code theme.

• One primary scan action that becomes a truthful progress surface while work is active, plus analysis-depth controls and compact severity filters. Coverage limitations stay visible; detailed scan metadata expands on demand.

• Connection settings open in one panel. Failed saves retain the entered values; successful saves clear the key field. Settings refreshes preserve drafts.

• The main panel automatically loads centrally managed rule policies. End users can choose an available policy but cannot edit its detector membership.

• The latest 20 project scans appear in a compact, clickable history. Active rows update automatically; selecting a completed row loads its findings. The confirmed Clear action removes them from this workspace panel without deleting server-side scan evidence.

• Start FAST, SEMANTIC, or DEEP scans from the activity-bar play button or the Command Palette.

• Save, package, checksum, and upload the current local workspace, including uncommitted source changes.

• Configure only the Okscanner server URL and API key in the Okscanner Connections Settings view.

• Create a private Okscanner project automatically on the first scan and retain its ID against the repository, so every branch and every Git worktree of that repository reuses the same project.

• Declare the scanned area in the repository itself with .okscanner.json, so it is the same for every checkout and every colleague.

• Scan automatically once the workspace is connected, and again whenever the checked-out branch or worktree changes.

• Store the API key only in VS Code SecretStorage, never in workspace settings or extension output.

• Monitor queued and running scans and load findings when analysis finishes.

• Review severity filters, search findings, open a quiet in-panel finding detail, copy its evidence, and jump to its workspace-relative source location.

• Show results in batches of 30. Status updates preserve the focused finding; query and severity filters survive panel recreation.

• Keep detailed results in the extension UI while publishing native VS Code diagnostics; the Output channel remains optional diagnostic logging.

• Export the currently loaded bounded result set as SARIF 2.1.0.

Coverage and server compatibility (1.20)

1.20 is a client-side release and needs no server change beyond what 1.18 already required; see CHANGELOG.md for the full list.

Deploy the matching gateway/runner and migration 0049 before installing this extension version. It requires the project-scoped workspace-scan-preview API. Policy loading requires API-key access to GET /api/v1/rulesets. Policies are authored and maintained centrally in Okscanner. The IDE stores only the selected policy ID for the workspace, previews it before upload, and sends that ID to scan admission. Actual admission resolves the policy again and the completed scan carries its immutable selection. Analysis depth is a separate end-user choice; the server raises it when the selected policy requires a deeper profile.

Job completion is not coverage completeness. The panel and SARIF retain parser degradations, unsupported inputs, native size/read limits, and zero-rule engines. New scans retain scan-time findings independently of later scans and triage. Historical scans predating migration 0049 are explicitly marked incomplete; missing historical findings cannot be reconstructed from current findings.

SARIF includes all selected rule descriptors, source context, proof semantics, dependency fix metadata, evidence, traces, engine versions, and truncation state. Archive SHA-256 values are exported as source archive identities, not Git commits.

Setup

1. In the Okscanner web application, open Settings > API Keys and create a key with the Developer role, access to all current and future projects, and projects:write, scans:read, scans:write, and findings:read scopes.
2. Open the gorilla icon in the activity bar and expand Connections.
3. Enter the server URL and API key, then select Save connection. The key is stored in VS Code SecretStorage.
4. In Security Overview, choose the analysis depth and one of the centrally managed policies. Policies and scan history load automatically.
5. Select Scan Workspace to package, upload, and scan the workspace. Okscanner creates and links the project automatically; no Project ID is entered by the user.

For the local Docker deployment, use http://localhost:8080. Production should use its validated HTTPS origin. The extension does not provide an insecure TLS bypass.

The Okscanner deployment must include the workspace-upload API and matching gateway, orchestrator, and scan-runner versions shipped with this extension.

The scan area

What a scan covers is a property of the project, not of whoever runs it. Commit a .okscanner.json at the repository root and every branch, every worktree and every colleague scans the same tree at the same depth:

{
  "scanRoot": "services/api",
  "branch": "",
  "exclude": ["generated", "docs/vendor/**"],
  "excludeGitIgnored": true,
  "profile": "semantic",
  "engines": ["sast", "sca", "secrets"],
  "sourceScope": "application",
  "autoScan": true
}

Every field is optional and overrides the corresponding VS Code setting. Okscanner: Create Project Scan Configuration writes the file seeded with what is currently in effect. Okscanner: Show Scan Area prints the resolved area - directory, branch, worktree, commit, and what is being left out - without starting a scan; the same block is printed before every scan.

• scanRoot is a directory relative to the workspace folder. A value that escapes the repository or does not exist is refused rather than ignored: a scan of the wrong tree reports a clean result for code nobody read.
• branch overrides the recorded branch. Left empty, the checked-out Git branch is used, and a detached HEAD is recorded as detached/<short commit>.
• exclude accepts glob patterns (**, *, ?, character classes). A bare directory name also prunes the file search rather than only filtering it.
• Anything else invalid warns in the Output channel and falls back to the VS Code setting, so one typo cannot block a scan.

Settings entered in the Connections view - server URL, analysis depth, source scope - are stored in user settings, not in the checkout's .vscode/settings.json. A branch that does not carry that file, or a worktree that has its own, no longer clears the connection. A value you have deliberately pinned to a workspace stays pinned. The API key remains in SecretStorage, and the project link, upload identity and scan history are filed under the repository, shared by all of its worktrees.

With okscanner.autoScan enabled (the default), a scan starts once the workspace is connected to Okscanner and again when the checked-out branch or worktree changes. Each branch-and-commit pair is scanned once; the checkout is allowed to settle first.

Source package boundary

Use Okscanner: Configure Image Targets to list project images or register a Linux amd64/arm64 image using an explicit registry/repository@sha256:digest. Registration requires projects:write; listing requires scans:read, both project-scoped. No registry secret is read or stored by the extension. Configure private registry credentials in the server UI. Container scans require semantic or deep profile. Without an enabled digest-pinned target, only Container is reported as not applicable while the other selected engines continue.

Upload preflight logs included-file origin counts (tracked, ignored, untracked or unknown), non-regular omissions and bounded samples of files exceeding the Secrets limit. These are client observations, not server-attested Git evidence. The last admitted report is locally retained and exported only with its matching archive SHA-256. Git history is not scanned by workspace upload.

With migration 0050 and matching server versions, each finding also carries server-verified archive membership and a per-file SHA-256. This does not prove that the file was Git-tracked, published or executed. SARIF preserves this provenance and frozen same-scan cross-engine diagnostic links; a link is not an exploit chain or a reason to change severity.

The extension uploads regular files from the resolved scan area. Before packaging, it asks VS Code to save open workspace files. Symlinks and non-regular files are not included. The reserved .okscanner-generated tree is excluded by default. The okscanner.sourceExclude glob applies; the default omits Git metadata, dependencies, caches, and common build outputs, including .gocache*, .angular, .nx, .turbo, bin, build, dist, out, and target directories.

Four further exclusions apply, and each one is reported in the Output channel with a count of what it removed:

• Files Git ignores are left out while okscanner.excludeGitIgnored is on (the default). Files named .env or .env.* are kept regardless: an uncommitted .env is ignored in almost every repository that has one, and it is the most productive input the Secrets engine has.
• Files above the 32 MiB per-file limit are skipped and listed by name and size. No upload can carry them either way, and one build-cache artifact used to abort the entire scan.
• Git worktrees checked out inside the scan area are excluded. They are a second copy of the repository on another branch; packaging one doubles the archive and reports every finding twice.
• Patterns the repository declares in exclude in .okscanner.json.

Uploads are bounded to 50,000 files, 32 MiB per file, 512 MiB expanded, and 64 MiB compressed. The server rechecks the checksum, archive paths, entry types, and every size bound before creating a scan. The file-count and total-size bounds remain fatal: dropping files to fit under them would report nothing for source that was never read, and a clean result nobody can trust is worse than a refused upload. When one is hit, the error names the directories that account for most of the package so the exclusion can be written without measuring the workspace by hand.

Stopping during packaging or upload prevents a scan from being queued when the server has not accepted it yet. After queueing, Stop calls the tenant-scoped scan cancellation route with scans:write, records the server-side canceled state, and stops local monitoring only after the server accepts the cancellation.

Development

From the repository root:

cd extensions\vscode
npm.cmd install
npm.cmd test

The compiled extension entry point is extensions/vscode/out/extension.js. Install a built VSIX with Extensions: Install from VSIX... in the Command Palette, or code --install-extension okscanner-vscode-<version>.vsix.