How to Configure VulnClaw: Complete Setup Guide for the AI Security Agent

VulnClaw stores configuration in ~/.vulnclaw/config.yaml and supports CLI-based editing, provider presets, and environment variable overrides loaded via Pydantic models in vulnclaw/config/schema.py.

VulnClaw is an open-source AI-powered security testing framework that requires specific configuration before executing vulnerability scans. The repository Unclecheng-li/VulnClaw manages settings through a layered system combining YAML files, provider presets, and runtime environment variables. Understanding how to configure VulnClaw properly ensures secure LLM integration and proper MCP service activation.

Where VulnClaw Stores Configuration

By default, VulnClaw creates a user-specific configuration directory at ~/.vulnclaw. This path can be overridden by setting the VULNCLAW_CONFIG_DIR environment variable before running the tool.

The configuration directory contains the following structure:

• CONFIG_FILE (~/.vulnclaw/config.yaml) – The persistent YAML configuration file
• SESSIONS_DIR – Runtime session data storage
• TARGETS_DIR – Target specifications and metadata
• KB_DIR – Knowledge base storage
• SKILLS_DIR – Skill definitions and templates

The directories are created automatically when the first configuration operation runs via the ensure_dirs() function in vulnclaw/config/settings.py.

Editing Configuration via CLI

While you can edit the YAML file manually, VulnClaw provides a safe, typed CLI interface that validates inputs against Pydantic schemas defined in vulnclaw/config/schema.py.

Use the vulnclaw config set command with dot-notation to modify nested values:

# Set LLM API credentials

vulnclaw config set llm.api_key sk-xxxxxxxxxxxxxxxxxxxx

# Adjust session limits

vulnclaw config set session.max_rounds 30

# Disable Python execution for safety

vulnclaw config set safety.enable_python_execute false

The CLI parses the key, coerces the value to the appropriate type (int, bool, str), and persists changes through set_config_value() → save_config() in vulnclaw/config/settings.py.

Configuring LLM Providers

VulnClaw ships with built-in support for 13 OpenAI-compatible providers defined in the PROVIDER_PRESETS constant within vulnclaw/config/schema.py. The apply_provider_preset() function in vulnclaw/config/settings.py automatically configures the base URL and default model for your chosen provider.

Switch providers using the preset command:

# Auto-configure MiniMax (fills base_url and model)

vulnclaw config provider minimax

# Override with custom endpoint if needed

vulnclaw config set llm.base_url https://my-api.example.com/v1
vulnclaw config set llm.model my-custom-model

Setting Up MCP (Model-Context-Protocol) Services

MCP servers extend VulnClaw's capabilities with external tools like Chrome DevTools or Burp Suite. Built-in servers are defined in BUILTIN_MCP_SERVERS in vulnclaw/config/schema.py.

Enable services via the CLI:

vulnclaw config set mcp.servers.chrome-devtools.enabled true
vulnclaw config set mcp.servers.burp.enabled true

Each server configuration includes a transport field supporting three types defined in MCPTransportConfig: stdio, sse, or streamable-http. The transport specifies how VulnClaw communicates with the MCP server, including command paths, arguments, or URLs.

Overriding Settings with Environment Variables

Any configuration field can be overridden at runtime using environment variables prefixed with VULNCLAW_. The _overlay_env() function in vulnclaw/config/settings.py processes these variables after loading the YAML file, ensuring the precedence order: environment variables > config file > built-in defaults.

Common environment overrides:

export VULNCLAW_LLM_API_KEY=sk-xxxx
export VULNCLAW_SESSION_MAX_ROUNDS=20
export VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED=false

For reconnaissance services like FOFA or Shodan, export the standard key names (FOFA_KEY, SHODAN_KEY) and the loader will map them into config.recon automatically.

Configuring Safety and Sandbox Options

The safety section in vulnclaw/config/schema.py controls the python_execute tool used by the agent for dynamic code execution. Configure these carefully based on your risk tolerance:

• enable_python_execute – Default true; set to false to disable the tool entirely
• python_execute_mode – Default trusted-local; options include safe, lab, or trusted-local
• python_execute_max_lines – Default 50; limits code length per execution
• python_execute_audit_enabled – Default true; logs all executions to python_execute_audit.jsonl

Modify via CLI:

vulnclaw config set safety.python_execute_mode safe
vulnclaw config set safety.python_execute_max_lines 25

Loading Configuration Programmatically

Access the merged configuration in Python using the load_config() function from vulnclaw/config/settings.py:

from vulnclaw.config.settings import load_config

cfg = load_config()
print("LLM provider:", cfg.llm.provider)
print("Base URL:", cfg.llm.base_url)
print("Session dir:", cfg.session.output_dir)

This returns the final configuration object with all defaults, file values, and environment overlays applied.

Summary

• Configuration location: ~/.vulnclaw/config.yaml (override with VULNCLAW_CONFIG_DIR)
• CLI editing: Use vulnclaw config set <key> <value> for type-safe updates via set_config_value()
• Provider setup: Run vulnclaw config provider <name> to apply presets from PROVIDER_PRESETS
• MCP services: Enable built-in servers in BUILTIN_MCP_SERVERS using dot-notation keys
• Environment overrides: Prefix any config key with VULNCLAW_ and export; processed by _overlay_env()
• Safety controls: Adjust python_execute settings through the safety section in schema.py

Frequently Asked Questions

Where is the VulnClaw configuration file located?

VulnClaw stores its configuration in ~/.vulnclaw/config.yaml by default. The directory is created automatically by ensure_dirs() in vulnclaw/config/settings.py when you first run a configuration command. You can relocate this directory by setting the VULNCLAW_CONFIG_DIR environment variable before executing VulnClaw.

How do I switch between different LLM providers?

Use the vulnclaw config provider <name> command to switch between the 13 built-in OpenAI-compatible providers. This invokes apply_provider_preset() in vulnclaw/config/settings.py, which automatically populates the base_url and model fields in config.yaml based on the PROVIDER_PRESETS definition in vulnclaw/config/schema.py.

Can I configure VulnClaw using only environment variables without editing YAML?

Yes. Any configuration field supports environment variable overrides using the VULNCLAW_ prefix (e.g., VULNCLAW_LLM_API_KEY). The _overlay_env() function loads these after the YAML file, ensuring environment variables take precedence. For CI/CD deployments, you can rely entirely on environment variables without creating a config.yaml file.

How do I disable Python code execution for security hardening?

Set vulnclaw config set safety.enable_python_execute false or export VULNCLAW_SAFETY_ENABLE_PYTHON_EXECUTE=false. This disables the python_execute tool entirely. Alternatively, use vulnclaw config set safety.python_execute_mode safe to restrict execution to sandboxed environments, as defined in the Pydantic models in vulnclaw/config/schema.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}