How to Configure API Keys for Reconnaissance Tools in VulnClaw: A Complete Guide

VulnClaw stores reconnaissance API credentials in ~/.vulnclaw/config.yaml and supports both manual YAML editing and CLI dot-notation commands like vulnclaw config set recon.fofa_key <key>, with optional environment variable fallbacks for temporary overrides.

When using the Unclecheng-li/VulnClaw framework for vulnerability assessment, configuring API keys for reconnaissance tools is the first step to unlock integrated threat intelligence services. The application consolidates all credentials in a user-specific configuration file and provides both programmatic and interactive methods to manage these sensitive values securely.

Where VulnClaw Stores API Credentials

VulnClaw resolves the user configuration file path in vulnclaw/config/settings.py#L13-L25. By default, the framework reads from ~/.vulnclaw/config.yaml. If this file does not exist on first run, you must create it manually or use the CLI initialization commands.

The configuration schema is defined in vulnclaw/config/schema.py#L176-L191, specifically within the ReconConfig Pydantic model. This model validates all reconnaissance API keys at runtime, ensuring that only properly formatted credentials are passed to the underlying recon plugins.

Supported Reconnaissance Services

The ReconConfig model supports the following threat intelligence platforms:

• FOFA – requires both fofa_email and fofa_key
• Hunter – requires hunter_key
• Quake – requires quake_key
• ZoomEye – requires zoomeye_key
• Shodan – requires shodan_key
• ZeroZone – requires zerozone_key

Only the services you intend to use need configuration; all fields are optional by default.

Three Methods to Configure API Keys

VulnClaw offers three distinct approaches to populate your reconnaissance credentials, each suited for different operational contexts.

Method 1: Manual YAML Configuration

Edit the ~/.vulnclaw/config.yaml file directly to add a top-level recon: mapping. This method is ideal for bulk configuration during initial setup.

# ~/.vulnclaw/config.yaml

recon:
  fofa_email: "my@email.com"
  fofa_key: "abcd1234efgh5678ijkl9012mnop3456"
  hunter_key: "hunter-xxxxxxxxxxxxxxxx"
  quake_key: "quake-xxxxxxxxxxxxxxxx"
  zoomeye_key: "zoomeye-xxxxxxxxxxxxxxxx"
  shodan_key: "SHODAN1234567890"
  zerozone_key: "zerozone-xxxxxxxxxxxx"

As implemented in the source code, the ReconConfig model parses these values during application startup, validating them against the schema in [vulnclaw/config/schema.py](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py#L176-L191).

Method 2: CLI Dot-Notation Commands

Use the vulnclaw config set sub-command for incremental updates without opening a text editor. This command is implemented in vulnclaw/cli/main.py#L1460-L1483 and supports dot-notation paths corresponding to the YAML structure.

Set a single key:

vulnclaw config set recon.fofa_key abcd1234efgh5678ijkl9012mnop3456

Set multiple keys in one invocation using the key=value syntax:

vulnclaw config set \
  recon.fofa_key=abcd1234efgh5678ijkl9012mnop3456 \
  recon.hunter_key=hunter-xxxxxxxxxxxxxxxx \
  recon.shodan_key=SHODAN1234567890

Internally, these commands dispatch to the configuration save handler in vulnclaw.config.settings, which atomically updates the YAML file while preserving existing values.

Method 3: Environment Variable Overrides

For CI/CD pipelines or temporary testing, VulnClaw checks for environment variables before reading the config file. As defined in vulnclaw/config/schema.py#L179-L186, the application looks for uppercase service names suffixed with _KEY.

export FOFA_KEY=abcd1234efgh5678ijkl9012mnop3456
export HUNTER_KEY=hunter-xxxxxxxxxxxxxxxx
export QUAKE_KEY=quake-xxxxxxxxxxxxxxxx

vulnclaw recon fofa example.com

This approach prevents credentials from being written to disk and is useful in ephemeral execution environments.

Verifying Your Configuration

Unlike LLM API keys, reconnaissance keys are opaque and do not expose a public api_key_configured flag through the web interface (see vulnclaw/web/services/config_service.py#L11-L19). To verify that VulnClaw recognizes your credentials, execute a live reconnaissance query:

vulnclaw recon fofa "domain=\"example.com\""

A successful HTTP response confirms the key is properly loaded and authenticated with the target service.

Security Best Practices

• Never commit API keys. The ~/.vulnclaw/ directory is git-ignored by default, but verify your .gitignore excludes local configuration files.
• Use environment variables in shared or public development environments to avoid leaving credentials in the filesystem.
• Restrict file permissions on ~/.vulnclaw/config.yaml to owner-read only (chmod 600) when using the YAML storage method.
• Rotate keys regularly through the vulnclaw config set command to update values without service interruption.

Summary

• VulnClaw stores reconnaissance API keys in ~/.vulnclaw/config.yaml, with path resolution handled in vulnclaw/config/settings.py#L13-L25.
• The ReconConfig model in vulnclaw/config/schema.py#L176-L191 validates credentials for FOFA, Hunter, Quake, ZoomEye, Shodan, and ZeroZone.
• Use vulnclaw config set recon.<key> <value> (implemented in vulnclaw/cli/main.py#L1460-L1483) for command-line configuration.
• Environment variables like FOFA_KEY and HUNTER_KEY provide secure, temporary overrides without file persistence.
• Verify configuration by running actual reconnaissance commands, as keys are not exposed through the web UI's public config endpoint.

Frequently Asked Questions

Where is the VulnClaw configuration file located?

VulnClaw reads user-specific settings from ~/.vulnclaw/config.yaml by default. This path is resolved at runtime in vulnclaw/config/settings.py#L13-L25. If the directory does not exist, create it manually before adding your first API key.

Can I configure multiple reconnaissance API keys at once?

Yes. You can either edit the recon: section in ~/.vulnclaw/config.yaml manually to include multiple keys, or use chained CLI commands: vulnclaw config set recon.fofa_key=VALUE recon.hunter_key=VALUE. Both methods update the underlying YAML structure atomically through the save handler.

Does VulnClaw support environment variables for reconnaissance keys?

Yes. According to the ReconConfig model in vulnclaw/config/schema.py#L179-L186, VulnClaw will check for uppercase environment variables (e.g., FOFA_KEY, SHODAN_KEY) if the corresponding YAML key is missing or empty, enabling secure CI/CD integration.

Why does the web UI not show my reconnaissance API keys?

The web interface exposes only the api_key_configured flag for LLM credentials via vulnclaw/web/services/config_service.py#L11-L19. Reconnaissance keys remain server-side only for security reasons and are never transmitted to the frontend.

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