Brave Rotator

Brave Search API with automatic key rotation across multiple API keys to maximize free tier limits (2000 req/month per key). Use when performing web, news, o...

Security Scan

The skill does what it claims (rotates Brave Search API keys) but its runtime instructions and code store API keys in plaintext state on disk and the registry metadata omits the required env var, which is disproportionate and risky.

Purpose & Capability

The name/description match the code: it implements Brave Search calls with multi-key rotation. However the package metadata declares no required env vars/credentials while the SKILL.md and code require BRAVE_API_KEYS — a mismatch between declared requirements and actual needs.

Instruction Scope

Runtime instructions and the script read BRAVE_API_KEYS from the environment and persist full per-key state to a JSON file (~/.brave_key_state.json by default). The code uses the raw API keys as JSON object keys, so the state file will contain actual API keys in plaintext. SKILL.md even suggests inspecting that file, encouraging exposure of secrets.

Install Mechanism

No install spec — instruction-only plus a single Python script. No downloads or external installers are invoked, which minimizes install-time risk.

Credentials

The skill actually requires BRAVE_API_KEYS (comma-separated API keys) even though metadata lists none. Requesting multiple API keys is reasonable for rotation, but persisting them in an unencrypted state file is disproportionate and unnecessary for the stated purpose.

Persistence & Privilege

The skill writes a state file to the user's home directory and persists sensitive data (the API keys and usage metadata). It does not require elevated system privileges or always:true, but persistent storage of secrets increases blast radius if the environment is shared or backed up.

What to consider before installing

This skill legitimately implements key rotation for Brave Search, but it stores your API keys in plaintext in a state file and the registry metadata doesn't declare the required BRAVE_API_KEYS env var. Before installing or using it, consider: 1) review the script locally (you already have the code) and confirm you trust the source; 2) do not supply long-lived or high-privilege keys — prefer disposable keys; 3) change the code so it does not write raw keys to disk (store only masked identifiers or hashes, or avoid persistent state altogether), or set BRAVE_KEY_STATE_FILE to a secure, access-restricted path (or tmpfs); 4) run the skill in an isolated environment/container if possible; 5) if you cannot audit or modify the script, avoid providing multiple keys to it. Also consider updating registry metadata to declare BRAVE_API_KEYS so the requirement is explicit.

Multi-key Brave Search with automatic round-robin rotation and rate-limit fallback.

Setup

Set env var with comma-separated keys:

export BRAVE_API_KEYS=key1,key2,key3

Optionally set state file path (default: ~/.brave_key_state.json):

export BRAVE_KEY_STATE_FILE=/path/to/state.json

Script: scripts/brave_search.py

Run directly or import as module.

CLI usage

python3 brave_search.py "your query" [--count 5] [--type web|news|image] [--country us] [--lang en] [--json]

Import usage

import sys, os
sys.path.insert(0, "path/to/skill/scripts")
from brave_search import search, format_results

data, used_key, key_idx = search("your query", count=5, search_type="web")
results = format_results(data, "web")
# results = [{"title": ..., "url": ..., "snippet": ...}, ...]

Rotation Logic

• Maintains state in ~/.brave_key_state.json
• Round-robin across all keys
• On HTTP 429/403: blocks key for 60s, retries with next key
• All keys exhausted: uses least recently blocked key

Key State Inspection

cat ~/.brave_key_state.json

Shows per-key request count, last success, and blocked_until timestamps.

Search Types

Type	Endpoint	Result fields
web	/web/search	title, url, snippet
news	/news/search	title, url, snippet, age
image	/images/search	title, url, thumbnail

Notes

• Free plan: 2000 req/month/key, 1 req/sec
• With N keys: effectively N×2000 req/month
• See references/brave-api.md for full API params and plan details