VulKill Security

Overview Schema Source Related Servers Discussions Admin

Start Authorized VulKill Security Scan

vulkill_start_scan

Idempotent

Reserves scan credits and dispatches an authorized VulKill security scan job for owned, client, or open-source targets, rolling back if engine startup fails.

Instructions

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.

Input Schema

Name	Required	Description	Default
`mode`	No	Execution profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto').	auto
`files`	No	Repository file count to scan (0 to 100,000,000, default 0).
`sites`	No	Verified live site count to scan (0 to 10,000, default 0).
`targetUrl`	No	Repository URL or HTTPS web origin (for example, 'https://example.com').
`targetName`	No	Project or repository label (1–120 characters, default 'MCP Tarama Hedefi').
`idempotencyKey`	No	Optional client idempotency key (8–120 ASCII alphanumeric/dash/underscore characters).
`liabilityAccepted`	Yes	Boolean confirmation of explicit legal authorization and liability acceptance.
`authorizationScope`	Yes	Legal authorization basis ('own_asset', 'authorized_organization_or_client', or 'open_source_or_bounty').

Output Schema

Name	Required	Description
`ok`	Yes	True when credits were reserved and the scanner engine accepted the job.
`scanId`	Yes	Unique VulKill scan report identifier (pass to vulkill_complete_scan).
`status`	Yes	Authoritative scan state ('running' or 'completed').
`reportUrl`	Yes	URL where the live report and findings can be viewed (https://app.vulkill.com/scans).
`engineJobId`	Yes	Authoritative remote scanner engine job identifier bound to scanId.
`sitesCharged`	Yes	Live-site credits atomically reserved for this scan.
`creditsCharged`	Yes	File credits atomically reserved for this scan.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.9Nov 3, 2026

changedInput schema / properties / mode / description

Previous value: -"Scan execution profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto')."New value: +"Execution profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto')."

changedInput schema / properties / targetName / description

Previous value: -"Human-readable project or repository label (1–120 characters, default 'MCP Tarama Hedefi')."New value: +"Project or repository label (1–120 characters, default 'MCP Tarama Hedefi')."

Changed9 schema fields changedv0.1.5Nov 3, 2026

changedInput schema / properties / authorizationScope / description

Previous value: -"Mandatory legal authorization basis: 'own_asset' (first-party code/system), 'authorized_organization_or_client' (written client/employer mandate), or 'open_source_or_bounty' (open-source license or official bug bounty scope)."New value: +"Legal authorization basis ('own_asset', 'authorized_organization_or_client', or 'open_source_or_bounty')."

changedInput schema / properties / files / description

Previous value: -"Number of files to scan and atomically reserve from file credits (0 to 100,000,000; 5,000 files per container shard). At least one of files or sites must be > 0."New value: +"Repository file count to scan (0 to 100,000,000, default 0)."

changedInput schema / properties / idempotencyKey / description

Previous value: -"Optional client-generated idempotency key (8–120 alphanumeric/dash/underscore characters) to guarantee single job creation and single credit deduction across network retries."New value: +"Optional client idempotency key (8–120 ASCII alphanumeric/dash/underscore characters)."

changedInput schema / properties / liabilityAccepted / description

Previous value: -"Must be set to true to confirm explicit legal authorization and acceptance of the VulKill liability waiver before any worker starts."New value: +"Boolean confirmation of explicit legal authorization and liability acceptance."

changedInput schema / properties / mode / description

Previous value: -"Execution profile: 'auto' (all engines, 35m watchdog), 'source' (SAST/SCA/secrets, 25m), 'semantic' (deep taint/symbolic solver, 30m), 'infrastructure' (containers/IaC, 25m), or 'web' (live DAST, 35m). Defaults to 'auto'."New value: +"Scan execution profile ('auto', 'source', 'semantic', 'infrastructure', or 'web'; default 'auto')."

changedInput schema / properties / sites / description

Previous value: -"Number of verified live sites to scan and atomically reserve from site credits (0 to 10,000). At least one of files or sites must be > 0."New value: +"Verified live site count to scan (0 to 10,000, default 0)."

changedInput schema / properties / targetName / description

Previous value: -"Human-readable project, repository, or target label (1–120 characters, e.g., 'acme-payments-api'). Defaults to 'MCP Tarama Hedefi' if omitted."New value: +"Human-readable project or repository label (1–120 characters, default 'MCP Tarama Hedefi')."

changedInput schema / properties / targetUrl / description

Previous value: -"Target repository URL, package identifier, or domain-verified HTTPS origin (e.g., 'https://example.com'). Required when sites > 0 or mode is 'web'."New value: +"Repository URL or HTTPS web origin (for example, 'https://example.com')."

changedOutput schema / properties / scanId / description

Previous value: -"Unique VulKill scan report identifier (e.g., 'scan_...'). Pass this to vulkill_complete_scan."New value: +"Unique VulKill scan report identifier (pass to vulkill_complete_scan)."

Changed16 schema fields changedv0.1.1Nov 3, 2026

addedInput schema / properties / authorizationScope / description

Added value: +"Mandatory legal authorization basis: 'own_asset' (first-party code/system), 'authorized_organization_or_client' (written client/employer mandate), or 'open_source_or_bounty' (open-source license or official bug bounty scope)."

addedInput schema / properties / files / default
```
Added value: +0
```

addedInput schema / properties / files / description

Added value: +"Number of files to scan and atomically reserve from file credits (0 to 100,000,000; 5,000 files per container shard). At least one of files or sites must be > 0."

addedInput schema / properties / files / maximum
```
Added value: +100000000
```
addedInput schema / properties / files / minimum
```
Added value: +0
```

addedInput schema / properties / idempotencyKey

Added value: +{
+  "description": "Optional client-generated idempotency key (8–120 alphanumeric/dash/underscore characters) to guarantee single job creation and single credit deduction across network retries.",
+  "type": "string"
+}

addedInput schema / properties / liabilityAccepted / description

Added value: +"Must be set to true to confirm explicit legal authorization and acceptance of the VulKill liability waiver before any worker starts."

addedInput schema / properties / mode / default
```
Added value: +"auto"
```

addedInput schema / properties / mode / description

Added value: +"Execution profile: 'auto' (all engines, 35m watchdog), 'source' (SAST/SCA/secrets, 25m), 'semantic' (deep taint/symbolic solver, 30m), 'infrastructure' (containers/IaC, 25m), or 'web' (live DAST, 35m). Defaults to 'auto'."

addedInput schema / properties / sites / default
```
Added value: +0
```

addedInput schema / properties / sites / description

Added value: +"Number of verified live sites to scan and atomically reserve from site credits (0 to 10,000). At least one of files or sites must be > 0."

addedInput schema / properties / sites / maximum
```
Added value: +10000
```
addedInput schema / properties / sites / minimum
```
Added value: +0
```

addedInput schema / properties / targetName / description

Added value: +"Human-readable project, repository, or target label (1–120 characters, e.g., 'acme-payments-api'). Defaults to 'MCP Tarama Hedefi' if omitted."

addedInput schema / properties / targetUrl / description

Added value: +"Target repository URL, package identifier, or domain-verified HTTPS origin (e.g., 'https://example.com'). Required when sites > 0 or mode is 'web'."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "creditsCharged": {
+      "description": "File credits atomically reserved for this scan.",
+      "type": "integer"
+    },
+    "engineJobId": {
+      "description": "Authoritative remote scanner engine job identifier bound to scanId.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "True when credits were reserved and the scanner engine accepted the job.",
+      "type": "boolean"
+    },
+    "reportUrl": {
+      "description": "URL where the live report and findings can be viewed (https://app.vulkill.com/scans).",
+      "type": "string"
+    },
+    "scanId": {
+      "description": "Unique VulKill scan report identifier (e.g., 'scan_...'). Pass this to vulkill_complete_scan.",
+      "type": "string"
+    },
+    "sitesCharged": {
+      "description": "Live-site credits atomically reserved for this scan.",
+      "type": "integer"
+    },
+    "status": {
+      "description": "Authoritative scan state ('running' or 'completed').",
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok",
+    "scanId",
+    "engineJobId",
+    "status",
+    "creditsCharged",
+    "sitesCharged",
+    "reportUrl"
+  ],
+  "type": "object"
+}

