Environment Variables That Override VulnClaw Config File Settings

Environment variables prefixed with VULNCLAW_ override any setting defined in the VulnClaw config.yaml file, with reconnaissance API keys also accepting short-form names like FOFA_KEY or HUNTER_KEY.

VulnClaw uses a hierarchical configuration system defined in the Unclecheng-li/VulnClaw repository that loads settings from built-in defaults, a user-provided YAML file, and environment variables. According to vulnclaw/config/settings.py, environment variables represent the highest-priority layer and can dynamically override any configuration field without modifying disk files.

How VulnClaw Configuration Loading Works

The configuration loader implements a three-step merge process in the load_config function within vulnclaw/config/settings.py:

1. Built-in defaults establish base values for all settings.
2. User-provided config.yaml overlays user preferences if the file exists.
3. Environment variables apply the final override via the private helper _overlay_env starting at line 78.

This design ensures that any variable prefixed with VULNCLAW_ takes precedence over both defaults and YAML configuration values.

LLM Configuration Environment Variables

The following variables control Large Language Model connectivity and parameters, mapping directly to fields in the LLMConfig model:

• VULNCLAW_LLM_API_KEY – Overrides config.llm.api_key
• VULNCLAW_LLM_BASE_URL – Overrides config.llm.base_url
• VULNCLAW_LLM_MODEL – Overrides config.llm.model
• VULNCLAW_LLM_PROVIDER – Overrides config.llm.provider
• VULNCLAW_LLM_MAX_TOKENS – Overrides config.llm.max_tokens
• VULNCLAW_LLM_MAX_CONTEXT_TOKENS – Overrides config.llm.max_context_tokens
• VULNCLAW_LLM_TEMPERATURE – Overrides config.llm.temperature
• VULNCLAW_LLM_AUTH_MODE – Overrides config.llm.auth_mode
• VULNCLAW_LLM_CHATGPT_AUTO_PROXY – Overrides config.llm.chatgpt_auto_proxy

Session Behavior Environment Variables

Session management settings can be overridden using these environment variables, which target fields in SessionConfig:

• VULNCLAW_SESSION_OUTPUT_DIR – Overrides config.session.output_dir
• VULNCLAW_SESSION_AUTO_SAVE – Overrides config.session.auto_save
• VULNCLAW_SESSION_REPORT_FORMAT – Overrides config.session.report_format
• VULNCLAW_SESSION_MAX_ROUNDS – Overrides config.session.max_rounds
• VULNCLAW_SESSION_SHOW_THINKING – Overrides config.session.show_thinking
• VULNCLAW_SESSION_STALE_ROUNDS_THRESHOLD – Overrides config.session.stale_rounds_threshold
• VULNCLAW_SESSION_REASONING_STATE_ENABLED – Overrides config.session.reasoning_state_enabled
• VULNCLAW_SESSION_REFLEXION_ENABLED – Overrides config.session.reflexion_enabled
• VULNCLAW_SESSION_REFLEXION_MAX_SAME_VULN_FAILS – Overrides config.session.reflexion_max_same_vuln_fails
• VULNCLAW_SESSION_REFLEXION_MAX_TOTAL_NO_PROGRESS – Overrides config.session.reflexion_max_total_no_progress
• VULNCLAW_SESSION_ESCALATION_MAX_LEVEL – Overrides config.session.escalation_max_level
• VULNCLAW_SESSION_PLUGIN_RUNTIME_ENABLED – Overrides config.session.plugin_runtime_enabled
• VULNCLAW_SESSION_PLUGIN_DEFAULT_TIMEOUT – Overrides config.session.plugin_default_timeout
• VULNCLAW_SESSION_PLUGIN_MAX_REQUESTS_PER_TARGET – Overrides config.session.plugin_max_requests_per_target
• VULNCLAW_SESSION_EVIDENCE_MIN_REPORT_LEVEL – Overrides config.session.evidence_min_report_level

Safety and Execution Controls

Security-related execution settings can be modified via:

• VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED – Overrides config.safety.enable_python_execute
• VULNCLAW_SAFETY_PYTHON_EXECUTE_RESTRICTED – Overrides config.safety.python_execute_restricted
• VULNCLAW_SAFETY_PYTHON_EXECUTE_MODE – Overrides config.safety.python_execute_mode
• VULNCLAW_SAFETY_PYTHON_EXECUTE_MAX_LINES – Overrides config.safety.python_execute_max_lines
• VULNCLAW_SAFETY_PYTHON_EXECUTE_SHOW_WARNING – Overrides config.safety.python_execute_show_warning
• VULNCLAW_SAFETY_PYTHON_EXECUTE_MAX_OUTPUT_CHARS – Overrides config.safety.python_execute_max_output_chars
• VULNCLAW_SAFETY_PYTHON_EXECUTE_AUDIT_ENABLED – Overrides config.safety.python_execute_audit_enabled

Reconnaissance API Keys

VulnClaw accepts external reconnaissance service credentials in two formats. The short-form names are recognized for backward compatibility, while the VULNCLAW_ prefixed versions follow the standard naming convention:

• FOFA: FOFA_EMAIL or VULNCLAW_RECON_FOFA_EMAIL; FOFA_KEY or VULNCLAW_RECON_FOFA_KEY
• Hunter: HUNTER_KEY or VULNCLAW_RECON_HUNTER_KEY
• Quake: QUAKE_KEY or VULNCLAW_RECON_QUAKE_KEY
• ZoomEye: ZOOMEYE_KEY or VULNCLAW_RECON_ZOOMEYE_KEY
• Shodan: SHODAN_KEY or VULNCLAW_RECON_SHODAN_KEY
• ZeroZone: ZEROZONE_KEY or VULNCLAW_RECON_ZEROZONE_KEY

Practical Usage Examples

To override the LLM model and API key without editing config.yaml:

export VULNCLAW_LLM_PROVIDER=openai
export VULNCLAW_LLM_API_KEY=sk-REDACTED
export VULNCLAW_LLM_MODEL=gpt-4o-mini
vulnclaw run

To change session behavior for temporary execution:

export VULNCLAW_SESSION_MAX_ROUNDS=5
export VULNCLAW_SESSION_SHOW_THINKING=true
export VULNCLAW_SESSION_OUTPUT_DIR=$HOME/.vulnclaw/custom_sessions
vulnclaw start

To disable Python execution safety guards:

export VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED=false
vulnclaw run --plugin my_custom_plugin.py

To use FOFA reconnaissance with the short-form variable:

export FOFA_KEY=abcd1234efgh5678
vulnclaw recon fofa --query 'app="Apache"'

Summary

• VulnClaw applies a three-layer configuration system where environment variables take precedence over both built-in defaults and config.yaml values.
• The _overlay_env function in vulnclaw/config/settings.py processes all variables beginning with the VULNCLAW_ prefix.
• LLM, Session, Safety, and Recon sections each expose specific environment variables that map directly to Pydantic model fields.
• Reconnaissance API keys support dual naming conventions, accepting both VULNCLAW_RECON_* prefixed variables and legacy short-form names like FOFA_KEY.
• No file modification is required to override configuration—simply export the appropriate variables before invoking the CLI.

Frequently Asked Questions

What prefix must environment variables use to override VulnClaw settings?

All environment variables must begin with VULNCLAW_ to be recognized by the configuration loader in vulnclaw/config/settings.py. The exception is reconnaissance API keys, which also accept short-form names like FOFA_KEY or SHODAN_KEY for backward compatibility.

Do environment variables override the config.yaml file completely?

Yes. According to the implementation in the _overlay_env function, environment variables represent the highest-priority layer. If a VULNCLAW_* variable is set, it will overwrite the corresponding value from config.yaml regardless of the YAML content.

Can I disable Python code execution using environment variables?

Yes. Set VULNCLAW_SAFETY_PYTHON_EXECUTE_ENABLED=false to disable the Python execution feature, or use VULNCLAW_SAFETY_PYTHON_EXECUTE_MODE=restricted to enforce restricted execution mode without modifying the configuration file.

Where is the environment variable mapping logic implemented?

The mapping logic is implemented in the private helper function _overlay_env starting at line 78 of vulnclaw/config/settings.py. This function reads the OS environment and applies matching variables to the VulnClawConfig Pydantic model defined in vulnclaw/config/schema.py.

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