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

> Learn to configure API keys for reconnaissance tools in VulnClaw. Utilize manual YAML editing or CLI commands for secure credential management. Get started today!

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: how-to-guide
- Published: 2026-06-30

---

**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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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.

```yaml

# ~/.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)](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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py#L1460-L1483) and supports dot-notation paths corresponding to the YAML structure.

Set a single key:

```bash
vulnclaw config set recon.fofa_key abcd1234efgh5678ijkl9012mnop3456

```

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

```bash
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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/schema.py#L179-L186), the application looks for uppercase service names suffixed with `_KEY`.

```bash
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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/services/config_service.py#L11-L19)). To verify that VulnClaw recognizes your credentials, execute a live reconnaissance query:

```bash
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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py#L13-L25).
- The **`ReconConfig`** model in [`vulnclaw/config/schema.py#L176-L191`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/web/services/config_service.py#L11-L19). Reconnaissance keys remain server-side only for security reasons and are never transmitted to the frontend.