First observedv0.1.0Nov 3, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly=false, openWorld=true, idempotent=true, destructive=false; the description goes well beyond with billing behavior ('deducts active credit_periods quota before dispatch'), failure semantics ('rolls back if engine startup fails'), the shard formula, target-binding rules, and auth requirements (VULKILL_API_KEY or OAuth 2.1). The idempotency replay/reject semantics also explain concretely what idempotentHint means here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences with no filler, and the purpose plus the call precondition are front-loaded. The final sentence is a long multi-clause run that packs auth, quota deduction, and rollback together, which is dense but each clause carries distinct operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, open-world, credit-consuming mutation with legal attestation requirements, the description supplies prerequisites, cost model, target verification, idempotency contract, auth options, and rollback behavior. With an output schema present it rightly omits return-value detail, leaving nothing material an agent needs before invoking.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even at 100% schema coverage, the description adds cross-parameter meaning the schema cannot express: cost is 1 file credit per ceil(files/5000) shards plus 1 site credit per site, sites>0 or mode='web' mandates an HTTPS targetUrl verified at the targets page, and idempotencyKey binds the reservation to (mode, files, sites, targetUrl). These are conditional constraints an agent would otherwise miss by reading properties individually.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Atomically reserve credits and dispatch an authorized security scan job to the VulKill scanner engine' — which tells an agent exactly what happens (credit reservation plus job dispatch), not just 'start scan'. It also implicitly separates itself from the read-only siblings by naming the execution role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition chain ('Call only to execute a real scan after vulkill_check_credits or vulkill_scan_guided_interactive') and two explicit exclusions with the correct alternative named ('Do not use for dry-run estimates or to poll an active job (use vulkill_complete_scan instead)'). This is the when/when-not/alternative pattern at full strength.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server