Query the authenticated workspace's remaining file-scan and live-site credits, active UTC billing period, shard capacity, and legal authorization scopes. Call this tool first before planning or starting a scan. Use vulkill_scan_guided_interactive to compute a shard execution plan, or vulkill_list_reports to inspect past findings. Leaving plannedFiles and plannedSites at 0 inspects current balances only. Positive values convert each file to 1 file credit across ceil(plannedFiles / 5000) shards and each site to 1 site credit against the active credit_periods row, reporting any quota shortfall without throwing an error. Requires VULKILL_API_KEY or OAuth 2.1 Bearer auth and charges zero credits. Enforces a 60 requests/minute rate limit per workspace.

Calculate a dry-run scan execution plan for covered files, live sites, shard count, and uncovered overflow. Call after vulkill_check_credits and before vulkill_start_scan to preview scope. Use vulkill_start_scan to launch a real scan, or vulkill_check_credits when only raw balances are needed. Parameters files and sites specify requested counts, while coveredFiles and coveredSites return accepted quota-bounded counts at 1 file credit per file across ceil(coveredFiles / 5000) shards and 1 site credit per site, placing any over-quota excess into missingFiles and missingSites without failing. Code modes ('source', 'semantic', 'infrastructure') force coveredSites=0, 'web' forces coveredFiles=0 and shards=0, and 'auto' evaluates both. Requires VULKILL_API_KEY or OAuth 2.1 auth, charges zero credits, and launches no workers.

Atomically reserve credits and dispatch an authorized security scan job to the VulKill scanner engine. Call only to execute a real scan after vulkill_check_credits or vulkill_scan_guided_interactive. Do not use for dry-run estimates or to poll an active job (use vulkill_complete_scan instead). Requires liabilityAccepted=true and authorizationScope ('own_asset' for self-owned targets, 'authorized_organization_or_client' for contracted engagements, or 'open_source_or_bounty' for public repos). Each file reserves 1 file credit across ceil(files / 5000) shards and each site reserves 1 site credit, while sites > 0 or mode='web' requires an HTTPS targetUrl verified in https://app.vulkill.com/targets. Passing idempotencyKey binds the reservation to (mode, files, sites, targetUrl) to replay scanId on retries and reject mismatched reuse. Requires VULKILL_API_KEY or OAuth 2.1 auth, deducts active credit_periods quota before dispatch, and rolls back if engine startup fails.

Synchronize the remote scanner engine state for an existing scanId, finalizing verified findings or issuing an atomic credit refund when the engine confirms the job never started. Call after vulkill_start_scan to settle an active job. Do not use to start new scans (use vulkill_start_scan) or to browse workspace history (use vulkill_list_reports). The scanId must belong to the caller's workspace. Refund verification triggers when cancelRequested=true or started=false (cancelRequested takes precedence when both are passed, and omitting both runs normal completion sync), while summary is ignored when finalized findings exist and saved only as an audit note when a not_started job is refunded. Requires scan-owner VULKILL_API_KEY or OAuth 2.1 auth and returns HTTP 403 for foreign workspaces. Queries the authoritative engine rather than client claims, blocks refunds on running or completed jobs after network timeouts, and credits the originating credit_periods row at most once.

Retrieve the workspace's security scan reports, including severity counts, CVSS/CWE findings, and credit usage. Call after vulkill_start_scan or vulkill_complete_scan to inspect past results. Do not use to settle an in-flight job (use vulkill_complete_scan) or to check wallet quota (use vulkill_check_credits). Filters status ('running', 'completed', 'not_started_refunded' with creditsCharged=0, or 'failed') and mode ('auto', repository 'source'/'semantic'/'infrastructure', or live 'web') combine with logical AND and sort by createdAt DESC before limit truncates the slice. Because cursor pagination is not used, narrow status or mode to inspect older runs beyond the 25-report cap. Requires VULKILL_API_KEY or OAuth 2.1 auth and isolates records to the caller's workspace. Charges zero credits and enforces 60 requests/minute per workspace.